在 VoltAgent 模型路由中使用 v0 模型：快速接入、环境变量与源码级路由原理

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载导读v0 是 Vercel AI SDK 生态下的模型提供方其模型以v0/model形式接入 VoltAgent 的内置模型路由model router例如v0/v0-1.0-md。本文以 website/models-docs/providers/v0.md 为骨架完整覆盖 v0 的快速开始、环境变量、Base URL 覆盖与模型清单并结合 packages/core/src/registries/model-provider-registry.ts 的源码实现讲清楚v0/model字符串从解析、鉴权到最终调用ai-sdk/vercel的完整链路。读完本文你将能在 VoltAgent 中直接使用 v0 模型并能自行覆盖端点、排查缺少 API Key 之类的常见错误。v0 在 VoltAgent 模型注册表中的位置v0 是 VoltAgent 模型注册表MODEL_PROVIDER_REGISTRY中的一等公民。在 packages/core/src/registries/model-provider-registry.generated.ts 中可以看到它的完整注册条目v0: { id: v0, name: v0, npm: ai-sdk/vercel, env: [V0_API_KEY], doc: https://sdk.vercel.ai/providers/ai-sdk-providers/vercel, },该条目包含四个关键字段字段值作用idv0路由前缀即provider/model字符串中的provider部分namev0展示名称npmai-sdk/vercel运行时按需加载的 provider 包env[V0_API_KEY]鉴权所需的环境变量需要注意的是这份注册表文件与 website/models-docs/providers/v0.md 一样都是由 website/scripts/generate-model-docs.js 从 models.dev 数据源自动生成并随包发布的因此不需要手动编辑也不要手动安装 provider 包——VoltAgent 会在首次使用v0/model时按需加载。快速开始用v0/model创建 Agent原文档给出的最小示例非常简洁直接在Agent的model字段写入v0/model字符串即可import { Agent } from voltagent/core; const agent new Agent({ name: v0-agent, instructions: You are a helpful assistant, model: v0/v0-1.0-md, });这里不需要任何 provider 相关 import。模型字符串的解析发生在ModelProviderRegistry.splitModelIdmodel-provider-registry.ts它先按/拆分provider/model把v0归一化为小写 provider id再交给resolveLanguageModel完成加载splitModelId同时支持/与:两种分隔符v0/v0-1.0-md与v0:v0-1.0-md等价若字符串中没有分隔符或分隔后任一侧为空会抛出Invalid model id .... Use provider/model.错误provider 尚未注册时会抛出No provider registered for v0.并列出当前可用 provider。类型安全的模型 ID为了让model字段获得 IDE 自动补全与类型校验可以直接使用ModelRouterModelId类型定义见 packages/core/src/registries/model-provider-types.generated.tsimport type { ModelRouterModelId } from voltagent/core; const modelId: ModelRouterModelId v0/v0-1.0-md;该类型由ProviderModelsMap推导而来因此当你写错 v0 的模型名比如打成v0/v0-1.0-l时TypeScript 会在编译期直接报错。环境变量V0_API_KEYv0 只要求一个环境变量V0_API_KEY访问 v0 模型所需的 API Key。运行时ModelProviderRegistry会在加载 provider 时调用requireApiKeymodel-provider-registry.ts它从注册条目env中过滤出含KEY、TOKEN、SECRET的变量名并逐一探测。如果V0_API_KEY未设置或为空字符串会抛出明确错误Missing API key for v0. Set process.env.V0_API_KEY.这个错误信息由formatEnvList自动生成process.env.V0_API_KEY因此排查环境变量问题时直接按报错提示设置即可。在本地开发时建议将V0_API_KEY放入.env文件并在启动前加载在生产环境则通过进程环境注入。Provider 包ai-sdk/vercelv0 条目对应的 provider 包是ai-sdk/vercel。在PACKAGE_ADAPTERS映射表model-provider-registry.ts中ai-sdk/vercel对应buildVercelProvider适配器model-provider-registry.tsconst buildVercelProvider: ProviderAdapter (config, moduleExports) { const createFn getModuleFunction(moduleExports, createVercel); const providerExport resolveProviderExport(moduleExports, vercel); if (!createFn !providerExport) { throw new Error(Missing Vercel provider export in ${config.npm}.); } const apiKeyMatch requireApiKey(config); const baseURL resolveBaseUrl(config); return (createFn?.({ apiKey: apiKeyMatch.value, baseURL }) ?? providerExport) as ModelProviderEntry; };由此可以看到 v0 的底层调用链首次使用v0/model时createProviderLoader动态import(ai-sdk/vercel)model-provider-registry.tsbuildVercelProvider从模块中寻找createVercel或vercel导出从环境变量取 API KeyV0_API_KEY与 Base URL返回一个(modelId) LanguageModel工厂最终由resolveLanguageModel用v0-1.0-md等具体模型 ID 调用它。如果ai-sdk/vercel尚未安装加载失败时会得到提示Failed to load provider v0 from ai-sdk/vercel. Install the package and try again.在 VoltAgent 的 monorepo 中该依赖由 packages/core/package.json 声明实际使用时请确保你的应用能解析到这个包。默认 Base URL 与V0_BASE_URL覆盖原文档指出 v0 的默认 Base URL Not listed未在注册表中声明这与注册条目中缺少api字段是一致的。如果你需要把请求指向自定义端点可以通过设置V0_BASE_URL来覆盖。覆盖逻辑实现在resolveBaseUrlmodel-provider-registry.ts优先级如下注册条目env中名称匹配ENDPOINT/BASE_URL/BASEURL的变量值按惯例推导的${PROVIDER}_BASE_URL即V0_BASE_URL回退到注册条目中的api字段v0 未声明故回退为空。# 例如将 v0 请求转发到自建网关 export V0_API_KEYyour-key export V0_BASE_URLhttps://your-gateway.example.com/v1V0_BASE_URL的变量名由envKeyForProvider规则生成providerId.toUpperCase().replace(/-/g, _) _BASE_URLmodel-provider-registry.ts这也是文档中 You can override the base URL by settingV0_BASE_URL 一句的源码依据。可用模型清单当前仓库快照中v0 提供 3 个模型model-provider-types.generated.tsv0-1.0-mdv0-1.5-lgv0-1.5-md它们可直接作为v0/model使用例如v0/v0-1.0-md—— 适合轻量任务的紧凑模型v0/v0-1.5-md—— 中量级推理v0/v0-1.5-lg—— 需要更强能力的大模型此外在vercelprovider 的模型列表中也出现了v0-1.0-md与v0-1.5-mdmodel-provider-types.generated.ts说明这两类模型 ID 在 Vercel 生态中可互认——你可以按v0/...或vercel/...两种前缀使用路由行为由各自注册条目的 npm 包与环境变量决定。该模型清单由generate-model-docs.js从注册表快照自动生成并支持通过ModelProviderRegistry.refreshRegistry()拉取 models.dev 的最新数据刷新默认每 30 分钟自动刷新一次见 model-provider-registry.ts因此模型列表会随上游更新而演进具体以你当前安装版本为准。进阶用法在运行时动态选择 v0 模型model字段除了静态字符串还支持接收一个函数根据请求上下文动态决定模型。例如按调用方传入的 tier 在 v0 的不同型号间切换const agent new Agent({ name: v0-runtime-router, model: ({ context }) { const tier (context.get(tier) as string) || fast; return tier fast ? v0/v0-1.0-md : v0/v0-1.5-lg; }, });也可以把 v0 与其他 provider 混排在同一个工作流里——例如用v0/v0-1.0-md做高吞吐的实体抽取用更强模型做关键结论复核VoltAgent 的模型路由会按provider/model前缀自动分派到正确的 provider 适配器。常见问题排查Missing API key for v0. Set process.env.V0_API_KEY.V0_API_KEY未设置或为空按提示配置后重试。Failed to load provider v0 from ai-sdk/vercel. Install the package and try again.ai-sdk/vercel包未被解析安装或声明该依赖。Invalid model id v0. Use provider/model.模型字符串缺少/分隔符请写成v0/v0-1.0-md形式。需要自定义端点设置V0_BASE_URL覆盖默认 Base URL。需要更细粒度的 provider 控制也可以绕过字符串路由直接用 ai-sdk 的LanguageModel实例传入model字段例如通过createVercel(...)构造并附加自定义 headers此时注册表仅负责鉴权约定具体请求行为由你传入的实例决定。总结v0 接入 VoltAgent 的核心是一条注册表条目加一条环境变量注册表声明npm: ai-sdk/vercel与env: [V0_API_KEY]运行时通过buildVercelProvider适配器完成动态加载、鉴权与 Base URL 解析。你只需要写model: v0/v0-1.0-md即可使用配合V0_BASE_URL可灵活覆盖端点配合ModelRouterModelId可享受编译期类型校验。相关源码与生成脚本均可直接在 packages/core/src/registries/model-provider-registry.ts、packages/core/src/registries/model-provider-registry.generated.ts、packages/core/src/registries/model-provider-types.generated.ts 与 website/scripts/generate-model-docs.js 中进一步研读。赞分享人工智能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 接入 xAI Grok 模型模型路由、环境变量与源码级原理解析VoltAgent 接入 xAI Grok 模型模型路由、环境变量与源码级原理解析 xAI 是 VoltAgent 内置模型注册表中可直接调用的官方提供商之一人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音在 VoltAgent 模型路由中使用 Inceptioninception/mercury接入指南与源码级原理在 VoltAgent 模型路由中使用 Inceptioninception/mercury接入指南与源码级原理 本指南讲解如何在 VoltAgent 的人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音如何免费快速提升英语打字速度Qwerty Learner 新手入门教程如何免费快速提升英语打字速度Qwerty Learner 新手入门教程 Qwerty Learner 是一款免费开源的英语打字训练工具一边背单词一边锻炼英人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇Astro 中 Shiki 的 wrap 三态行为解析以 wrap-null 测试场景理解代码块换行与滚动下一篇Simple Live一款颠覆传统直播观看体验的开源神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考