Docker - Cartesia Docs

Docker Compose および Docker Swarm によるデプロイは現在ベータ版です。サポートが必要な場合は Cartesia チームにお問い合わせください。

Docker Compose を使って単一マシン上に、または Docker Swarm を使ってマルチノードクラスタ上に Cartesia TTS をデプロイできます。

	Docker Compose	Docker Swarm
ノード	シングルホスト	複数ホスト（マネージャー + ワーカー）
GPU スケーリング	`WORKER_REPLICAS` 経由で複数ワーカー（GPU 1 つにつき 1 つ）	ラベル付き GPU ノード上にスケジュールされるワーカー
MIG サポート	`--mig` フラグによる自動検出	ノードラベルと `--mig` フラグによりノードごとに設定
ネットワーキング	Bridge（デフォルト）	Overlay（Swarm 管理）

前提条件

Docker がインストールされた 1 台以上のマシン（ユーザーが docker グループに所属している必要があります）
Compose のみ: Docker Compose V2（docker compose）
Swarm のみ: ノードが Docker の Swarm ネットワーキング要件を満たすこと
ドライバーがインストールされた NVIDIA GPU を 1 つ以上。対応する NVIDIA GPU 上では MIG（Multi-Instance GPU）パーティショニングがサポートされます
GPU ノードで NVIDIA Docker ランタイムがデフォルトに設定されていること（下記参照）
cartesia-kube のダウンロードで説明されている cartesia-kube リポジトリをダウンロード済みであること
オンボーディング時に提供される Cartesia API キーファイル（container_key）と GCS サービスアカウント JSON ファイル

GPU ランタイムの確認

各 GPU ノードで NVIDIA ランタイムを確認します:

nvidia-smi

docker info | grep "Default Runtime"
# Expected: Default Runtime: nvidia

docker run --rm nvidia/cuda:12.3.1-base-ubuntu22.04 nvidia-smi

nvidia がデフォルトランタイムでない場合は、NVIDIA Container Toolkit をインストールして次を実行します:

sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo systemctl restart docker

MIG を使用する場合: ホストで MIG を有効化してインスタンスを作成した後、それらが認識されていることを確認します:

nvidia-smi -L
# Each MIG instance appears as a MIG-... UUID line beneath its parent GPU.
# The deploy script reads these UUIDs automatically — no manual configuration required.

デプロイ前に、ホスト側で MIG を有効化してインスタンスを作成する必要があります。MIG インスタンスを再作成すると新しい UUID が生成されるため、その場合はスタックを再デプロイしてください。

ステップ 1 — シークレットの準備

以下のファイルを、ホスト（Compose）またはマネージャーノード（Swarm）に配置します:

container_key — Cartesia API キーを含むファイル
service-account.json — roles/artifactregistry.reader（イメージ取得）および roles/storage.objectViewer（GCS 同期）を持つ GCS サービスアカウント JSON

デプロイスクリプトを実行可能にします:

Compose
Swarm

chmod +x local/scripts/deploy-compose.sh

chmod +x local/scripts/deploy-swarm.sh

ステップ 2 — クラスタの初期化（Swarm のみ）

Docker Compose を使用する場合はこのステップをスキップしてください。 マネージャーノードで:

docker swarm init --advertise-addr <MANAGER_IP>

出力された docker swarm join コマンドをコピーします。各追加ノードで次を実行します:

docker swarm join --token <TOKEN> <MANAGER_IP>:2377

マネージャーから各ノードにラベル付けします。docker node ls でノード ID を一覧表示できます:

docker node update --label-add cpu=true <node-id>   # CPU services (API, NATS, etc.)
docker node update --label-add gpu=true <node-id>   # Standard GPU workers

MIG を使用する場合: MIG が有効なノードに mig=true ラベルと、MIG インスタンスの UUID（そのノード上の nvidia-smi -L から取得）をカンマ区切りで指定したリストを付与します。MIG ノードには gpu=true を付けないでください。

docker node update --label-add mig=true <node-id>
docker node update --label-add 'mig.uuids=MIG-<uuid1>,MIG-<uuid2>' <node-id>

標準 GPU ノードと MIG ノードが混在するクラスタもサポートされており、デプロイスクリプトが両方のスケジューリングを自動的に処理します。

ステップ 3 — 環境の設定

デプロイ前に環境変数を設定します。local/ 配下の .env ファイル（local/.env.example 参照）を使用するか、シェルでエクスポートします。

export IMAGE_REGISTRY="YOUR_IMAGE_REGISTRY"
export RELEASE_TAG="YOUR_RELEASE_TAG"
export MODEL_NAME="YOUR_MODEL_NAME"

export CONTAINER_KEY_FILE=/path/to/cartesia-api-key
export GCS_SA_FILE=/path/to/service-account.json

# Optional
export WORKER_REPLICAS=1
export WORKER_CAPACITY=4
export BUCKET_NAME=""
export CLUSTER_NAME="cartesia-compose"   # or "cartesia-swarm"
export USE_MIG=0                         # set to 1 to enable MIG mode (or pass --mig to the deploy script)

各変数の詳細は設定を参照してください。

ステップ 4 — デプロイ

Compose
Swarm

リポジトリのルートから:

# Standard deployment
./local/scripts/deploy-compose.sh

# With MIG support (auto-detects MIG instances via nvidia-smi)
./local/scripts/deploy-compose.sh --mig

--mig を使用すると、スクリプトは nvidia-smi から MIG インスタンスの UUID を自動検出し、スライスごとのワーカー設定を生成し、標準ワーカーをゼロにスケールします。

マネージャーノードで:

# Standard deployment
./local/scripts/deploy-swarm.sh

# With MIG support (reads UUIDs from node labels)
./local/scripts/deploy-swarm.sh --mig

このスクリプトは以下を行います:

ノードがラベル付けされていることを確認します（されていない場合は手順を示して失敗します）。
キーファイルとサービスアカウントファイルから暗号化された Swarm シークレットを作成します。
すべてのサービスをデプロイします。--mig を使用した場合、MIG インスタンスごとに専用のワーカーサービスが作成され、それぞれが対応するノードに固定されます。

TTS ワーカーは GPU メモリへのモデルロードに数分かかります。この間、コンテナが healthy 表示でも TTS リクエストはエラーを返します。ready シグナルを待ってください:

Compose
Swarm

cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml logs -f tts-worker 2>&1 | grep -i "ready"

docker service logs cartesia_tts-worker -f 2>&1 | grep -i "ready"

ステップ 5 — 検証

サービスが稼働しているか確認します:

Compose
Swarm

cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml ps

MIG を有効にしてデプロイした場合、各ワーカーが正確に 1 つの MIG デバイスを認識していることを確認します:

# List all running services (MIG workers appear as tts-worker-mig-0, tts-worker-mig-1, etc.)
cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml -f docker-compose.mig.generated.yaml ps

docker stack services cartesia

MIG を有効にしてデプロイした場合、MIG ワーカーサービスがスケジュールされて動作しているか確認します:

docker stack ps cartesia --filter 'name=cartesia_tts-worker-mig'

API をテストします:

curl http://localhost:5000/status

TTS をテストします:

curl -s -X POST "http://localhost:5000/tts/bytes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -d '{
    "model_id": "sonic-3.5",
    "transcript": "Hello from Cartesia.",
    "voice": {"mode": "id", "id": "00510a15-4216-4fdc-a0ab-05d74cd9f795"},
    "language": "en",
    "output_format": {"container": "mp3", "sample_rate": 44100, "bit_rate": 128000}
  }' --output test.mp3

トラブルシューティング

Compose
Swarm

cd local

docker compose -f docker-compose.base.yaml -f docker-compose.yaml logs api
docker compose -f docker-compose.base.yaml -f docker-compose.yaml logs tts-worker

# Restart everything
docker compose -f docker-compose.base.yaml -f docker-compose.yaml down
docker compose -f docker-compose.base.yaml -f docker-compose.yaml up -d

API が no servers available for connection（NATS が未準備）で終了した場合は、スタック起動後に API を再起動します:

cd local && docker compose -f docker-compose.base.yaml -f docker-compose.yaml up -d && docker compose -f docker-compose.base.yaml -f docker-compose.yaml restart api

docker stack ps cartesia --no-trunc

docker service logs cartesia_api
docker service logs cartesia_tts-worker

# Restart the stack
docker stack rm cartesia
sleep 10
cd local && docker stack deploy --with-registry-auth -c docker-compose.base.yaml -c docker-compose.swarm.yaml cartesia

設定

デプロイスクリプト実行前に以下の環境変数を設定します。IMAGE_REGISTRY、RELEASE_TAG、MODEL_NAME はオンボーディング時に Cartesia から提供されます。イメージを自身のレジストリにミラーリングしている場合は、IMAGE_REGISTRY にミラーの URL を指定してください。

必須

変数	説明
`IMAGE_REGISTRY`	コンテナイメージレジストリの URL（Cartesia レジストリまたはミラー）。
`RELEASE_TAG`	デプロイ対象リリースのイメージタグ（リリースごとに更新）。
`MODEL_NAME`	ワーカーイメージ用の TTS モデル識別子。
`CONTAINER_KEY_FILE`	Cartesia API キーを含むファイルへのパス。
`GCS_SA_FILE`	GCS サービスアカウント JSON ファイルへのパス。

オプション

変数	デフォルト	説明
`WORKER_REPLICAS`	`1`	TTS ワーカーコンテナの数。Compose では、ホスト上の GPU 数に設定します。Swarm では、GPU ノード数に合わせてスケールします。
`WORKER_CAPACITY`	`4`	ワーカーあたりの最大同時 TTS リクエスト数。GPU メモリ不足の場合は下げてください。
`BUCKET_NAME`	(空)	マイグレーション／LoRA 用の GCS バケット。空のままにすると同期が無効になります。
`CLUSTER_NAME`	`cartesia-compose` / `cartesia-swarm`	ログとメトリクス用の識別子。
`GCS_SYNC_INTERVAL`	`300`	GCS 同期間隔（秒）。
`USE_MIG`	`0`	`1` に設定すると MIG モードを有効化します。

​前提条件

​GPU ランタイムの確認

​ステップ 1 — シークレットの準備

​ステップ 2 — クラスタの初期化（Swarm のみ）

​ステップ 3 — 環境の設定

​ステップ 4 — デプロイ

​ステップ 5 — 検証

​トラブルシューティング

​設定

​必須

​オプション

前提条件

GPU ランタイムの確認

ステップ 1 — シークレットの準備

ステップ 2 — クラスタの初期化（Swarm のみ）

ステップ 3 — 環境の設定

ステップ 4 — デプロイ

ステップ 5 — 検証

トラブルシューティング

設定

必須

オプション