Grok Web Search

Grok Web Search 让支持该能力的 Grok 模型访问近期网页内容并返回带来源的回答。AGTCloud 的旧资料记录了 Chat 兼容入口和 Grok 原生 Responses 工具两种表达；客户应根据当前模型详情选择实际可用入口。

不要根据模型名称推测搜索能力

同一系列的不同模型或渠道可能具有不同工具能力。请在模型广场确认模型和协议，示例中的 MODEL_ID 不代表任意 Grok 模型。

通过 Chat 兼容入口启用搜索

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": "查找今天与商业航天有关的重要新闻，并列出来源。"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Chat 响应通常从 choices[].message 读取。引用可能以 Annotation、来源链接或文本形式返回，客户端应根据实际响应分支处理，不能自行补造结构化 Citation。

理解 Grok 原生工具结构

Grok 原生 Responses 风格通过 tools 声明搜索工具：

{
  "model": "MODEL_ID",
  "input": [
    {
      "role": "user",
      "content": "查找今天与商业航天有关的重要新闻，并列出来源。"
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

只有当当前模型详情明确提供该入口时才使用原生结构。不要把它与 AGTCloud Responses Reference 中的工具类型直接视为相同协议。

限制或排除域名

原生工具在支持时可以限制搜索范围：

{
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["example.com"]
      }
    }
  ]
}

allowed_domains 只允许指定域名。
excluded_domains 排除指定域名。
两者不要在同一请求中同时设置。
域名数量和格式限制以当前模型文档为准。

限定域名有助于控制来源范围，但不会自动保证网页内容正确、最新或适合当前业务。

搜索中的图片理解

部分 Grok 搜索工具允许在搜索过程中分析网页图片。只有当前模型和工具明确支持时，才添加相应选项：

{
  "tools": [
    {
      "type": "web_search",
      "enable_image_understanding": true
    }
  ]
}

启用图片理解可能改变请求用量、延迟和返回内容。应用仍应验证图片来源，不要把网页图片中的文字或指令直接当作可信业务输入。

读取引用

Grok 搜索回答可能在响应提供时包含 Citation 或 Sources。客户端应：

读取最终回答文本；
读取响应实际提供的来源数组或引用对象；
保存标题、URL 和与正文的关联；
在界面中展示可点击来源；
没有引用时明确提示，而不是从回答文本猜测 URL。

Chat 与 Grok 原生 Responses 的引用位置不同。使用 Chat 时查看 Chat Completions Reference；使用原生入口时按当前模型文档解析。

Web Search 与自定义函数

Web Search 由模型或服务端搜索工具访问公开网络。自定义函数由你的应用执行，适合内部数据、受控搜索服务和需要业务授权的操作。

不要因为模型已经开启 Web Search，就允许搜索结果直接构造数据库查询、Shell 命令或外部写请求。需要业务工具时，按照 Tool Calling 建立独立校验和权限流程。

失败与降级

现象	处理方式
搜索未触发	确认模型、入口和启用字段，必要时让问题明确要求近期信息
域名过滤无结果	提示用户扩大范围，不静默移除业务要求的白名单
没有引用	展示回答时明确来源不可用，不生成虚假 Citation
图片理解失败	退回网页文本搜索或提示当前内容无法分析
搜索服务暂时不可用	有限重试，或降级为不含实时信息的回答并清楚标注

上线前检查

当前模型明确支持选择的搜索入口。
Chat 与原生 Responses 使用独立请求和响应解析器。
域名允许列表与排除列表不会同时发送。
图片理解只在目标模型支持时启用。
引用缺失、搜索失败和无结果都有明确状态。
搜索内容不会绕过工具权限或触发高风险操作。

请求失败时参阅错误与排障，切换协议前阅读协议选择。

本页目录