VoltAgent 接入 Inference 模型提供商：使用 OpenAI 兼容适配器配置 inference/＜model＞ 模型路由

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

Inference（inference.net）是一家提供多厂商开源模型托管与统一推理 API 的模型提供商，在 VoltAgent 中通过inference/<model>形式的模型字符串即可接入。本文以 website/models-docs/providers/inference.md 为核心，结合 VoltAgent 模型注册表源码，完整讲解环境变量配置、默认 Base URL 覆盖、可用模型清单，以及如何利用模型路由、类型安全的模型 ID 和运行时选型编写可运行的 Agent 代码。

Inference 在 VoltAgent 模型注册表中的定位

VoltAgent 内置了一个由 models.dev）。

在注册表源码中，Inference 被登记为独立的提供商条目（见 model-provider-registry.generated.ts）：

• id：inference
• name：Inference
• npm：@ai-sdk/openai-compatible
• api：https://inference.net/v1
• env：["INFERENCE_API_KEY"]
• doc：https://inference.net/models

其中npm字段决定了该提供商使用的适配器类型——Inference 属于 OpenAI 兼容适配器（@ai-sdk/openai-compatible），因此任何符合 OpenAI Chat Completions 协议的客户端都能通过统一格式调用其 API。

快速开始：用模型字符串创建 Agent

和 VoltAgent 中其他 80+ 提供商一样，接入 Inference 不需要额外安装依赖，只需在创建 Agent 时把model指定为inference/<model>：

import { Agent } from "@voltagent/core"; const agent = new Agent({ name: "inference-agent", instructions: "You are a helpful assistant", model: "inference/google/gemma-3", });

运行时，VoltAgent 的模型路由器会根据inference/前缀查表：读取注册表中该提供商的适配器与 API 配置，检查所需的INFERENCE_API_KEY环境变量，随后完成模型实例的构建与调用。官方文档明确说明："At runtime, VoltAgent checks required environment variables and reports the exact one that's missing."——即如果缺少密钥，VoltAgent 会明确报出缺失的变量名，方便快速定位问题。

环境变量配置

使用 Inference 提供商只需配置一个环境变量：

• INFERENCE_API_KEY：Inference 平台颁发的 API 密钥，是模型路由时被校验的必需变量（对应注册表条目的env: ["INFERENCE_API_KEY"]）。

在部署到 Next.js、Cloudflare Workers 等平台时，需要按对应方式注入该变量（如.env文件、平台 Dashboard 或wrangler.toml），可参考仓库中的 with-nextjs、with-cloudflare-workers 等示例工程。

默认 Base URL 与覆盖方式

Inference 的默认 Base URL 为：

https://inference.net/v1

如果你使用的是自建网关、代理或兼容端点，可以通过设置INFERENCE_BASE_URL环境变量覆盖默认地址。VoltAgent 注册表条目中的api字段（https://inference.net/v1）即默认端点，INFERENCE_BASE_URL提供运行时覆盖入口。

更精细的自定义场景（例如需要追加自定义请求头）可以通过 ai-sdk 的LanguageModel直接传入，VoltAgent 在模型字段中接受任意 ai-sdk 模型实例。例如使用createOpenAICompatible手动构造带额外头部、自定义 Base URL 的模型：

import { Agent } from "@voltagent/core"; import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; const inferenceProvider = createOpenAICompatible({ name: "inference", baseURL: process.env.INFERENCE_BASE_URL ?? "https://inference.net/v1", apiKey: process.env.INFERENCE_API_KEY, headers: { "X-Client-Source": "voltagent-docs", }, }); const agent = new Agent({ name: "custom-inference-agent", model: inferenceProvider("google/gemma-3"), });

该写法与 模型总览 中"Custom headers"一节展示的createOpenAICompatible用法一致，适合需要细粒度控制请求头的场景。

可用模型清单

VoltAgent 注册表为inference提供商收录了 9 个模型（见 model-provider-types.generated.ts）：

以上模型覆盖了文本对话、视觉理解（vision-instruct 系列）、轻量部署（1B/3B）以及嵌入（embedding）等多种用途，可直接在model字段中使用。其中qwen/qwen3-embedding-4b这类嵌入模型可用作 VoltAgent 记忆/检索场景的向量模型。具体模型规格与计费可查阅 Inference 官方模型页（文档地址见注册表条目doc: "https://inference.net/models"）。

注：模型清单由注册表生成脚本自动维护，实际可用模型以 Inference 平台为准；调用前建议核对模型 ID 是否与平台当前列表一致。

类型安全的模型 ID 与运行时路由

VoltAgent 提供了ModelRouterModelId类型，可在编译期对inference/...这类模型字符串做自动补全与校验：

import type { ModelRouterModelId } from "@voltagent/core"; const modelId: ModelRouterModelId = "inference/google/gemma-3";

模型路由器还支持运行时动态选型，例如根据请求上下文（如租户或业务分级）在不同模型间切换：

const agent = new Agent({ name: "runtime-inference-router", model: ({ context }) => { const tier = (context.get("tier") as string) || "fast"; return tier === "fast" ? "inference/meta/llama-3.2-1b-instruct" : "inference/meta/llama-3.1-8b-instruct"; }, });

借助这类机制，可以把成本敏感的吞吐型任务路由到meta/llama-3.2-1b-instruct等轻量模型，把关键分析任务路由到google/gemma-3等更强模型，实现按需分配。

小结

在 VoltAgent 中接入 Inference 提供商的关键点可概括为四步：

1. 设置环境变量INFERENCE_API_KEY（必要时同时设置INFERENCE_BASE_URL覆盖默认端点https://inference.net/v1）；
2. 在Agent的model字段使用inference/<model>字符串（无需安装额外依赖）；
3. 从注册表收录的 9 个模型中选择合适 ID，可用ModelRouterModelId获得类型提示；
4. 需要自定义头部/网关时，用@ai-sdk/openai-compatible的createOpenAICompatible构造LanguageModel直接传入。

该接入方式与 VoltAgent 内置模型注册表的整体设计一致——零导入的模型字符串、注册表驱动的环境变量映射、类型感知的模型 ID 与运行时路由，让多提供商接入保持统一且可维护。

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