在 VoltAgent 模型路由中使用 Inception（inception/mercury）：接入指南与源码级原理-育师

人工智能
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

本指南讲解如何在 VoltAgent 的模型路由（model router）中接入 Inception 平台的inception/mercury与inception/mercury-coder模型。你将掌握从Agent配置、INCEPTION_API_KEY环境变量到自定义 Base URL 的完整接入方式，并通过仓库源码理解 VoltAgent 如何把inception/<model>字符串解析为 OpenAI 兼容的 LanguageModel 实例。

一、Inception 接入概览

Inception 是 VoltAgent 内置模型注册表（model registry）中众多 provider 之一。与 OpenAI、Anthropic 等 provider 一样，你不需要额外安装 Inception 专属 SDK，只需要在Agent配置中直接使用inception/<model>形式的模型字符串，VoltAgent 会自动完成 provider 的加载与鉴权。

在 model-provider-registry.generated.ts 中，Inception 的注册条目如下：

inception: { id: "inception", name: "Inception", npm: "@ai-sdk/openai-compatible", api: "https://api.inceptionlabs.ai/v1/", env: ["INCEPTION_API_KEY"], doc: "https://platform.inceptionlabs.ai/docs", },

这个条目来自 models.dev 的快照数据，由 website/scripts/generate-model-docs.js 自动生成并打包进 VoltAgent。它定义了 Inception 的四个关键事实：使用 OpenAI 兼容适配器、默认 API 地址、需要INCEPTION_API_KEY，以及官方文档地址。

二、快速开始：创建 Inception Agent

只需把model字段设为inception/<model>即可：

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

运行前确保环境中已设置INCEPTION_API_KEY。模型字符串的解析由ModelProviderRegistry.splitModelId完成（见 model-provider-registry.ts）：它先在/处切分provider/model，再通过resolveLanguageModel找到已注册的 Inception provider，最终返回一个绑定好mercury模型 ID 的LanguageModel实例。

三、环境变量与鉴权机制

接入 Inception 需要配置以下环境变量：

变量	作用	是否必填
`INCEPTION_API_KEY`	Inception 平台 API 密钥	必填
`INCEPTION_BASE_URL`	覆盖默认 API Base URL	可选

VoltAgent 在解析 provider 时会检查必填环境变量并给出精确的缺失提示。相关逻辑位于requireApiKey（model-provider-registry.ts），当找不到INCEPTION_API_KEY时会抛出类似下面的错误：

Missing API key for "inception". Set process.env.INCEPTION_API_KEY.

密钥的读取采用"逐个尝试"策略：resolveEnvValue会遍历该 provider 声明的所有环境变量名，取第一个非空值（model-provider-registry.ts）。对于 Inception 而言，命中的就是INCEPTION_API_KEY。

四、Provider 包：OpenAI 兼容适配器

Inception 的 provider 包是@ai-sdk/openai-compatible，这意味着 Inception 的 API 与 OpenAI 的 Chat Completions 接口兼容，VoltAgent 直接复用 AI SDK 的 OpenAI 兼容适配器，无需任何 Inception 专属代码。

在 PACKAGE_ADAPTERS 中，@ai-sdk/openai-compatible对应buildOpenAICompatibleProvider适配器。该适配器会：

从环境变量解析 API 密钥；
通过resolveBaseUrl确定请求地址（详见下一节）；
调用createOpenAICompatible({ name, baseURL, apiKey, supportsStructuredOutputs: true })创建 provider；
返回一个(modelId) => LanguageModel的工厂函数。

其中supportsStructuredOutputs: true表示该 provider 支持结构化输出（structured outputs），可用于 JSON Schema 约束的生成场景。

如果你需要自定义请求头（如附加X-Client-Source之类的标记），可以绕过注册表、直接手写 provider：

import { Agent } from "@voltagent/core"; import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; const inceptionProvider = createOpenAICompatible({ name: "inception", baseURL: "https://api.inceptionlabs.ai/v1/", apiKey: process.env.INCEPTION_API_KEY, headers: { "X-Client-Source": "my-app", }, }); const agent = new Agent({ name: "inception-agent", instructions: "You are a helpful assistant", model: inceptionProvider("mercury"), });

五、默认 Base URL 与自定义覆盖

Inception 的默认 Base URL 为：

https://api.inceptionlabs.ai/v1/

你可以通过设置INCEPTION_BASE_URL来覆盖它，例如切换区域端点或走内部网关。这一机制的底层实现在resolveBaseUrl（model-provider-registry.ts），其解析顺序为：

遍历 provider 声明的环境变量中名称含ENDPOINT/BASE_URL/BASEURL的项，取第一个非空值；
否则读取环境变量前缀_BASE_URL（即INCEPTION_BASE_URL，前缀由envKeyForProvider把inception转成大写并替换连字符得到）；
都没有时回退到注册表中的api字段（https://api.inceptionlabs.ai/v1/）。

# 覆盖 Base URL 示例 export INCEPTION_API_KEY="your-key-here" export INCEPTION_BASE_URL="https://your-gateway.example.com/v1/"

注意：Base URL 解析在非生产环境下还会受到缓存注册表的影响。VoltAgent 在开发模式下会从~/.voltagent/model-registry/provider-registry.json加载快照，并从 models.dev 每 30 分钟自动刷新一次注册表（见 model-provider-registry.ts），以保证新增模型和配置变更能及时同步到运行时。

六、可用的 Inception 模型

当前注册表快照中 Inception 提供以下模型（见 model-provider-types.generated.ts）：

inception/mercury
inception/mercury-coder

在类型层面，VoltAgent 通过ModelRouterModelId为模型字符串提供 IDE 自动补全与编译期校验：

import type { ModelRouterModelId } from "@voltagent/core"; // 合法：自动补全会提示 inception/mercury 与 inception/mercury-coder const modelId: ModelRouterModelId = "inception/mercury";

该类型由 model-provider-registry.ts 根据注册表自动生成，它把ProviderId与模型列表组合成provider/model字面量联合类型。注意：类型文件是自动生成的，模型清单会随注册表刷新而变化，因此实际可用的模型以运行时注册表快照为准。

七、进阶：按需切换与自定义 provider

在同一个 Agent 内根据请求上下文动态选择 Inception 或其他模型：

const agent = new Agent({ name: "runtime-router", model: ({ context }) => { const task = (context.get("task") as string) || "general"; return task === "coding" ? "inception/mercury-coder" : "inception/mercury"; }, });

在拆分工作负载时，可以把inception/mercury-coder用于代码生成类步骤，而把通用对话类步骤交给其他 provider，实现成本与能力的灵活组合：

import { Agent } from "@voltagent/core"; const coderAgent = new Agent({ name: "code-gen", instructions: "Generate production-ready TypeScript code.", model: "inception/mercury-coder", }); const reviewerAgent = new Agent({ name: "code-review", instructions: "Review the generated code and flag risks.", model: "inception/mercury", });

如果你需要 Inception 特有（或 OpenAI 兼容协议外）的能力，也可以在任何 VoltAgent 期望LanguageModel的位置直接使用 AI SDK 的 provider 模块，此时你完全掌控 provider 的初始化参数，注册表不再介入。

八、小结

接入 Inception 到 VoltAgent 只需三步：设置INCEPTION_API_KEY、在Agent的model字段写入inception/mercury（或inception/mercury-coder）、按需通过INCEPTION_BASE_URL覆盖默认端点。底层由@ai-sdk/openai-compatible适配器和内置的ModelProviderRegistry完成解析、鉴权与实例化，你也可以随时查看 model-provider-registry.generated.ts 和 model-provider-registry.ts 了解完整的 provider 解析链。

相关参考：providers 总览见 providers/overview.md，模型路由的整体用法见 models-docs/overview.md。