AI SDK xAI Grok Provider 接入指南：从安装到 Responses API 服务端工具-平芜编程栈

AI SDK xAI Grok Provider 接入指南：从安装到 Responses API 服务端工具

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai

导读

本文围绕 AI SDK（Vercel 出品的 TypeScript AI 工具包）中的xAI Grok Provider（@ai-sdk/xai包）展开，系统讲解如何在项目中安装接入 xAI 语言模型、创建与定制 Provider 实例、通过generateText与streamText完成文本生成，并深入覆盖基于 xAI Responses API 的服务端 Agentic 工具（网页搜索、X 搜索、代码执行、图像生成、MCP 等）以及语音、图像、视频等扩展能力。读完本文，你将掌握在 AI SDK 应用中完整接入并充分调用 xAI Grok 全系能力的实战方案。

一、xAI Grok Provider 概览

@ai-sdk/xai是 AI SDK 官方提供的 xAI Grok 模型接入包，为 xAI 的 Chat Completions API 与 Responses API 提供完整的语言模型支持。它不仅是文本生成入口，还是一个覆盖多模态能力的 Provider 工厂：语言模型（chat/responses）、图像生成（image）、视频生成（video）、语音合成（speech）、语音转写（transcription）、实时语音（experimental_realtime）、文件管理（files）与批处理（experimental_batch）均可在同一个 Provider 实例下创建。

从源码看，Provider 接口定义在 packages/xai/src/xai-provider.ts（XaiProvider接口，实现ProviderV4），包的默认导出与全部类型定义集中在 packages/xai/src/index.ts，包括createXai、xai以及全部服务端工具的工厂函数。

二、安装与前置准备

xAI Grok Provider 以@ai-sdk/xai模块发布，使用 npm 安装即可：

npm i @ai-sdk/xai

从 packages/xai/package.json 可以看到该包的运行时依赖只有@ai-sdk/provider与@ai-sdk/provider-utils两个工作区包（zod为 peer 依赖，要求^3.25.76 || ^4.1.8），因此安装体积很小，且sideEffects: false便于摇树优化。

为编码 Agent 添加 AI SDK 技能

如果你使用 Claude Code、Cursor 等编码 Agent 开发本项目，建议将 AI SDK 官方技能加入仓库，让 Agent 获得最新、最准确的 AI SDK 使用规范：

npx skills add vercel/ai

API Key 配置

Provider 默认从XAI_API_KEY环境变量读取 API Key。源码中通过loadApiKey加载：

优先使用createXai({ apiKey })传入的显式 Key；
否则读取XAI_API_KEY环境变量（见 xai-provider.ts）。

默认的 API Base URL 为https://api.x.ai/v1。

三、Provider 实例：默认导入与自定义创建

默认实例

@ai-sdk/xai导出了一个开箱即用的默认 Provider 实例xai：

import { xai } from '@ai-sdk/xai';

自定义实例

当需要定制 API Key、代理地址、自定义请求头或自定义fetch实现时，使用createXai创建：

import { createXai } from '@ai-sdk/xai'; const xai = createXai({ apiKey: 'your-api-key', });

支持的设置项

XaiProviderSettings（定义于 xai-provider.ts）支持以下可选配置：

配置项	类型	说明
`baseURL`	`string`	API 调用地址前缀，可用于指向代理服务器。默认`https://api.x.ai/v1`
`apiKey`	`string`	通过`Authorization`请求头发送的 API Key，默认取`XAI_API_KEY`环境变量
`headers`	`Record<string, string>`	附加到每个请求的自定义请求头
`fetch`	`FetchFunction`	自定义 fetch 实现，可作中间件拦截请求，或用于测试环境注入 mock
`webSocket`	`WebSocketConstructor`	自定义 WebSocket 实现。当运行时的原生 WebSocket 构造器不支持携带请求头（xAI 流式语音转写需要）时必填

底层实现中（xai-provider.ts），所有模型工厂共享同一套baseURL、getHeaders与fetch，并会为请求附加ai-sdk/xai/<VERSION>的 User-Agent 后缀。

四、语言模型：最小示例与两种 API

最小示例

xAI 语言模型可直接在 AI SDK 的generateText中使用：

import { xai } from '@ai-sdk/xai'; import { generateText } from 'ai'; const { text } = await generateText({ model: xai('grok-4.6'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', });

Responses API 与 Chat Completions API

自 AI SDK 7 起，xai(modelId)默认走xAI Responses API；如需使用较旧的 Chat Completions API，请显式调用xai.chat(modelId)。两种入口在 Provider 上均有对应工厂方法（源码见 xai-provider.ts）：

const modelA = xai('grok-4.6'); // 默认：Responses API const modelB = xai.responses('grok-4.6'); // 显式：Responses API const modelC = xai.chat('grok-4.6'); // 显式：Chat Completions API

模型 ID 联合类型定义在 xai-chat-language-model-options.ts 与 xai-responses-language-model-options.ts，当前包括grok-4.20-non-reasoning、grok-4.20-reasoning、grok-4.3、grok-4.5、grok-4.6、grok-latest，也支持以字符串形式传入任意可用模型 ID。

流式输出与结构化输出

语言模型同样可用于streamText实现流式输出，并可通过 AI SDK Core 的Output进行结构化数据生成（见 content/docs/03-ai-sdk-core）。

五、Provider 选项：推理强度、优先级处理与更多控制

xAI 特有的配置通过providerOptions.xai传入，并在请求组装阶段由 zod schema 校验（Chat 路径见 xai-chat-language-model-options.ts，Responses 路径见 xai-responses-language-model-options.ts）。

Reasoning Effort（推理强度）

对于支持可配置推理的模型，通过reasoningEffort控制模型"思考"的深度，两种 API 均适用：

import { xai } from '@ai-sdk/xai'; import { generateText } from 'ai'; const { text } = await generateText({ model: xai('grok-4.3'), prompt: 'Explain quantum entanglement.', providerOptions: { xai: { reasoningEffort: 'medium' }, }, });

可选值与适用场景：

'none'— 完全禁用推理，不消耗思考 token，适合追求近即时响应的简单场景；
'low'（默认）— 使用少量推理 token，速度快，适合通用 Agent 与工具调用；
'medium'— 更多思考，适合对延迟不敏感的复杂数据分析、长上下文推理；
'high'— 更深思考，适合复杂数学、多步逻辑与竞赛级任务；
'xhigh'— 最多推理 token，仅grok-4.6支持。

各模型支持的值与默认值不同：grok-4.3支持none/low/medium/high；grok-4.5仅支持low/medium/high且默认high，无法禁用推理；grok-4.6支持low/medium/high/xhigh且默认high；grok-4.20-reasoning与grok-4.20-non-reasoning不接受该选项；grok-4.20-multi-agent下low/medium/high控制的是 Agent 数量而非推理深度。具体请以 xAI 官方文档为准。

Priority Processing（优先级处理）

serviceTier: 'priority'可请求更高调度优先级，通常降低首 token 延迟并提升 token 间速度：

const { providerMetadata } = await generateText({ model: xai('grok-4.6'), prompt: 'Explain quantum entanglement.', providerOptions: { xai: { serviceTier: 'priority' }, }, }); // 实际生效的档位：'priority' 或 'default'（优先级容量不足时） console.log(providerMetadata?.xai?.serviceTier);

优先级请求按 token 收取溢价，且只有响应确认命中优先级档位时才会按该费率计费。因此务必从providerMetadata.xai.serviceTier读回实际生效档位，而非假设请求即结果。省略该选项等价于'default'。

其他选项

Chat Completions API：logprobs（返回输出 token 的对数概率）、topLogprobs（每 token 位置返回最可能的 0–8 个 token）、parallel_function_calling（并行函数调用，默认 true）；searchParameters（Live Search）已被 xAI 废弃，改用web_search/x_search工具。
Responses API：logprobs、topLogprobs、store（是否存储输入与响应以便检索，默认true；启用 Zero Data Retention 的团队必须设为false）、previousResponseId（续接上一次响应的会话）、include（如['file_search_call.results']携带文件搜索结果）、reasoningSummary（auto/concise/detailed）。

六、Responses API 服务端 Agentic 工具

xAI Responses API 的核心价值在于：模型可以在 xAI 服务器侧自主编排工具调用并完成研究，无需客户端逐轮驱动。全部服务端工具由xai.tools暴露，实现集中在 packages/xai/src/tool 目录，入口见 tool/index.ts。

注意：Responses API 只支持服务端工具，同一请求中不能混用服务端工具与客户端函数工具。

1. Web Search（网页搜索）

支持域名过滤与图片理解：

const { text, sources } = await generateText({ model: xai.responses('grok-4.6'), prompt: 'What are the latest developments in AI?', tools: { web_search: xai.tools.webSearch({ allowedDomains: ['arxiv.org', 'openai.com'], enableImageUnderstanding: true, }), }, }); console.log(text); console.log('Citations:', sources);

参数说明：

allowedDomains（string[]，最多 5 个）— 仅在这些域名内搜索，不能与excludedDomains同用；
excludedDomains（string[]，最多 5 个）— 排除指定域名，不能与allowedDomains同用；
enableImageSearch（boolean）— 允许模型在图片对答案有帮助时以独立图像搜索模式检索，响应可包含 Markdown 图片嵌入；
enableImageUnderstanding（boolean）— 允许模型查看并分析搜索到的图片，会增加 token 消耗。

2. X Search（X/Twitter 搜索）

按账号与日期范围检索 X 帖子：

const { text, sources } = await generateText({ model: xai.responses('grok-4.6'), prompt: 'What are people saying about AI on X this week?', tools: { x_search: xai.tools.xSearch({ allowedXHandles: ['elonmusk', 'xai'], fromDate: '2025-10-23', toDate: '2025-10-30', enableImageUnderstanding: true, enableVideoUnderstanding: true, }), }, });

参数说明：

allowedXHandles（最多 10 个）— 仅检索这些账号的帖子，不能与excludedXHandles同用；
excludedXHandles（最多 10 个）— 排除指定账号的帖子；
fromDate/toDate（ISO8601YYYY-MM-DD）— 帖子日期范围；
enableImageUnderstanding/enableVideoUnderstanding（boolean）— 是否分析帖子中的图片与视频。

3. Code Execution（代码执行）

让模型编写并执行 Python 代码完成计算与数据分析：

const { text } = await generateText({ model: xai.responses('grok-4.6'), prompt: 'Calculate the compound interest for $10,000 at 5% annually for 10 years', tools: { code_execution: xai.tools.codeExecution(), }, });

4. View Image / View X Video（图片与 X 视频分析）

// 分析图片 const { text } = await generateText({ model: xai.responses('grok-4.6'), prompt: 'Describe what you see in the image', tools: { view_image: xai.tools.viewImage() }, }); // 分析 X 帖子中的视频 const { text } = await generateText({ model: xai.responses('grok-4.6'), prompt: 'Summarize the content of this X video', tools: { view_x_video: xai.tools.viewXVideo() }, });

5. Image Generation（对话内图像生成）

模型自行决定何时调用、撰写图像提示词，并在文本回复的同时返回成品图（基于 Grok Imagine）：

const result = await generateText({ model: xai.responses('grok-4.6'), prompt: 'Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print', tools: { image_generation: xai.tools.imageGeneration(), }, }); for (const toolResult of result.staticToolResults) { if (toolResult.toolName === 'image_generation') { const base64Image = toolResult.output.result; } }

action参数（默认'auto'）可限制能力：'generate'仅文生图、'edit'仅编辑对话内已有图片（含模型先前生成的图片）、'auto'两者皆可。工具结果中还包含模型为图像模型撰写的提示词，便于理解与调试。

6. MCP Server（远程 MCP 连接）

连接远程 Model Context Protocol 服务器并使用其工具：

const { text } = await generateText({ model: xai.responses('grok-4.6'), prompt: 'Use the weather tool to check conditions in San Francisco', tools: { weather_server: xai.tools.mcpServer({ serverUrl: 'https://example.com/mcp', serverLabel: 'weather-service', serverDescription: 'Weather data provider', allowedTools: ['get_weather', 'get_forecast'], }), }, });

参数说明：serverUrl（必填）为远程 MCP 地址；serverLabel/serverDescription用于标识与描述服务器；allowedTools限制模型可用的工具名列表，不传则全部可用；headers与authorization用于携带自定义请求头与鉴权信息（如'Bearer token123'）。

7. File Search（向量库文档检索）

在 xAI 向量库（collections）中检索文档：

import { xai, type XaiLanguageModelResponsesOptions } from '@ai-sdk/xai'; import { streamText } from 'ai'; const result = streamText({ model: xai.responses('grok-4.6'), prompt: 'What documents do you have access to?', tools: { file_search: xai.tools.fileSearch({ vectorStoreIds: ['collection_your-collection-id'], maxNumResults: 10, }), }, providerOptions: { xai: { include: ['file_search_call.results'], } satisfies XaiLanguageModelResponsesOptions, }, });

vectorStoreIds（必填）指定要检索的向量库 ID；maxNumResults限制返回条数。通过providerOptions.xai.include = ['file_search_call.results']可让响应携带带分数与内容的实际检索结果。该工具要求 grok-4 家族模型（含 grok-4.20）与 Responses API。

8. 多工具组合与流式消费

多个服务端工具可组合完成综合研究，配合streamText流式消费文本与引用来源：

import { xai } from '@ai-sdk/xai'; import { streamText } from 'ai'; const { stream } = streamText({ model: xai.responses('grok-4.6'), prompt: 'Research AI safety developments and calculate risk metrics', tools: { web_search: xai.tools.webSearch(), x_search: xai.tools.xSearch(), code_execution: xai.tools.codeExecution(), file_search: xai.tools.fileSearch({ vectorStoreIds: ['collection_your-documents'], }), data_service: xai.tools.mcpServer({ serverUrl: 'https://data.example.com/mcp', serverLabel: 'data-service', }), }, }); for await (const part of stream) { if (part.type === 'text-delta') { process.stdout.write(part.text); } else if (part.type === 'source' && part.sourceType === 'url') { console.log('\nSource:', part.url); } }

七、视觉能力：图像输入与分辨率控制

Responses API 支持向视觉模型输入图片：

import { xai } from '@ai-sdk/xai'; import { generateText } from 'ai'; const { text } = await generateText({ model: xai.responses('grok-4.6'), messages: [ { role: 'user', content: [ { type: 'text', text: 'What do you see in this image?' }, { type: 'file', mediaType: 'image', data: fs.readFileSync('./image.png'), }, ], }, ], });

可在图片 part 上通过providerOptions.xai.imageDetail控制解析分辨率：'low'（降分辨率处理、消耗更少输入 token）、'high'（全分辨率）、'auto'（由 xAI API 决定）；不设置时按全分辨率处理。

八、语音能力：语音合成与语音转写

Speech（文本转语音）

xAI 的 TTS 端点不要求模型 ID，直接xai.speech()创建模型：

import { xai } from '@ai-sdk/xai'; import { generateSpeech } from 'ai'; const result = await generateSpeech({ model: xai.speech(), text: 'Hello from the AI SDK!', voice: 'ara', language: 'en', outputFormat: 'mp3', speed: 1.1, });

支持的参数：

text（必填）— 可内嵌 xAI 语音标签，如[pause]、[laugh]、<whisper>...</whisper>；
voice— 默认'eve'，内置'eve'/'ara'/'rex'/'sal'/'leo'，也接受自定义 voice ID；
language— BCP-47 语言码或'auto'自动检测，默认'auto'；
speed— 语速倍率，范围0.7–1.5；
outputFormat—'mp3'/'wav'/'pcm'/'mulaw'/'alaw'，默认'mp3'。

Provider 选项（providerOptions.xai，类型XaiSpeechModelOptions）包括sampleRate（8000–48000 Hz）、bitRate（32000–192000，仅 mp3）、optimizeStreamingLatency（0/1/2）、textNormalization、withTimestamps（返回字符级时间轴）、replace（发音替换映射，支持重拼或 IPA 音标）。结果元数据在providerMetadata.xai中：traceId、duration、contentType与audioTimestamps（逐字符对齐数据）。

Transcription（语音转文本）

批量转写端点同样不需要模型 ID：

import { xai } from '@ai-sdk/xai'; import { transcribe } from 'ai'; import { readFile } from 'fs/promises'; const result = await transcribe({ model: xai.transcription(), audio: await readFile('meeting.mp3'), providerOptions: { xai: { language: 'en', format: true, keyterm: ['AI SDK', 'Grok'], diarize: true, } satisfies XaiTranscriptionModelOptions, }, });

Provider 选项包括：audioFormat（pcm/mulaw/alaw）、sampleRate、language（配合format做反向文本归一化）、multichannel与channels（2–8 声道交错音频）、diarize（说话人分离）、keyterm（术语偏置）、fillerWords（是否包含uh/um等填充词），以及streaming子选项（供experimental_streamTranscribe走 WebSocket 流式识别：interimResults中途结果、endpointing0–5000ms 静音判定、smartTurn0.0–1.0 结束检测阈值、smartTurnTimeout1–5000ms 强制结束静音上限）。逐词时间戳、说话人标签与分段仅在请求/响应路径（transcribe）返回。

九、图像生成模型

通过xai.image()工厂创建图像模型，配合generateImage使用：

import { xai } from '@ai-sdk/xai'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: xai.image('grok-imagine-image'), prompt: 'A futuristic cityscape at sunset', });

要点：

xAI 图像模型不支持size参数，改用aspectRatio，支持1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20与auto；
编辑能力：通过prompt.images传入输入图（支持Buffer/ArrayBuffer/Uint8Array/base64 字符串），用文本描述变换目标；不支持蒙版，编辑完全由提示词驱动；
Provider 选项（XaiImageModelOptions）：resolution（'1k'约 1024×1024 /'2k'约 2048×2048，2k仅grok-imagine-image-pro）、quality（'low'/'medium'/'high'）。

十、视频生成模型

xai.video()工厂支持文生视频、图生视频、视频编辑、视频续写与参考图转视频（R2V）五种操作，配合experimental_generateVideo使用（注意：视频生成是异步任务，可能耗时数分钟，建议将pollTimeoutMs设为至少 600000ms，且生成的视频 URL 是临时的，应及时下载）。

文生视频

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: xai.video('grok-imagine-video'), prompt: 'A chicken flying into the sunset in the style of 90s anime.', aspectRatio: '16:9', duration: 5, providerOptions: { xai: { user: 'user-123', pollTimeoutMs: 600000, // 10 minutes } satisfies XaiVideoModelOptions, }, });

视频编辑与链式并发编辑

mode: 'edit-video'+videoUrl编辑现有视频（输入上限 8.7 秒，输出继承输入属性并被限制在 720p）。xAI 托管的输出 URL 位于providerMetadata.xai.videoUrl，可据此串联多次编辑或用Promise.all并发分支编辑。

视频续写

mode: 'extend-video'+videoUrl从源视频最后一帧续写，duration只控制续写片段的长度，宽高比与分辨率继承自源视频。

参考图转视频（R2V）

mode: 'reference-to-video'+referenceImageUrls（1–7 张，HTTPS URL 或 base64 data URI），提示词中用<IMAGE_1>、<IMAGE_2>引用图片；也可用 Provider 无关的顶层inputReferences选项（自动进入 R2V 模式，接受文件数据或{ type: 'url', url }）。referenceVoiceIds最多传 3 个 xAI 预设语音 ID（不能用自有音频），用<AUDIO_0>/<AUDIO_1>/<AUDIO_2>在提示词中引用——该能力目前仅限美国地区可信合作伙伴。

视频 Provider 选项与分辨率

pollIntervalMs（默认 5000）/pollTimeoutMs（默认 600000）— 任务轮询间隔与最长等待；
resolution—'480p'/'720p'/'1080p'；SDK 标准参数1920x1080/1280x720/854x480会自动映射到对应档位；1080p原生支持需grok-imagine-video-1.5，R2V 最高720p（1080p请求会被降级并告警）；
mode—'edit-video'/'extend-video'/'reference-to-video'，互斥，省略时走标准生成；
user— 终端用户标识，xAI 用于滥用监控，建议使用不透明稳定标识。

十一、批处理、实时语音与更多工厂方法

Batch（实验性）：xai.experimental_batch()提供异步文本生成批处理能力，配合 AI SDK 的 Batch API 使用；同一批次内可使用不同的文本模型。注意 xAI Batch API 不支持按批次 webhook，传入webhookUrl时会收到 unsupported 告警并照常启动批次。
Realtime（实验性）：xai.experimental_realtime('grok-voice-latest')创建实时语音模型。会话运行在浏览器端，需先在服务端通过xai.experimental_realtime.getToken({ model: 'grok-voice-latest' })获取短期令牌，完整接入模式见 content/docs/03-ai-sdk-core 的 Realtime 章节。
Files：xai.files()提供文件上传接口，实现见 packages/xai/src/files。
嵌入模型：embeddingModel/textEmbeddingModel会抛出NoSuchModelError，即当前 xAI Provider 不提供嵌入能力（见 xai-provider.ts）。

十二、模型能力速查

语言模型

模型	图像输入	对象生成	工具调用	工具流式	推理
`grok-4.6`	✅	✅	✅	✅	✅
`grok-4.5`	✅	✅	✅	✅	✅
`grok-4.20-reasoning`	✅	✅	✅	✅	✅
`grok-4.20-non-reasoning`	✅	✅	✅	✅	❌
`grok-3`	❌	✅	✅	✅	❌
`grok-3-mini`	❌	✅	✅	✅	✅

（更多模型请查阅 xAI 官方文档，也可将任意可用模型 ID 以字符串传入。）

图像模型

模型	分辨率	宽高比	图像编辑
`grok-imagine-image-pro`	`1k`、`2k`	全套 13 种 +`auto`	✅
`grok-imagine-image`	`1k`	全套 13 种 +`auto`	✅

视频模型

模型	时长	分辨率	图生视频	编辑	续写	R2V
`grok-imagine-video`	1–15s	`480p`、`720p`	✅	✅	✅	✅
`grok-imagine-video-1.5`	1–15s	`480p`、`720p`、`1080p`*	✅	✅	✅	✅

（*原生1080p适用于文生视频与图生视频，R2V 上限720p。）

十三、进一步探索

Provider 完整实现：packages/xai/src/xai-provider.ts
公开导出与类型：packages/xai/src/index.ts
Chat 语言模型实现与选项校验：xai-chat-language-model.ts、xai-chat-language-model-options.ts
Responses 语言模型实现与选项校验：packages/xai/src/responses/xai-responses-language-model.ts、xai-responses-language-model-options.ts
服务端工具集合：packages/xai/src/tool
官方配套文档：content/providers/01-ai-sdk-providers/01-xai.mdx
完整测试用例（含流式输出、工具调用、错误处理等快照）：xai-chat-language-model.test.ts、xai-responses-language-model.test.ts

结合 AI SDK 的核心 API（generateText、streamText、generateSpeech、transcribe、generateImage、experimental_generateVideo），@ai-sdk/xai让你能以统一接口调用 xAI 的文本、搜索、代码执行、图像、视频与语音全栈能力，是构建多模态 AI 应用与自主 Agent 的实用选择。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考