VoltAgent 接入 ZenMux：通过 OpenAI 兼容适配器用 `zenmux/＜model＞` 统一路由多厂商大模型

人工智能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 内置模型路由器Model Router支持以provider/model的形式引用任意已注册的模型提供方ZenMux 正是其中一家通过ai-sdk/openai-compatible适配器接入的聚合网关。本文基于 VoltAgent 仓库中的 ZenMux 提供方文档website/models-docs/providers/zenmux.md与 ModelProviderRegistry 源码完整讲解如何配置ZENMUX_API_KEY、覆盖默认 Base URL、在 Agent 中引用 ZenMux 的 51 个模型并深入剖析模型路由器底层是如何解析、加载并缓存该提供方的。读完本文你将能够在 VoltAgent 中快速启用 ZenMux并理解这套零配置前缀 OpenAI 兼容适配器的接入机制。ZenMux 在 VoltAgent 中的定位ZenMux 是一个聚合型模型网关通过单一 API 端点暴露 Anthropic、DeepSeek、Google Gemini、OpenAI、xAI、智谱 GLM、Kimi、MiniMax 等多家厂商的模型。在 VoltAgent 中它的接入方式与其他OpenAI 兼容提供方完全一致模型前缀zenmux即用zenmux/model引用其模型适配器ai-sdk/openai-compatible提供的createOpenAICompatible默认端点https://zenmux.ai/api/v1Base URL 值可通过ZENMUX_BASE_URL覆盖认证环境变量ZENMUX_API_KEY。上述元数据被固化在自动生成的注册表条目中packages/core/src/registries/model-provider-registry.generated.ts#L610-L617运行时由ModelProviderRegistry统一消费zenmux: { id: zenmux, name: ZenMux, npm: ai-sdk/openai-compatible, api: https://zenmux.ai/api/v1, env: [ZENMUX_API_KEY], doc: https://docs.zenmux.ai, },也就是说ZenMux 并不需要专门的原生 provider 包而是走通用 OpenAI 兼容通道这也是 VoltAgent 支持数百家提供方的关键设计之一。快速开始三步启用 ZenMux1. 安装依赖ZenMux 的适配器包是ai-sdk/openai-compatible。从注册表的npm字段可以确认运行时加载器会执行import(config.npm)来动态引入该包model-provider-registry.ts#L827-L851因此使用前需要先安装它npm install voltagent/core ai-sdk/openai-compatible # 或 pnpm / yarn 安装上述两个包2. 配置环境变量在.env或运行环境中设置# 必填ZenMux API Key ZENMUX_API_KEYyour-zenmux-api-key # 可选覆盖默认 Base URL默认 https://zenmux.ai/api/v1 # ZENMUX_BASE_URLhttps://custom.zenmux.endpoint/api/v1如果未设置ZENMUX_API_KEY运行时会在加载 provider 时抛出明确错误Missing API key for zenmux. Set process.env.ZENMUX_API_KEY.见 model-provider-registry.ts#L517-L524。3. 在 Agent 中引用模型直接以zenmux/model作为model字段值即可与文档 Quick start 一致import { Agent } from voltagent/core; const agent new Agent({ name: zenmux-agent, instructions: You are a helpful assistant, model: zenmux/anthropic/claude-haiku-4.5, });例如上面的配置会通过 ZenMux 网关调用 Anthropic 的 Claude Haiku 4.5。若参照 examples/base/src/index.ts 的完整形态还可以在同一 Agent 上叠加记忆、向量检索、日志与 HTTP 服务import { Agent, Memory, VoltAgent } from voltagent/core; import { LibSQLMemoryAdapter, LibSQLVectorAdapter } from voltagent/libsql; import { createPinoLogger } from voltagent/logger; import { honoServer } from voltagent/server-hono; const agent new Agent({ name: zenmux-agent, instructions: You are a helpful assistant., model: zenmux/anthropic/claude-haiku-4.5, memory: new Memory({ storage: new LibSQLMemoryAdapter(), embedding: openai/text-embedding-3-small, vector: new LibSQLVectorAdapter(), }), }); new VoltAgent({ agents: { agent }, server: honoServer(), logger: createPinoLogger({ name: zenmux-base, level: info }), });环境变量与 Base URL 覆盖规则ZenMux 提供方涉及两个环境变量作用各不相同环境变量是否必填作用ZENMUX_API_KEY必填API 认证密钥缺失时 provider 加载直接报错ZENMUX_BASE_URL可选覆盖默认端点https://zenmux.ai/api/v1用于私有网关、代理或区域端点从源码看Base URL 的解析优先级由resolveBaseUrl决定model-provider-registry.ts#L217-L232优先查找注册表env列表中名称匹配ENDPOINT|BASE_URL|BASEURL的变量其次查找按 provider id 推导出的约定变量名${PROVIDER_ID}_BASE_URLzenmux经envKeyForProvider大写转换后即ZENMUX_BASE_URL见 model-provider-registry.ts#L185-L186兜底使用注册表中的api字段值https://zenmux.ai/api/v1。这套机制与 MiniMax 的测试用例should support MINIMAX_BASE_URL override验证的行为一致model-provider-registry-minimax.spec.ts#L112-L129ZenMux 同样适用。可用模型清单zenmux/model前缀下的 51 个模型以下 51 个模型是当前仓库注册表快照中 ZenMux 提供的完整列表同时被固化在类型定义文件 packages/core/src/registries/model-provider-types.generated.ts#L2243-L2295 中使用时可获得完整的 TypeScript 类型提示。ZenMux 的模型命名采用厂商/模型名的双层结构引用时整体拼在zenmux/前缀之后。AnthropicClaude 系列模型 IDzenmux/前缀之后说明anthropic/claude-haiku-4.5快速轻量档anthropic/claude-opus-4旗舰档anthropic/claude-opus-4.1旗舰迭代版anthropic/claude-opus-4.5旗舰迭代版anthropic/claude-sonnet-4均衡档anthropic/claude-sonnet-4.5均衡迭代版DeepSeek 与 Baidu模型 ID说明deepseek/deepseek-chat通用对话deepseek/deepseek-reasoner推理增强deepseek/deepseek-v3.2V3.2 系列deepseek/deepseek-v3.2-expV3.2 实验版baidu/ernie-5.0-thinking-preview文心 ERNIE 5.0 思考预览版Google Gemini 系列模型 ID说明google/gemini-2.5-flash快速档google/gemini-2.5-flash-lite轻量快速档google/gemini-2.5-pro旗舰档google/gemini-3-flash-previewGemini 3 预览google/gemini-3-flash-preview-freeGemini 3 免费预览google/gemini-3-pro-previewGemini 3 Pro 预览OpenAIGPT 系列含 Codex模型 ID说明openai/gpt-5GPT-5 通用openai/gpt-5-codex代码智能体openai/gpt-5.1GPT-5.1openai/gpt-5.1-chatGPT-5.1 对话openai/gpt-5.1-codexGPT-5.1 代码openai/gpt-5.1-codex-miniGPT-5.1 代码轻量版openai/gpt-5.2GPT-5.2xAIGrok 系列模型 ID说明x-ai/grok-4Grok 4x-ai/grok-4-fastGrok 4 快速版x-ai/grok-4.1-fastGrok 4.1 快速版x-ai/grok-4.1-fast-non-reasoningGrok 4.1 快速非推理版x-ai/grok-code-fast-1Grok 代码快速版智谱 GLMz-ai 系列模型 ID说明z-ai/glm-4.5GLM-4.5z-ai/glm-4.5-airGLM-4.5 轻量版z-ai/glm-4.6GLM-4.6z-ai/glm-4.6vGLM-4.6 视觉版z-ai/glm-4.6v-flashGLM-4.6 视觉快速版z-ai/glm-4.6v-flash-freeGLM-4.6 视觉免费快速版z-ai/glm-4.7GLM-4.7Kimi / MiniMax / Qwen / StepFun / 火山引擎模型 ID说明moonshotai/kimi-k2-0905Kimi K2moonshotai/kimi-k2-thinkingKimi K2 思考版moonshotai/kimi-k2-thinking-turboKimi K2 思考加速版minimax/minimax-m2MiniMax M2minimax/minimax-m2.1MiniMax M2.1qwen/qwen3-coder-plusQwen3 代码增强版stepfun/step-3阶跃 Step-3volcengine/doubao-seed-1.8豆包 Seed 1.8volcengine/doubao-seed-code豆包 Seed 代码版其他厂商模型 ID说明inclusionai/ling-1tInclusion AI Ling 1Tinclusionai/ring-1tInclusion AI Ring 1Tkuaishou/kat-coder-pro-v1快手 KAT 编程 Prokuaishou/kat-coder-pro-v1-free快手 KAT 编程 Pro 免费版xiaomi/mimo-v2-flash小米 MiMo 快速版xiaomi/mimo-v2-flash-free小米 MiMo 免费快速版以上 51 个模型与 zenmux.md 文档中details折叠清单一一对应未增删。底层原理模型路由器如何解析zenmux/model1. 前缀解析provider/model与provider:model两种写法ModelProviderRegistry.resolveLanguageModel首先调用splitModelId拆解字符串model-provider-registry.ts#L774-L801。它同时支持斜杠与冒号两种分隔符splitModelId(zenmux/anthropic/claude-haiku-4.5); // → { providerId: zenmux, modelId: anthropic/claude-haiku-4.5 }注意 ZenMux 的模型 ID 本身又含一层/因此splitModelId只取第一个斜杠之前的部分作为 provider id剩余部分anthropic/claude-haiku-4.5原样作为 model id 传给适配器——这正是双层模型命名能被正确路由的原因。provider id 会统一小写并去除首尾空白normalizeProviderId。2. Provider 加载createOpenAICompatible组装ZenMux 在注册表中登记的 npm 包为ai-sdk/openai-compatible因此命中PACKAGE_ADAPTERS中的buildOpenAICompatibleProvider分支model-provider-registry.ts#L599-L619。该适配器会调用requireApiKey读取ZENMUX_API_KEY调用resolveBaseUrl得到最终端点以{ name, baseURL, apiKey, supportsStructuredOutputs: true }调用createOpenAICompatible(...)生成 provider。其中supportsStructuredOutputs: true表示该通道声明支持结构化输出供 VoltAgent 在生成 JSON / 工具调用时选用。MiniMax 的同款适配器测试用例验证了baseURL与apiKey会原样传入createOpenAICompatiblemodel-provider-registry-minimax.spec.ts#L72-L129ZenMux 走的是完全相同的代码路径。3. 从 Agent 到模型实例的调用链在 Agent 侧model字段既可以是LanguageModel实例也可以是zenmux/...这样的字符串。resolveModel→resolveModelReference会先把字符串交给ModelProviderRegistry.getInstance().resolveLanguageModel(...)agent.ts#L5851-L5875随后由getProviderEntry触发懒加载首次使用时动态import适配器包并将结果缓存在 provider 表中后续调用直接复用model-provider-registry.ts#L1071-L1102。该行为在 agent.spec.ts#L368-L414 中有专门测试should resolve string model ids via registry。4. 注册表来源与自动刷新ZenMux 的模型清单并非手写死代码而是来自https://models.dev/api.jsonMODELS_DEV_API_URL见 model-provider-registry.ts#L33。ModelProviderRegistry在非生产环境下每 30 分钟自动拉取一次最新注册表DEFAULT_AUTO_REFRESH_INTERVAL_MS 30 * 60 * 1000把结果快照写入~/.voltagent/model-registry/缓存并同步生成.d.ts类型文件生产环境则直接读取内置快照。因此 model-provider-types.generated.ts 中zenmux的 51 个模型就是发布时点的官方快照。你也可以在代码中显式调用refreshRegistry()或startAutoRefresh()来手动触发/恢复自动刷新model-provider-registry.ts#L910-L986。常见问题排查Missing API key for zenmux. Set process.env.ZENMUX_API_KEY.说明ZENMUX_API_KEY未设置或为空字符串检查环境变量是否已正确导出。Failed to load provider zenmux from ai-sdk/openai-compatible. Install the package and try again.说明ai-sdk/openai-compatible未安装按上文安装依赖后重启进程。想换端点但没生效确认变量名严格为ZENMUX_BASE_URLprovider idzenmux大写转换后拼接_BASE_URL并注意 Base URL 需指向兼容 OpenAI/chat/completions风格的路由例如形如https://zenmux.ai/api/v1的根路径。想要更好的类型提示zenmux/model在 model-provider-types.generated.ts 中有完整的字面量联合类型只要使用仓库内置的ModelRouterModelId类型写错模型名即可在编译期报错。总结ZenMux 在 VoltAgent 中是一个开箱即用的聚合网关提供方只需安装ai-sdk/openai-compatible、设置ZENMUX_API_KEY就能以zenmux/厂商/模型的形式在 Agent 中切换 Anthropic、OpenAI、DeepSeek、Gemini、GLM、Kimi、Grok 等 51 个模型且无需改动 Agent 代码。其底层由 ModelProviderRegistry 统一承担前缀解析、懒加载、Base URL 覆盖与 30 分钟自动刷新这就是 VoltAgent 以一套 model router 统一适配器支撑数百家模型提供方的核心机制。赞分享人工智能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 接入 Venice AI通过 OpenAI 兼容适配器使用 venice/model 模型路由VoltAgent 接入 Venice AI通过 OpenAI 兼容适配器使用 venice/model 模型路由 Venice AI 是一个提供多厂商模型人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent 接入 NovitaAI通过模型路由器调用 77 个 OpenAI 兼容模型VoltAgent 接入 NovitaAI通过模型路由器调用 77 个 OpenAI 兼容模型 在 VoltAgent 中模型路由model router人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Privatemode AI 接入指南通过 VoltAgent 模型路由器使用 OpenAI 兼容端点Privatemode AI 接入指南通过 VoltAgent 模型路由器使用 OpenAI 兼容端点 output_article Privatemode人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇图说设计模式之设计原则SOLID原则的图形化解释下一篇5分钟极速入门RVC语音克隆如何颠覆你的声音创作体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考