aiq-deploy

AIQ Deploy Skill

技能用途

本 Skill 用于启动并验证本地或私有化部署的 NVIDIA AI-Q Blueprint 服务器，以供 aiq-research 调用。

本 Skill 负责环境配置、服务部署、运行状态检查、故障排查及服务关闭。它本身不直接执行深度研究任务。部署完成且健康检查通过后，将已验证的服务器 URL 交付给 aiq-research。
整体工作流保持清晰透明，以便在各种支持的 Agent 客户端上实现可复现的部署验证与交付。

前置条件

用户需要准备：

• 能够克隆或更新 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 托管的模型 Endpoint 以及所选搜索服务提供商的网络。
• 在对话上下文之外保存的凭证。使用托管模型需要配置 NVIDIA_API_KEY；使用 Web 联网搜索需至少配置一个支持的搜索 Provider API Key（如 TAVILY_API_KEY、SERPER_API_KEY 或 EXA_API_KEY）。
• 所选运行环境所需的系统资源容量。Docker Compose 模式默认会启动 AI-Q 后端和 PostgreSQL；浏览器 UI 模式还会占用前端端口 3000。私有化部署模型或 RAG 系统可能需要 GPU 资源。

在写入密钥/凭证前，请先确认 deploy/.env 已被 .gitignore 忽略：

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 但未指定模式，请询问用户：

您希望以哪种方式运行 AI-Q？

1. Skill 后端（Skill backend） - 仅后端服务，供 aiq-research 调用，无浏览器 UI。
2. CLI - 终端交互式 AI-Q。
3. UI - 包含后端和前端的浏览器 AI-Q 应用。
4. 自定义（Custom） - 选择已有的 AI-Q 配置文件，或在部署前查阅高级自定义文档。

请等待用户回答后再启动相关服务。

当用户已经明确指定了模式（例如 Docker Compose、Helm、UI、CLI 或 Agent Skill 后端）时，不要重复询问。当 aiq-research 因为深度研究请求需要后端服务而路由到本 Skill 时，也不要弹出完整的模式选择提示；在此情况下，优先使用 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 使用）、作为 Agent Skill 的 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>"

除非用户明确要求或确认了部署后的验证提示，否则不要直接进入深度研究或深度研究完成度验证。本 Skill 的成功标准是“完成服务器部署并成功通过基础验证”，而非研究报告的生成质量。

版本兼容性

重要提示： 本 Skill 专为 NVIDIA AI-Q Blueprint 2.1.0 版本设计。

语义化版本（Semantic Versioning）兼容规则：

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

满足以下条件时兼容：
1. A == X（主版本号必须一致）
2. B >= Y（次版本号必须大于等于 Skill 的次版本号）
3. C 可以为任意值（修订版本号不影响兼容性）

示例：

• 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 卷）前必须先征得用户同意。
• 除非 RAG_SERVER_URL 和 RAG_INGEST_URL 均已配置且网络连通，否则不要声明 FRAG 已准备就绪。
• 在可行的情况下，尽可能自行运行验证命令。

局限性

• 本 Skill 仅负责准备和验证 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 启动 aiq-agent 及其依赖项>
<health endpoint 返回成功响应>

如果 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 环境变量生效。

参考文档

主题	文档
定位或克隆 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
全流程完成度验证	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）、无效 Key（invalid key）或缺少 Provider 配置。

原因：

• NVIDIA_API_KEY 缺失或为空。
• 未配置任何支持的搜索 Provider Key 以用于联网研究。

解决方案：

1. 参考 references/env-and-secrets.md 检查环境变量是否存在（切勿打印明文）。