Grok Web Search（Grok 联网搜索）¶

Grok 模型支持通过 Web Search 工具 实时访问互联网，搜索网页并抽取关键信息，从而回答带有最新内容的问题。

重点说明：
- 本站网关 统一采用了兼容 OpenAI 规范的 /v1/chat/completions 接口，通过 web_search_options 字段来触发包括 Grok 在内的各家模型的联网能力。
- xAI 官方 则是通过专有的 /v1/responses 接口声明 type: "web_search" 工具来进行。

下文将为你对比展示 本站统一调用方式 和 xAI 官方调用方式。

快速开始（Quick start）¶

本站示例（New API 平台）¶

在本平台中，无论你是调用 GPT、Gemini 还是 Grok，只需要向 /v1/chat/completions 端点发送请求，并在请求体中添加 web_search_options 字段即可开启联网功能。

curl https://api-cs-al.naci-tech.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-4-1-fast-reasoning",
    "messages": [
      { "role": "user", "content": "明天北京天气怎么样？" }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

web_search_options：开启联网搜索的标志。目前支持的配置项（如 search_context_size 控制搜索上下文量等）与平台中其他模型联网机制完全一致。

xAI 官方示例（原生 API）¶

如果你是直连 xAI 官方 API，需要在他们的 /v1/responses 接口中，通过 tools 数组声明原生的 web_search 工具：

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4-1-fast-reasoning",
  "input": [
    {
      "role": "user",
      "content": "What is xAI?"
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}'

xAI 官方高级特性说明¶

虽然在本站你可以非常简单地用 web_search_options 解决问题，但了解官方的原生能力有助于你理解 Grok Web Search 的潜力。

根据 xAI 官方文档，原生的 Web Search 工具支持以下常用参数（通过 tools[].filters 或工具属性传入）：

参数	说明
`allowed_domains`	仅在指定域名内进行搜索（最多 5 个）
`excluded_domains`	在搜索中排除指定域名（最多 5 个）
`enable_image_understanding`	启用图片理解，对搜索过程中遇到的图片进行分析

仅搜索特定域名（allowed_domains）¶

xAI 官方示例：

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4-1-fast-reasoning",
  "input": [
    { "role": "user", "content": "What is xAI?" }
  ],
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["grokipedia.com"]
      }
    }
  ]
}'

注意：allowed_domains 与 excluded_domains 不能同时设置。

启用图片理解（enable_image_understanding）¶

设置 enable_image_understanding: true 将使代理可以在搜索过程中调用 view_image 等内部工具，从网页中抽取和理解图片内容。

xAI 官方示例：

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4-1-fast-reasoning",
  "input": [
    {
      "role": "user",
      "content": "What is included in the image in xAI'\''s official website?"
    }
  ],
  "tools": [
    {
      "type": "web_search",
      "enable_image_understanding": true
    }
  ]
}'

引用（Citations）¶

Grok Web Search 会在搜索结果的基础上生成带引用的回答。
在 xAI 官方 Responses API 中，你可以通过 response.citations 或 SDK 返回的 sources 字段查看引用详情（参见官方文档 Citations）。

在本平台使用 /v1/chat/completions 调用时，网关会在后台进行处理并直接将整理后的结果以纯文本格式拼接，或者通过兼容的 Citation 形式返回，与其他模型行为一致。

补充：自定义函数（Function Calling）¶

除了 Web Search 之外，你还可以为 Grok 定义你自己的业务工具，本站统一兼容 OpenAI 的 Function Calling 格式。例如：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_user_info",
        "description": "获取用户信息",
        "parameters": {
          "type": "object",
          "properties": {
            "user_id": { "type": "string" }
          },
          "required": ["user_id"]
        }
      }
    }
  ]
}

更多关于工具调用的通用说明，可以参考本目录的工具总览文档：index.md。