Qwen Web Search

为 Qwen 请求启用网络搜索，并正确处理搜索引擎与引用结果。

Qwen Web Search 让支持该能力的 Qwen 模型访问网络信息，并在响应允许时返回来源引用。它适合天气、新闻、产品更新和其他需要近期信息的任务。

Qwen 搜索可能通过 Chat 扩展字段、Responses 内置工具或模型原生搜索框架提供。三者的启用方式和引用结构不同，应按当前模型详情选择。

搜索入口需要模型明确支持

不要根据 Qwen 系列名称推断 enable_search、Responses Web Search 或搜索引擎选择均可用。请在模型广场确认模型与协议。

通过 Chat 启用搜索

旧文档记录的 Qwen Chat 主路径使用 enable_search：

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "今天杭州天气怎么样？请给出来源。"
      }
    ],
    "enable_search": true
  }'

enable_search 是模型或渠道扩展字段，不是所有 Chat 模型的公共参数。如果 SDK 类型没有该字段，可使用原始 HTTP 请求或 SDK 提供的扩展参数能力，并以实际模型文档为准。

通过 Responses 使用内置搜索

当前模型支持 Responses Web Search 时，可以使用内置工具结构：

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview"
      }
    ],
    "input": "今天杭州天气怎么样？请给出来源。"
  }'

Responses 结果可能包含 web_search_call、文本 Output Item 和 url_citation。完整结构见 Responses Reference。

搜索引擎或 Provider 选择

Qwen 原生搜索框架可能支持选择不同搜索 Provider。该配置属于具体模型、Agent 框架或渠道能力，不是 AGTCloud Chat 的统一字段。

当当前模型文档明确提供 Provider 选项时：

使用默认 Provider 可以减少配置并保留服务端降级能力。
指定 Provider 适合对来源范围、检索质量或合规边界有明确要求的场景。
Provider 凭证和权限应保存在服务端，不放入 Prompt 或浏览器代码。
Provider 不可用时是否自动切换，以当前工具实现为准，客户端仍需处理失败。

不要把旧文档中的搜索引擎名称和默认顺序写成长期平台承诺。

读取回答和引用

不同入口可能返回：

入口	回答	引用
Chat 扩展	`choices[].message.content`	响应提供的 Annotation、链接或编号来源
Responses	Message Output Item	`annotations` 中的 `url_citation`
原生搜索框架	框架生成的回答	编号来源列表或 Provider 返回的来源对象

如果回答文本使用 [1]、[2] 等编号，客户端还必须取得与编号对应的来源 URL，不能只展示没有目标链接的编号。

{
  "answer": "杭州今天预计有阵雨。[1]",
  "sources": [
    {
      "index": 1,
      "title": "来源标题",
      "url": "https://example.com/weather"
    }
  ]
}

该示例表示应用内部可以整理成的展示数据，不是 AGTCloud API 的固定响应 Schema。

原生搜索与自定义函数

内置 Web Search 面向公开网络信息。需要查询企业内部搜索、订单或私有知识库时，应使用 Tool Calling 调用你自己的受控服务。

自定义工具返回的文本不自动获得可信 Citation。应用应同时返回来源元数据，并在最终界面中保持回答与来源的对应关系。

失败与降级

现象	处理方式
`enable_search` 被拒绝	确认模型和渠道是否支持扩展字段，或选择已登记的 Responses 入口
搜索没有触发	检查问题是否需要近期信息，同时确认启用字段实际送达上游
编号没有来源 URL	不显示为可点击引用，提示本次响应缺少完整来源信息
Provider 不可用	按当前工具规则切换或有限重试，不无限循环不同 Provider
搜索结果相互冲突	展示来源和日期，不让模型替应用隐藏重要分歧

上线前检查

当前模型明确支持 enable_search 或选择的 Responses 工具。
模型扩展字段没有被 SDK 静默丢弃。
Chat、Responses 和原生搜索结果使用独立解析器。
引用编号能够映射到真实标题和 URL。
Provider 配置和凭证不会进入客户端 Prompt。
无结果、搜索失败和来源缺失都有明确降级。

Chat 公共字段见 Chat Completions Reference，请求失败时参阅错误与排障。