Ollama OpenAI 兼容 API：访问、定价、集成与生产指南

Ollama OpenAI 兼容 API：访问、定价、集成与生产指南

Ollama OpenAI 兼容 API让应用程序能够保留熟悉的 OpenAI SDK 形式，同时将请求发送到本地 Ollama 服务器或直接发送到 Ollama Cloud。这很有用，但并不意味着功能可以一一完全对等：Ollama 记录了对 OpenAI API 子集的支持，且某些功能取决于您选择的端点和模型。

本指南介绍如何访问此接口、如何在现有 Python 或 JavaScript 应用程序中配置它、如何理解云端与本地成本的差异，以及如何为其设置真正的生产环境边界。

快速回答：对于本地 Ollama 服务器，请使用 http://localhost:11434/v1/，并提供 SDK 所需但会被 Ollama 忽略的占位 API 密钥。对于直接云端访问，请使用 https://ollama.com/v1 和 OLLAMA_API_KEY。在依赖流式传输、视觉、工具、结构化输出或 Responses API 行为之前，请验证具体端点和模型。

对 Ollama 而言，“OpenAI 兼容”意味着什么？

这是一个 OpenAI 客户端集成接口，而不是由 OpenAI 托管的 API。它允许您将兼容客户端指向 Ollama 基础 URL，并使用聊天补全、嵌入、模型发现和无状态 Responses 请求等受支持路由。

Ollama 的兼容性参考是了解受支持子集的权威来源。尤其是：

• /v1/chat/completions 支持流式传输、JSON 模式、视觉、工具、可复现输出、logprobs，以及仅适用于兼容模型的控制项等功能。
• /v1/embeddings 支持字符串和数组输入。
• /v1/models 和 /v1/models/{model} 支持模型发现，但某些返回字段具有 Ollama 特有的含义。
• POST /v1/responses 可用，但它是无状态的：请勿依赖 previous_response_id 或 conversation。

在生产环境中启用某项功能之前，请参阅实时更新的 Ollama OpenAI 兼容性参考。“兼容”应被视为复用客户端和请求形式的理由，而不是跳过功能测试的理由。

访问 Ollama OpenAI 兼容 API：本地与云端

最简单的实施选择在于：推理是在您自己的机器上运行，还是访问 Ollama 的云端端点。

这种划分记录在 Ollama 的 API 简介和身份验证指南中。直接云端调用需要 API 密钥；本地调用则不需要。

本地设置

安装 Ollama，然后拉取您打算使用的模型。Ollama 文档展示了通用模式：

ollama pull gpt-oss:20b
ollama serve

现在验证本地端点能够枚举模型：

curl http://localhost:11434/v1/models

如果连接失败，请先解决本地服务器问题，再修改应用程序代码。当 API 基础 URL 和模型清单已能独立正常工作时，客户端迁移会更容易调试。

直接云端设置

如需直接使用云端，请在您的 Ollama 账户中创建 API 密钥，并将其放入环境变量：

export OLLAMA_API_KEY="replace-with-your-key"

云端基础 URL 为 https://ollama.com/v1。Ollama 文档指出，其托管 API 使用 Authorization: Bearer；请勿将长期有效的密钥放入浏览器代码、代码仓库或客户端配置文件中。

使用 OpenAI SDK 集成 Ollama OpenAI 兼容 API

迁移的关键点是客户端配置。请将应用程序消息和错误处理保留在您自己的接口之后，然后仅替换基础 URL、密钥和模型配置。

Python：本地服务器

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

print(response.choices[0].message.content)

本地端点不会对请求进行身份验证。占位密钥的存在只是因为 OpenAI 客户端需要一个值；它并不能保护本地服务器。

Python：直接连接云端

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

print(response.choices[0].message.content)

代码结构被刻意设计得相似，但运行层面的差异却很明显：直接调用云端依赖 API 密钥和所选的云端模型；本地调用则依赖已拉取的模型和主机上的可用资源。

JavaScript：保持端点可配置

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

console.log(completion.choices[0].message.content);

针对每个部署环境设置环境变量：

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

这种配置使后续对调用路径或模型的更改清晰可见且可供审查，也能防止环境专用的基础 URL 成为应用中隐含的行为。

兼容性矩阵：上线前需要测试什么

当您将兼容性作为测试计划，而不是预先假定的条件时，Ollama OpenAI 兼容 API才能发挥最大价值。

有两个细节经常让团队感到意外：

1. 状态应由应用管理。应用应存储所需的消息或会话状态，而不是期望 Ollama 提供有状态的 Responses 行为。
2. 模型名称并不保证能力。请求即使使用兼容端点，也可能无法提供工作流所需的质量或工具行为。应结合测试模型、提示词大小、输出限制和工具。

如果现有集成将默认 OpenAI 模型名称硬编码，Ollama 文档说明可以使用 ollama cp 创建临时本地模型别名。仅应有意识地将其用作兼容性适配方案，记录该别名，并在配置明确后将其移除。

Ollama 定价：本地总拥有成本与云端 token 费率

Ollama OpenAI 兼容 API 的定价取决于调用路径。

本地推理不会产生 token 账单，但并非没有成本

运行本地模型不会产生按 token 计费的 Ollama 云端账单，但会带来以下运营成本：

• GPU 或 CPU 算力、内存/显存、存储及设备折旧
• 电力和冷却
• 模型拉取时间和镜像存储
• 容量规划、监控、补丁更新和事件响应
• 为满足低延迟请求而让模型保持预热状态的机会成本

对于单个开发者而言，这可能是一笔非常划算的交易。对于流量呈突发性或使用多个模型的产品，应将硬件利用率和可靠性工作与原始推理成本一并计算。

直连云端定价按每百万个 token 公布

Ollama 的实时定价页面列出了每百万个 token 的云端费率，包括单独的输入、缓存输入和输出价格。以下示例于 2026 年 10 月 22 日核对；请使用实时价目表进行采购和部署决策。

Ollama 的价格页面还说明了符合条件条目的非高峰时段定价。不要仅根据模型标签制定预算：应使用适用于实际路由、模型和时段的价格行。

一个实用的月度估算公式为：

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

例如，按照上述公布的 gpt-oss:20b 费率，100 万个未缓存输入 token 加上 25 万个输出 token，估算费用为 $0.145，尚未考虑任何价格变动或账户专属抵扣。对于生产环境预测，应使用观测到的 token 遥测数据，而不是猜测的聊天长度。

生产指南：暴露本地服务器之前先做好安全防护

Ollama OpenAI 兼容 API 最重要的生产规则很简单：本地 Ollama 服务器默认未经身份验证。

Ollama 默认绑定到 127.0.0.1:11434。其文档说明，OLLAMA_HOST 可以更改绑定地址，Nginx 等代理可以将流量转发至服务器。这些是实现选项，而不是身份验证。如果将服务移出 localhost，请围绕它部署经过审慎设计的控制措施。

生产环境检查清单

1. 除非已有明确的访问路径，否则保留默认的回环绑定。不要将端口 11434 直接暴露到互联网。
2. 在边缘层部署 TLS 和身份验证。根据你的环境使用反向代理、私有网络、服务身份和按客户端授权。虚设的 OpenAI SDK 密钥不是访问控制。
3. 严格限制浏览器来源。Ollama 文档使用 OLLAMA_ORIGINS 配置额外允许的来源。仅添加需要访问的确切 Web 应用或扩展来源；不要将其变成全面绕过跨域限制的手段。
4. 使用模型允许列表。将请求的 model 视为需要验证的输入。生产环境调用方不应能够拉取任意模型或选择未经审查的模型。
5. 设置队列策略并处理过载。Ollama 文档指出，过载服务器可能返回 HTTP 503，并提供 OLLAMA_MAX_QUEUE。使用带指数退避和抖动的有界重试，然后向调用方返回受控失败。
6. 同时进行 VRAM 和并发容量规划。OLLAMA_NUM_PARALLEL 会提高每个模型的并行度，但内存需求也会随之增长。OLLAMA_MAX_LOADED_MODELS 和 OLLAMA_KEEP_ALIVE 决定模型占用内存的积极程度。
7. 为关键路径添加监控。跟踪延迟、排队时间、HTTP 503、活动模型清单、请求大小、流断开、工具调用错误以及 GPU/CPU 内存压力。ollama ps 有助于验证已加载模型的运行位置。
8. 测试重启和冷启动。本地模型在部署或被逐出后可能需要加载时间。在 API 支撑面向客户的工作流之前，执行负载、回滚和超时演练。
9. 不要将密钥放在客户端。对于云端模式，将 OLLAMA_API_KEY 存储在服务器端密钥管理器或受保护的运行时环境中，而不是前端构建包内。
10. 固定验收测试套件，而不仅是依赖版本。每当升级 Ollama、更换模型或修改路由层时，都要重新运行聊天、流式传输、工具、JSON、视觉和响应状态测试。

Ollama 的常见问题文档介绍了这些建议背后的绑定地址、CORS 配置、队列行为、并发设置以及本地/云端控制。

更安全的发布路径

对于起步于本地且日后可能使用托管模型的应用程序，请采用以下顺序：

1. 验证本地端点。拉取一个模型，列出模型，并发送一个非流式聊天补全请求。
2. 稳定 OpenAI 客户端配置。将基础 URL、API 密钥和模型设为环境变量，而不是散落在整个代码库中的字面量。
3. 创建兼容性套件。包括 JSON 输出、流式传输、所有工具模式、相关场景下的视觉输入、超时行为和格式错误的请求。
4. 对主机进行负载测试。记录延迟、队列深度、VRAM/RAM，以及开始出现 503 的临界点。
5. 在远程访问前添加经过身份验证的边缘层。将 Ollama 保持为私有服务，置于应用服务或受信任代理之后。
6. 单独评估云模式。使用专用云密钥、允许列表中的模型、预算警报，以及覆盖云端特定 Responses 限制的测试用例。
7. 将提供商选择与业务逻辑解耦。如果产品需要比较托管模型或添加回退路由，请将 OpenAI 客户端契约封装在一个小型适配器之后。

对于最后一步，OpenAI 兼容 API 网关迁移清单可以帮助您将客户端集成与模型提供商选择分离开来。如果您想在不为每个提供商添加新的客户端模式的情况下评估多个托管提供商，请参阅 Flatkey API 快速入门以及有关何时适合使用 AI API 网关的指南。

使用 Ollama OpenAI 兼容 API 时的常见错误

将 localhost 服务器当作已受保护的服务

本地请求可能成功，是因为进程位于同一台机器上，而不是因为访问已经过身份验证。一旦绑定地址、隧道、代理或容器端口发生变化，就应重新审视身份、网络策略、TLS 和审计日志。

假定具备与 OpenAI 完全一致的功能

Ollama 明确支持 OpenAI API 的一个子集。请将能力检查纳入 CI，并测试语义，而不仅仅是测试是否返回 200 响应。一个能在本地解析的工具定义，在更换模型后可能表现不同。

将云端价格标签当作预算

输入、缓存输入和输出费率可能存在很大差异。记录 token 字段，计算每个成功任务的有效成本，并在承诺固定预算前重新查看定价页面。

在没有内存模型的情况下提高并行度

更多并行请求会增加上下文和内存需求。在更改并发设置前，应使用具有代表性的提示词监控实际主机压力。

将云密钥交给浏览器

浏览器直连云端会使密钥轮换、预算控制和滥用防范变得困难得多。请将云密钥保留在受信任的后端，并且只暴露应用所需的操作。

常见问题

Ollama 的 OpenAI 兼容 API 与 OpenAI API 相同吗？

不相同。Ollama 的兼容层支持 OpenAI API 中有文档说明的一个子集，使兼容客户端能够连接到 Ollama。在将某项功能视为可移植功能之前，请在 Ollama 的兼容性参考文档中确认各个端点和字段。

本地 Ollama API 需要 API 密钥吗？

不需要。Ollama 表示本地 API 不需要身份验证。SDK 示例中的 api_key="ollama" 值是客户端要求的非空值，而不是凭据。请将本地服务器保留在 localhost 上，或在远程暴露前添加实际的控制措施。

Ollama Cloud 需要 API 密钥吗？

需要。直接访问云端 https://ollama.com/v1 时，需要通过 Bearer token 传递 API 密钥。请将其存储在服务端。

我可以使用 /v1/responses 吗？

可以，用于非状态化的 Responses 请求。不要依赖 previous_response_id 或 conversation。云端文档还指出，内置网页搜索以及自定义/自由格式工具调用重放存在限制。

Ollama OpenAI 兼容 API 是免费的吗？

本地推理不会产生按 token 计费的 Ollama 云端费用，但您仍需支付所运行硬件和运维的成本。直接云端推理采用已公布的按 token 定价和账户额度。

我应该何时改用网关？

当本地/云端路径满足工作负载的模型、隐私和运维需求时，请直接使用 Ollama。当您的产品需要跨多个托管提供商的一致集成、模型评估工作流或单独的回退路径时，请考虑使用网关。先明确 统一 AI API 的决策，然后保留相同的应用层客户端适配器。

结论

Ollama OpenAI 兼容 API为开发者提供了一种实用方式，可通过本地或云端提供的模型复用 OpenAI SDK。安全的实现并不只是更改基础 URL：它还需要经过测试的能力矩阵、清晰的本地与云端成本模型、私有的本地部署边界，以及针对队列和模型内存经过负载测试的计划。

如果您需要掌控能力并能够运维硬件，请从本地部署开始。当您希望通过相同的客户端形式获得托管推理时，请使用直连云端。无论哪种情况，都应保持端点选择可配置，并让每项受支持的功能都在您的生产测试套件中证明其价值。