Vercel AI SDK, Multiple Providers: One App Contract, Multiple PathsVercel 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 accessVercel AI SDK 接入多个供应商：网关还是直连
The AI SDK supports three useful integration shapes. A plain creator/model string uses Vercel AI Gateway as the default provider; dedicated provider packages connect directly and expose provider-specific options; and createProviderRegistry() gives an application a central registry with identifiers in the providerId:modelId form. Custom providers can add aliases or preconfigured model settings on top of those adapters.
AI SDK 常见的接入方式有三种：直接使用 creator/model 字符串时，默认通过 Vercel AI Gateway；专用 Provider Package 负责直连并暴露供应商特定选项；createProviderRegistry() 则为应用建立中央注册表，以 providerId:modelId 形式引用模型。还可以用 Custom Provider 在这些适配器之上增加别名或预设模型配置。
Choose by control boundary rather than code brevity. Gateway access is useful when one credential, centralized usage and provider routing are desired. Direct packages fit workloads that depend on native parameters or separate commercial relationships. A registry is valuable when both approaches must coexist without scattering imports and model strings across request handlers.
选择时应看控制边界，而不是只比较代码长短。需要统一凭证、集中用量记录和供应商路由时，Gateway 更合适；依赖原生参数或独立商务关系的工作负载更适合专用 Package；如果两种方式必须共存，Registry 能避免在各个请求处理器中散落 Import 与模型字符串。
Whichever shape you choose, pin the registry and routing configuration, keep credentials on the server and preserve the resolved provider, model and adapter version in telemetry. A friendly alias must not hide a change in data path, policy or feature support.
无论选择哪种形态，都应固定注册表与路由配置，将凭证保留在服务端，并在遥测中记录最终解析出的供应商、模型和 Adapter 版本。便于使用的别名不能掩盖数据路径、策略或功能支持发生了变化。
Provider setup options供应商设置选项
| Option选项 | Best fit最适合 | Verify before choosing选择前验证 |
|---|---|---|
| AI GatewayAI 网关 | 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-compatibleOpenAI 兼容 | Reuse a compatible client shape.复用兼容客户端形状。 | Test tools, object output, streams, errors and usage semantics.测试工具、Object Output、流、错误与用量语义。 |
| Custom providerCustom 供应商 | 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测试每条供应商路径
A provider switch is safe only when the application-level contract still holds. Build fixtures around the AI SDK functions your product actually uses—text generation, streaming, structured output, embeddings and tools—and assert both normalized events and any provider-specific metadata the application depends on.
只有应用层契约仍然成立时，供应商切换才算安全。应围绕产品实际使用的 AI SDK 能力构建 Fixture，例如文本生成、流式输出、结构化输出、Embedding 与工具调用，同时验证标准化事件以及应用所依赖的供应商特定元数据。
- Run the same text, object, tool and streaming fixtures across direct, registry and gateway paths.
- Inject timeout, rate limit, partial stream, invalid structured output and malformed tool arguments.
- Verify one retry owner, a shared deadline and bounded provider or model fallback ordering.
- Compare time to first token, total latency, token accounting, cost attribution and finish reasons.
- Canary aliases and routing options, then keep the previous registry version ready for an immediate rollback.
- 在直连、Registry 和 Gateway 路径上运行同一组文本、Object、工具与流式 Fixture。
- 注入超时、限流、流中断、无效结构化输出和异常工具参数。
- 验证唯一重试负责人、共享截止时间，以及有界的供应商或模型故障切换顺序。
- 比较首 Token 延迟、总延迟、Token 统计、成本归因与结束原因。
- 灰度发布别名与路由选项，并保留旧 Registry 版本以便立即回滚。
Put a provider registry behind the application在应用后设置供应商注册表
Application code should call stable AI SDK functions with a workload alias such as support-fast or analysis-structured. A server-side registry resolves that alias to a gateway model string, dedicated provider model or compatible adapter plus its required middleware and options. The resolution should also return a policy snapshot and configuration version, not just a model object.
应用代码应通过 support-fast、analysis-structured 等工作负载别名调用稳定的 AI SDK 函数。服务端 Registry 再将别名解析为 Gateway 模型字符串、专用 Provider Model 或兼容 Adapter，并附上所需 Middleware 与选项。解析结果不能只有模型对象，还应包含策略快照与配置版本。
Keep gateway routing options such as provider ordering or restrictions in versioned configuration. On each response, preserve normalized AI SDK events alongside the requested alias, resolved model, actual provider endpoint, fallback history and provider-native evidence. This makes it possible to distinguish an application regression from a routing or provider change.
Provider 顺序、限制等 Gateway 路由选项应保存在版本化配置中。每次响应都应在 AI SDK 标准化事件之外，保留请求别名、解析模型、实际 Provider Endpoint、故障切换历史和供应商原生证据，从而区分应用回归、路由变化与供应商变化。
Production rule: never let a model string or alias silently change the provider, policy, feature contract or data path.
生产规则：绝不能让模型字符串或别名静默改变供应商、策略、功能契约或数据路径。
Add QVeris beside the AI SDK model interface在 AI SDK 模型接口旁增加 QVeris
The AI SDK and gateway handle model inference, while QVeris supplies external APIs, tools, services and live data through Discover → Inspect → Call. Keep those responsibilities explicit. Selecting a different language model should not automatically grant a new tool, change an API credential or bypass the approval required for an external action.
AI SDK 与 Gateway 处理模型推理，QVeris 则通过 Discover → Inspect → Call 提供外部 API、工具、服务与实时数据。两类职责必须清晰分开：更换语言模型不应自动授予新工具、替换 API 凭证，或绕过外部动作所需的审批。
Share the parent trace, tenant, deadline and policy snapshot so a single workflow can be reconstructed, but keep model and capability credentials, quotas and retry budgets separate. Before exposing a QVeris capability as an AI SDK tool, inspect its schema and permissions, validate the returned evidence and decide whether the action is safe to repeat after a model fallback.
双方可共享父 Trace、租户、截止时间和策略快照，以便还原完整工作流；但模型与能力的凭证、配额和重试预算应彼此独立。在把 QVeris 能力暴露为 AI SDK Tool 之前，应检查 Schema 与权限、验证返回证据，并判断模型故障切换后该动作是否可以安全重复。
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。
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 供应商。
不支持。验证当前模型与供应商能力矩阵。
放在一个选定网关或应用层，不要两层同时负责。