name: aiq-deploy displayName: AI-Q Blueprint 部署與運維 description: | 當被要求安裝、部署、執行、驗證、排查或停止 NVIDIA AI-Q Blueprint 基礎設施時使用。 license: Apache-2.0 compatibility: | Designed for Claude Code, OpenCode, Codex, and Agent Skills-compatible tools. Requires Git, network access to GitHub, and one selected runtime path: Docker Compose v2 for the default local deployment, Python 3.11+ and uv for local process or CLI mode, Node.js 20+ and npm for local web UI mode, or kubectl 1.28+ and Helm 3.12+ for Kubernetes and Helm mode. metadata: version: "2.1.0" author: "NVIDIA AI-Q Blueprint Team aiq-blueprint@nvidia.com" github-url: "https://github.com/NVIDIA-AI-Blueprints/aiq" tags: - nvidia - aiq - blueprint - deploy - operations - agent-skills allowed-tools: Read Bash

AIQ 部署技能

目的

使用此技能讓本地或自託管的 NVIDIA AI-Q Blueprint 伺服器執行並通過驗證，供 aiq-research 使用。

此技能負責安裝配置、部署、執行檢查、故障排查和關閉。它本身不執行深度研究。部署健康後，將驗證通過的伺服器 URL 移交給 aiq-research。工作流程保持顯式，以確保部署驗證和移交在支援的 agent 客戶端間可重複。

前置條件

使用者需要：

• 能夠克隆或更新 https://github.com/NVIDIA-AI-Blueprints/aiq。
• Shell 中可用 Git。
• 一種部署執行時：
• Docker Engine 及 Docker Compose v2（用於預設的持久化本地部署）。
• Python 3.11+ 及 uv（用於本地程序或 CLI 模式）。
• Node.js 20+ 及 npm（用於本地瀏覽器 UI 開發模式）。
• kubectl 1.28+、Helm 3.12+ 及 Kubernetes 叢集訪問（用於 Helm 模式）。
• 能夠訪問 GitHub、NVIDIA 託管的模型端點和所選搜尋提供方。
• 憑據儲存在聊天之外。使用託管模型需要 NVIDIA_API_KEY；網頁研究需要至少一個支援的搜尋提供方金鑰，例如 TAVILY_API_KEY、SERPER_API_KEY 或 EXA_API_KEY。
• 所選執行時所需系統資源。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_SERVER_URL 給 aiq-research。
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 - 路由到所選部署路徑

匹配使用者請求，然後在執行前閱讀引用的檔案：

步驟 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)

示例：

• 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 版本匹配的更新版本技能。
2. 使用與此技能相容的 Blueprint 版本。
3. 僅在使用者接受相容性風險時謹慎繼續；部署命令或配置名稱可能已更改。

安全最佳實踐

• 切勿列印金鑰值。僅檢查所需的環境變數是否已設定。
• 將憑據儲存在 deploy/.env 或環境變數中，而非聊天記錄、shell 歷史、已提交的檔案或示例命令中。
• 當 deploy/.env 已存在時不要覆蓋它。
• 在執行破壞性清理（如使用 down -v 刪除 Docker 卷）前詢問使用者。
• 除非 RAG_SERVER_URL 和 RAG_INGEST_URL 均已配置並可訪問，否則不要聲稱 FRAG 已就緒。
• 儘可能自己執行驗證命令。

限制

• 此技能負責準備和驗證 AI-Q 基礎設施；它不評估深度研究報告的質量。
• 無法提供或檢查金鑰值。使用者必須在聊天之外配置憑據。
• Helm、FRAG、自定義配置和自託管模型路徑依賴於使用者控制的基礎設施。
• 破壞性清理（如刪除 Docker 卷）需要使用者明確批准。

示例

示例 1：使用 Docker Compose 部署僅後端技能伺服器

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：向 aiq-research 移交非預設後端 URL

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

預期輸出：成功的健康響應。然後告訴使用者在呼叫 aiq-research 前保持 AIQ_SERVER_URL 已設定。

參考檔案

常見問題

問題：後端埠已被佔用

症狀：

• Docker Compose 無法繫結埠 8000。
• curl -sf http://localhost:8000/health 訪問到意外服務或失敗。

原因：

• 另一個 AI-Q 後端或本地開發伺服器正在執行。
• deploy/.env 中的 PORT 與現有程序衝突。

解決方案：

1. 識別程序： bash lsof -nP -iTCP:8000 -sTCP:LISTEN
2. 在使用者批准後停止衝突程序，或在 deploy/.env 中設定其他埠（例如 PORT=8100）。
3. 重啟所選部署路徑並驗證： bash curl -sf http://localhost:8100/health

問題：所需憑據缺失

症狀：

• 基礎設施啟動，但基於模型的聊天或研究請求失敗。
• 日誌提示未授權、禁止訪問、無效金鑰或缺少提供方配置。

原因：

• 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 報告非同步 agent 不可用。

原因：

• 所選配置僅為 CLI 模式，未暴露技能所需的 Web/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 作業或檢查點資料。

  小蔥技能7w4.net有完整的技能分類。

原因：

• down -v 會刪除 Docker 卷。
• 通常重啟和重建對於配置或映象變更已足夠。

解決方案：

1. 優先使用 references/shutdown.md 中的正常重啟。
2. 在運行卷刪除前請求明確批准。
3. 清理後，從所選路徑重新執行部署和驗證。

這款 Skill 質量較好，文件清晰、步驟完整，安全性做得不錯，不會洩露金鑰。部署驗證流程規範，故障排查指南實用。主要不足是部分操作可能過於直接（如自動克隆倉庫），效率表現參差不齊，新手使用時需留意安全提示。