Back to Details

aiq-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AIQ Deploy Skill

AIQ 部署技能

Purpose

用途

Use this skill to get a local or self-hosted NVIDIA AI-Q Blueprint server running and verified for use by 
aiq-research
.
This skill owns setup, deployment, operational checks, troubleshooting, and shutdown. It does not run deep research itself. After deployment is healthy, hand off the verified server URL to 
aiq-research
.
使用本技能搭建本地或自托管的NVIDIA AI-Q Blueprint服务器，并完成验证以供
aiq-research
使用。
本技能负责设置、部署、运行检查、故障排查和停机操作，但不执行深度研究任务。部署完成且状态正常后，需将已验证的服务器URL交付给
aiq-research
。

Prerequisites

前提条件

Users need:
  • Access to clone or update 
    https://github.com/NVIDIA-AI-Blueprints/aiq
    .
  • Git available in the shell.
  • One deployment runtime:
    • Docker Engine with Docker Compose v2 for the default durable local deployment.
    • Python 3.11+ and 
      uv
      for local process or CLI mode.
    • Node.js 20+ and 
      npm
      for local browser UI development mode.
    • kubectl
      1.28+, Helm 3.12+, and access to a Kubernetes cluster for Helm mode.
  • Network access to GitHub, NVIDIA-hosted model endpoints, and any selected search provider.
  • Credentials stored outside chat. Hosted-model usage requires 
    NVIDIA_API_KEY
    ; web research requires at least one supported search provider key such as 
    TAVILY_API_KEY
    , 
    SERPER_API_KEY
    , or 
    EXA_API_KEY
    .
  • System capacity for the selected runtime. Docker Compose mode starts the AI-Q backend and PostgreSQL by default; browser UI mode also uses frontend port 
    3000
    . Self-hosted model or RAG deployments may require GPU resources.
Before writing secrets, verify 
deploy/.env
is ignored:
bash
git check-ignore deploy/.env
Expected output: 
deploy/.env
or a matching ignore rule. If it is not ignored, stop and fix the ignore rule before placing credentials in the file.
用户需要满足以下条件：
  • 拥有克隆或更新
    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托管模型端点及所选搜索提供商的网络权限。
  • 在聊天外存储凭证：使用托管模型需要
    NVIDIA_API_KEY
    ；网页研究需要至少一个受支持的搜索提供商密钥，如
    TAVILY_API_KEY
    、
    SERPER_API_KEY
    或
    EXA_API_KEY
    。
  • 所选运行环境的系统容量满足要求：Docker Compose模式默认启动AI-Q后端和PostgreSQL；浏览器UI模式还会占用前端端口
    3000
    。自托管模型或RAG部署可能需要GPU资源。
在写入密钥前，需确认
deploy/.env
已被忽略：
bash
git check-ignore deploy/.env
预期输出：
deploy/.env
或匹配的忽略规则。如果未被忽略，需先修复忽略规则，再在文件中存放凭证。

Instructions

操作步骤

  1. Locate or clone the AI-Q repository.
  2. Confirm the expected repository files exist.
  3. Select the deployment mode.
  4. Prepare 
    deploy/.env
    without overwriting user secrets.
  5. Check runtime prerequisites for the selected path.
  6. Start the selected deployment.
  7. Run basic validation.
  8. Report the verified 
    AIQ_SERVER_URL
    for 
    aiq-research
    .
  9. Ask whether to run optional deep research completion validation.
  1. 定位或克隆AI-Q代码仓库。
  2. 确认预期的仓库文件存在。
  3. 选择部署模式。
  4. 准备
    deploy/.env
    文件，且不覆盖用户已有的密钥。
  5. 检查所选部署路径的运行环境前提条件。
  6. 启动所选部署。
  7. 执行基础验证。
  8. 向
    aiq-research
    报告已验证的
    AIQ_SERVER_URL
    。
  9. 询问是否运行可选的深度研究完成验证。

Step 1 - Locate or clone AI-Q

步骤1 - 定位或克隆AI-Q

If no AI-Q checkout exists, read 
references/locate-or-clone.md
before cloning. In an existing checkout, confirm the required files:
bash
pwd
test -f pyproject.toml
test -f deploy/.env.example
test -d configs
Expected output: 
pwd
prints the AI-Q repository path; the 
test
commands exit with status 0 and no output.
如果尚未检出AI-Q代码，克隆前请阅读
references/locate-or-clone.md
。在已有的代码检出目录中，确认所需文件存在：
bash
pwd
test -f pyproject.toml
test -f deploy/.env.example
test -d configs
预期输出：
pwd
打印AI-Q仓库路径；
test
命令执行后返回状态0且无输出。

Step 2 - Select the deployment mode

步骤2 - 选择部署模式

If the user asks to install, deploy, set up, or run AI-Q without naming a mode, ask:
text
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.
Wait for the user's answer before starting services.
Do not ask this question when the user already specified a mode, such as Docker Compose, Helm, UI, CLI, or Agent Skill backend. Do not ask the full mode question when 
aiq-research
routed here because a deep research request needs a backend. In that case, prefer Agent Skill backend and ask only for permission to start it if needed.
如果用户要求安装、部署、设置或运行AI-Q但未指定模式，请询问：
text
你希望以哪种方式运行AI-Q？

1. Skill后端 - 仅为aiq-research提供后端服务，无浏览器UI。
2. CLI - 交互式终端AI-Q。
3. UI - 包含后端和前端的浏览器AI-Q应用。
4. 自定义 - 部署前选择现有AI-Q配置或查看高级自定义文档。
等待用户回复后再启动服务。
如果用户已指定模式（如Docker Compose、Helm、UI、CLI或Agent Skill后端），则无需询问此问题。如果是
aiq-research
因深度研究请求需要后端而跳转至此，则优先选择Agent Skill后端，仅在需要时询问用户是否允许启动。

Step 3 - Prepare environment and secrets

步骤3 - 准备环境和密钥

Read 
references/env-and-secrets.md
before changing 
deploy/.env
.
bash
if [ ! -f deploy/.env ]; then
  cp deploy/.env.example deploy/.env
  echo "created deploy/.env from deploy/.env.example"
fi
Expected output when the file is missing: 
created deploy/.env from deploy/.env.example
. Expected output when the file already exists: no output, and the existing file is preserved.
Never print secret values. If credentials are missing, ask the user to update 
deploy/.env
; do not ask them to paste secret values into chat.
修改
deploy/.env
前，请阅读
references/env-and-secrets.md
。
bash
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
；不要让用户将密钥粘贴到聊天中。

Step 4 - Route to the selected deployment path

步骤4 - 路由至所选部署路径

Match the user request, then read the referenced file before acting:
User IntentReference
No AI-Q checkout exists, install AIQ, clone AIQ, locate repo
references/locate-or-clone.md
Configure environment, check API keys, inspect 
.env
references/env-and-secrets.md
Choose an AI-Q workflow config, understand config files, set 
BACKEND_CONFIG
or 
CONFIG_FILE
references/configs.md
Backend-only local server for 
aiq-research
, AIQ as an Agent Skill
references/skill-backend.md
Terminal assistant, CLI-only run, no web UI
references/terminal-cli.md
Quick local development run, start UI/backend without containers
references/local-web.md
Default durable local deployment, Docker Compose, containers, PostgreSQL
references/docker-compose.md
Kubernetes, Helm, cluster deployment
references/kubernetes-helm.md
Foundational RAG / FRAG integration
references/frag.md
Basic health checks, shallow smoke checks, handoff to 
aiq-research
references/validation.md
Optional deep research completion validation
references/end-to-end-validation.md
Logs, unhealthy services, port conflicts, config failures
references/troubleshooting.md
Stop services, restart, rebuild, safe cleanup
references/shutdown.md
匹配用户请求，执行操作前先阅读参考文档：
用户需求参考文档
未检出AI-Q、安装AI-Q、克隆AI-Q、定位仓库
references/locate-or-clone.md
配置环境、检查API密钥、查看
.env
references/env-and-secrets.md
选择AI-Q工作流配置、理解配置文件、设置
BACKEND_CONFIG
或
CONFIG_FILE
references/configs.md
为
aiq-research
提供仅后端本地服务器、AI-Q作为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

Step 5 - Validate and hand off

步骤5 - 验证并交付

After startup, read 
references/validation.md
and run the appropriate checks for the selected mode. For the default local backend, verify health:
bash
curl -sf http://localhost:8000/health
Expected output: a successful JSON health response or an empty successful response depending on the server build. If the command fails, read 
references/troubleshooting.md
and diagnose before claiming the backend is ready.
aiq-research
needs a reachable AI-Q server URL. If the backend is on the default port, no extra configuration is needed:
bash
AIQ_SERVER_URL=http://localhost:8000
If the backend runs elsewhere, tell the user to set:
bash
export AIQ_SERVER_URL="http://localhost:<PORT>"
Do not continue into deep research or deep research completion validation unless the user asks for it or confirms the post-deploy validation prompt. This skill's success criterion is a deployed and basically validated server, not report generation quality.
启动后，阅读
references/validation.md
并针对所选模式执行相应检查。对于默认本地后端，验证健康状态：
bash
curl -sf http://localhost:8000/health
预期输出：返回成功的JSON健康响应或空成功响应（取决于服务器构建）。如果命令执行失败，请先阅读
references/troubleshooting.md
进行诊断，再确认后端是否就绪。
aiq-research
需要可访问的AI-Q服务器URL。如果后端使用默认端口，则无需额外配置：
bash
AIQ_SERVER_URL=http://localhost:8000
如果后端运行在其他位置，请告知用户设置：
bash
export AIQ_SERVER_URL="http://localhost:<PORT>"
除非用户要求或确认部署后验证提示，否则不要继续执行深度研究或深度研究完成验证。本技能的成功标准是部署并完成基础验证的服务器，而非研究报告的生成质量。

Version Compatibility

版本兼容性

IMPORTANT: This skill is designed for NVIDIA AI-Q Blueprint version 2.1.0.
Semantic Versioning Compatibility Rules:
text
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)
Examples:
  • Skill version 2.1.0 is compatible with Blueprint version 2.1.0.
  • Skill version 2.1.0 is compatible with Blueprint version 2.2.0.
  • Skill version 2.1.0 is compatible with Blueprint version 2.1.5.
  • Skill version 2.1.0 is not compatible with Blueprint version 3.0.0.
  • Skill version 2.1.0 is not compatible with Blueprint version 2.0.0.
If your Blueprint version is not compatible:
  1. Check for an updated skill version matching your Blueprint version.
  2. Use a Blueprint version compatible with this skill.
  3. Proceed with caution only when the user accepts the compatibility risk; deployment commands or config names may have changed.
重要提示： 本技能专为NVIDIA AI-Q Blueprint 2.1.0版本设计。
语义版本兼容性规则：
text
技能版本：X.Y.Z
Blueprint版本：A.B.C

兼容条件：
1. A == X（主版本必须匹配）
2. B >= Y（次版本必须大于或等于）
3. C无限制（补丁版本不影响兼容性）
示例：
  • 技能版本2.1.0与Blueprint版本2.1.0兼容。
  • 技能版本2.1.0与Blueprint版本2.2.0兼容。
  • 技能版本2.1.0与Blueprint版本2.1.5兼容。
  • 技能版本2.1.0与Blueprint版本3.0.0不兼容。
  • 技能版本2.1.0与Blueprint版本2.0.0不兼容。
如果你的Blueprint版本不兼容：
  1. 检查是否有与你的Blueprint版本匹配的更新技能版本。
  2. 使用与本技能兼容的Blueprint版本。
  3. 仅当用户接受兼容性风险时才谨慎继续；部署命令或配置名称可能已更改。

Security Best Practices

安全最佳实践

  • Never print secret values. Check only whether required environment variables are set.
  • Store credentials in 
    deploy/.env
    or environment variables, not in chat transcripts, shell history, committed files, or example commands.
  • Do not overwrite 
    deploy/.env
    when it already exists.
  • Ask before destructive cleanup such as deleting Docker volumes with 
    down -v
    .
  • Do not claim FRAG is ready unless both 
    RAG_SERVER_URL
    and 
    RAG_INGEST_URL
    are configured and reachable.
  • Run verification commands yourself when possible.
  • 切勿打印密钥值。仅检查所需环境变量是否已设置。
  • 将凭证存储在
    deploy/.env
    或环境变量中，不要存储在聊天记录、终端历史、已提交文件或示例命令中。
  • 当
    deploy/.env
    已存在时，不要覆盖它。
  • 执行破坏性清理（如使用
    down -v
    删除Docker卷）前需询问用户。
  • 仅当
    RAG_SERVER_URL
    和
    RAG_INGEST_URL
    均已配置且可访问时，才可确认FRAG已就绪。
  • 尽可能自行执行验证命令。

Limitations

局限性

  • This skill prepares and validates AI-Q infrastructure; it does not judge deep research report quality.
  • It cannot provide or inspect secret values. Users must configure credentials outside chat.
  • Helm, FRAG, custom config, and self-hosted model paths depend on infrastructure the user controls.
  • Destructive cleanup, such as deleting Docker volumes, requires explicit user approval.
  • 本技能仅负责准备和验证AI-Q基础设施，不评判深度研究报告的质量。
  • 无法提供或查看密钥值。用户必须在聊天外配置凭证。
  • Helm、FRAG、自定义配置和自托管模型路径依赖于用户控制的基础设施。
  • 破坏性清理（如删除Docker卷）需要用户明确批准。

Examples

示例

Example 1: Deploy a backend-only Skill server with Docker Compose

示例1：使用Docker Compose部署仅后端的Skill服务器

bash
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
Expected output:
text
deploy/.env
<docker compose starts aiq-agent and dependencies>
<health endpoint returns a successful response>
If Docker, ports, credentials, or health checks fail, read 
references/troubleshooting.md
before retrying.
bash
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
预期输出：
text
deploy/.env
<docker compose启动aiq-agent及依赖服务>
<健康端点返回成功响应>
如果Docker、端口、凭证或健康检查失败，请先阅读
references/troubleshooting.md
再重试。

Example 2: Hand off a non-default backend URL to aiq-research

示例2：向aiq-research交付非默认后端URL

bash
export AIQ_SERVER_URL="http://localhost:8100"
curl -sf "$AIQ_SERVER_URL/health"
Expected output: a successful health response. Then tell the user to keep 
AIQ_SERVER_URL
set before invoking 
aiq-research
.
bash
export AIQ_SERVER_URL="http://localhost:8100"
curl -sf "$AIQ_SERVER_URL/health"
预期输出：返回成功的健康响应。然后告知用户在调用
aiq-research
前保持
AIQ_SERVER_URL
已设置。

References

参考文档

TopicDocumentation
Locate or clone AI-Q
references/locate-or-clone.md
Environment and secrets
references/env-and-secrets.md
Workflow configs
references/configs.md
Agent Skill backend
references/skill-backend.md
CLI deployment
references/terminal-cli.md
Local web deployment
references/local-web.md
Docker Compose deployment
references/docker-compose.md
Kubernetes and Helm deployment
references/kubernetes-helm.md
FRAG integration
references/frag.md
Basic validation
references/validation.md
End-to-end validation
references/end-to-end-validation.md
Troubleshooting
references/troubleshooting.md
Shutdown and cleanup
references/shutdown.md
主题文档路径
定位或克隆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

Common Issues

常见问题

Issue: Backend port is already in use

问题：后端端口已被占用

Symptoms:
  • Docker Compose fails to bind port 
    8000
    .
  • curl -sf http://localhost:8000/health
    reaches an unexpected service or fails.
Causes:
  • Another AI-Q backend or local development server is already running.
  • PORT
    in 
    deploy/.env
    conflicts with an existing process.
Solutions:
  1. Identify the process:
    bash
    lsof -nP -iTCP:8000 -sTCP:LISTEN
  2. Either stop the conflicting process with the user's approval or set a different port in 
    deploy/.env
    , such as 
    PORT=8100
    .
  3. Restart the selected deployment path and verify:
    bash
    curl -sf http://localhost:8100/health
症状：
  • 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

Issue: Required credentials are missing

问题：缺少必要凭证

Symptoms:
  • Infrastructure starts, but model-backed chat or research requests fail.
  • Logs mention unauthorized, forbidden, invalid key, or missing provider configuration.
Causes:
  • NVIDIA_API_KEY
    is missing or empty.
  • No supported search provider key is configured for web research.
Solutions:
  1. Check presence without printing values by following 
    references/env-and-secrets.md
    .
  2. Ask the user to update 
    deploy/.env
    ; do not ask them to paste secrets into chat.
  3. Rerun 
    references/validation.md
    after the user updates credentials.
症状：
  • 基础设施启动，但基于模型的聊天或研究请求失败。
  • 日志提及未授权、禁止访问、无效密钥或缺少提供商配置。
原因：
  • NVIDIA_API_KEY
    缺失或为空。
  • 未配置网页研究所需的受支持搜索提供商密钥。
解决方案：
  1. 按照
    references/env-and-secrets.md
    检查凭证是否存在，不要打印密钥值。
  2. 要求用户更新
    deploy/.env
    ；不要让用户将密钥粘贴到聊天中。
  3. 用户更新凭证后，重新执行
    references/validation.md
    中的验证步骤。

Issue: Backend is healthy but not compatible with aiq-research

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

Symptoms:
  • /health
    succeeds, but 
    /chat
    or 
    /v1/jobs/async/agents
    fails.
  • aiq-research
    reports that async agents are unavailable.
Causes:
  • The selected config is CLI-only or does not expose the web/API backend expected by the skill.
  • BACKEND_CONFIG
    or 
    CONFIG_FILE
    points at the wrong AI-Q config.
Solutions:
  1. Read 
    references/configs.md
    and confirm the selected config is API-enabled.
  2. For the default Skill backend, use 
    configs/config_web_default_llamaindex.yml
    .
  3. Restart the backend and rerun 
    references/validation.md
    .
症状：
  • /health
    请求成功，但
    /chat
    或
    /v1/jobs/async/agents
    请求失败。
  • aiq-research
    报告异步Agent不可用。
原因：
  • 所选配置仅支持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
    中的验证步骤。

Issue: Docker cleanup would remove useful state

问题：Docker清理会删除有用状态

Symptoms:
  • Troubleshooting suggests 
    docker compose down -v
    .
  • The user may have local PostgreSQL job or checkpoint data they want to keep.
Causes:
  • down -v
    removes Docker volumes.
  • Rebuilds and restarts are often enough for config or image changes.
Solutions:
  1. Prefer a normal restart from 
    references/shutdown.md
    .
  2. Ask for explicit approval before running volume deletion.
  3. After cleanup, rerun deployment and validation from the selected route.
症状：
  • 故障排查建议执行
    docker compose down -v
    。
  • 用户可能希望保留本地PostgreSQL的任务或检查点数据。
原因：
  • down -v
    会删除Docker卷。
  • 对于配置或镜像变更，通常重建和重启即可解决问题。
解决方案：
  1. 优先选择
    references/shutdown.md
    中的常规重启方式。
  2. 执行卷删除前需获得用户明确批准。
  3. 清理完成后，从所选路径重新执行部署和验证步骤。