VoltAgent 模型注册中心（Model Registry）完全指南：provider/model 零导入路由与 ai-sdk LanguageModel 高级用法

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载VoltAgent 内置了一个基于 models.dev 数据快照生成并随包分发的模型注册中心支持 80 个 Provider、2193 个模型。开发者只需使用provider/model形式的字符串即可完成模型路由无需为每个厂商单独安装 Provider 包当需要厂商专属能力如自定义请求头、推理强度控制时也可以直接传入 ai-sdk 的LanguageModel。读完本文你将掌握模型字符串的快速上手、类型安全的模型 ID、运行时动态选型、Provider 专属参数透传以及注册中心底层的自动刷新与环境变量解析机制。核心概念模型字符串与 LanguageModel 双通道VoltAgent 的模型接入遵循“两条通道”设计二者可在Agent配置中自由混用模型字符串Model strings形如openai/gpt-4.1-mini、anthropic/claude-3-5-haiku的provider/model标识。这是零导入路由通道——你不需要安装任何厂商 SDKVoltAgent 会在运行时按需加载对应 Provider 包。ai-sdkLanguageModel直接传入 Vercel AI SDK 生态的模型实例如mistral(mistral-small-latest)适合需要精细控制 Provider 行为、自定义 baseURL/headers 的场景。两条通道在类型层面被统一为AgentModelReference LanguageModel | ModelRouterModelId见 agent/types.ts因此Agent的model配置可以自由接受字符串或模型实例。快速开始零导入模型字符串在Agent的model字段直接写入provider/model字符串即可无需安装任何 Provider 包import { Agent } from voltagent/core; // OpenAI const openaiAgent new Agent({ name: openai-summary, instructions: Summarize the update in 2 bullets., model: openai/gpt-4.1-mini, }); // Anthropic const claudeAgent new Agent({ name: claude-notes, instructions: Turn notes into action items., model: anthropic/claude-3-5-haiku, }); // Google Gemini const geminiAgent new Agent({ name: gemini-translator, instructions: Translate to Turkish and keep tone friendly., model: google/gemini-2.0-flash, }); // xAI const grokAgent new Agent({ name: grok-ideas, instructions: Brainstorm five product names., model: xai/grok-3-mini, }); // OpenRouter注意路由前缀中包含厂商的嵌套格式 const openrouterAgent new Agent({ name: openrouter-agent, instructions: Answer in short paragraphs., model: openrouter/anthropic/claude-3.5-haiku, });字符串格式的底层解析规则模型字符串并非简单的“把字符串塞给 SDK”而是由注册中心统一解析。在 model-provider-registry.ts 的splitModelId中可以看到以第一个/分隔providerId与modelIdprovider/model若没有/则回退尝试provider:model冒号分隔格式分隔后任一侧为空或格式均不匹配会抛出Invalid model id .... Use provider/model. 的明确错误。也就是说provider/model字符串会被拆解为 Provider 标识与模型 ID再交由对应的 Provider 工厂构造真实的LanguageModel。Provider 目录与注册中心快照VoltAgent 的注册中心快照来自 models.dev每个 Provider 的独立页面如 openai.md包含用法示例、必需的环境变量、默认 base URL 说明以及从注册快照拉取的全部模型清单。这些文档与类型文件均由 generate-model-docs.js 自动生成其数据源是packages/core/src/registries/model-provider-registry.generated.ts与model-provider-types.generated.ts两个自动生成文件——这也解释了为什么文档中会标注“DO NOT EDIT MANUALLY”。常用 Provider 的环境变量速查Provider模型前缀必需环境变量OpenAIopenaiOPENAI_API_KEYAnthropicanthropicANTHROPIC_API_KEYGoogle GeminigoogleGOOGLE_GENERATIVE_AI_API_KEY或GEMINI_API_KEYxAIxaiXAI_API_KEYOpenRouteropenrouterOPENROUTER_API_KEYAmazon Bedrockamazon-bedrockAWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGIONAzureazureAZURE_RESOURCE_NAME、AZURE_API_KEYGoogle Vertexgoogle-vertexGOOGLE_VERTEX_PROJECT、GOOGLE_VERTEX_LOCATION、GOOGLE_APPLICATION_CREDENTIALSGroqgroqGROQ_API_KEYMistralmistralMISTRAL_API_KEYHugging FacehuggingfaceHF_TOKENGitHub Copilot / GitHub Modelsgithub-copilot/github-modelsGITHUB_TOKENDeepSeekdeepseekDEEPSEEK_API_KEYZhipu AIzhipuaiZHIPU_API_KEY完整 80 Provider 的环境变量矩阵可查阅 Providers overview。除表格所列还有 Cerebras、Cohere、Fireworks AI、Perplexity、Together AI、NVIDIA、硅基流动SiliconFlow、MiniMax、Moonshot AI、v0、Vercel AI Gateway、Weights Biases 等众多厂商。环境变量缺失时的精确报错注册中心“知道每个 Provider 期望哪些环境变量”并在运行时做精确校验。相关逻辑位于 model-provider-registry.tsrequireApiKey会先筛选出KEY/TOKEN/SECRET模式的环境变量名再逐一读取process.env若全部缺失会抛出类似下面的错误明确指出需要设置哪个变量Missing API key for openai. Set process.env.OPENAI_API_KEY.此外resolveBaseUrlmodel-provider-registry.ts支持两种 base URL 覆盖方式优先读取 env 列表中名称匹配ENDPOINT|BASE_URL|BASEURL的变量其次读取惯例命名PROVIDER_ID_BASE_URL例如OPENAI_BASE_URL最后才回退到注册快照中的默认api地址。类型安全的模型 IDModelRouterModelId直接手写字符串容易拼错模型名。VoltAgent 提供ModelRouterModelId类型为每个 Provider 枚举出快照中全部有效模型从而获得 IDE 自动补全与类型校验import type { ModelRouterModelId } from voltagent/core; const modelId: ModelRouterModelId openai/gpt-4.1-mini; // ✓ 合法 // const bad: ModelRouterModelId openai/not-a-real-model; // ✗ 编译报错该类型的实际定义由注册中心的类型生成器产出model-provider-registry.ts它遍历所有 Provider 的模型列表构造出${ProviderId}/${ProviderModelsMap[P][number]}的模板字面量联合类型并兜底(string {})以兼容快照更新前的旧字符串。同时ProviderForProvider、ProviderModelsMap等辅助类型也可用于更细粒度的泛型约束。在 agent.spec-d.ts 的类型测试中可以验证ModelRouterModelId对静态字符串、异步动态函数async () openai/gpt-4o-mini以及非法返回值如数字123的约束行为。拆分工作负载为不同步骤分配不同模型通过创建多个Agent可以把“高吞吐步骤”和“关键分析步骤”拆分到成本不同的模型上import { Agent } from voltagent/core; // 吞吐密集抽取实体与关键事实 const ingestAgent new Agent({ name: ingest-agent, instructions: Extract entities and key facts from raw notes., model: google/gemini-2.0-flash, }); // 关键分析审查总结并标记风险或缺口 const reviewAgent new Agent({ name: review-agent, instructions: Review the summary and flag risks or gaps., model: anthropic/claude-3-5-sonnet, });运行时动态选型按请求上下文路由模型Agent的model字段支持函数形式ModelDynamicValueT见 agent/types.ts可以根据每次请求的上下文动态决定模型——非常适合按租户、按套餐档位、按任务复杂度路由const agent new Agent({ name: runtime-router, model: ({ context }) { const tier (context.get(tier) as string) || fast; return tier fast ? openai/gpt-4.1-mini : anthropic/claude-3-5-sonnet; }, });AgentModelValueagent/types.ts进一步支持静态值、动态函数与模型回退列表AgentModelConfig[]三种形态其中回退列表中的每一项可配置id用于日志标识、model静态或动态引用、maxRetries与enabled开关。Provider 专属选项透传providerOptions当需要按请求传入厂商专属参数时可在调用方法如generateText的第二参数中通过providerOptions透传const analyst new Agent({ name: analyst, instructions: Explain tradeoffs clearly and concisely., model: openai/o3-mini, }); const response await analyst.generateText( Compare JWTs vs cookies for auth., { providerOptions: { openai: { reasoningEffort: high }, }, }, );providerOptions的键是 Provider 名称值为该 Provider 的 SDK 选项对象。从 agent/types.ts 的导入可以看出VoltAgent 直接复用ai-sdk/openai、ai-sdk/anthropic、ai-sdk/google、ai-sdk/xai等包导出的ProviderOptions类型确保reasoningEffort、temperature、thinking等参数获得类型提示。自定义请求头传入 ai-sdk LanguageModel如果需要自定义请求头如携带来源标识、调试信息模型字符串通道无法表达应直接构造 ai-sdk 的LanguageModel传给Agentimport { Agent } from voltagent/core; import { createOpenAICompatible } from ai-sdk/openai-compatible; const customProvider createOpenAICompatible({ name: openai, baseURL: https://api.openai.com/v1, apiKey: process.env.OPENAI_API_KEY, headers: { X-Client-Source: voltagent-docs, }, }); const agent new Agent({ name: custom-agent, model: customProvider(gpt-4o-mini), });注意VoltAgent 目前尚未内置模型回退链fallback chains。如需重试或故障转移请在应用层自行实现例如基于AgentModelConfig[]的maxRetries机制或自行捕获错误后切换到备用模型。直接使用 ai-sdk Provider 模块凡是 VoltAgent 期望LanguageModel的地方都可以直接使用任意 ai-sdk Provider 模块的模型实例import { mistral } from ai-sdk/mistral; import { Agent } from voltagent/core; const agent new Agent({ name: mistral-agent, model: mistral(mistral-small-latest), });这要求你自行安装对应的 ai-sdk Provider 包如ai-sdk/mistral适合需要模型字符串通道未覆盖的精细选项或使用社区自定义 Provider 的场景。底层原理注册中心的自动刷新与按需加载ModelProviderRegistrymodel-provider-registry.ts是单例实现其关键机制如下静态注册 动态刷新。构造时先注册STATIC_PROVIDER_REGISTRY自动生成的 providers 加上 Ollama、MiniMax 等 EXTRA 条目随后在非production环境下启动自动刷新默认每 30 分钟DEFAULT_AUTO_REFRESH_INTERVAL_MS 30 * 60 * 1000从https://models.dev/api.json拉取最新注册数据model-provider-registry.ts并将快照缓存到~/.voltagent/model-registry/provider-registry.json同时把生成的.d.ts类型文件写入缓存目录与voltagent/core的dist/registries下。按需懒加载 Provider 包。resolveLanguageModel(openai/gpt-4.1-mini)model-provider-registry.ts先拆解字符串再通过getProviderEntry触发生成 loaderloader 动态import(config.npm)对应 Provider 包并按 npm 包名分发到不同的适配器PACKAGE_ADAPTERS见 model-provider-registry.ts——例如ai-sdk/openai走buildApiKeyProvider、ai-sdk/openai-compatible走buildOpenAICompatibleProvider、ai-sdk/azure走buildAzureProvider、ai-sdk/amazon-bedrock走buildAmazonBedrockProvider。加载结果会被缓存同一 Provider 的并发请求会共享同一个 pending Promise避免重复加载model-provider-registry.ts。环境变量即配置。每个适配器从注册条目中读取env列表并映射到process.envAPI Key 类走requireApiKeyAzure 需要RESOURCE_NAMEBedrock 需要AWS_REGION/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEYVertex 需要PROJECT/LOCATIONWorkers AI 需要ACCOUNT_ID。若某个 Provider 包未安装loader 会抛出提示Install the package and try again的可读错误。实战建议优先使用模型字符串无额外依赖、开箱即用且注册快照已内置完整模型清单配合ModelRouterModelId享受类型安全动态选型服务多租户把model写成函数按context中的租户/套餐/任务类型返回不同模型兼顾成本与质量Provider 专属能力用providerOptions透传如reasoningEffort、thinking等厂商特有参数无需放弃字符串通道自定义请求头/私有网关必须用LanguageModel通过createOpenAICompatible等工厂自定义baseURL与headers可对接自建网关或兼容 OpenAI 协议的私有端点生产环境注意注册中心在生产模式下默认不做自动刷新模型清单以随包快照为准同时确认所需 Provider 的 npm 包已安装并检查注册文档中列出的全部环境变量。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐PyTorch Image Models模型注册MLflow Model Registry终极指南PyTorch Image Models模型注册MLflow Model Registry终极指南 PyTorch Image Models简称timm是人工智能计算机视觉深度学习预训练VoltAgent 接入 Groq用 groq/model 模型路由构建超快推理 AI Agentwith-groq-ai 示例全解VoltAgent 接入 Groq用 groq/model 模型路由构建超快推理 AI Agentwith groq ai 示例全解 VoltAgent人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音10 分钟上手res-downloader 代理嗅探下载网络资源完整教程10 分钟上手res downloader 代理嗅探下载网络资源完整教程 刷微信视频号看到一条 3 分钟的教程视频想存到本地却找不到保存按钮抖音、小红书的桌面应用网络音视频上一篇KMS_VL_ALL_AIO终极指南Windows与Office智能激活5大核心技术深度解析下一篇如何免费无限期使用IDM下载器一个安全又简单的解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考