Grok 工具调用（Tools）¶

Grok 模型支持通过 OpenAI 标准 Tools/Function Calling 的方式接入工具调用。除了自定义函数外，Grok 还提供了强大的原生 联网搜索（Web Search） 能力。

✅ 推荐阅读¶

🌐 联网搜索（Web Search）¶

Grok 的联网搜索功能允许模型实时访问互联网信息，并返回包含引用来源（Citations）的回答。

1. 基础调用方式¶

在 New-API 平台中，你可以通过以下两种工具类型名启用 Grok 的联网搜索：

web_search_preview：New-API 平台统一的内置搜索工具名（推荐，兼容性强）。
web_search：xAI 原生的工具名。

OpenAI Responses 接口示例（推荐）¶

使用 v1/responses 接口可以更方便地获取结构化的搜索结果和引用。

curl https://api-cs-al.naci-tech.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-2",
    "tools": [
      { "type": "web_search_preview" }
    ],
    "input": "纽约现在的天气和当地时间是多少？"
  }'

OpenAI Chat Completions 接口示例¶

curl https://api-cs-al.naci-tech.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-2",
    "messages": [
      { "role": "user", "content": "帮我搜索一下 xAI 最近发布的 Grok-3 有哪些亮点？" }
    ],
    "tools": [
      { "type": "web_search" }
    ],
    "tool_choice": "auto"
  }'

2. 高级搜索参数¶

Grok 的原生 web_search 工具支持通过 filters 或扩展参数进行精细化控制。在 New-API 中，这些参数通常可以直接在工具对象中传递。

参数	类型	说明
`allowed_domains`	数组	仅允许搜索特定域名（最多 5 个），如 `["wikipedia.org", "github.com"]`
`excluded_domains`	数组	排除特定域名（最多 5 个）。不能与 `allowed_domains` 同时使用
`enable_image_understanding`	布尔	是否启用对搜索结果中图片的分析能力

示例（限定域名搜索）：

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

3. 获取引用来源 (Citations)¶

当模型执行联网搜索后，响应中会包含 citations 字段，详细列出信息的来源。

Responses 接口：在 output[].message.content[].annotations 中包含 url_citation。
原生/Chat 接口：在返回的消息对象或 citations 数组中查找。

🧩 自定义函数（Function Calling）¶

如果你需要让 Grok 调用你自己的业务接口（如查订单、操作数据库），请使用标准的 type: "function"。

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