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

人工智能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中接入 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_KEYInception 平台 API 密钥必填INCEPTION_BASE_URL覆盖默认 API Base URL可选VoltAgent 在解析 provider 时会检查必填环境变量并给出精确的缺失提示。相关逻辑位于requireApiKeymodel-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之类的标记可以绕过注册表、直接手写 providerimport { 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来覆盖它例如切换区域端点或走内部网关。这一机制的底层实现在resolveBaseUrlmodel-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_KEYyour-key-here export INCEPTION_BASE_URLhttps://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.tsinception/mercuryinception/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。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Tiled自动化映射深度解析如何实现高效地图绘制的完整指南Tiled自动化映射深度解析如何实现高效地图绘制的完整指南 Tiled地图编辑器的自动化映射Automapping功能是游戏地图制作中的革命性工具它通过人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音在 VoltAgent 中使用 GitHub Copilot 模型github-copilot/model 模型路由接入指南在 VoltAgent 中使用 GitHub Copilot 模型github copilot/model 模型路由接入指南 本篇基于 VoltAgent人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音5分钟快速上手开源网盘直链下载助手LinkSwift完整指南5分钟快速上手开源网盘直链下载助手LinkSwift完整指南 还在为网盘下载速度慢而烦恼吗LinkSwift网盘直链下载助手是一个基于JavaScript的人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇UniRelight安全与伦理考量在商业应用中需要注意的5个关键问题下一篇革命性3D资产生成工具NVIDIA Asset-Harvester如何从单张图片创建仿真级模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考