企业官网建设流程全解析

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

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_KEY

Ollama Cloud 供应商需要的唯一环境变量是：

• OLLAMA_API_KEY：Ollama Cloud 的 API 访问密钥，用于请求鉴权。

在源码中，该供应商的注册条目定义于 model-provider-registry.generated.ts：

"ollama-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中实现，共三级：

1. 注册表env列表中名称匹配/ENDPOINT|BASE_URL|BASEURL/i的环境变量（优先命中即返回）；
2. 约定式环境变量${供应商ID大写}_BASE_URL，即OLLAMA_CLOUD_BASE_URL；
3. 兜底使用注册表中的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.ts：

const 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中。splitModelId（model-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 文档 一致）：

使用方式均为ollama-cloud/<模型ID>，例如：

model: "ollama-cloud/deepseek-v3.1:671b-cloud",

由于模型清单由 models.dev 上游数据自动生成并随版本刷新，实际可用列表以你所安装的@voltagent/core版本为准；若引用仓库中不存在的模型 ID，注册表会因无法匹配而提示供应商加载失败。

接入清单与注意事项

完成 Ollama Cloud 接入，只需三步：

1. 安装核心包：pnpm add @voltagent/core @ai-sdk/openai-compatible（provider 包由运行期动态加载，需确保已安装）；
2. 设置环境变量：OLLAMA_API_KEY=<你的密钥>；如需代理或私有端点，追加OLLAMA_CLOUD_BASE_URL=<自定义端点>；
3. 在 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 Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆