企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆

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/v1（Base 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 支持数百家提供方的关键设计之一。

快速开始：三步启用 ZenMux

1. 安装依赖

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_KEY=your-zenmux-api-key # 可选：覆盖默认 Base URL（默认 https://zenmux.ai/api/v1） # ZENMUX_BASE_URL=https://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 提供方涉及两个环境变量，作用各不相同：

从源码看，Base URL 的解析优先级由resolveBaseUrl决定（model-provider-registry.ts#L217-L232）：

1. 优先查找注册表env列表中名称匹配ENDPOINT|BASE_URL|BASEURL的变量；
2. 其次查找按 provider id 推导出的约定变量名${PROVIDER_ID}_BASE_URL（zenmux经envKeyForProvider大写转换后即ZENMUX_BASE_URL，见 model-provider-registry.ts#L185-L186）；
3. 兜底使用注册表中的api字段值https://zenmux.ai/api/v1。

这套机制与 MiniMax 的测试用例should support MINIMAX_BASE_URL override验证的行为一致（model-provider-registry-minimax.spec.ts#L112-L129），ZenMux 同样适用。

可用模型清单：zenmux/<model>前缀下的 51 个模型

以下 51 个模型是当前仓库注册表快照中 ZenMux 提供的完整列表，同时被固化在类型定义文件 packages/core/src/registries/model-provider-types.generated.ts#L2243-L2295 中，使用时可获得完整的 TypeScript 类型提示。ZenMux 的模型命名采用厂商/模型名的双层结构，引用时整体拼在zenmux/前缀之后。

Anthropic（Claude 系列）

DeepSeek 与 Baidu

Google Gemini 系列

OpenAI（GPT 系列，含 Codex）

xAI（Grok 系列）

智谱 GLM（z-ai 系列）

Kimi / MiniMax / Qwen / StepFun / 火山引擎

其他厂商

以上 51 个模型与 zenmux.md 文档中<details>折叠清单一一对应，未增删。

底层原理：模型路由器如何解析zenmux/<model>

1. 前缀解析：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）。该适配器会：

1. 调用requireApiKey读取ZENMUX_API_KEY；
2. 调用resolveBaseUrl得到最终端点；
3. 以{ name, baseURL, apiKey, supportsStructuredOutputs: true }调用createOpenAICompatible(...)生成 provider。

其中supportsStructuredOutputs: true表示该通道声明支持结构化输出，供 VoltAgent 在生成 JSON / 工具调用时选用。MiniMax 的同款适配器测试用例验证了baseURL与apiKey会原样传入createOpenAICompatible（model-provider-registry-minimax.spec.ts#L72-L129），ZenMux 走的是完全相同的代码路径。

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.json（MODELS_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_URL（provider 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 Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆