AI SDK Gateway Provider 完全指南：用统一网关接入多厂商大模型-北京尧图网络

AI SDK Gateway Provider 完全指南用统一网关接入多厂商大模型【免费下载链接】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/aiAI SDK 的 Gateway Providerai-sdk/gateway是一个托管式统一网关允许通过单一 Provider 实例、以统一的模型 ID 约定如xai/grok-4.6、anthropic/claude-sonnet-5、openai/gpt-5.2访问 OpenAI、Anthropic、Google、DeepSeek、xAI 等数十家厂商的模型并附带智能路由、成本追踪、批量任务、实时语音等能力。读完本文你将掌握 Gateway Provider 的安装、认证配置、Provider 实例构建、全部模型能力接口、网关级路由选项、内置搜索工具以及错误处理体系可直接在 AI SDK 项目中落地使用。Gateway Provider 在 AI SDK 中的定位AI SDKThe AI Toolkit for TypeScript本身是框架无关的 LLM 应用构建库而 Provider 层负责把各家模型的私有 API 协议统一成标准接口。ai-sdk/gateway包当前仓库版本为 4.0.78见 packages/gateway/package.json实现的则是网关型 Provider它不直连某一家厂商而是把请求发送到托管网关https://ai-gateway.vercel.sh/v4/ai默认 baseURL源码见 gateway-provider.ts由网关侧完成模型路由、凭据管理、限流与用量统计。这意味着使用体验与普通 Provider 完全一致——你只需要一个 API Key就能在代码里同时切换 Grok、Claude、GPT、Gemini 等模型而无需为每家厂商单独申请凭据、单独初始化实例。该包依赖ai-sdk/provider与ai-sdk/provider-utils工作区内部依赖并内置了vercel/oidc以支持 Vercel 部署环境下的无密钥认证。安装与最小可用示例安装Gateway Provider 发布在ai-sdk/gateway模块下与ai核心包配合使用npm i ai-sdk/gateway仓库包声明要求 Node.js 22见 package.json且将zod声明为 peer dependency^3.25.76 || ^4.1.8主包会一并安装。最小示例import { gateway } from ai-sdk/gateway; import { generateText } from ai; const { text } await generateText({ model: gateway(xai/grok-4.6), prompt: Tell me about the history of the San Francisco Mission-style burrito., });调用前需配置 API Key见下节认证方式。gateway(xai/grok-4.6)返回一个标准的LanguageModelV4实例因此可以无缝用于generateText、streamText、generateObject以及useChat/useAssistant等 AI SDK 核心 API。为 Coding Agent 安装技能如果你使用 Claude Code、Cursor 等编码 Agent可以把 AI SDK 技能添加到仓库让 Agent 在写代码时自动遵循 SDK 的最佳实践npx skills add vercel/ai认证方式API Key 与 OIDC 自动降级getGatewayAuthToken的认证解析逻辑源码见 gateway-provider.ts遵循以下优先级显式传入的apiKey通过createGateway({ apiKey })提供环境变量AI_GATEWAY_API_KEY未显式传入时自动读取OIDC 令牌两者都缺失时在 Vercel 部署环境中通过vercel/oidc获取 OIDC 访问令牌getVercelOidcToken见 vercel-environment.ts实现无密钥部署。认证信息最终通过请求头发送Authorization: Bearer token ai-gateway-auth-method: api-key | oidc ai-gateway-protocol-version: 0.0.1 x-vercel-ai-gateway-team: teamIdOrSlug # 配置了 teamIdOrSlug 时其中ai-gateway-auth-method头由常量GATEWAY_AUTH_METHOD_HEADER定义见 gateway-headers.ts。若认证信息缺失会抛出GatewayAuthenticationError401。最典型的本地开发配置方式export AI_GATEWAY_API_KEYyour-gateway-api-key构建 Provider 实例createGateway 与默认实例包入口src/index.ts同时导出默认实例gateway和工厂函数createGatewaycreateGatewayProvider为兼容旧名的别名import { gateway, createGateway } from ai-sdk/gateway; // 方式一直接用默认实例读取环境变量 AI_GATEWAY_API_KEY const text await generateText({ model: gateway(openai/gpt-5.2), prompt: hi }); // 方式二按需定制配置 const gw createGateway({ apiKey: sk-..., teamIdOrSlug: my-team, });GatewayProviderSettings完整配置项如下定义见 gateway-provider.ts配置项类型默认值说明baseURLstringhttps://ai-gateway.vercel.sh/v4/aiAPI 请求基础地址可指向自托管网关apiKeystringAI_GATEWAY_API_KEY环境变量通过Authorization头发送的网关密钥或 Vercel Access TokenteamIdOrSlugstring无多团队访问令牌的团队 ID 或 slug通过x-vercel-ai-gateway-team头传递headersRecordstring, string无附加到每次请求的自定义头fetchFetchFunction全局 fetch自定义 fetch 实现可用于拦截请求或测试webSocketWebSocketConstructor全局 WebSocket流式转录使用的自定义 WebSocket 实现metadataCacheRefreshMillisnumber5 * 60 * 1000模型元数据缓存刷新间隔毫秒其中metadataCacheRefreshMillis控制getAvailableModels()结果的缓存时长源码中默认值为 5 分钟见 gateway-provider.ts_internal.currentDate仅供测试注入时间源。支持的模型能力矩阵GatewayProvider实现了 ProviderV4 规范模型 ID 采用厂商/模型约定语言模型 ID 全集定义在 gateway-language-model-settings.ts例如alibaba/qwen3-max、anthropic/claude-opus-5、deepseek/deepseek-v4-pro、google/gemini-3-pro-image、openai/gpt-5.2、spacexai/grok-4.6、zai/glm-5.2等GatewayModelId类型还带有(string {})逃生舱允许传入网关侧新上线的模型 ID。除文本对话外同一 Provider 还暴露了多种模态与高级能力方法定义见 gateway-provider.ts能力调用方式返回类型文本生成gateway(modelId)、gateway.chat(id)、gateway.languageModel(id)LanguageModelV4Embeddinggateway.embedding(id)、gateway.embeddingModel(id)EmbeddingModelV4图像生成gateway.image(id)、gateway.imageModel(id)ImageModelV4视频生成gateway.video(id)、gateway.videoModel(id)Experimental_VideoModelV4重排序gateway.reranking(id)、gateway.rerankingModel(id)RerankingModelV4语音合成gateway.speech(id)、gateway.speechModel(id)SpeechModelV4语音转写gateway.transcription(id)、gateway.transcriptionModel(id)TranscriptionModelV4实时对话实验gateway.experimental_realtime(id)RealtimeFactoryV4流式转录实验gateway.experimental_transcription(id)TranscriptionModelV4getToken批量任务实验gateway.experimental_batch()BatchV4{ text: GatewayModelId }例如同时使用文本与图像模型import { gateway } from ai-sdk/gateway; import { generateText, generateImage } from ai; // 文本 const { text } await generateText({ model: gateway(anthropic/claude-sonnet-5), prompt: Explain quantum entanglement simply., }); // 图像 const { image } await generateImage({ model: gateway(google/gemini-3.1-flash-image), prompt: A watercolor of a Mission-style burrito., });批量任务与幂等控制gateway.experimental_batch()提供异步批处理能力通过POST {baseURL}/batch/start提交一批文本生成请求返回网关侧 job id状态与结果均回查该 job实现见 gateway-batch.ts。批处理支持idempotencyKey幂等键——使用相同键重试不会创建重复批次并支持webhookUrl回调通知。Realtime 与流式转录的短期令牌机制experimental_realtime与experimental_transcription都提供了getToken()方法在服务端用网关长期凭据向/v1/realtime/client-secrets换取短期客户端密钥vcst_前缀浏览器只持有该短期令牌即可建立 WebSocket 连接网关凭据永远不会暴露给客户端。源码中通过assertGatewayClientSecretServerEnvironment强制该操作仅可在服务端执行见 gateway-provider.ts。令牌有效期默认 60 秒最长 300 秒expiresAfterSeconds。网关级路由与 Provider Options请求层面GatewayProviderOptions定义见 gateway-provider-options.ts通过 AI SDK 的providerOptions通道把网关侧的路由策略传给服务端常见用法import { gateway } from ai-sdk/gateway; import { generateText } from ai; const { text } await generateText({ model: gateway(anthropic/claude-sonnet-5), prompt: Write a haiku about Tokyo., providerOptions: { gateway: { only: [anthropic, openai], // 只允许这两个厂商 order: [anthropic, openai], // 按此顺序尝试 models: [anthropic/claude-sonnet-5, openai/gpt-5.2], // 回退模型 sort: cost, // 按成本/吞吐/首字延迟排序: cost | tps | ttft serviceTier: flex, // flex | priority caching: auto, // 自动缓存 disallowPromptTraining: true, // 禁止使用提示词训练 zeroDataRetention: true, // 仅使用零数据保留协议厂商 has: [vision], // 要求模型具备视觉/隐式缓存能力 tags: [prod], // 用量标签 user: user-123, // 终端用户标识 quotaEntityId: org-1, // 配额实体 byok: { anthropic: [...] }, // 请求级 BYOK 凭据 providerTimeouts: { byok: { anthropic: 3000 } }, // 单厂商超时(ms) }, }, });关键选项速查选项类型作用only/order/modelsstring[]分别限定可用厂商、厂商尝试顺序、回退模型列表sortcost \| tps \| ttft路由前按成本、每秒 token 数或首 token 延迟排序serviceTierflex \| priority统一服务层级意图cachingauto启用网关侧自动缓存disallowPromptTrainingboolean过滤不训练提示词的厂商zeroDataRetentionboolean过滤签署零数据保留协议的厂商hasArrayimplicit-caching \| vision限制为具备指定能力的模型idempotencyKeystring批处理幂等键tags/user/quotaEntityIdstring[] \| string用量标签、终端用户标识、配额实体网关内置搜索工具gateway.tools暴露了四个由网关服务端执行的搜索工具见 gateway-tools.tsexaSearch基于 Exa 的网页搜索返回面向 Agent 工作流优化的 token 高效摘录支持类型、领域、日期、位置等过滤parallelSearch基于 Parallel AI 的搜索 API接受自然语言目标单次调用即可替代多次关键词搜索支持深度与广度的权衡perplexitySearch基于 Perplexity 的实时信息、新闻、论文检索提供带排序的结果与领域、语言、日期范围过滤takoSearch在网页与 Tako 知识图谱中联合搜索返回结构化数据结果与可视化信息。这些工具可直接作为 AI SDK 的 tool 传给generateText/streamText的tools字段例如import { gateway } from ai-sdk/gateway; import { generateText } from ai; const { text } await generateText({ model: gateway(openai/gpt-5.2), tools: { search: gateway.tools.perplexitySearch }, prompt: Search for the latest Vercel AI Gateway pricing., });成本、用量与可观测性元数据与账户查询Provider 实例提供四个查询方法实现见 gateway-fetch-metadata.ts 与 gateway-spend-report.tsconst gw createGateway({ apiKey: process.env.AI_GATEWAY_API_KEY }); // 1. 网关可用模型列表含定价信息结果缓存 5 分钟 const { models } await gw.getAvailableModels(); // 2. 账户余额remaining balance / totalUsed const credits await gw.getCredits(); // 3. 消费报表按天/用户/模型/标签/厂商/凭据类型聚合 const report await gw.getSpendReport({ startDate: 2026-09-01, endDate: 2026-09-11, groupBy: model, }); // 4. 单次生成的明细成本、token、延迟、厂商 const info await gw.getGenerationInfo({ id: gen_xxx });getSpendReport的聚合维度支持day | user | model | tag | provider | credential_type并可组合userId、model、provider、credentialTypebyok | system、tags过滤结果行包含totalCost、marketCost、inputTokens、outputTokens、cachedInputTokens、cacheCreationInputTokens、reasoningTokens、requestCount等字段。Vercel 可观测性头当部署在 Vercel 上时Provider 会自动读取VERCEL_DEPLOYMENT_ID、VERCEL_ENV、VERCEL_REGION、VERCEL_PROJECT_ID环境变量见 gateway-provider.ts并为每次请求附加ai-o11y-deployment-id、ai-o11y-environment、ai-o11y-region、ai-o11y-request-id、ai-o11y-project-id头使网关侧可以按部署维度追踪流量请求 ID 来自x-vercel-id见 vercel-environment.ts。错误处理体系包内建了完整的错误类型体系导出见 src/index.ts类型定义在 src/errors/ 目录错误类型语义GatewayAuthenticationError认证失败 / 凭据缺失401GatewayForbiddenError无权限访问403GatewayNotFoundError资源不存在404GatewayModelNotFoundError指定模型 ID 不存在GatewayInvalidRequestError请求参数非法400GatewayRateLimitError触发限流GatewayTimeoutError请求超时GatewayFailedDependencyError上游依赖失败GatewayInternalServerError网关服务端错误500GatewayResponseError通用响应错误GatewayError所有网关错误的基础类型所有 API 调用生成、批处理、元数据、消费报表等在捕获底层错误后都会通过asGatewayError归一化并携带认证方式信息抛出见 errors/as-gateway-error.ts因此调用方可以统一捕获处理import { GatewayRateLimitError, GatewayModelNotFoundError } from ai-sdk/gateway; try { await generateText({ model: gateway(unknown/vendor-model), prompt: hi }); } catch (error) { if (error instanceof GatewayModelNotFoundError) { // 处理模型不存在 } else if (error instanceof GatewayRateLimitError) { // 退避重试 } }总结ai-sdk/gateway把 AI SDK 的多厂商接入收敛到一条网关链路一个createGateway()实例即可覆盖文本、图像、视频、语音、Embedding、重排序、实时对话与批量任务配合only/order/models/sort等路由选项实现模型回退与成本优化借助getCredits/getSpendReport/getGenerationInfo完成用量与成本核算并通过层次化的GatewayError体系保证错误可诊断。若需更深入地了解其实现可继续阅读 gateway-provider.tsProvider 工厂与认证、gateway-language-model.ts文本模型调用与流式、gateway-batch.ts批处理以及 src/errors/错误归一化等源码文件或参考同一仓库下其他 Provider 包如 packages/openai、packages/anthropic对比其接入模式。【免费下载链接】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辅助生成（AIGC），仅供参考

AI SDK Gateway Provider 完全指南：用统一网关接入多厂商大模型

相关推荐

Backstage v1.29.0 版本解析：新后端系统收敛、Root Health 服务与 Catalog 生态增强

Ultimate Vocal Remover 5.6 使用指南：把一首歌拆成人声与伴奏两条轨

面向 oh-my-posh 文档仓库的 Markdown 内容规范与 markdownlint-cli2 校验工作流

更多资讯

Roo Code 连接 LLM Provider 完全指南：从 API Key 到首个 AI Agent 任务

AI安全测试实战：从越狱到意图偏离，中小团队如何低成本守住底线

如何用 Terraform 在 AWS EC2 上部署 Infisical Relay Server 并完成认证配置？

Drawnix 完整指南：免费开源一体化白板，思维导图、流程图、自由手绘一站搞定

Elasticsearch 实战四周路线图：极客时间电子书 8 本书单与验收标准

AP9196宽压升降压模块实战解析：9-30V输入稳定输出10V/2.5A

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？