VoltAgent 接入 Ollama Cloud：模型路由配置、环境变量与 OpenAI 兼容适配器全解析

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载Ollama Cloud 是 Ollama 提供的云端托管推理服务VoltAgent 通过ollama-cloud/model前缀即可将其纳入统一的模型路由体系。本文以 Ollama Cloud 官方文档 为骨架结合 VoltAgent 核心包的模型供应商注册表源码完整讲解接入步骤、API Key 与 Base URL 的解析优先级以及底层 OpenAI 兼容适配器的工作原理读完即可在自己的 Agent 中直接使用 Cogito、DeepSeek、Kimi、Qwen 等云端模型。快速开始在 Agent 中启用 Ollama Cloud 模型Ollama Cloud 在 VoltAgent 中的用法与其它供应商完全一致只需在Agent构造时把model字段写成ollama-cloud/模型名即可无需额外安装专有 provider 包。以下代码直接取自官方文档import { Agent } from voltagent/core; const agent new Agent({ name: ollama-cloud-agent, instructions: You are a helpful assistant, model: ollama-cloud/cogito-2.1:671b-cloud, });创建 Agent 后VoltAgent 的模型路由会解析model字符串中的供应商前缀并自动完成 provider 加载、鉴权与模型实例化。cogito-2.1:671b-cloud是 Ollama Cloud 的旗舰推理模型671B 参数、支持思考链如果你尚未配置 API Key程序会在解析供应商时抛出缺少凭证的错误详见下文环境变量小节。环境变量OLLAMA_API_KEYOllama Cloud 供应商需要的唯一环境变量是OLLAMA_API_KEYOllama Cloud 的 API 访问密钥用于请求鉴权。在源码中该供应商的注册条目定义于 model-provider-registry.generated.tsollama-cloud: { id: ollama-cloud, name: Ollama Cloud, npm: ai-sdk/openai-compatible, api: https://ollama.com/v1, env: [OLLAMA_API_KEY], doc: https://docs.ollama.com/cloud, },注意model-provider-registry.generated.ts与model-provider-types.generated.ts均由website/scripts/generate-model-docs.js脚本从 models.dev 的公开注册表自动生成因此供应商清单与模型清单会随上游数据源同步更新。在env数组之外VoltAgent 还支持一套约定式的 Key 命名——OLLAMA_CLOUD_BASE_URL可用于覆盖默认端点见下一节。从 model-provider-registry.ts 的源码可以看到环境变量查找逻辑const envKeyForProvider (providerId: string): string providerId.trim().toUpperCase().replace(/-/g, _);即供应商 idollama-cloud会先被规范化为OLLAMA_CLOUD再拼接出OLLAMA_CLOUD_BASE_URL这样的约定环境变量而 API Key 的读取则遵循注册表中env数组的声明顺序取第一个非空值。默认 Base URL 与OLLAMA_CLOUD_BASE_URL覆盖机制Ollama Cloud 的默认 API 端点为https://ollama.com/v1该端点同时兼容 OpenAI 的/v1风格接口因此 VoltAgent 可以直接复用 OpenAI-compatible 适配器。当你需要把流量转发到自定义代理、网关或私有部署的 Ollama 服务时可以设置OLLAMA_CLOUD_BASE_URL覆盖默认值。Base URL 的解析优先级在 model-provider-registry.ts 的resolveBaseUrl中实现共三级注册表env列表中名称匹配/ENDPOINT|BASE_URL|BASEURL/i的环境变量优先命中即返回约定式环境变量${供应商ID大写}_BASE_URL即OLLAMA_CLOUD_BASE_URL兜底使用注册表中的api字段默认值https://ollama.com/v1。这意味着只要设置了OLLAMA_CLOUD_BASE_URL它就会覆盖文档默认端点若未设置则自动回退到官方云端地址无需任何额外配置。Provider 包与 OpenAI 兼容适配器Ollama Cloud 使用的 provider 包是ai-sdk/openai-compatible即 VoltAgent 并非针对 Ollama Cloud 编写专用 SDK而是通过ai-sdk/openai-compatible提供的createOpenAICompatible工厂函数动态构建供应商。对应适配器位于 model-provider-registry.tsconst buildOpenAICompatibleProvider: ProviderAdapter (config, moduleExports) { const createFn getModuleFunction(moduleExports, createOpenAICompatible); if (!createFn) { throw new Error(Missing createOpenAICompatible export in ${config.npm} for ${config.id}.); } const apiKeyMatch requireApiKey(config); const baseURL resolveBaseUrl(config); if (!baseURL) { throw new Error(Missing base URL for ${config.id}. Set ${formatEnvList(config.env ?? [])}.); } const provider createFn({ name: config.id, baseURL, apiKey: apiKeyMatch.value, supportsStructuredOutputs: true, }); return provider as ModelProviderEntry; };这段实现揭示了三个关键事实动态加载provider 包在运行时通过import(config.npm)懒加载见 model-provider-registry.ts所以使用前需确认ai-sdk/openai-compatible已安装到项目依赖中结构化输出开箱即用适配器固定开启supportsStructuredOutputs: true因此基于 Ollama Cloud 的 Agent 可以直接使用 VoltAgent 的工具调用与结构化输出能力缺少配置即报错如果既没有 API Key 也没有 Base URL会抛出带明确提示的错误信息方便定位问题。对于Agent内部如何完成模型路由核心逻辑在ModelProviderRegistry单例getInstance()见 model-provider-registry.ts与splitModelId中。splitModelIdmodel-provider-registry.ts支持两种供应商前缀分隔符斜杠格式ollama-cloud/cogito-2.1:671b-cloud冒号格式ollama-cloud:cogito-2.1:671b-cloud解析时取前缀作为 providerId规范化为小写并连字符化剩余部分作为模型 id随后由注册表查找到ollama-cloud条目并执行懒加载适配器。可用模型列表12 个截至当前仓库快照Ollama Cloud 在 VoltAgent 注册表中支持以下 12 个模型定义于 model-provider-types.generated.ts与 Ollama Cloud 文档 一致模型 ID说明按命名推断cogito-2.1:671b-cloud671B 级推理/思考模型deepseek-v3.1:671b-cloudDeepSeek V3.1 671B 级gemini-3-pro-preview:latestGemini 3 Pro 预览版glm-4.6:cloudGLM 4.6 云端版gpt-oss:120b-cloudGPT-OSS 120Bgpt-oss:20b-cloudGPT-OSS 20Bkimi-k2-thinking:cloudKimi K2 思考模式kimi-k2:1t-cloudKimi K2 1T 参数级minimax-m2:cloudMiniMax M2qwen3-coder:480b-cloudQwen3 Coder 480Bqwen3-vl-235b-cloudQwen3 VL 235Bqwen3-vl-235b-instruct-cloudQwen3 VL 235B Instruct使用方式均为ollama-cloud/模型ID例如model: ollama-cloud/deepseek-v3.1:671b-cloud,由于模型清单由 models.dev 上游数据自动生成并随版本刷新实际可用列表以你所安装的voltagent/core版本为准若引用仓库中不存在的模型 ID注册表会因无法匹配而提示供应商加载失败。接入清单与注意事项完成 Ollama Cloud 接入只需三步安装核心包pnpm add voltagent/core ai-sdk/openai-compatibleprovider 包由运行期动态加载需确保已安装设置环境变量OLLAMA_API_KEY你的密钥如需代理或私有端点追加OLLAMA_CLOUD_BASE_URL自定义端点在 Agent 中引用模型model: ollama-cloud/模型ID。补充说明本文基于当前仓库快照packages/core的生成式注册表编写Ollama Cloud 的模型列表、默认端点和环境变量规则均以该快照为准上游 models.dev 数据更新后文档与生成文件会同步变化生产环境中建议通过 VoltAgent 官方部署文档完成 API Key 的密钥管理避免把OLLAMA_API_KEY硬编码进源码若希望对比 Ollama Cloud 与本地 Ollama 的接入差异可参考仓库内 with-ollama 示例 与 with-custom-endpoints 示例后者展示了自定义端点的完整配置路径。赞分享人工智能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 接入 Synthetic 模型路由OpenAI 兼容适配器配置与 25 个可用模型实战指南VoltAgent 接入 Synthetic 模型路由OpenAI 兼容适配器配置与 25 个可用模型实战指南 VoltAgent 内置了由 models.d人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音使用 VoltAgent 模型路由器接入 CortecsOpenAI 兼容适配器配置、模型清单与路由源码解析使用 VoltAgent 模型路由器接入 CortecsOpenAI 兼容适配器配置、模型清单与路由源码解析 本文基于仓库文档 website/models人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent 接入 OpenAI 全指南openai/model 模型路由、环境变量与 40 个内置模型详解VoltAgent 接入 OpenAI 全指南 openai/model 模型路由、环境变量与 40 个内置模型详解 本文围绕 VoltAgent 官方模型人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇MongoDB数据验证规则冲突检测Robo 3T识别约束矛盾下一篇如何使用Brave浏览器主题开发API样式注入与动态修改完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考