aiq-research

AIQ 研究技能

用途

使用此技能，通过辅助脚本 scripts/aiq.py 调用本地运行的 NVIDIA AI-Q Blueprint 服务。

将此技能用于研究类请求，包括：

• “深入研究……”
• “AIQ 研究……”
• “研究……”
• “使用 AI-Q 回答……”
• “询问 AI-Q 关于……的问题”

不要将此技能用于安装、部署、启动、停止、UI、CLI、Docker、Helm 或故障排除请求。这些请求应交由 aiq-deploy 处理。

前提条件

用户需要：

• 可用作 python3 的 Python 3.11+。
• 可访问的本地或可自托管 AI-Q Blueprint 后端。
• 当后端未运行在 http://localhost:8000 时，设置 AIQ_SERVER_URL；在发送任何查询前，用户必须信任非本地值。
• 为此公共辅助工具配置了禁用身份验证的后端，或者在需要身份验证的环境中使用单独的、经过身份验证的 AI-Q 技能。
• 本地计算机可通过网络访问 AI-Q 后端 URL。
• 在后端环境中配置的凭据，而非在此技能中配置。此公共辅助工具不会收集或管理 API 密钥。

辅助脚本没有第三方 Python 包依赖；它使用 Python 标准库中的 HTTP 模块。

说明

1. 确定目标后端 URL。
2. 发送研究请求前先运行 health。
3. 如果无法访问任何后端，请索要后端 URL，或转交给 aiq-deploy。
4. 发送任何用户查询前，说明将接收查询的确切 AI-Q 后端 URL。对于非本地 URL，只有当用户在当前对话中明确确认信任该 URL 后，才继续操作。
5. 如果 AI-Q 返回了作业 ID，则轮询异步深度研究作业。
6. 展示返回的报告，并保留其中的引用和来源 URL。
7. 作业失败时停止并显示返回的错误；不要自动重试。
8. 展示报告后，支持后续操作：使用相同命令回答有关报告的问题 （ask），或开展优化后的研究（redo）。

步骤 1 - 确定后端

如果已设置 AIQ_SERVER_URL，则使用该值。否则尝试默认的本地后端：

python3 $SKILL_DIR/scripts/aiq.py health

预期输出：来自可访问的 AI-Q 健康检查端点的 JSON。

如果 health 失败且未显式设置 AIQ_SERVER_URL，请询问：

I do not see a reachable local AI-Q backend. Do you already have an AI-Q backend URL you want to use, or should I deploy a local Skill backend?

• 如果用户提供了 URL，请为后续辅助工具调用设置 AIQ_SERVER_URL，然后重新运行 health。
• 如果用户希望进行本地部署，请转交给 aiq-deploy，并保留原始研究请求。
• 如果可访问的后端返回 401 或 403，请停止并说明此公共技能不管理身份验证。请用户使用经过身份验证的 AI-Q 技能，或为其环境配置身份验证。
• 如果 health 成功，但 /chat 或 /v1/jobs/async/agents 失败，请报告后端可访问，但与此公共研究流程不兼容，然后提出运行 aiq-deploy 验证。

步骤 2 - 发送路由后的研究请求

发送请求前，说明已确定的端点：

I will send this query to <AIQ_SERVER_URL>. Make sure this endpoint is trusted before sending sensitive information.

不要通过查询文本发送凭据、Cookie、Bearer 令牌或机密值。

运行：

python3 $SKILL_DIR/scripts/aiq.py chat "<USER_QUESTION>"

预期输出：

• 浅层或直接回答对应的普通 JSON 响应。
• 或者包含 {"status": "deep_research_running", "job_id": "<JOB_ID>"} 的结构化 JSON，表示深度研究正在异步运行。

如果响应为普通 JSON，请立即展示结果。如果没有 job_id，不要强行轮询。

步骤 3 - 轮询异步作业

如果响应包含 deep_research_running，请提取 job_id，并使用相同的绝对脚本路径进行轮询：

python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

预期输出：作业成功完成后的最终报告 JSON。

如可用，请使用运行时的非阻塞或后台执行机制。如果所选执行方式需要提升权限，请先征求用户的明确批准，并说明原因。告知用户深度研究正在后台运行。

步骤 4 - 中断后恢复

如果轮询中断，任务会在服务端继续运行。使用以下命令恢复：

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

使用 status 查看任务状态和已保存的产物。任务已完成且只需要最终输出时，使用 report。使用 research_poll 继续等待任务完成。

步骤 5 - 提交报告

research_poll 成功完成后，获取并提交完整报告。保留引用和来源 URL，不要改动。 如果任务状态为 failed、failure 或 cancelled，显示状态响应中的错误，并询问用户是否要使用范围更窄的查询或不同的方法重试。

步骤 6 - 后续跟进：询问报告相关问题或重新生成报告

提交报告后，用户通常会希望深入了解或调整范围。 继续使用现有的后端流程——步骤 1-5 中的相同身份验证边界、轮询和报告检索流程都适用；没有单独的后续跟进端点。

询问 — 针对已获取报告的后续问题：

• 对于可依据现有报告回答的问题，直接根据报告内容和引用作答；不要再次调用后端。

• 对于需要新调查的问题，发送新请求，并将先前问题和报告中所需的上下文纳入新查询文本，然后提交新结果：

  python3 $SKILL_DIR/scripts/aiq.py chat "<FOLLOW_UP_QUESTION> (context: <PRIOR_TOPIC>)"
  

  如果此操作返回 deep_research_running 任务 ID，请按照步骤 3 中的方式使用 research_poll 轮询。

重新生成 — 使用调整后的范围（更窄的查询、更正后的问题或不同的深度）重新运行研究：

python3 $SKILL_DIR/scripts/aiq.py research "<REFINED_QUERY>" [agent_type]

• 选择与所需深度相匹配的 agent_type（例如，全面研究时使用深度 Agent，快速研究时使用 shallow_researcher）；如果不确定，可使用 agents 列出选项。
• 将重新生成视为新任务：发送请求前再次说明目标端点（步骤 2），然后按照步骤 3-5 进行轮询并提交结果。

后续查询文本中不要发送凭据或机密值，并且在每次后续回答中都要保留引用和来源 URL。

版本兼容性

重要： 此技能专为 NVIDIA AI-Q Blueprint 2.1.0 版设计。

语义化版本兼容性规则：

Skill version: X.Y.Z
Blueprint or endpoint 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)

示例：

• 技能版本 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. 仅在用户接受兼容性风险时谨慎继续；API 路由或响应结构可能已发生变化。

可用脚本

脚本	用途	参数
scripts/aiq.py health	检查配置的服务是否有响应	无
scripts/aiq.py chat	POST /chat；可能返回内联输出或深度研究任务 ID	<query>
scripts/aiq.py agents	列出可用的异步 Agent 类型	无
scripts/aiq.py submit	提交显式的异步任务	<query> [agent_type]
scripts/aiq.py research	提交异步任务、轮询并打印最终报告 JSON	<query> [agent_type]
scripts/aiq.py research_poll	继续轮询现有异步任务	<job_id>
scripts/aiq.py status	获取任务状态及 /state 产物	<job_id>
scripts/aiq.py state	仅获取事件存储产物	<job_id>
scripts/aiq.py report	获取已完成任务的最终报告	<job_id>
scripts/aiq.py stream	流式接收任务的 SSE 事件	<job_id>
scripts/aiq.py cancel	取消正在运行的任务	<job_id>

当宿主支持 run_script() 助手函数时，使用 scripts/aiq.py 和上述参数调用它。否则，运行等效的 shell 命令，例如 python3 $SKILL_DIR/scripts/aiq.py health。

环境变量

变量	必需	默认值	描述
AIQ_SERVER_URL	否	http://localhost:8000	本地或可自托管的 AI-Q 服务基础 URL

安全最佳实践

• 请勿将 API 密钥、Bearer 令牌、Cookie 或基本身份验证凭据放入 AIQ_SERVER_URL。
• 将后端凭据存储在 AI-Q 部署环境中，而非此技能或命令示例中。
• 用户查询文本会传输到配置的 AIQ_SERVER_URL。发送敏感或机密信息前，请确认该端点可信。
• 如果后端使用私有数据源，请将返回的报告视为可能包含敏感信息。
• 请勿截断返回报告中的引用或来源 URL。

限制

• 此技能需要正在运行的 AI-Q 后端；它不会部署后端。
• 公共助手不会管理身份验证令牌或 Cookie。
• 远程 AIQ_SERVER_URL 端点可能会记录提示词、响应和元数据。
• 如果后端返回 HTTP 500 或缺少异步 Agent，请报告故障，不要编造研究答案。

示例

示例 1：运行路由聊天或研究请求

python3 $SKILL_DIR/scripts/aiq.py health
python3 $SKILL_DIR/scripts/aiq.py chat "Compare local AIQ deep research with a standard web search workflow"

预期输出：

<health JSON from AI-Q>
<JSON chat response or {"status": "deep_research_running", "job_id": "<JOB_ID>"}>

如果 AI-Q 返回任务 ID，请使用 research_poll 继续操作。

示例 2：恢复现有任务

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

将 <JOB_ID> 替换为 AI-Q 返回的 UUID。预期输出：状态 JSON，任务完成后接着显示报告 JSON。如果任务失败，请显示返回的状态，不要自动重试。

示例 3：提出后续问题，或使用优化后的查询重新执行

# Ask: a follow-up that needs new investigation, carrying prior context.
python3 $SKILL_DIR/scripts/aiq.py chat "How does that compare on cost? (context: local AIQ deep research vs web search)"

# Redo: re-run research with a narrower query and explicit depth.
python3 $SKILL_DIR/scripts/aiq.py research "AIQ deep research cost on a single workstation" shallow_researcher

预期输出：路由聊天响应，或新的 deep_research_running 任务 ID，可使用 research_poll 轮询。展示后续回答时，请保留引用和来源 URL。

参考资料

主题	文档
助手脚本	scripts/aiq.py
部署和后端验证	../aiq-deploy/SKILL.md

常见问题

问题：无法连接到任何后端

症状：

• health 因连接被拒绝而失败。
• 默认的 http://localhost:8000 URL 无响应。

原因：

• AI-Q 未运行。
• AI-Q 运行在其他主机或端口上。
• 本地防火墙或网络设置阻止了连接。

解决方案：

1. 询问用户是否有现成的 AI-Q 后端 URL。
2. 如果用户提供了 URL，请设置该 URL 并重新运行 health：

   export AIQ_SERVER_URL="http://localhost:<PORT>"
   python3 $SKILL_DIR/scripts/aiq.py health
   

3. 如果用户需要本地后端，请转交给 aiq-deploy，并保留原始研究请求。

问题：后端需要身份验证

症状：

• 请求失败，返回 HTTP 401 或 HTTP 403。
• 可以访问后端，但后端拒绝 /chat 或异步任务调用。

原因：

• 部署后端时启用了身份验证。
• 公共辅助工具不会附带用户令牌或 Cookie。

解决方案：

1. 停止操作，并说明此公共技能不负责管理身份验证。
2. 请用户使用经过身份验证的 AI-Q 技能，或为此公共本地工作流配置后端。
3. 只有在解决身份验证边界问题后，才重新运行 health 和原始查询。

问题：健康检查成功，但研究路由失败

症状：

• health 成功返回。
• /chat、/v1/jobs/async/agents 或轮询命令失败。

原因：

• 后端使用的不是启用了 API 的 AI-Q 配置。
• 所选后端没有可用的异步任务注册表。
• 后端版本与此技能不兼容。

解决方案：

1. 运行：

   python3 $SKILL_DIR/scripts/aiq.py agents
   

2. 如果无法使用智能体，请报告兼容性问题，并提出运行 aiq-deploy 验证。
3. 确认已部署的 Blueprint 版本与技能版本 2.1.0 兼容。

问题：任务中断或似乎卡住

症状：

• 本地轮询中断。
• 任务一直显示 running。
• 轮询输出显示 running，但已返回报告，或取消时提示任务已是 success。

原因：

• 深度研究以异步方式运行，并在服务端继续执行。
• 本地轮询输出可能落后于服务端的最终状态。

解决方案：

1. 检查当前状态：

   python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
   

2. 如果 has_report: true 或 job_status.status: success，请获取报告：

   python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>
   

3. 如果任务仍在运行，请继续轮询：

   python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>