aiq-deploy

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 步 - 路由到选定的部署路径

匹配用户请求，然后在采取行动前阅读引用的文件：

用户意图	参考文件
不存在 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 用作 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
Foundational 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)

示例：

• 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 已存在，不要覆盖它。
• 删除 Docker 卷等破坏性清理操作（例如 down -v）前，先征求同意。
• 只有在 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
本地 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
   

问题：缺少必需的凭据

症状：

• 基础设施已启动，但由模型驱动的聊天或研究请求失败。
• 日志中出现未授权、禁止访问、密钥无效或缺少提供商配置等信息。

原因：

• 未设置 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. 清理后，按照所选路径重新部署并验证。