aiq-deploy

AIQ Deploy Skill

目的

使用此 Skill 來啟動並驗證本機或自建（Self-hosted）的 NVIDIA AI-Q Blueprint 伺服器，供 aiq-research 使用。

本 Skill 負責建置、部署、維運檢查、故障排查與關機等操作。它本身不執行深度研究（deep research）。在部署狀況健康後，請將已驗證的伺服器 URL 移交給 aiq-research。
工作流程保持明確規範，確保部署驗證與移交程序可在支援的 Agent 用戶端之間重複執行。

先決條件

使用者需要具備以下條件：

• 具有複製（clone）或更新 https://github.com/NVIDIA-AI-Blueprints/aiq 的存取權限。
• Shell 環境中可使用 Git。
• 以下其中一種部署執行期環境：
  • 預設本機耐久部署：帶有 Docker Compose v2 的 Docker Engine。
  • 本機程序或 CLI 模式：Python 3.11+ 與 uv。
  • 本機瀏覽器 UI 開發模式：Node.js 20+ 與 npm。
  • Helm 模式：kubectl 1.28+、Helm 3.12+ 以及 Kubernetes 叢集的存取權限。
• 具備存取 GitHub、NVIDIA 託管模型端點（endpoints）以及任何選定搜尋提供者（search provider）的網路連線。
• 金鑰憑證（Credentials）需儲存於聊天視窗之外。使用託管模型需要 NVIDIA_API_KEY；網路研究則至少需要金鑰如 TAVILY_API_KEY、SERPER_API_KEY 或 EXA_API_KEY 等其中一種支援的搜尋提供者金鑰。
• 選定執行期環境所需的系統資源容量。Docker Compose 模式預設會啟動 AI-Q 後端與 PostgreSQL；瀏覽器 UI 模式則會額外使用前端連接埠 3000。自建模型或 RAG 部署可能需要 GPU 資源。

在寫入敏感金鑰前，請先確認 deploy/.env 已被 Git 忽略：

git check-ignore deploy/.env

預期輸出：deploy/.env 或對應的忽略規則。若未被忽略，請先停止並修正忽略規則，再將憑證寫入檔案。

操作說明

1. 定位或複製（clone）AI-Q 儲存庫。
2. 確認預期的儲存庫檔案存在。
3. 選擇部署模式。
4. 準備 deploy/.env，切勿覆蓋使用者的既存金鑰。
5. 檢查所選路徑的執行期先決條件。
6. 啟動選定的部署。
7. 執行基本驗證。
8. 回報已驗證的 AIQ_SERVER_URL 給 aiq-research 使用。
9. 詢問是否要執行選配的深度研究完成度驗證（deep research completion validation）。

步驟 1 - 定位或複製 AI-Q

若尚未檢出（checkout）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 Key、檢視 .env	references/env-and-secrets.md
選擇 AI-Q 工作流設定檔、瞭解設定檔結構、設定 BACKEND_CONFIG 或 CONFIG_FILE	references/configs.md
僅含後端服務的本機伺服器（供 aiq-research 使用）、將 AIQ 作為 Agent Skill	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
基本健康檢查、輕量冒煙測試（smoke check）、移交至 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>"

除非使用者明確要求或確認執行部署後驗證提示，否則切勿自動進入深度研究或深度研究完成度驗證。本 Skill 的成功衡量標準是「成功部署並完成基本驗證的伺服器」，而非報告產生的品質。

版本相容性

**重要事項：**本 Skill 專為 NVIDIA AI-Q Blueprint 版本 2.1.0 設計。

語意化版本（Semantic Versioning）相容性規則：

Skill 版本: X.Y.Z
Blueprint 版本: A.B.C

相容條件：
1. A == X（主版本號 Major MUST 完全一致）
2. B >= Y（次版本號 Minor 必須大於或等於）
3. C 可為任意值（修訂號 Patch 不影響相容性）

範例：

• Skill 版本 2.1.0 與 Blueprint 版本 2.1.0 相容。
• Skill 版本 2.1.0 與 Blueprint 版本 2.2.0 相容。
• Skill 版本 2.1.0 與 Blueprint 版本 2.1.5 相容。
• Skill 版本 2.1.0 與 Blueprint 版本 3.0.0 不相容。
• Skill 版本 2.1.0 與 Blueprint 版本 2.0.0 不相容。

若您的 Blueprint 版本不相容：

1. 檢查是否有與您的 Blueprint 版本匹配的新版 Skill。
2. 使用與此 Skill 相容的 Blueprint 版本。
3. 僅在使用者同意承擔相容性風險時才謹慎繼續；部署命令或設定檔名稱可能已有變更。

資安最佳實踐

• 切勿列印敏感金鑰數值。僅檢查必填的環境變數是否已設定。
• 將金鑰憑證儲存於 deploy/.env 或環境變數中，絕不暴露於聊天紀錄、Shell 歷史紀錄、已版控提交的檔案或範例命令中。
• 當 deploy/.env 已存在時，切勿將其覆蓋。
• 在執行破壞性清除（例如使用 down -v 刪除 Docker volumes）前必須先詢問使用者。
• 除非 RAG_SERVER_URL 與 RAG_INGEST_URL 均已正確設定且可連線，否則切勿宣稱 FRAG 已就緒。
• 在可行情況下，請自行執行驗證命令。

使用限制

• 本 Skill 僅負責建置與驗證 AI-Q 基礎架構，不會評估深度研究報告的品質。
• 無法提供或檢視敏感金鑰數值。使用者必須在聊天視窗外自行設定金鑰憑證。
• Helm、FRAG、自訂設定檔及自建模型等路徑均依賴使用者自行管理的基礎架構。
• 破壞性清除作業（如刪除 Docker volumes）必須取得使用者的明確授權。

範例

範例 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 啟動 aiq-agent 及其相依套件>
<健康檢查端點傳回成功回應>

若 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
本機 Web 部署	references/local-web.md
Docker Compose 部署	references/docker-compose.md
Kubernetes 與 Helm 部署	references/kubernetes-helm.md
FRAG 整合	references/frag.md
基本驗證	references/validation.md
端到端（End-to-end）驗證	references/end-to-end-validation.md
疑難排解	references/troubleshooting.md
關機與清除	references/shutdown.md

常見問題

問題：後端連接埠已被佔用

症狀：

• Docker Compose 無法繫結（bind）連接埠 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 檢查金鑰是否存在，切勿印出金鑰數值。