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 版兼容。

  发现更多技能插件，请访问7w4.net。

• 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 作业或检查点数据。

原因：

• down -v 会删除 Docker 卷。
• 通常重启和重建对于配置或镜像变更已足够。

解决方案：

1. 优先使用 references/shutdown.md 中的正常重启。
2. 在运行卷删除前请求明确批准。
3. 清理后，从所选路径重新运行部署和验证。

这款 Skill 质量较好，文档清晰、步骤完整，安全性做得不错，不会泄露密钥。部署验证流程规范，故障排查指南实用。主要不足是部分操作可能过于直接（如自动克隆仓库），效率表现参差不齐，新手使用时需留意安全提示。