介绍
# xAI Grok Search
使用 xAI 的 Grok API 搜索互联网和 X (Twitter)，具备实时互联网接入、引用来源以及可选的图像/视频理解功能。
## 何时使用此技能
### 使用网络搜索适用于： - 来自网站、新闻文章、文档的最新信息 - 实时数据（股价、天气、近期事件） - 具有最新网络资源的研究主题 - 查找来自特定网站/域名的信息 - 验证当前事实
### 使用 X 搜索适用于： - 人们在 X/Twitter 上对某个话题的讨论 - 热门讨论和社交情绪 - 对事件的实时反应 - 来自特定 X 帐号/用户的帖子 - 特定日期范围内的近期社交媒体活动
**请勿用于：** - 不会改变的历史事实 - 已有的通用知识 - 数学计算 - 代码生成 - 创意写作
## 设置
### 所需环境变量
```bash export XAI_API_KEY="your-xai-api-key-here" ```
从以下网址获取您的 API 密钥：https://console.x.ai/
## 用法
代理将根据用户的查询自动选择合适的工具：
**用户：**“关于 AI 监管有什么最新新闻？” → 使用 `web_search`
**用户：**“人们在 X 上对 OpenAI 有什么评价？” → 使用 `x_search`
## API 参考
### 函数：search_web
使用 xAI 的 Grok API 搜索网络。
**参数：** - `query`（必需）：搜索查询字符串 - `model`（可选）：要使用的模型（默认："grok-4-1-fast-reasoning"） - `allowed_domains`（可选）：限制搜索的域名数组（最多 5 个） - `excluded_domains`（可选）：排除的域名数组（最多 5 个） - `enable_image_understanding`（可选）：启用图像分析（默认：false）
**返回：** - `content`：搜索响应文本 - `citations`：包含 url、title 和 snippet 的来源数组 - `usage`：令牌使用统计信息
### 函数：search_x
使用 xAI 的 Grok API 搜索 X (Twitter)。
**参数：** - `query`（必需）：搜索查询字符串 - `model`（可选）：要使用的模型（默认："grok-4-1-fast-reasoning"） - `allowed_x_handles`（可选）：要搜索的 X 帐号数组（最多 10 个，不含 @） - `excluded_x_handles`（可选）：要排除的 X 帐号数组（最多 10 个，不含 @） - `from_date`（可选）：ISO8601 格式的开始日期 (YYYY-MM-DD) - `to_date`（可选）：ISO8601 格式的结束日期 (YYYY-MM-DD) - `enable_image_understanding`（可选）：启用图像分析（默认：false） - `enable_video_understanding`（可选）：启用视频分析（默认：false）
**返回：** - `content`：搜索响应文本 - `citations`：包含 url、title 和 snippet 的 X 帖子数组 - `usage`：令牌使用统计信息
## 实现
此技能使用 xAI Responses API (`/v1/responses` 端点)。
### 网络搜索
```javascript async function search_web(options) { const { query, model = 'grok-4-1-fast-reasoning', allowed_domains, excluded_domains, enable_image_understanding } = options;
const tool = { type: 'web_search' }; if (allowed_domains) tool.allowed_domains = allowed_domains; if (excluded_domains) tool.excluded_domains = excluded_domains; if (enable_image_understanding) tool.enable_image_understanding = true;
const response = await fetch('https://api.x.ai/v1/responses', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.XAI_API_KEY}` }, body: JSON.stringify({ model, input: [{ role: 'user', content: query }], tools: [tool] }) });
const data = await response.json(); return { content: data.output[data.output.length - 1].content, citations: data.citations }; } ```
### X 搜索
```javascript async function search_x(options) { const { query, model = 'grok-4-1-fast-reasoning', allowed_x_handles, excluded_x_handles, from_date, to_date, enable_image_understanding, enable_video_understanding } = options;
const tool = { type: 'x_search' }; if (allowed_x_handles) tool.allowed_x_handles = allowed_x_handles; if (excluded_x_handles) tool.excluded_x_handles = excluded_x_handles; if (from_date) tool.from_date = from_date; if (to_date) tool.to_date = to_date; if (enable_image_understanding) tool.enable_image_understanding = true; if (enable_video_understanding) tool.enable_video_understanding = true;
const response = await fetch('https://api.x.ai/v1/responses', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.XAI_API_KEY}` }, body: JSON.stringify({ model, input: [{ role: 'user', content: query }], tools: [tool] }) });
const data = await response.json(); return { content: data.output[data.output.length - 1].content, citations: data.citations }; } ```
## 示例
### 网络搜索 - 当前事件 ```javascript const result = await search_web({ query: "latest AI regulation developments" }); ```
### 网络搜索 - 特定域名 ```javascript const result = await search_web({ query: "UN climate summit latest", allowed_domains: ["un.org", "gov.uk", "grokipedia.com"] }); ```
### X 搜索 - 社交情绪 ```javascript const result = await search_x({ query: "new iPhone reactions opinions" }); ```
### X 搜索 - 特定帐号 ```javascript const result = await search_x({ query: "AI thoughts", allowed_x_handles: ["elonmusk", "cstanley"], from_date: "2025-01-01" }); ```
### X 搜索 - 包含媒体 ```javascript const result = await search_x({ query: "Mars landing images", enable_image_understanding: true, enable_video_understanding: true }); ```
## 最佳实践
### 网络搜索 - 使用 `allowed_domains` 将搜索限制在特定域名（最多 5 个） - 使用 `excluded_domains` 排除已知的不良来源（最多 5 个） - 不能同时使用两者 - 仅在需要时启用图像理解
### X 搜索 - 使用 `allowed_x_handles` 专注于特定帐号（最多 10 个） - 使用 `excluded_x_handles` 过滤噪声（最多 10 个） - 不能同时使用两者 - 帐号名中不要包含 @ 符号 - 使用 ISO8601 日期格式：YYYY-MM-DD - 媒体理解功能会增加 API 成本
## 故障排除
### “未找到 XAI_API_KEY” ```bash export XAI_API_KEY="your-key-here" ```
### 速率限制 - 实现指数退避 - 缓存频繁查询
### 结果不佳 - 添加域名/帐号过滤器 - 使查询更具体 - 缩小日期范围
### 响应缓慢
使用推理模型（例如 `grok-4-1-fast-reasoning`）的搜索查询可能需要 30-60 秒或更长时间才能返回，尤其是当模型执行多次网络或 X 搜索时。如果搜索滞后，请告知用户结果仍在加载中，并让他们输入 **“poll”** 以检查完成的响应。
## API 文档
- 网络搜索：https://docs.x.ai/developers/tools/web-search - X 搜索：https://docs.x.ai/developers/tools/x-search