企业官网建设流程全解析

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

Deep Infra 是 VoltAgent 内置模型注册表（Model Provider Registry）中直接支持的一家推理服务提供商，你只需以deepinfra/<model>的模型字符串配置 Agent，即可通过 VoltAgent 的模型路由器完成鉴权、路由与调用。本文以 deepinfra.md 为骨架，结合仓库中注册表生成逻辑与源码适配器实现，完整讲解快速接入步骤、环境变量要求、Provider 底层适配原理以及当前注册表快照收录的 9 个模型，帮助你直接在项目中落地。

Deep Infra 在 VoltAgent 模型体系中的定位

VoltAgent 的模型能力围绕"Provider + Model"统一抽象展开：每个外部模型服务在providerId前缀下注册，调用时以provider/model的字符串形式传入 Agent 的model配置项。Deep Infra 对应的 providerId 为deepinfra，注册表实体定义在 model-provider-registry.generated.ts：

deepinfra: { id: "deepinfra", name: "Deep Infra", npm: "@ai-sdk/deepinfra", env: ["DEEPINFRA_API_KEY"], doc: "https://deepinfra.com/models", },

从该实体可以看到三项关键信息：

• npm 包：@ai-sdk/deepinfra，即 VoltAgent 复用的 AI SDK 官方 Provider 实现；
• 必需环境变量：DEEPINFRA_API_KEY；
• 文档字段：注册表记录了官方模型文档地址，用于生成 Provider 文档页（对应 deepinfra.md 中的 "Provider docs" 小节）。

值得一提的是，website/models-docs/providers/下的所有 Provider 文档均由 generate-model-docs.js 依据注册表与模型类型定义自动生成（文件头部标注了AUTO-GENERATED声明），因此 deepinfra.md 中的结构（快速开始、环境变量、Provider 包、Base URL、模型清单）与其他 80+ 个 Provider 页面完全一致，你可以在 overview.md 中横向对比各 Provider 的接入差异。

快速开始：三条代码接入 Deep Infra

在 deepinfra.md 给出的最小示例中，创建 Agent 时只需把model指定为deepinfra/<model>：

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

要点拆解：

• Agent来自@voltagent/core，model字段接受provider/model形式的模型字符串；
• 示例选用注册表快照中的第一个模型MiniMaxAI/MiniMax-M2作为演示，实际可替换为下文模型清单中的任意 ID；
• 无需手动导入@ai-sdk/deepinfra或自行构造 Provider 实例——VoltAgent 会根据前缀deepinfra在运行时自动解析对应的 Provider 适配器并完成构建。

环境变量：DEEPINFRA_API_KEY与运行时校验

使用 Deep Infra 前必须配置 API Key，环境变量名为DEEPINFRA_API_KEY（对应 model-provider-registry.generated.ts 的env字段）：

export DEEPINFRA_API_KEY="your-deepinfra-api-key"

从源码结构看，Provider 的 API Key 校验逻辑在 model-provider-registry.ts 中实现：requireApiKey会从注册表的env字段中筛选包含KEY/TOKEN/SECRET的环境变量名并逐一解析，若缺失则抛出明确错误：

Missing API key for "deepinfra". Set DEEPINFRA_API_KEY.

也就是说，漏配环境变量时 VoltAgent 会直接给出"缺哪个变量"的可读错误信息，而不是在远端 API 返回 401 时才暴露问题，这与其他 Provider 的错误提示策略保持一致。

Provider 底层：@ai-sdk/deepinfra与适配器注入

deepinfra.md 明确指出其 Provider 包为@ai-sdk/deepinfra。在 VoltAgent 的注册表适配层（model-provider-registry.ts）中，@ai-sdk/deepinfra被映射到通用的 API Key 型适配器：

"@ai-sdk/deepinfra": buildApiKeyProvider("createDeepInfra", "deepinfra"),

buildApiKeyProvider（实现见 model-provider-registry.ts L581-L597）的工作流程如下：

1. 调用requireApiKey(config)解析DEEPINFRA_API_KEY；
2. 从@ai-sdk/deepinfra模块导出中寻找createDeepInfra工厂函数，并以{ apiKey }调用；
3. 若工厂函数不可用，则回退到模块的deepinfra命名导出或default导出（通过resolveProviderExport兜底）；
4. 最终返回可用的ModelProviderEntry（LanguageModel 工厂或 ModelProvider 对象）。

这意味着你完全不需要在业务代码里手动createDeepInfra({ apiKey })——VoltAgent 的注册表会在首次使用deepinfra/<model>时按需完成 Provider 构建并缓存注册表快照（构建结果会 best-effort 写入dist/registries下的缓存文件，见 model-provider-registry.ts L500-L508）。

默认 Base URL 与DEEPINFRA_BASE_URL覆盖

deepinfra.md 的 "Default base URL" 一节标注为Not listed.（注册表中未声明api字段），但文档同时说明可以通过设置DEEPINFRA_BASE_URL覆盖默认地址：

export DEEPINFRA_BASE_URL="https://your-custom-endpoint.example.com"

适用场景包括：公司内部网关、代理出口、或自建兼容 Deep Infra API 的中转服务。需要说明的是，当前注册表对@ai-sdk/deepinfra使用的是纯 API Key 适配器（只传入apiKey），因此如果你需要精细控制 Base URL 或自定义请求头，更直接的方式是绕过模型字符串、直接向model传入由@ai-sdk/deepinfra构造的LanguageModel实例（AI SDK 的createDeepInfra({ apiKey, baseURL })支持这类扩展参数）。

模型清单：注册表快照中的 9 个模型

deepinfra.md 的模型列表来自 model-provider-types.generated.ts 的deepinfra类型定义，当前快照共收录 9 个模型：

这些模型 ID 保留了 Deep Infra 平台托管的原始命名（组织/模型 两级），使用时需保持与上表完全一致的大小写。从模型构成可以推断，Deep Infra 主要托管开源及开放权重模型的推理服务，覆盖编码（Qwen3-Coder 系列）、推理（Kimi-K2-Thinking、gpt-oss）、通用对话（MiniMax、GLM）等场景。

值得注意的是，模型列表属于"注册表快照"，其生成逻辑见 generate-model-docs.js：脚本用正则从model-provider-types.generated.ts中解析每个 Provider 的模型数组，再渲染进文档<details>折叠块。若后续 Deep Infra 新增模型，会随注册表快照更新同步反映到文档中。

结合模型路由器的进阶用法

deepinfra.md 是 Provider 维度文档，配合 overview.md 中描述的模型路由器能力，可以进一步把 Deep Infra 用出深度：

类型安全的模型 ID：使用ModelRouterModelId类型可以获得 IDE 自动补全与编译期校验：

import type { ModelRouterModelId } from "@voltagent/core"; const modelId: ModelRouterModelId = "deepinfra/openai/gpt-oss-120b";

按请求动态选模型：model支持函数形式，可在运行时根据context决定是否走 Deep Infra（例如低成本任务走 Deep Infra、关键分析走旗舰模型）：

const agent = new Agent({ name: "runtime-router", model: ({ context }) => { const tier = (context.get("tier") as string) || "fast"; return tier === "fast" ? "deepinfra/openai/gpt-oss-20b" : "deepinfra/MiniMaxAI/MiniMax-M2"; }, });

多 Agent 分工：把吞吐型任务（实体抽取、摘要）分配给 Deep Infra 等低成本模型，把质量敏感任务分配给更强的模型，这是官方 overview 推荐的负载拆分模式。

按请求传入 Provider 专属选项：在generateText的第二个参数中可通过providerOptions透传 AI SDK Provider 的专属参数：

const response = await agent.generateText("Explain how RAG works.", { providerOptions: { deepinfra: { /* @ai-sdk/deepinfra 支持的选项 */ }, }, });

具体可选参数以@ai-sdk/deepinfra当前版本导出的类型为准，建议结合该包的类型定义确认。

相关仓库资源

• Provider 文档源文件：deepinfra.md
• Provider 注册表实体（env/npm/doc 字段）：model-provider-registry.generated.ts
• Deep Infra 模型类型清单：model-provider-types.generated.ts
• Provider 适配器与 API Key 校验实现：model-provider-registry.ts
• Provider 文档自动生成脚本：generate-model-docs.js
• 模型路由总览与进阶用法：overview.md
• 快速上手指南中的 Provider 对照表：providers-models.md

按照以上配置，你可以直接复制 Quick start 代码、设置DEEPINFRA_API_KEY，用deepinfra/<model>在几分钟内把 Deep Infra 的低成本推理接入 VoltAgent Agent；需要路由到其他 Provider 时，替换前缀即可，无需改动任何调用代码。

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