Docker クイックスタート

Docker クイックスタート

ホストに Python や PyTorch をインストールせずに SDK を実行します。CPU のクイックスタートでは 8 GB のメモリと 10 GB の空きディスクを用意し、Docker Engine か Docker Desktop、および Compose v2 以降を入れてください。

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

docker compose run --build --rm laya

これはチェックアウトをビルドし、CPU 上でサンプルリクエスト を実行して、choice、score、noul を含む JSON を出力します。最初のリクエストで、選ばれた公開 の Hugging Face チェックポイントをダウンロードします。アカウントは不要です。初回のダウンロード には数分を見込んでください。重みは名前付きボリュームに残ります。以降の実行は docker compose run --rm laya を使います。

予測と信頼度は、自分のワークロードで評価する必要があります。 ベンチマークの制限 を参照して ください。

ARM64 ホスト、DGX Spark、Apple Silicon については、 ARM64 と DGX Spark のコンテナ を参照してください。

NVIDIA GPU / CUDA

互換性のある NVIDIA ドライバをインストールし、 NVIDIA Container Toolkit で Docker を設定します。GPU イメージは PyTorch CUDA 12.8 の wheel を使います。GPU の計算能力と ドライバを PyTorch の対応ビルド と照らし合わせて確認 してください。古いカードは別のビルドが必要なことがあります。CUDA のレイヤーには追加のディスク 容量を見込んでください。必要な VRAM は、チェックポイント、バッチサイズ、入力長に依存します。

docker compose -f compose.yaml -f compose.cuda.yaml run --build --rm laya

この override は GPU 0 を選び、既定で LAYA_DEVICE=cuda になります。LAYA_GPU_ID を別の ホストインデックスまたは UUID に設定してください。その GPU はコンテナ内でデバイス 0 として 見えます。重みをダウンロードせずにアクセスを確認できます：

docker compose -f compose.yaml -f compose.cuda.yaml run --rm laya python -c \
  'import torch; assert torch.cuda.is_available(); print(torch.cuda.get_device_name(0)); print(torch.ones(1, device="cuda").cpu())'

サンプルは、チェックポイントを読み込む前に利用できない CUDA を拒否します。Laya はメモリや推論の エラーの後でも CPU にフォールバックすることがあるので、その警告を確認してください。CPU と CUDA の構成を切り替えるときは再ビルドしてください。

イメージは TORCH_DISABLE_NATIVE_JIT=1 を設定します。これがないと PyTorch 2.14 は一部の eager CUDA 演算を Triton カーネルに置き換え、初回の推論時にそれらをコンパイルします。それには slim イメージが持たない C コンパイラが必要で、コンテナはヘルシーと報告したうえで毎リクエストが失敗 します（#365）。標準のカーネルは同じ答えを同じレイテンシで返します。ベアメタルのインストールで predict が Failed to find C compiler で失敗する場合も、同じ変数を設定してください。

これは Compose の GPU 予約 を使います。 Windows には Docker Desktop が対応する WSL2 の GPU 設定が必要です。Apple MPS、AMD/ROCm、Intel GPU のコンテナはこのクイックスタートの対象外です。別のバックエンドを構成して検証しない限り、CPU を使ってください。

設定

Compose の変数は、シェル、ローカルの .env ファイル、またはサービスの environment ブロック で設定します。.env にシークレットをコミットしないでください。実行時の変数は docker run -e でも使えます。Compose 専用の設定は下で示します。

Compose は実行時の変数を転送しますが、HF_HOME は除きます —— これは固定のキャッシュマウントと 足並みを揃えたままです。また LAYA_MPS_AMP_MIN_ROWS（MPS の行数ゲート）も除きます。ここにある どのイメージもそこに到達できず、ここにあるどのコンテナも MPS を選べないからです。docker run や 自分の Compose ファイルで HF_HOME を上書きする場合は、UID 10001 が書き込める対応するマウントを 用意してください。直接の Docker ビルドは --build-arg TORCH_INDEX=cu128 で PyTorch を選びます。 実行時の -e はインストール済みの wheel を変えられません。

LAYA_MODEL=english OMP_NUM_THREADS=2 docker compose run --build --rm laya

docker build -t laya:local .
docker run --rm -e LAYA_MODEL=english -e OMP_NUM_THREADS=2 \
  -v laya-model-cache:/home/laya/.cache/huggingface laya:local

自分のリクエストを使う場合：

docker compose run --rm --volume "$PWD/request.json:/inputs/request.json:ro" \
  --env LAYA_REQUEST_FILE=/inputs/request.json laya

リクエスト、チェックポイント、シークレットファイルのマウントを含む、コメント付きの構成については、 compose.example.yml を参照してください：

docker compose -f compose.yaml -f compose.example.yml run --build --rm laya

NVIDIA GPU では run の前に -f compose.cuda.yaml を追加します。この例は compose.yaml の override なので、キャッシュとイメージの設定は 1 か所に収まります。

シークレットファイル

HF_TOKEN_FILE は起動時にマウントされた UTF-8 ファイルを読み、前後の空白を取り除き、 HF_TOKEN より優先されます。読めない、空、または不正なファイルは、中身を出力せずに起動を止め ます。ファイルは UID 10001 から読めなければなりません。_FILE は対応するシークレットにだけ 当てはまり、すべての設定に当てはまるわけではありません。

HF_TOKEN_PATH がチェックアウトの外にある既存のホストファイルを指す場合：

docker compose run --rm --volume "$HF_TOKEN_PATH:/run/secrets/hf_token:ro" \
  --env HF_TOKEN_FILE=/run/secrets/hf_token laya

Docker のシークレットや Kubernetes の Secret ボリュームでも同じファイルを供給できます。値は起動 時にプロセスの環境に読み込まれます。ファイルを変えたら再起動してください。token をビルド引数に 使ったり、イメージに焼き込んだりしないでください。公開チェックポイントに token は不要です。

ファインチューニング済みチェックポイント

このイメージは推論を実行します。ファインチューニングはその外で行います —— ファインチューニング用ノートブック は Kaggle の無料の 2xT4 GPU 上でループ全体を回し、このイメージが提供できるチェックポイントを エクスポートします。学習インターフェースについての背景と未解決の問いは #4 と #26 にあります。

LAYA_CHECKPOINT_PATH に、rl_agent_config.json、model.safetensors、および対応する tokenizer ファイルを含むホストの絶対ディレクトリを指定します：

docker compose run --rm --volume "$LAYA_CHECKPOINT_PATH:/models/custom" \
  --env LAYA_MODEL_PATH=/models/custom laya

ローダーが tokenizer の設定を更新することがあるので、UID 10001 が書き込める作業用コピーを 使ってください。LoRA アダプタだけでは完全なチェックポイントになりません。LAYA_MODEL_PATH を 設定するときは LAYA_MODEL=auto のままにしてください。明示的な別名とローカルパスは同時に使え ません。ローカルパスの応答は Agent からのもので、Router の routing メタデータはありません。 これらの設定は CUDA の override とも併用できます。ファインチューニング済みチェックポイントは、 それに頼る前にホールドアウトした例で評価してください。

開発と後片付け

docker compose run --rm laya python で Python プロンプトを開きます。重みをダウンロードせずに、 既存のルーティング・criteria のチェックとシークレットファイルのテストを自分のチェックアウトに 対して実行するには：

docker compose run --rm --volume "$PWD:/workspace:ro" --workdir /workspace laya \
  sh -ec 'python tests/test_router.py; python tests/test_criteria.py; python tests/test_docker_entrypoint.py'

ソースや同梱のサンプルを変えた後は --build で再ビルドします。イメージは UID/GID 10001 として 実行されます。新しい名前付きボリュームはイメージのキャッシュディレクトリの所有権を引き継ぎます。 ホストのディレクトリはその UID から書き込める必要があります。tokenizer の互換性更新のために、 モデルキャッシュは書き込み可能に保ってください。

--rm は完了したコンテナを削除します。docker compose down はキャッシュを残します。 ダウンロード済みの重みを削除するには、同じ Compose ファイルと LAYA_CACHE_VOLUME 設定を 使って docker compose down --volumes を実行します。次回のリクエストで再度ダウンロードされ ます。別のプロジェクトと共有しているキャッシュは削除しないでください。

HTTP での提供

イメージは laya-serve を同梱しているので、ワンショットのクイックスタートを実行する同じビルド が、Jev 互換の API を提供できます。compose.http.yaml はそれを 2 つ目のサービスとして追加し、 laya はそのままにします：

docker compose -f compose.yaml -f compose.http.yaml up --build laya-serve
curl -s localhost:8000/health
curl -s localhost:8000/v1/systemone -H 'content-type: application/json' \
  --data @examples/docker/request.json

NVIDIA では、CUDA の override を追加します。laya-serve は別のサービスで、laya への override は決してそこに届かないため、この override はビルド引数とデバイス予約を laya-serve 向けに 繰り返します：

docker compose -f compose.yaml -f compose.http.yaml -f compose.cuda.yaml up --build laya-serve

up はサービスをフォアグラウンドで動かし続けます。-d でデタッチします。重みはクイックスタート と同じ名前付きの model-cache ボリュームに入るので、クイックスタートを実行した後の提供は、 チェックポイントがすでにディスク上にある状態で始まります。停止は docker compose ... down で、 同じ Compose ファイルを使います。

ポートは 127.0.0.1 でのみ公開されます。API は LAYA_API_KEY を設定するまで認証がないので、 LAYA_BIND_ADDRESS=0.0.0.0 で公開する前にキーを設定し、リモートのクライアントには前面に TLS リバースプロキシを置いてください。/health はどちらの場合も認証を必要としません。

サービスには /health のヘルスチェックがあります。サーバーは待ち受けを始める前にプリロード するので、LAYA_PRELOAD=1 ならヘルシーなコンテナはチェックポイントが読み込み済みです。 docker compose ... up -d --wait laya-serve はヘルシーになると戻ります。

/health は device を、常駐チェックポイントが実際に計算しているデバイスとして報告します。 これは LAYA_DEVICE が要求したものとは限りません。得られない GPU を求めるチェックポイントは、 黙って CPU にフォールバックし、それでも正しく答えます。checkpoint_devices は読み込み済みの各 チェックポイントを名指しし、device_is_preference は何も常駐していない間だけ true です。これに より、GPU を静かに失ったデプロイは、自分の構成をそのまま繰り返すのではなく、そう報告します。

サーバー設定

これらは laya-serve サービスにのみ当てはまります。

たとえば、API を /laya の下で公開するときは LAYA_ROOT_PATH=/laya を設定します。プロキシは コンテナへ転送する前にそのプレフィックスを取り除く必要があります。この設定は FastAPI が生成する URL を更新するもので、内部の /health や /v1/systemone のルートは変えません。

LAYA_PRELOAD の既定は、ここではパッケージの既定である 1 ではなく 0 です。プリロードすると 初回起動で 3 つすべてのチェックポイントをダウンロードするからです。長時間動かすデプロイでは 1 に設定し、最初のリクエストがビルドのコストを払わないようにしてください。

LAYA_PORT は公開するホストポートとサーバーがバインドするポートの両方を設定するので、この 2 つ がずれることはありません。サービスを移すには 1 か所を変えるだけです：

LAYA_PORT=9000 docker compose -f compose.yaml -f compose.http.yaml up --build laya-serve

ファイルからのベアラートークン

LAYA_API_KEY_FILE は起動時に 1 度読まれ、LAYA_API_KEY に移され、サーバーが exec する前に _FILE 変数が削除されます。キーを環境に置くより、こちらを優先してください：

docker compose -f compose.yaml -f compose.http.yaml run --rm \
  --volume "$PWD/laya_api_key:/run/secrets/laya_api_key:ro" \
  -e LAYA_API_KEY_FILE=/run/secrets/laya_api_key \
  --service-ports laya-serve