xAI 文档

外观

工具 ​

X 搜索 ​

X 搜索工具使 Grok 能够在 X（前身为 Twitter）上执行关键词搜索、语义搜索、用户搜索和线程获取。这个强大的工具使模型能够访问实时社交媒体内容、分析帖子并从 X 的海量数据中收集洞察。

SDK 支持 ​

SDK/API工具名称
xAI SDKx_search
OpenAI Responses APIx_search
Vercel AI SDKxai.tools.xSearch()

此工具也支持所有与 Responses API 兼容的 SDK。

基本用法 ​

python
import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",  # reasoning model
    tools=[x_search()],
    include=["verbose_streaming"],
)

chat.append(user("What are people saying about xAI on X?"))

is_thinking = True
for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
    if response.usage.reasoning_tokens and is_thinking:
        print(f"\\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
    if chunk.content and is_thinking:
        print("\\n\\nFinal Response:")
        is_thinking = False
    if chunk.content and not is_thinking:
        print(chunk.content, end="", flush=True)

print("\\n\\nCitations:")
print(response.citations)
python
import os
from openai import OpenAI

api_key = os.getenv("XAI_API_KEY")
client = OpenAI(
    api_key=api_key,
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "role": "user",
            "content": "What are people saying about xAI on X?",
        },
    ],
    tools=[
        {
            "type": "x_search",
        },
    ],
)

print(response)
javascript
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What are people saying about xAI on X?',
  tools: {
    x_search: xai.tools.xSearch(),
  },
});

console.log(text);
console.log('Citations:', sources);
bash
curl https://api.x.ai/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": "What are people saying about xAI on X?"
    }
  ],
  "tools": [
    {
      "type": "x_search"
    }
  ]
}'

X 搜索参数 ​

参数描述
allowed_x_handles仅考虑来自特定 X 帐号的帖子（最多 20 个）
excluded_x_handles排除来自特定 X 帐号的帖子（最多 20 个）
from_date搜索范围的开始日期（ISO8601 格式）
to_date搜索范围的结束日期（ISO8601 格式）
enable_image_understanding启用对帖子中图像的分析
enable_video_understanding启用对帖子中视频的分析

仅考虑来自特定帐号的帖子 ​

使用 allowed_x_handles 仅考虑来自给定 X 帐号列表的帖子。可以包含的最大帐号数为 20。

NOTE

allowed_x_handles 不能与 excluded_x_handles 在同一请求中设置。

python
import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(allowed_x_handles=["elonmusk"]),
    ],
)

chat.append(user("What is the current status of xAI?"))
# stream or sample the response...
python
response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "allowed_x_handles": ["elonmusk"],
        },
    ],
)
javascript
const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      allowedXHandles: ['elonmusk'],
    }),
  },
});

排除来自特定帐号的帖子 ​

使用 excluded_x_handles 防止模型在任何 X 搜索工具调用中包含来自指定帐号的 X 帖子。可以排除的最大帐号数为 20。

python
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(excluded_x_handles=["elonmusk"]),
    ],
)
python
response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "excluded_x_handles": ["elonmusk"],
        },
    ],
)
javascript
const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      excludedXHandles: ['elonmusk'],
    }),
  },
});

日期范围 ​

通过指定 from_date 和 to_date 可以限制搜索数据的日期范围。这将数据限制在从 from_date 到 to_date 的期间，包括两个日期。

两个字段都需要是 ISO8601 格式，例如 "YYYY-MM-DD"。如果您使用的是 xAI Python SDK，from_date 和 to_date 字段可以作为 datetime.datetime 对象传递。

python
import os
from datetime import datetime

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(
            from_date=datetime(2025, 10, 1),
            to_date=datetime(2025, 10, 10),
        ),
    ],
)

chat.append(user("What is the current status of xAI?"))
# stream or sample the response...
python
response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "from_date": "2025-10-01",
            "to_date": "2025-10-10",
        },
    ],
)
javascript
const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      fromDate: '2025-10-01',
      toDate: '2025-10-10',
    }),
  },
});

启用图像理解 ​

将 enable_image_understanding 设置为 true 可使代理在搜索过程中分析遇到的 X 帖子中的图像。

python
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(enable_image_understanding=True),
    ],
)
python
response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "Find X posts with images about AI"}],
    tools=[
        {
            "type": "x_search",
            "enable_image_understanding": True,
        },
    ],
)
javascript
const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'Find X posts with images about AI',
  tools: {
    x_search: xai.tools.xSearch({
      enableImageUnderstanding: true,
    }),
  },
});

启用视频理解 ​

将 enable_video_understanding 设置为 true 可使代理分析 X 帖子中的视频。此功能仅适用于 X 搜索（不适用于网页搜索）。

python
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(enable_video_understanding=True),
    ],
)
python
response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "Find X posts with videos about AI"}],
    tools=[
        {
            "type": "x_search",
            "enable_video_understanding": True,
        },
    ],
)
javascript
const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'Find X posts with videos about AI',
  tools: {
    x_search: xai.tools.xSearch({
      enableVideoUnderstanding: true,
    }),
  },
});

引用 ​

有关如何检索和使用搜索结果中的引用的详细信息，请参阅 引用 页面。

本文档为 docs.x.ai 全站中文翻译，由 AI 自动翻译生成。代码示例请以原文为准。

xAI 文档中文版 · 仅供学习参考