tao-run-inference-service

TAO 推論マイクロサービス

スタンドアロンでインストールする場合は？ このセッションが TAO skill bank プラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前チェック、認証情報、スキル間の検出）。

手順

推論サービスを起動するには：

1. 必要な入力を収集し（セクション 1）、コンテナイメージを解決します（セクション 2）。
2. ジョブペイロードと内部コマンドを作成します（セクション 3〜4.1）。references/code-templates.yaml → job_payload_builder を使用してください。
3. skills/platform/<platform>/SKILL.md を読み、コンテナを起動します（セクション 4.2）。
4. サービスレジストリを書き込み、準備状況をポーリングします（セクション 4.3）。references/code-templates.yaml → registry_write.<platform> および readiness_check を使用してください。

推論リクエストを送信するには：

1. セクション 6.0 に従って、リクエストを受け取るサービスを特定します（job_id、network_arch、または複数のサービスが実行中の場合はユーザーの明示的な選択によって決定します。複数のサービスが存在する場合、"latest" を黙ってデフォルトとして使用してはいけません）。次に、解決した job_id を使って references/code-templates.yaml → request.registry_read からエンドポイントを読み取ります。
2. リクエスト本文を作成する前に、vLLM 形式のサンプリングパラメーターについてユーザーに確認します（セクション 6.1）。 max_tokens、top_p、temperature（およびアーキテクチャごとの追加項目）をデフォルト値とともに提示します。それぞれについて、ユーザーが値を変更するか、デフォルトを受け入れるために指定を省略できるようにします。デフォルト値を黙って使用してはいけません。
3. セクション 6.2 に従って本文を作成して送信し、セクション 6.3 に従ってレスポンスを処理します。

サービスを停止するには： references/code-templates.yaml → stop.registry_read を読み取って job_id を特定し、skills/platform/<platform>/SKILL.md を読んでから、セクション 5 に従います。

参照データ（スキーマ、マッピング、有効な値。手順は含まれません）：

• references/service.yaml — イメージのマッピング、有効な network_arch 名、ジョブペイロードのスキーマ、環境変数名、シークレットの分類。
• references/request.yaml — エンドポイントの定義、リクエストフィールドのスキーマ、レスポンス形式、コード例。
• references/code-templates.yaml — ペイロードの作成、レジストリへの書き込み、準備状況の確認、停止／リクエストフローの Python テンプレート。

---

シークレットのルール（このスキルで生成されるすべてのコードブロックに適用）

プロンプトにシークレット値を入力するようユーザーに求めてはいけません。 シークレット値ごとに、次の手順に従います。

1. 設定する環境変数をユーザーに伝えます。シェルで export HF_TOKEN=... を実行するか、ユーザーが承認した環境ファイルに KEY=value の行を記述し、set -a; source /path/to/.env; set +a で読み込みます。
2. そのようなファイルを表示、cat、または Read してはいけません。存在の確認だけを行います：[ -n "$HF_TOKEN" ] && echo SET || echo UNSET
3. os.environ["VAR_NAME"] で読み取るコードを生成します。値をハードコード、補間、または入力させてはいけません。

シークレット環境変数（全リストは references/service.yaml → secrets_handling を参照）： HF_TOKEN、WANDB_API_KEY、CLEARML_API_ACCESS_KEY、CLEARML_API_SECRET_KEY、TAO_API_KEY、TAO_USER_KEY。

プロンプトで収集しても安全な情報： network_arch、model_path、num_gpus、プロンプトテキスト、WANDB_* 設定 URL、CLEARML_*_HOST URL。

---

1. ユーザーから収集する情報

入力	役割
network_arch	コンテナイメージ、アーキテクチャごとの内部コマンド形式（references/service.yaml → container_commands.<network_arch>）、および該当する場合はジョブ JSON の neural_network_name を選択します。references/service.yaml の valid_network_arch_config_basenames にあるベース名と一致する必要があります（例：cosmos-rl、cosmos-predict2.5）。
model_path	学習済みモデルのチェックポイントです。有効な形式は、hf_model://<org>/<model>（HuggingFace Hub — ゲート付きモデルの場合は HF_TOKEN を設定）またはローカルコンテナファイルシステムのパスです。クラウド URI（s3://、gs://、az://）はサポートされていません — 推論サービスにはクラウドストレージへの依存関係がありません。必ずユーザーに確認し、プレースホルダーで代用しないでください。references/service.yaml → model_path_protocols を参照してください。
platform	コンピューティングプラットフォーム：local-docker、brev、slurm、または kubernetes。
num_gpus	デフォルトは 1、推論での最小値は 1 です。

---

2. イメージの解決

各 network_arch には、{network_arch}.config.json という名前のサイドカー設定ファイルがあります。次の手順でコンテナイメージを解決します。

1. {network_arch}.config.json を読み込み、api_params.image（例：COSMOS_RL）を取得します。これにより、references/service.yaml の docker_image_defaults からエントリが選択されます。
2. ホストの環境変数 IMAGE_<KEY> が設定されている場合（例：IMAGE_COSMOS_RL）、パッケージに含まれるデフォルト値を上書きします。
3. model_skill_defaults のキーの場合は、モデル、アクション、バックエンドを指定して scripts/resolve_tao_image.py を呼び出します。これにより、Cosmos モデルスキルの references/skill_info.yaml に記載された正確な Cosmos イメージを使用できます。
4. mapping のキーの場合は、リポジトリルートの versions.yaml に対して、ドット区切りの値を scripts/resolve_versions_key.py で解決します。絶対パスの環境変数による上書き値は、そのまま使用されます。Python の例は references/code-templates.yaml にあります。
5. 設定ファイルが見つからない場合、または api_params.image が空の場合は、COSMOS_RL キーにフォールバックします。

設定ファイルには spec_params.inference.model_path も含まれており、フォルダーとファイルのパスの扱いを決定します。値に部分文字列 folder が含まれる場合、コンテナはパスをディレクトリとして扱います。

---

3. 環境変数（コールバックなし）

env_json をエンコードする前に、これらを env_payload に設定します。TAO_LOGGING_SERVER_URL または TAO_ADMIN_KEY は設定しないでください。

TAO_EXECUTION_BACKEND — プラットフォームと一致させる必要があります。

プラットフォーム	TAO_EXECUTION_BACKEND の値
local-docker	local-docker
brev	local-docker
slurm	slurm
kubernetes	local-k8s

CLOUD_BASED — このスキルでは常に "False" にします（TAO_LOGGING_SERVER_URL へのコールバック投稿を無効にします）。

GPU 環境変数 — プラットフォームスキルが GPU の注入を自動的に処理しない場合にのみ必要です。

• Tegra / Jetson：NVIDIA_DRIVER_CAPABILITIES=all および NVIDIA_VISIBLE_DEVICES=<ids> とともに --runtime=nvidia を指定します。
• 標準の x86 + nvidia-container-toolkit：Docker の device_requests を使用します。これはプラットフォームスキルが処理します。

---

4. プラットフォーム間での実行

ジョブのペイロードと内部コマンド（セクション 1～3）はプラットフォームに依存しません。各プラットフォームについて、実行コードを生成する前に、事前チェックと認証情報を確認するため skills/platform/<name>/SKILL.md を読んでください。

4.1 内部コマンドをビルドする（アーキテクチャごと）

内部コマンドの形式は network_arch ごとに異なります — 一律のテンプレートはありません。references/service.yaml → container_commands.<network_arch> でアーキテクチャごとのエントリを参照してください。存在しない場合、そのアーキテクチャは未サポートです — 停止して確認してください。references/code-templates.yaml → job_payload_builder.<network_arch> で一致するサブブロックを選択してください。コマンドの先頭に umask 0 && を付け、プラットフォーム間で同一（local-docker、brev、slurm、kubernetes）に保ってください。

アーキテクチャ共通の事項：

• job_id: 新規の uuid.uuid4() — コンテナ名およびレジストリキーになります。
• image: セクション 2 に従って解決します。
• シークレット（access_key、secret_key、HF_TOKEN など）は実行時に環境変数から読み取ります — 決してハードコードせず、ログや標準出力に出力しないでください。

アーキテクチャ固有の注意事項（詳細は references/service.yaml → container_commands を参照）：

• cosmos-rl — 単一の --job '<JOB_JSON>' --docker_env_vars '<ENV_JSON>' ブロブ。json.dumps(...) + shlex.quote(...)。env_payload は TAO_EXECUTION_BACKEND（セクション 3 の表に準拠）、TAO_API_JOB_ID、CLOUD_BASED=False を保持します。推論サービスにはクラウドストレージへの依存はありません。適用される認証情報の環境変数は HF_TOKEN のみです（ゲート付き HuggingFace モデル用）。
• cosmos-predict2.5 — フラグ形式の cosmos_predict inference_microservice start ... --port 8080（setup. プレフィックスなし。tyro.conf.OmitArgPrefixes を使用）。--job/--docker_env_vars は 受け付けられません。model_path を --checkpoint-path（ローカルパス）または --model <registered_key>（hf_model://）に変換してください。クラウド URI は拒否されます。適用される認証情報の環境変数は、ゲート付き HuggingFace モデル用の HF_TOKEN のみです。リクエストごとのパラメータ（prompt、inference_type、num_output_frames、guidance、seed、num_steps、negative_prompt）はリクエスト本文に含め、起動時には指定しません。TAO_EXECUTION_BACKEND/TAO_API_JOB_ID/CLOUD_BASED は使用されないため、省略できます。

4.2 プラットフォームスキルに実行を委任する

skills/platform/<platform>/SKILL.md を読み、手順に従ってコンテナを起動します。

基本パラメーター（全プラットフォーム共通）：

パラメーター	値
image	解決済みのコンテナイメージ（セクション 2）
command	inner — セクション 4.1 で構築したシェル文字列
gpu_count	num_gpus
env_vars	env_payload
ジョブ／コンテナ名	job_id — レジストリから参照できるように、4.1 の UUID と一致させる必要があります
host_port (local-docker、brev)	コンテナのポート 8080 にバインドするホスト側ポート。デフォルトは 8080 ですが、同時に実行するサービスごとに一意である必要があります — 以下のポート割り当てルールを参照してください。

プラットフォーム固有の追加入力：

プラットフォーム	追加入力
local-docker	基本入力以外はありません
brev	instance_id（省略可能 — 既存のインスタンスを再利用する場合）；複数の認証情報／ワークスペースを持つアカウントでは、初回作成時に cloud_cred_id と workspace_group_id も指定します — skills/platform/tao-run-on-brev/SKILL.md を参照してください
slurm	partition と account — SLURM_PARTITION／SLURM_ACCOUNT 環境変数を確認してください。未設定の場合はユーザーに尋ねてください
kubernetes	namespace（デフォルト：default）；image_pull_secret（nvcr.io イメージでは必須）

ポートのバインド（local-docker と brev）： -p <host_port>:8080 を渡せて、コンテナ名が job_id と完全に一致するように、docker run を直接実行してください。

ポート割り当てルール（local-docker と brev、同時に実行するサービスでは必須）： サービスを起動する前に、レジストリ（/tmp/tao-inf-ms-state.json）を読み込み、同じプラットフォーム（brev の場合は同じ instance_id）上のすべての既存エントリーから host_port の値を集めます。その集合に含まれない、8080 から始まる最小の空きポートを選びます。例：host_port = next(p for p in range(8080, 8200) if p not in used_ports)。デフォルトの 8080 が使えるのは、他に実行中のサービスがない場合のみです。これにより、「3 つのサービスを起動し、それぞれ異なる host_url からアクセスできる」ようになります。このルールがない場合、2 番目と 3 番目のサービスは bind: address already in use で失敗します。SLURM と kubernetes は、それぞれのプラットフォームの仕組みで異なるエンドポイントを取得するため、この手順は不要です。

4.3 起動後：サービスレジストリとエンドポイント

プラットフォームからコンテナの実行が確認できたら、ただちにサービスレジストリを書き込みます。レジストリ（/tmp/tao-inf-ms-state.json）は job_id をキーとし、"latest" は常に最後に起動したサービスを指します。

Python テンプレートについては、references/code-templates.yaml → registry_write.<platform> を参照してください。

プラットフォーム	host_url	platform_job_id	書き込み前の追加手順
local-docker	http://localhost:{host_port}	—	なし
brev	http://{brev_ip}:{host_port}	—	brev ls → インスタンスの IP を取得します（リモート VM では localhost は無効です）
slurm	http://localhost:{host_port}	SLURM スケジューラのジョブ ID	Running になるまで待機し、SSH でポートフォワードします：localhost:{host_port}→{node}:8080
kubernetes	http://{external_ip}:8080	k8s のジョブ名	kubectl expose job … --type=LoadBalancer を実行し、外部 IP が割り当てられるまで待機します

レジストリを書き込んだ後、job_id と URL を出力します。

print(f"Inference service started.")
print(f"  Job ID : {job_id}")
print(f"  Arch   : {network_arch}")
print(f"  URL    : {state[job_id]['host_url']}/v1/chat/completions")
print(f"Use this Job ID to send requests or stop the service.")

次に、準備が整うまでポーリングします — references/code-templates.yaml → readiness_check を参照してください。コンテナはバックグラウンドでモデルを読み込みます。200 が返る前にリクエストを送信しないでください。

---

5. 推論サービスの停止

停止する job_id をユーザーに尋ねます。指定がない場合は state["latest"] をデフォルトとして使用し、どの job_id を停止するか確認します。references/code-templates.yaml → stop.registry_read を使ってレジストリを読み込み、続けて skills/platform/<platform>/SKILL.md を読み、そこに記載されたキャンセル／停止の仕組みを使用します。

プラットフォーム	渡す識別子	追加のクリーンアップ
local-docker	job_id_to_stop — コンテナ名	なし
brev	job_id_to_stop — コンテナ名	なし
slurm	entry["platform_job_id"] — SLURM ジョブ ID	pkill -f "ssh.*-L.*{entry['host_port']}"
kubernetes	entry["platform_job_id"] — k8s ジョブ名	kubectl delete svc {entry["platform_job_id"]} -n <namespace>

ここで entry = state[job_id_to_stop] です。停止後、レジストリをクリーンアップします：references/code-templates.yaml → stop.registry_cleanup。

---

6. 推論リクエストの送信

6.0 リクエストを受け取るサービスの解決（必須）

各リクエストは、該当するモデルを実行する特定のサービスにルーティングする必要があります。ルーティングは job_id によって行われます。レジストリにはエントリごとに network_arch が保存されるため、ユーザーが job_id ではなくモデル名を指定した場合は、アーキテクチャによって送信先を解決できます。次のルールを順番に適用します。

1. ユーザーが job_id を明示的に指定した場合 → それを使用します。state に存在することを確認します。
2. ユーザーが network_arch を指定した場合（例：「これを cosmos-rl サービスに送信して」）→ 一致するエントリを検索します：candidates = [j for j, e in state.items() if j != "latest" and isinstance(e, dict) and e["network_arch"] == arch]。
   • 一致がちょうど1件 → それを使用します。
   • 複数一致 → 候補の job_id と started_at をユーザーに確認し、自動選択しないでください。
   • 一致なし → 停止し、そのアーキテクチャのサービスが稼働していないことをユーザーに伝えます。
3. job_id も network_arch も指定されていない場合 → state 内の "latest" 以外のエントリ数を数えます。
   • 稼働中のサービスがちょうど1つ → それを使用します。
   • 2つ以上 → state["latest"] を暗黙にデフォルトとして使用しないでください。全候補（job_id、network_arch、host_url）をユーザーに提示し、明示的な選択を求めます。"latest" ポインターは単一サービスのワークフローで便利に使うためのものであり、複数のサービスが共存する場合のルーティング先ではありません。
   • 0件 → 停止し、先にサービスを起動するようユーザーに伝えます。

解決後、レジストリからエンドポイントを読み込み（references/code-templates.yaml → request.registry_read）、解決済みの job_id を user_provided_job_id として渡します。ユーザーに「job_id=… arch=… url=… に送信します」と確認します。サービスがまだ読み込み中の可能性がある場合は、先に準備状況を確認します（references/code-templates.yaml → readiness_check）。

送信前のクロスチェック： ユーザーが指定したリクエスト本文にアーキテクチャ固有のフィールド（例：guidance ／ num_steps ／ seed ／ negative_prompt → cosmos-predict2.5、必須の image_url ／ video_url コンテンツ項目 → cosmos-rl）が含まれている場合は、state[job_id]["network_arch"] と一致していることを確認します。不一致の場合は処理を停止してユーザーに確認してください。cosmos-predict2.5 用の本文を cosmos-rl サービスに送信すると、コンテナで 4xx／5xx エラーになり、この段階で検出するより診断が難しくなります。

6.1 サンプリングパラメーター — リクエストごとにユーザーに必ず事前確認

リクエスト本文を構築する前に、vLLM 形式のサンプリングパラメーターについて、必ずユーザーに明示的に確認してください。デフォルト値を黙って適用してはいけません。フィールドごとに1つ質問する形式で、次の条件を満たす構造化されたプロンプトを使用してください。

1. 該当するすべてのフィールドについて、型とデフォルト値を示します。
2. フィールドごとにスキップ／デフォルト値の採用を選択できるようにします。値の入力を必須にしてはいけません。
3. すべてのフィールドを1回のやり取りで確認します。

確認後、ユーザーが入力した値はそのまま適用し、スキップされたフィールドにはデフォルト値を代入します。値を独自に作り出したり、黙って上限・下限に合わせたりしてはいけません。

フィールド一覧、デフォルト値、アーキテクチャごとの適用可否： references/request.yaml → chat_completions_request_body（基本のサンプリングフィールド：max_tokens、top_p、temperature）および network_arch_constraints.<network_arch>（cosmos-predict2.5 の guidance／num_steps／seed／negative_prompt など、アーキテクチャごとのオーバーライドと追加フィールド）。アクティブなアーキテクチャでサポート対象外とされているフィールドは、確認せず、リクエスト本文にも含めないでください。

6.2 リクエスト形式

Content-Type: application/json を指定し、タイムアウトを300秒以上に設定して、{BASE_URL}/v1/chat/completions に POST を送信します。本文は OpenAI 互換（vLLM チャット補完）です。すべてのフィールドのスキーマとコンテンツ項目の形式（text／image_url／video_url）については references/request.yaml → chat_completions_request_body を、すぐに実行できる Python と curl のサンプルについては code_examples を参照してください。

制約： 処理されるのは最初のユーザーメッセージのみです。リクエスト本文にシークレット値を含めないでください。ネットワークごとの制約（例：cosmos-rl ではすべてのリクエストに画像または動画を含める必要があります。cosmos-rl は data: URI を受け付けません）については references/request.yaml → network_arch_constraints を参照してください。

6.3 レスポンスの処理

HTTP ステータス	意味	対応
200	成功 — choices[0].message.content に生成されたテキストが含まれます	結果を読み取る
202	サーバーの初期化中、またはモデルの読み込み中です	待ってから再試行する
503	初期化失敗、モデルの読み込み失敗、またはモデルの準備未完了	error.type を確認する：model_not_ready → 再試行する、initialization_error／model_load_error → 諦めてログを確認する
400	JSON 本文がない、または空です	リクエストを修正する
500	推論中に未処理の例外が発生しました	コンテナーログを確認する

202 および 503 の場合、本文には {"error": {"type": "<error_type>", "message": "<reason>"}} が含まれます。エラータイプの文字列については references/request.yaml の container_response_shapes を参照してください。