Vercel AI SDK, Multiple Providers: One App Contract, Multiple Paths Vercel AI SDK 接入多个供应商：一个应用契约，多条调用路径
The AI SDK can use gateway, dedicated or compatible providers. Keep provider configuration centralized, capabilities explicit and stream, tool, error and usage behavior under contract tests.
AI SDK 可以使用网关、专用或兼容供应商。集中管理供应商配置、显式表达能力，并对流、工具、错误与用量行为做契约测试。
TL;DR
Gateway simplifies access; dedicated adapters expose native controls.
Keep keys, base URLs, aliases and ownership outside UI code.
Tools, object output, streaming and provider options vary.
Assign routing and retry policy to one layer.
网关简化访问；专用适配器暴露原生控制。
让密钥、基础地址（Base URL）、别名与负责人远离 UI 代码。
工具、Object Output、流与供应商选项会变化。
把路由与重试策略交给一个层。
Vercel AI SDK with multiple providers: gateway or direct access Vercel AI SDK 接入多个供应商：网关还是直连
A gateway provider offers one model namespace and shared operations. Dedicated packages connect directly and may expose provider-specific options. A custom provider can implement another contract.
网关供应商提供一个模型命名空间与共享运营；专用 Package 直连并可能暴露供应商特定选项；Custom 供应商可实现另一种契约。
Whichever shape you choose, pin configuration, protect server-side credentials and preserve provider identity in telemetry.
无论选择何种形态，都应固定配置、保护服务端凭证，并在遥测中保留供应商身份。
Provider setup options 供应商设置选项
| Option 选项 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| AI Gateway AI 网关 | One integration and shared routing across supported models. 一次集成与跨支持模型的共享路由。 | Verify gateway options, data path, capabilities and native evidence. 验证网关选项、数据路径、能力与原生证据。 |
| Dedicated provider 专用供应商 | Native package and provider-specific controls. 原生 Package 与供应商特定控制。 | More dependencies, keys and operational paths to manage. 需要管理更多依赖、密钥与运营路径。 |
| OpenAI-compatible OpenAI 兼容 | Reuse a compatible client shape. 复用兼容客户端形状。 | Test tools, object output, streams, errors and usage semantics. 测试工具、Object Output、流、错误与用量语义。 |
| Custom provider Custom 供应商 | Implement a controlled application abstraction. 实现受控应用抽象。 | You own conformance, maintenance and failure behavior. 你负责一致性、维护与故障行为。 |
Provider registry checklist 供应商注册表检查
Load server-side keys by environment and provider scope.
Map workload names to versioned model and capability sets.
Handle text, tool, finish, error and usage events consistently.
Record provider, model, route, native ID and usage.
按环境与供应商范围加载服务端密钥。
把工作负载名称映射到版本化模型与能力集合。
一致处理文本、工具、结束、错误与用量事件。
记录供应商、模型、路由、原生 ID 与用量。
Test every provider path 测试每条供应商路径
- Run the same text, object, tool and streaming fixtures across providers.
- Inject timeout, rate limit, partial stream and malformed tool results.
- Verify one retry owner and bounded fallback ordering.
- Canary aliases and keep the previous registry version ready.
- 跨供应商运行相同文本、Object、工具与流 Fixture。
- 注入超时、限流、部分流与异常工具结果。
- 验证单一重试负责人及有界故障切换顺序。
- 灰度别名，并准备旧注册表版本。
Put a provider registry behind the application 在应用后设置供应商注册表
Application code calls stable AI SDK functions with a workload alias. The server registry resolves gateway, dedicated or compatible adapters. A response envelope preserves normalized events and provider-native evidence.
应用代码通过工作负载别名调用稳定 AI SDK 函数；服务端注册表解析网关、专用或兼容适配器；响应封装保留标准化事件与供应商原生证据。
Production rule: never let a model string silently change the provider, policy or data path.
生产规则：绝不能让模型字符串静默改变供应商、策略或数据路径。
Add QVeris beside the AI SDK model interface 在 AI SDK 模型接口旁增加 QVeris
The AI SDK and gateway handle model calls. QVeris supplies external APIs, tools, services and live data through Discover → Inspect → Call. Share trace context while keeping model and capability credentials separate.
AI SDK 与网关处理模型调用；QVeris 通过 Discover → Inspect → 调用提供外部 API、工具、服务与实时数据。共享调用链上下文，同时分离模型与能力凭证。
Create an explicit AI SDK provider registry 创建显式 AI SDK 供应商注册表
The AI SDK's OpenAI-compatible package creates named provider instances with independent base URLs and keys. Keep those instances in a server-only registry, map product workloads to stable aliases, and never allow a browser request to supply an arbitrary provider URL.
AI SDK 的 OpenAI Compatible 包可创建拥有独立基础地址（Base URL）与密钥的命名供应商实例。应把这些实例保存在仅服务端注册表中，将产品工作负载映射到稳定别名，并禁止浏览器请求传入任意供应商 URL。
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
const gateway = createOpenAICompatible({
name: 'qveris-gateway',
apiKey: process.env.LLM_GATEWAY_API_KEY!,
baseURL: process.env.LLM_GATEWAY_BASE_URL!,
includeUsage: true,
});
const models = {
fast: gateway(process.env.LLM_FAST_MODEL!),
quality: gateway(process.env.LLM_QUALITY_MODEL!),
} as const;
const result = await generateText({ model: models.fast, prompt: 'Reply AI_SDK_OK' });
console.log(result.text, result.usage);
- Resolve the alias on the server and reject unknown aliases.
- Contract-test tools, structured output, streaming, abort signals, and usage for each exact model.
- Log the registry version and chosen model with every request.
- 只在服务端解析别名，并拒绝未知别名。
- 针对每个准确模型契约测试工具、结构化输出、流式、Abort Signal 与用量。
- 每个请求都记录注册表版本与最终模型。
Verified implementation reference: AI SDK OpenAI-compatible provider.
实施参考已根据官方资料核验：AI SDK OpenAI-compatible provider。
Production Acceptance Checklist for Vercel AI SDK multiple-provider setupVercel AI SDK 多供应商配置生产验收清单
For Vercel AI SDK Providers, a successful hello-world call proves connectivity only. Production acceptance must prove that the framework contract, model behavior, failures, evidence, and rollback remain predictable under the application’s real workflows.
针对“Vercel AI SDK 多供应商”，Hello World 调用成功只能证明连接。生产验收还必须证明，在应用真实工作流中，框架契约、模型行为、失败处理、证据和回滚都保持可预测。
Version provider registry, model aliases, generate and stream APIs, tool schemas, structured output, middleware, usage normalization, and runtime deployment. Keep environment-specific secrets outside code, use stable internal model aliases, and document which layer owns transformations, retries, fallbacks, and timeout policy.
版本化供应商注册表、模型别名、Generate 与 Stream API、工具 Schema、结构化输出、中间件、用量规范化和运行时部署。把环境专属密钥放在代码之外，使用稳定内部模型别名，并记录转换、重试、故障切换和超时策略分别由哪一层负责。
To validate Vercel AI SDK Providers, cover system and user messages, long context, Unicode, streaming, structured output, tools, refusals, usage, cancellation, and provider errors. Store expected event order and required fields instead of checking text equality alone.
验证“Vercel AI SDK 多供应商”时，覆盖系统与用户消息、长上下文、Unicode、流式、结构化输出、工具、拒绝、用量、取消和供应商错误，保存预期事件顺序与必需字段，而不只比较文本是否相同。
To validate Vercel AI SDK Providers, test invalid credentials, unknown models, rate limits, slow first token, broken streams, malformed tool arguments, partial output, network loss, duplicate retries, and a provider outage. Confirm errors stay structured and side effects stay bounded.
验证“Vercel AI SDK 多供应商”时，测试无效凭证、未知模型、限流、首 Token 过慢、流中断、工具参数畸形、部分输出、网络丢失、重复重试和供应商中断，确认错误保持结构化且副作用范围受控。
Before rolling out Vercel AI SDK Providers, start with a reversible workflow, compare completion quality, latency, cost, and trace coverage, then expand by task class. Define rollback signals, preserve the previous configuration, and assign an owner for drift and incident review.
上线“Vercel AI SDK 多供应商”前，先选择可逆工作流，比较完成质量、延迟、成本和追踪覆盖，再按任务类别扩大。定义回滚信号，保留原配置，并明确负责漂移与事故复盘的人员。
FAQ
No. The AI SDK also supports dedicated, compatible and custom providers.
No. Verify the current model and provider capability matrix.
In one selected gateway or application layer, not both.
不必。AI SDK 也支持专用、兼容与 Custom 供应商。
不支持。验证当前模型与供应商能力矩阵。
放在一个选定网关或应用层，不要两层同时负责。