VoltAgent 接入 NanoGPT：通过模型路由使用 OpenAI 兼容多模型网关

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

【免费下载链接】voltagent

AI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework

项目地址：https://gitcode.com/gh_mirrors/vo/voltagent

点击查看免费下载

NanoGPT 是一个提供多家主流开源大模型统一接入的推理网关（OpenAI 兼容 API），在 VoltAgent 中它以nano-gpt/<model>的模型 ID 形式注册进模型路由器，让你可以在同一个 Agent 里直接选用 DeepSeek、Llama、Kimi、GLM、Qwen 等 20+ 模型，而无需分别对接各家 SDK。读完本文，你将掌握 NanoGPT 提供方的环境变量配置、默认端点与覆盖方式、完整模型清单，以及 VoltAgent 模型路由器在底层是如何解析provider/model并懒加载对应 SDK 适配器的。

NanoGPT 在 VoltAgent 中的定位

VoltAgent 的模型路由器（Model Router）采用provider/model这种两级模型 ID 约定：provider段标识模型提供方，model段标识该提供方下的具体模型。NanoGPT 提供方的注册信息可以在 model-provider-registry.generated.ts 中查到：

• id：nano-gpt
• name：NanoGPT
• npm：@ai-sdk/openai-compatible（底层 SDK 包）
• api：https://nano-gpt.com/api/v1（默认 Base URL）
• env：["NANO_GPT_API_KEY"]（必需的环境变量）
• doc：官方文档地址（由注册表条目记录）

所有支持提供方的总览见 overview.md，其中 NanoGPT 对应的模型前缀为nano-gpt，环境变量为NANO_GPT_API_KEY。

快速开始：创建 NanoGPT Agent

在 VoltAgent 中，只需要把model配置成nano-gpt/<model>形式的字符串，Agent 内部就会自动通过模型路由器解析并完成 SDK 装配：

import { Agent } from "@voltagent/core"; const agent = new Agent({ name: "nano-gpt-agent", instructions: "You are a helpful assistant", model: "nano-gpt/deepseek/deepseek-r1", });

这里nano-gpt/deepseek/deepseek-r1中的nano-gpt是提供方前缀，deepseek/deepseek-r1是 NanoGPT 网关侧的模型标识（模型本身也带厂商前缀，所以整个 ID 会有两段斜杠）。运行前请确保：

1. 已安装@voltagent/core及其依赖的 AI SDK（ai与@ai-sdk/openai-compatible）——注册表加载器在 import 不到config.npm指定的包时会抛出Install the package and try again提示；
2. 已配置NANO_GPT_API_KEY环境变量。

环境变量与端点覆盖

必需变量：NANO_GPT_API_KEY

NANO_GPT_API_KEY是 NanoGPT 提供方唯一必需的凭据。在注册表实现 model-provider-registry.ts 中，requireApiKey会先过滤出名称匹配KEY|TOKEN|SECRET的变量（即NANO_GPT_API_KEY），若缺失则直接抛出错误：Missing API key for "nano-gpt". Set process.env.NANO_GPT_API_KEY.，提示清晰，便于排查。

可选变量：NANO_GPT_BASE_URL

默认 Base URL 为https://nano-gpt.com/api/v1。需要自定义端点（例如企业代理、网关转发或本地调试）时，设置NANO_GPT_BASE_URL即可覆盖。该逻辑来自注册表的resolveBaseUrl（model-provider-registry.ts），其解析优先级为：

1. 先查找config.env中名称匹配ENDPOINT|BASE_URL|BASEURL的变量（NanoGPT 条目的 env 只有 API Key，因此此步通常不命中）；
2. 再按“提供方 ID 转大写并替换-为_”的约定规则查找<PROVIDER_ID>_BASE_URL，即NANO_GPT_BASE_URL；
3. 都未命中时回落到注册表中的api默认值https://nano-gpt.com/api/v1。

在命令行/.env中配置

export NANO_GPT_API_KEY="your_nano_gpt_api_key" export NANO_GPT_BASE_URL="https://nano-gpt.com/api/v1" # 可选，使用默认端点时可省略

Provider 包与 OpenAI 兼容适配器

NanoGPT 提供方对应的 SDK 包是@ai-sdk/openai-compatible，即通过 OpenAI 兼容适配器接入。在注册表实现里，所有 npm 为@ai-sdk/openai-compatible的提供方都走buildOpenAICompatibleProvider适配器（model-provider-registry.ts）：

const provider = createFn({ name: config.id, // "nano-gpt" baseURL, // 默认 https://nano-gpt.com/api/v1，可被 NANO_GPT_BASE_URL 覆盖 apiKey: apiKeyMatch.value, // NANO_GPT_API_KEY 的值 supportsStructuredOutputs: true, });

两个值得注意的实现细节：

• supportsStructuredOutputs: true表示该提供方声明支持结构化输出（Structured Outputs），启用后 Agent 在需要 JSON Schema 约束输出时会走服务端结构化生成路径；
• 适配器是懒加载的：只有在首次真正使用nano-gpt/...模型时，注册表才会import("@ai-sdk/openai-compatible")并构造 provider（model-provider-registry.ts），未用到的提供方不会产生额外的加载开销。

NanoGPT 模型清单（21 个）

以下模型列表来自模型注册快照，与 model-provider-types.generated.ts 中nano-gpt提供方的类型定义一一对应，可直接作为model字符串使用（前缀nano-gpt/+ 下表模型 ID）：

模型 ID	备注
deepseek/deepseek-r1	DeepSeek 推理模型
deepseek/deepseek-v3.2:thinking	DeepSeek V3.2 思考模式
meta-llama/llama-3.3-70b-instruct	Llama 3.3 70B 指令模型
meta-llama/llama-4-maverick	Llama 4 Maverick
minimax/minimax-m2.1	MiniMax M2.1
mistralai/devstral-2-123b-instruct-2512	Mistral Devstral 2
mistralai/ministral-14b-instruct-2512	Mistral Ministral 14B
mistralai/mistral-large-3-675b-instruct-2512	Mistral Large 3
moonshotai/kimi-k2-instruct	Kimi K2 指令模式
moonshotai/kimi-k2-thinking	Kimi K2 思考模式
nousresearch/hermes-4-405b:thinking	Hermes 4 405B 思考模式
nvidia/llama-3_3-nemotron-super-49b-v1_5	NVIDIA Nemotron Super
openai/gpt-oss-120b	OpenAI GPT-OSS 120B
qwen/qwen3-235b-a22b-thinking-2507	Qwen3 235B 思考版
qwen/qwen3-coder	Qwen3 Coder
z-ai/glm-4.6	GLM-4.6
z-ai/glm-4.6:thinking	GLM-4.6 思考模式
zai-org/glm-4.5-air	GLM-4.5-Air
zai-org/glm-4.5-air:thinking	GLM-4.5-Air 思考模式
zai-org/glm-4.7	GLM-4.7
zai-org/glm-4.7:thinking	GLM-4.7 思考模式

使用示例：

// 选用 Kimi K2 思考模式 model: "nano-gpt/moonshotai/kimi-k2-thinking", // 选用 GLM-4.7 思考模式 model: "nano-gpt/zai-org/glm-4.7:thinking",

注意:thinking后缀的模型属于“思考/推理”模式，通常延迟更高、但推理质量更好，适合复杂任务；-instruct/非 thinking 变体则更适合低延迟的常规对话场景。

模型路由底层解析原理

把model: "nano-gpt/deepseek/deepseek-r1"这样的字符串交给 Agent 后，实际发生的是以下调用链：

1. Agent 的resolveModelReference发现model值是字符串，便调用ModelProviderRegistry.getInstance().resolveLanguageModel(resolved)（agent.ts）；
2. 注册表的resolveLanguageModel先通过splitModelId把字符串切分为providerId = "nano-gpt"与modelId = "deepseek/deepseek-r1"——按第一个/切分，provider 段做小写归一化（model-provider-registry.ts）；
3. 接着懒加载nano-gpt提供方（如上文所述），最终以provider(resolvedModelId)的形式返回一个 Vercel AI SDK 的LanguageModel实例，交给 Agent 执行。

这一机制意味着同一个 Agent 可以在不同模型间自由切换，只要改model字符串即可，例如：

model: "nano-gpt/deepseek/deepseek-v3.2:thinking", // 低成本思考 model: "nano-gpt/moonshotai/kimi-k2-instruct", // 通用指令 model: "nano-gpt/openai/gpt-oss-120b", // 开源旗舰

注册表自动刷新与模型列表维护

VoltAgent 的模型列表并非硬编码，而是来自 models.dev 的提供方注册快照，并带有本地缓存与自动刷新机制（model-provider-registry.ts）：

• 非生产环境（NODE_ENV !== "production"）下，注册表启动时即开始自动刷新，默认间隔 30 分钟；
• 刷新结果写入~/.voltagent/model-registry/provider-registry.json与类型定义缓存，也会同步到@voltagent/core的dist/registries目录；
• 因此 NanoGPT 上线的新模型可能不需要手动升级 SDK 就能通过刷新获得（前提是该模型已出现在 models.dev 注册表中）。

这意味着本文的 21 个模型清单是一个“快照事实”：以当前仓库注册表为准，实际可用模型集可能随时间扩展。

常见问题与注意事项

• API Key 缺失：启动时若未设置NANO_GPT_API_KEY，会在首次解析模型时抛出Missing API key for "nano-gpt"，请检查.env或 shell 导出。
• 端点不通：确认NANO_GPT_BASE_URL（如已设置）指向https://nano-gpt.com/api/v1格式的 OpenAI 兼容根路径，不要误填成/v1/chat/completions之类的完整接口路径。
• SDK 未安装：懒加载适配器会提示Install the package and try again，需要确保@ai-sdk/openai-compatible与ai已安装。
• thinking 模型延迟：带:thinking后缀的模型属于思考模式，调用耗时与 token 消耗通常更高，生产环境按任务复杂度选型。

通过nano-gpt/<model>路由，你可以把 NanoGPT 网关背后的 DeepSeek、Llama、Kimi、GLM、Qwen 等模型统一纳入 VoltAgent 的 Agent 配置体系，用一套 API Key 和一套代码，按需切换到最合适的开源模型。

赞分享

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

【免费下载链接】voltagent

AI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework

项目地址：https://gitcode.com/gh_mirrors/vo/voltagent

点击查看免费下载

相关推荐

• Alipay Ruby Gem生产环境部署终极指南：监控、日志与性能优化策略

  Alipay Ruby Gem生产环境部署终极指南：监控、日志与性能优化策略 Alipay Ruby Gem是一个非官方的支付宝支付集成库，为Ruby开发者提供

  人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音

• Haystack 集成指南：用 OrcaRouterChatGenerator 接入 OpenAI 兼容模型路由网关

  Haystack 集成指南：用 OrcaRouterChatGenerator 接入 OpenAI 兼容模型路由网关 OrcaRouterChatGenerat

  人工智能大模型RAGAI AgentNLP

• VoltAgent 接入 Moonshot AI（中国）：用模型路由将 Kimi-K2 系列接入 OpenAI 兼容适配器

  VoltAgent 接入 Moonshot AI（中国）：用模型路由将 Kimi K2 系列接入 OpenAI 兼容适配器 在基于 VoltAgent 构建 A

  人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音

上一篇：如何快速上手coat_mini.in1k：从零开始的图像分类实战教程

下一篇：Vue.js 2.x 计算属性与侦听器：提升应用性能的10个最佳实践