ドキュメント

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 13.0 の 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 専用の設定は下で示します。

変数 既定値 目的
LAYA_DEVICE cpu / cuda ベース / GPU 構成が選ぶデバイス
LAYA_CUDA_AMP 未設定(チェックポイントの amp_dtype) CUDA フォワードで fp16/float16 または bf16/bfloat16。それ以外の値は無視される。見た目だけの話ではない:README のしきい値の節では、fp16 が 1 つも argmax を反転させない同値集合で、bf16 が 864 個中 3 個を反転させると測定されている
LAYA_CPU_AMP 未設定 bf16 または bfloat16 で CPU フォワードが bf16 になる。それ以外の値は fp32 のまま。fp16 の綴りでも有効にはならない:CPU autocast には fp32 を上回る fp16 の高速パスがなく、このデバイスで core が提供する低精度は bf16 だけである
LAYA_MODEL auto Router の別名:auto、english、multilingual、typed-decisions
LAYA_MODEL_PATH 未設定 コンテナ内の互換チェックポイントのパス
LAYA_REVISION 未設定 すべてのチェックポイントのダウンロードに使う Hub の commit、branch、tag。または reviewed で laya/revisions.py のレビュー済み SHA。revision= 引数は引き続き優先される
LAYA_REQUEST_FILE 同梱のリクエスト コンテナ内の JSON リクエストのパス
OMP_NUM_THREADS 4 CPU スレッド数。使用可能なコア数の範囲に収めてください
HF_TOKEN / HF_TOKEN_FILE 未設定 任意の Hugging Face 資格情報
LAYA_API_KEY / LAYA_API_KEY_FILE 未設定 laya-serve のみ: Authorization: Bearer <key> を必須にする
LAYA_PORT 8000 laya-serve のみ: コンテナポート、およびそのために公開するホストポート
HF_HUB_OFFLINE 0 1 はキャッシュ済みのチェックポイントだけを使う
HF_HOME /home/laya/.cache/huggingface キャッシュパス。下のマウント要件を参照
LAYA_CACHE_VOLUME プロジェクトのモデルキャッシュ Compose のみ: 名前付きキャッシュボリューム
LAYA_GPU_ID 0 Compose のみ: NVIDIA のデバイスインデックスまたは UUID
LAYA_TORCH_INDEX cu130(CUDA)/ cpu Compose ビルド: PyTorch の wheel インデックス。cu126 も固定した torch を同梱し、cu128 は同梱しません
LAYA_TORCH_VERSION 2.14.0 Compose ビルド: 固定する PyTorch のバージョン

Compose は実行時の変数を転送しますが、HF_HOME は除きます —— これは固定のキャッシュマウントと 足並みを揃えたままです。また LAYA_MPS_AMP_MIN_ROWS(MPS の行数ゲート)も除きます。ここにある どのイメージもそこに到達できず、ここにあるどのコンテナも MPS を選べないからです。docker run や 自分の Compose ファイルで HF_HOME を上書きする場合は、UID 10001 が書き込める対応するマウントを 用意してください。直接の Docker ビルドは --build-arg TORCH_INDEX=cu130 で 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 とも併用できます。ファインチューニング済みチェックポイントは、 それに頼る前にホールドアウトした例で評価してください。

ModelScope からのモデル

ホストが huggingface.co に到達できないときは、チェックポイントを ModelScope から取得し、ビルド時にイメージへ焼き込めます。どの チェックポイントを選ぶかは 1 つの引数で指定し、既定では多言語版になります。Compose の override はプリフェッチ引数を両方のサービスに追加し、コンテナを Hub から切り離します:

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

NVIDIA の場合は up の前に -f compose.cuda.yaml を追加します。これは両方のサービスに 対して自分の引数を繰り返すので、2 つの override の順序は関係ありません。素の Docker は 引数を直接受け取ります:

docker build --build-arg MODELSCOPE_MODEL=multilingual \
  -t laya:local .
docker run --rm -e HF_HUB_OFFLINE=1 -p 127.0.0.1:8000:8000 laya:local laya-serve

以前にこれを実行したことのあるホストには、1 つ前提があります。焼き込まれた重みはイメージ内の $HF_HOME/hub、つまり compose.yaml が model-cache ボリュームをマウントするキャッシュ ディレクトリ(/home/laya/.cache/huggingface)の下に置かれ、Docker が名前付きボリュームを イメージからシードするのはそのボリュームが空のときだけです。Hub ベースのクイックスタートから 残ったボリュームは古い Hub スナップショットを保持しており、再シードされることはなく、焼き 込まれた重みはその背後で見えないままです:ローダーは refs/main を古い Hub コミットに解決 し、コンテナはすでにダウンロード済みの重みで答えます。まるで再ビルドが何も変えなかったかの ように。デプロイを空のキャッシュボリュームに向けてください —— 同じ Compose ファイルと同じ LAYA_CACHE_VOLUME で docker compose down --volumes を実行するか、新しいボリュームには LAYA_CACHE_VOLUME=<name> を使います。HF_HUB_OFFLINE=1 では、欠落または食い違う ref は フォールバックするネットワークのないロード失敗になりますが、前提は同じです。

docker/prefetch_modelscope.py は modelscope.cn 上のリポジトリを一覧し、チェックポイント自身のファイル —— laya/agent.py が Hub に要求するのと同じ集合なので、兄弟チェックポイントは取得されません —— をダウンロード し、snapshot_download がスナップショットを配置するのと同じ形でイメージの hub キャッシュに 書き込みます。ほかは何も変わりません:Agent、laya-serve が構築する Router、 laya.cli、そして各インテグレーションは自分の repo id を保ち、焼き込まれたスナップショット に解決するので、この方法でビルドしたコンテナはネットワークを一切必要としません。各ファイル のサイズは、スナップショットが公開される前にリポジトリが報告する値と照合され、リポジトリが 公開していれば SHA-256 も照合されます。サイズかダイジェストが一致しないとビルドは失敗します。 ダイジェストを公開しないリポジトリではサイズだけの検査になり、これは同じサイズのすり替えを 検出できません。

変数 既定値 目的
MODELSCOPE_MODEL multilingual(Compose)。Dockerfile では空 焼き込むチェックポイント:multilingual、english、typed-decisions、all。空はプリフェッチなしでイメージは変わらない
MODELSCOPE_REVISION master 焼き込む ModelScope のブランチ、タグ、コミット
HF_HUB_OFFLINE Compose の override で 1 1 は Hub に一切接続せず、焼き込まれたコピーを提供する

型はバンドルされたリポジトリ内のそのチェックポイントのパスに展開され、これは Router と ワンショットのクイックスタートが既定でロードするものなので、ある型を指定したビルドはそれ以上 変更なしにそれを提供します:

MODELSCOPE_MODEL=english docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve
MODELSCOPE_MODEL=all docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve

all は家族全体で、約 2.4 GB の重みです。この override は LAYA_MODELS=multilingual も 設定します。既定のリストで LAYA_PRELOAD=1 を使うとすべてのチェックポイントを構築しようと し、焼き込まれていない最初のもので失敗するからです。もっと焼き込むときは LAYA_MODELS を 焼き込んだリストに設定し、デプロイが本当に家族全体を提供するときは MODELSCOPE_MODEL=all を設定します。

複数の型を同時に指定できます —— MODELSCOPE_MODEL="english multilingual" は両方を焼き込み、 約 1.5 GB です —— これは通常、提供用イメージが求めるものです:Router は英語と多言語の チェックポイントを自分で選び、与えられていないものはログの does not contain 'rl_agent_config.json' とともに 500 inference failed を返します。同じ リポジトリを共有するチェックポイントは常に 1 つのスナップショットに焼き込まれます。キャッシュ されたリビジョンは単一のディレクトリに解決されるからで、ルートのチェックポイントと各 サブフォルダーの両方がそこに入ります。

型だけでなく、この引数は repo[:subfolder] 形式の指定も受け付けます。カンマまたは空白区切り で、ミラーの単独リポジトリ (laya、 laya-multilingual、 laya-typed-decisions) や、ファインチューニング済みチェックポイントを焼き込むのはこの方法です。単独リポジトリは Agent("convaiinnovations/laya-multilingual") が直接ロードするものです;Router の既定は バンドルされたパスなので、提供用イメージが通常求めるのは型です。

ピンと来歴について 2 つの詳細があります。ビルドはスナップショットが鍵とするコミット、つまり 焼き込まれたリビジョンの先端を出力します —— その SHA を revision= または LAYA_REVISION として渡せば、ロードを焼き込まれたものに正確に固定できます。ミラーリポジトリは複数の アップロードのファイルを保持しうるので、その先端が唯一存在するリポジトリ全体の鍵です。Hub 側 のピンはミラーのスナップショットを記述しません:reviewed は Hugging Face のコミットを 名指しし、SHA-256 ダイジェストのマップは Hub の成果物ハッシュを鍵とするので、どちらもここでは 当てはまらず、ミラーのスナップショットにはダイジェストのピンも存在しません。ビルドはすでに、 ミラーが報告するサイズと一致しないダウンロードを拒否します —— ミラーが公開していれば ダイジェストも同様です —— ただしこれはミラーのメタデータとの整合性を検査するもので、独立に ピンされたダイジェストではありません。重みは引数が名指しするミラーアカウントから来るので、 それはデプロイが下すべきサプライチェーンの判断そのものです。

開発と後片付け

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 はどちらの場合も認証を必要としないので、下の ヘルスチェックはそのまま機能します。キーを設定すると、未認証の呼び出し元には {"status": "ok"} と答え、bearer を必要とする checkpoint、revision、device の各フィールド は伏せます。

サービスには /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 サービスにのみ当てはまります。

変数 既定値 効果
LAYA_HOST 0.0.0.0 コンテナ内のバインドアドレス
LAYA_PORT 8000 コンテナポート、およびそのために公開するホストポート
LAYA_BIND_ADDRESS 127.0.0.1 ポートを公開するホストアドレス
LAYA_PRELOAD 0 1 は初回リクエスト時ではなく起動時にすべてのチェックポイントを構築
LAYA_MODELS (すべて) プリロードするカンマ区切りの一覧:english,multilingual,typed-decisions
LAYA_THREADS OMP_NUM_THREADS torch の演算内スレッド数を制限。物理コア数以下に保ってください
LAYA_AUTO_TASK 0 1 は router が typed-decisions に自動的に到達できるようにする
LAYA_DEFAULT_MODEL multilingual 言語の手がかりがない state がフォールバックするチェックポイント(文字がまったくない、または識別するには短すぎるラテン文字)。主に英語のトラフィックなら english を設定します。解決できない名前は、誰も求めていない構成を提供するのではなく、起動時にコンテナを停止します
LAYA_EXTRA_MODELS (なし) 同梱のチェックポイントに加えて追加のチェックポイントを登録する JSON オブジェクト {name: source}:文字列としての Hub リポジトリ ID かローカルのチェックポイントディレクトリ、または ["repo", "subfolder"] のペア
LAYA_IDLE_UNLOAD_SECONDS 0 この秒数だけアイドルが続いた常駐チェックポイントをアンロードします。次のリクエストでそのチェックポイントを再び読み込みます。ゼロはアンロードを無効にします
LAYA_MAX_LOADED 2 常駐させるチェックポイント。LAYA_AUTO_TASK は 3 つ目を必要時に到達可能にし、ルーティングが選ぶ数より低い上限は切り替えごとに 1 つを再構築させる
LAYA_MAX_CONCURRENT 16 同時に受け入れるリクエスト数。以降のものは 503 を受け取る(解析できない値、または正でない値は 16 にフォールバックする)
LAYA_LOG_LEVEL info uvicorn のログレベル
LAYA_API_KEY (なし) 設定すると Authorization: Bearer <key> を必須にする
LAYA_ROOT_PATH (空) リバースプロキシの背後で FastAPI が使う公開 URL プレフィックス。プロキシは転送前にそれを取り除くべき
LAYA_MAX_TOKEN_BUDGET 8192 リクエストごとの max_len と head_max_len の上書きに対する上限
LAYA_MAX_BATCH_TOKENS 131072 1 回の /v1/systemone/batch フォワードパスがまとめて処理できる token 数(states × 質問数 × 行幅)。これより大きいバッチは拒否されず、複数のパスに分割されます
LAYA_JEV_STRICT 0 1 は厳格な Jev のワイヤ契約(ルートの routing なし、答えごとの action / answer_confidence なし、縮小した usage)を厳格な Jev クライアント向けに提供します
LAYA_SHA256_DIGESTS (なし) チェックポイントを解析する前に検査する JSON ダイジェスト:すべてのチェックポイントに {artifact: digest}、またはチェックポイントごとに {model: {artifact: digest}}。セキュリティ を参照

たとえば、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