AIQ部署Skill aiq-deploy

名称	aiq-deploy
描述
开源协议	Apache-2.0 compatibility:
版本	“2.1.0”
作者	“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。
  • 用于本地进程或 CLI 模式的 Python 3.11+ 与 uv。
  • 用于本地浏览器 UI 开发模式的 Node.js 20+ 与 npm。
  • 用于 Helm 模式的 kubectl 1.28+、Helm 3.12+ 以及可用 Kubernetes 集群。
• 可访问 GitHub、NVIDIA 托管的模型端点以及所选搜索提供商的网络。
• 凭据存储在聊天之外。使用托管模型需要 NVIDIA_API_KEY；Web 研究至少需要一个受支持的搜索提供商密钥，如 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-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 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 因为深度研究请求需要后端而路由到这里时，也不要询问完整模式问题。此时应优先选择 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
基础 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 版本设计。

语义化版本兼容性规则：

技能版本：X.Y.Z
蓝图版本：A.B.C

兼容条件：
1. A == X（主版本必须匹配）
2. B >= Y（次版本必须大于或等于）
3. C 无关紧要（修订版本不影响兼容性）

示例：

• 技能版本 2.1.0 兼容蓝图版本 2.1.0。
• 技能版本 2.1.0 兼容蓝图版本 2.2.0。
• 技能版本 2.1.0 兼容蓝图版本 2.1.5。
• 技能版本 2.1.0 不兼容蓝图版本 3.0.0。
• 技能版本 2.1.0 不兼容蓝图版本 2.0.0。

如果蓝图版本不兼容：

1. 检查是否有与蓝图版本匹配的更新的技能版本。
2. 使用与此技能兼容的蓝图版本。
3. 仅在用户接受兼容性风险时谨慎继续；部署命令或配置名称可能已更改。

安全最佳实践

• 绝不打印密钥值。只检查必需的环境变量是否已设置。
• 将凭据存储在 deploy/.env 或环境变量中，而不是聊天记录、Shell 历史、已提交文件或示例命令中。
• 当 deploy/.env 已存在时不要覆盖它。
• 在执行破坏性清理（如使用 down -v 删除 Docker 卷）之前询问用户。
• 除非 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 启动 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
端到端验证	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 缺失或为空。
• 没有为 Web 研究配置受支持的搜索提供商密钥。

解决方案：

1. 按照 references/env-and-secrets.md 检查是否存在但不要打印值。
2. 请用户更新 deploy/.env；不要请他们粘贴密钥到聊天。
3. 在用户更新凭据后重跑 references/validation.md。

问题：后端健康但与 aiq-research 不兼容

症状：

• /health 成功，但 /chat 或 /v1/jobs/async/agents 失败。
• aiq-research 报告异步代理不可用。

原因：

• 所选配置仅用于 CLI，或未暴露该 Skill 期望的 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. 清理后，从所选路由重新运行部署和验证。