サーバーへデプロイ

HayaKoe は シングルトン TTS インスタンス + ビルドタイム重み内蔵 パターンでサーバー環境に合わせて設計されています。FastAPI・Docker の組み合わせでシンプルな API サーバーを立ち上げられます。

設計のポイント

1. モデルは一度だけロード（シングルトン）

TTS モデルは一度ロードするのにかなり時間がかかります。GPU 環境ではコンパイル段階まで含めると数十秒かかることもあります。リクエストごとに新しいインスタンスを作ると本番サービスが事実上不可能になるため、プロセスの存続期間中ひとつだけ 維持してすべてのリクエストが共有する必要があります。

実際のコードは FastAPI の lifespan フックで TTS(...).load(...).prepare(warmup=True) でシングルトンをビルドして app.state.tts に保存しておき、ハンドラーはこのひとつのインスタンスを再利用する構造です。

並行性は心配不要です。Speaker は内部に threading.Lock を持っているため、同じ話者に対する同時リクエストは自動的にシリアライズされ、異なる話者同士は並列で動作します — 別途のプール・キュー実装は不要です。

GPU バックエンドは torch.compile まで一緒に準備します

TTS.prepare() は CUDA バックエンドでモデルロードだけでなく torch.compile をすべての話者と BERT に一括適用します。

warmup=True を指定するとダミー推論を1回先行して、コンパイルコストを prepare 段階に前倒しします。このプロセス自体が数十秒かかることがあるため、必ずアプリ起動時に一度だけ実行する必要があります。リクエストごとに TTS を新規作成すると毎回再コンパイルが走り サーバーが事実上麻痺します。

CPU バックエンドは ONNX Runtime を使うため別途コンパイル段階がなく、prepare がはるかに高速です。

→ 実装は FastAPI 統合

2. 重みはビルドタイムにイメージに焼き込み

Docker イメージひとつに モデルの重みまですべて含めて、ランタイムでは外部ネットワークなしにすぐ起動できるようにするのが HayaKoe の推奨運用方式です。

これのために TTS.pre_download(device=...) — 「初期化はせずキャッシュだけを埋める」メソッドを提供します。Docker ビルド段階で呼び出して必要な話者ファイルをすべてイメージ内に焼き込んでおけば、ランタイムコンテナは HF・S3 にアクセスする必要がありません。

オフライン環境、ファイアウォール内側、HF・S3 の認証情報をランタイムコンテナに露出させたくない場合に特にクリーンなパターンです。

→ 実装は Docker イメージ

セクション構成

ページ	内容
FastAPI 統合	lifespan でシングルトンロード、agenerate / astream、並行性
Docker イメージ	ビルドタイム pre_download、BuildKit secret、マルチステージ
バックエンド選択	CPU（ONNX）vs GPU（PyTorch）トレードオフ