aiq-deploy

AIQ Deploy スキル

目的

このスキルは、ローカルまたはセルフホスト可能な NVIDIA AI-Q Blueprint サーバーを起動し、aiq-research で使える状態であることを確認するために使用します。

このスキルでは、セットアップ、デプロイ、運用チェック、トラブルシューティング、シャットダウンを担当します。詳細なリサーチ自体は実行しません。デプロイが正常な状態になったら、確認済みのサーバー URL を aiq-research に引き継ぎます。このワークフローは明示的に定義されているため、サポートされているエージェントクライアント間で、デプロイの検証と引き継ぎを繰り返し実行できます。

前提条件

以下が必要です。

• https://github.com/NVIDIA-AI-Blueprints/aiq をクローンまたは更新できること。
• シェルで Git を使用できること。
• 以下のいずれかのデプロイランタイムを用意すること。
  • デフォルトの永続的なローカルデプロイには Docker Engine と Docker Compose v2。
  • ローカルプロセスまたは CLI モードには Python 3.11 以降と uv。
  • ローカルのブラウザー UI 開発モードには Node.js 20 以降と npm。
  • Helm モードには kubectl 1.28 以降、Helm 3.12 以降、Kubernetes クラスターへのアクセス。
• GitHub、NVIDIA がホストするモデルエンドポイント、および選択した検索プロバイダーへのネットワークアクセス。
• チャットの外部に保存された認証情報。ホスト型モデルを使用するには NVIDIA_API_KEY が必要です。Web リサーチには、TAVILY_API_KEY、SERPER_API_KEY、EXA_API_KEY など、サポート対象の検索プロバイダーのキーが少なくとも 1 つ必要です。
• 選択したランタイムに必要なシステムリソース。Docker Compose モードでは、デフォルトで AI-Q バックエンドと PostgreSQL が起動します。ブラウザー UI モードでは、フロントエンド用のポート 3000 も使用します。セルフホスト型のモデルまたは RAG のデプロイには、GPU リソースが必要になる場合があります。

シークレットを書き込む前に、deploy/.env が無視対象であることを確認します。

git check-ignore deploy/.env

想定される出力：deploy/.env または該当する無視ルールです。無視対象でない場合は、ファイルに認証情報を記入する前に作業を中断し、無視ルールを修正してください。

手順

1. AI-Q リポジトリを見つけるか、クローンします。
2. 想定されるリポジトリファイルが存在することを確認します。
3. デプロイモードを選択します。
4. ユーザーのシークレットを上書きせずに deploy/.env を準備します。
5. 選択した方法のランタイム前提条件を確認します。
6. 選択したデプロイを起動します。
7. 基本的な検証を実行します。
8. aiq-research 用に、確認済みの AIQ_SERVER_URL を報告します。
9. 詳細なリサーチの完了検証を任意で実行するか、ユーザーに確認します。

ステップ 1 - AI-Q を見つけるか、クローンする

AI-Q のチェックアウトが見つからない場合は、クローンする前に references/locate-or-clone.md を読んでください。既存のチェックアウトでは、必要なファイルがあることを確認します。

pwd
test -f pyproject.toml
test -f deploy/.env.example
test -d configs

想定される出力：pwd が AI-Q リポジトリのパスを出力し、test コマンドはステータス 0 で終了して何も出力しないこと。

ステップ 2 - デプロイモードを選択する

ユーザーが AI-Q のインストール、デプロイ、セットアップ、または実行を依頼していて、モードを指定していない場合は、次のように質問します。

How do you want to run AI-Q?

1. Skill backend - backend-only service for aiq-research w/o browser UI.
2. CLI - interactive terminal AI-Q.
3. UI - browser AI-Q app with backend and frontend.
4. Custom - choose an existing AI-Q config or review advanced customization docs before deployment.

サービスを起動する前に、ユーザーの回答を待ってください。

Docker Compose、Helm、UI、CLI、Agent Skill バックエンドなど、ユーザーがすでにモードを指定している場合は、この質問をしないでください。詳細なリサーチのリクエストにバックエンドが必要なため aiq-research から引き継がれた場合も、モード全体に関する質問はしないでください。その場合は Agent Skill バックエンドを優先し、必要であれば起動の許可だけを求めてください。

ステップ 3 - 環境とシークレットを準備する

deploy/.env を変更する前に、references/env-and-secrets.md を読んでください。

if [ ! -f deploy/.env ]; then
  cp deploy/.env.example deploy/.env
  echo "created deploy/.env from deploy/.env.example"
fi

ファイルが存在しない場合の想定される出力：created deploy/.env from deploy/.env.example。ファイルがすでに存在する場合の想定される出力：何も出力されず、既存のファイルがそのまま保持されます。

シークレットの値は絶対に表示しないでください。認証情報が不足している場合は、ユーザーに deploy/.env を更新するよう依頼してください。シークレットの値をチャットに貼り付けるよう求めてはいけません。

ステップ 4 - 選択したデプロイパスに振り分ける

ユーザーのリクエストに合った項目を選び、作業を始める前に参照ファイルを読んでください。

ユーザーの意図	参照先
AI-Q のチェックアウトが存在しない、AIQ のインストール、AIQ のクローン、リポジトリの場所の特定	references/locate-or-clone.md
環境の設定、API キーの確認、.env の調査	references/env-and-secrets.md
AI-Q のワークフロー設定の選択、設定ファイルの理解、BACKEND_CONFIG または CONFIG_FILE の設定	references/configs.md
aiq-research 用のバックエンド専用ローカルサーバー、AIQ をエージェントスキルとして使う	references/skill-backend.md
ターミナルアシスタント、CLI のみの実行、Web UI なし	references/terminal-cli.md
コンテナを使わない、ローカル開発での簡単な実行、UI／バックエンドの起動	references/local-web.md
標準の永続的なローカルデプロイ、Docker Compose、コンテナ、PostgreSQL	references/docker-compose.md
Kubernetes、Helm、クラスターへのデプロイ	references/kubernetes-helm.md
基盤となる RAG／FRAG の統合	references/frag.md
基本的なヘルスチェック、簡易スモークチェック、aiq-research への引き継ぎ	references/validation.md
オプションの詳細なリサーチ完了検証	references/end-to-end-validation.md
ログ、異常のあるサービス、ポート競合、設定エラー	references/troubleshooting.md
サービスの停止、再起動、再ビルド、安全なクリーンアップ	references/shutdown.md

ステップ 5 - 検証して引き継ぐ

起動後、references/validation.md を読み、選択したモードに適したチェックを実行してください。標準のローカルバックエンドでは、ヘルスを確認します。

curl -sf http://localhost:8000/health

期待される出力は、サーバーのビルドに応じて、成功を示す JSON のヘルス応答、または成功を示す空の応答です。コマンドが失敗した場合は、references/troubleshooting.md を読み、バックエンドの準備ができたと判断する前に原因を特定してください。

aiq-research には、到達可能な AI-Q サーバー URL が必要です。バックエンドが標準ポートで動作している場合、追加の設定は不要です。

AIQ_SERVER_URL=http://localhost:8000

バックエンドが別の場所で動作している場合は、次の設定をユーザーに案内してください。

export AIQ_SERVER_URL="http://localhost:<PORT>"

ユーザーから依頼された場合、またはデプロイ後の検証プロンプトで確認を得た場合を除き、詳細なリサーチや詳細なリサーチ完了検証には進まないでください。このスキルの成功基準は、レポート生成の品質ではなく、サーバーがデプロイされ、基本的な検証が済んでいることです。

バージョン互換性

重要： このスキルは NVIDIA AI-Q Blueprint バージョン 2.1.0 向けに設計されています。

セマンティックバージョニングの互換性ルール：

Skill version: X.Y.Z
Blueprint version: A.B.C

Compatible IF:
1. A == X (Major versions MUST match)
2. B >= Y (Minor version must be equal or greater)
3. C can be anything (Patch version does not affect compatibility)

例：

• スキルバージョン 2.1.0 は、Blueprint バージョン 2.1.0 と互換性があります。
• スキルバージョン 2.1.0 は、Blueprint バージョン 2.2.0 と互換性があります。
• スキルバージョン 2.1.0 は、Blueprint バージョン 2.1.5 と互換性があります。
• スキルバージョン 2.1.0 は、Blueprint バージョン 3.0.0 と互換性がありません。
• スキルバージョン 2.1.0 は、Blueprint バージョン 2.0.0 と互換性がありません。

Blueprint のバージョンに互換性がない場合：

1. 使用している Blueprint のバージョンに対応する、更新済みのスキルバージョンがないか確認してください。
2. このスキルと互換性のある Blueprint バージョンを使用してください。
3. ユーザーが互換性リスクを了承した場合に限り、変更されている可能性のあるデプロイコマンドや設定名に注意して作業を進めてください。

セキュリティのベストプラクティス

• シークレットの値を表示しないでください。必要な環境変数が設定されているかどうかだけを確認してください。
• 認証情報は deploy/.env または環境変数に保存し、チャットの記録、シェルの履歴、コミット済みのファイル、例示用のコマンドには含めないでください。
• すでに deploy/.env が存在する場合は、上書きしないでください。
• down -v による Docker ボリュームの削除など、破壊的なクリーンアップを行う前に確認してください。
• RAG_SERVER_URL と RAG_INGEST_URL の両方が設定され、到達可能であることを確認しない限り、FRAG の準備ができたと判断しないでください。
• 可能な場合は、自分で検証コマンドを実行してください。

制限事項

• このスキルは AI-Q インフラストラクチャを準備して検証するものであり、詳細な調査レポートの品質を評価するものではありません。
• シークレット値の提供や確認はできません。ユーザーはチャット以外の場所で認証情報を設定する必要があります。
• Helm、FRAG、カスタム設定、セルフホスト型モデルのパスは、ユーザーが管理するインフラストラクチャに依存します。
• Docker ボリュームの削除など、破壊的なクリーンアップにはユーザーの明示的な承認が必要です。

例

例 1：Docker Compose でバックエンドのみの Skill サーバーをデプロイする

test -f deploy/.env || cp deploy/.env.example deploy/.env
git check-ignore deploy/.env
cd deploy/compose
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml config --quiet
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml up -d --build aiq-agent
curl -sf http://localhost:8000/health

期待される出力：

deploy/.env
<docker compose starts aiq-agent and dependencies>
<health endpoint returns a successful response>

Docker、ポート、認証情報、またはヘルスチェックで問題が発生した場合は、再試行する前に references/troubleshooting.md を確認してください。

例 2：デフォルト以外のバックエンド URL を aiq-research に引き継ぐ

export AIQ_SERVER_URL="http://localhost:8100"
curl -sf "$AIQ_SERVER_URL/health"

期待される出力：正常なヘルスレスポンス。その後、aiq-research を呼び出す前に AIQ_SERVER_URL を設定したままにするようユーザーに伝えてください。

参考資料

トピック	ドキュメント
AI-Q の場所の確認またはクローン	references/locate-or-clone.md
環境とシークレット	references/env-and-secrets.md
ワークフロー設定	references/configs.md
Agent Skill バックエンド	references/skill-backend.md
CLI のデプロイ	references/terminal-cli.md
ローカルウェブのデプロイ	references/local-web.md
Docker Compose のデプロイ	references/docker-compose.md
Kubernetes と Helm のデプロイ	references/kubernetes-helm.md
FRAG の統合	references/frag.md
基本的な検証	references/validation.md
エンドツーエンド検証	references/end-to-end-validation.md
トラブルシューティング	references/troubleshooting.md
シャットダウンとクリーンアップ	references/shutdown.md

よくある問題

問題：バックエンドのポートがすでに使用されています

症状：

• Docker Compose でポート 8000 のバインドに失敗します。
• curl -sf http://localhost:8000/health が予期しないサービスに接続するか、失敗します。

原因：

• 別の AI-Q バックエンドまたはローカル開発サーバーがすでに実行されています。
• deploy/.env の PORT が既存のプロセスと競合しています。

解決策：

1. プロセスを特定します：

   lsof -nP -iTCP:8000 -sTCP:LISTEN
   

2. ユーザーの承認を得て競合するプロセスを停止するか、deploy/.env で PORT=8100 などの別のポートを設定します。
3. 選択したデプロイ方法を再起動し、次のコマンドで確認します：

   curl -sf http://localhost:8100/health
   

問題：必要な認証情報がありません

症状：

• インフラストラクチャは起動しますが、モデルを使用するチャットや調査のリクエストが失敗します。
• ログに unauthorized、forbidden、invalid key、または missing provider configuration と表示されます。

原因：

• NVIDIA_API_KEY が未設定または空です。
• ウェブ調査用に、サポートされている検索プロバイダーのキーが設定されていません。

解決策：

1. references/env-and-secrets.md に従い、値を表示せずに設定の有無を確認します。
2. ユーザーに deploy/.env を更新するよう依頼してください。シークレットをチャットに貼り付けるよう求めてはいけません。
3. ユーザーが認証情報を更新した後、references/validation.md を再実行します。

問題：バックエンドは正常ですが、aiq-research と互換性がありません

症状：

• /health は成功しますが、/chat または /v1/jobs/async/agents が失敗します。
• aiq-research が非同期エージェントを利用できないと報告します。

原因：

• 選択した設定が CLI 専用であるか、このスキルが想定するウェブ/API バックエンドを公開していません。
• BACKEND_CONFIG または CONFIG_FILE が誤った AI-Q 設定を参照しています。

解決策：

1. references/configs.md を読み、選択した設定で API が有効になっていることを確認します。
2. デフォルトの Skill バックエンドには、configs/config_web_default_llamaindex.yml を使用します。
3. バックエンドを再起動し、references/validation.md を再実行します。

問題：Docker のクリーンアップで必要なデータが削除される可能性があります

症状：

• トラブルシューティングで docker compose down -v が提案されています。
• ユーザーが保持したいローカル PostgreSQL のジョブデータやチェックポイントデータがある可能性があります。

原因：

• down -v は Docker ボリュームを削除します。
• 設定やイメージの変更には、再ビルドと再起動だけで十分なことがよくあります。

解決策：

1. references/shutdown.md にある通常の再起動を優先します。
2. ボリュームを削除する前に、明示的な承認を求めます。
3. クリーンアップ後、選択した方法でデプロイと検証を再実行します。