当你准备在本地项目里用 OpenAI SDK 直接连 Ollama 时,关键不是装额外插件,而是把 OpenAI SDK 的 base_url 指向 Ollama 的兼容接口,并填入一个任意非空字符串作为 api_key。Ollama 默认监听本机 11434 端口,兼容接口路径是 /v1。也就是说,base_url 通常设置为 http://127.0.0.1:11434/v1,api_key 只需要满足 SDK 的格式要求,内容本身不会被验证。这个配置适用于 OpenAI Python SDK 0.x 与 1.x 大部分版本,也适用于 JavaScript SDK、LangChain 的 OpenAI 封装等遵循同一接口约定的工具。
确认 Ollama 服务地址与端口
先确认 Ollama 服务是否真的在 127.0.0.1:11434 上监听。在本地终端执行 curl 请求兼容接口的根路径:
curl http://127.0.0.1:11434/v1/models
如果返回一个包含 models 字段的 JSON 列表,说明端口和路径可用。如果连接被拒绝或超时,则可能是 Ollama 服务未启动,或者服务绑定在非默认地址。修改 OLLAMA_HOST 环境变量可以改变监听地址,例如 OLLAMA_HOST=0.0.0.0:11434 表示监听所有网卡;但只有明确需要局域网访问时才建议这么做,且需要评估同网段其他设备的访问风险。
OpenAI SDK 中的 base_url 与 api_key 写法
以下是以 Python OpenAI SDK 为例的最小配置。关键点是 base_url 必须包含 /v1 路径,api_key 用任意字符串占位,例如 "ollama"。不要把占位符留空,因为部分 SDK 版本在 api_key 为空时会直接报错或拒绝请求。
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:11434/v1",
api_key="ollama" # 非空占位即可,Ollama 不校验该值
)
response = client.chat.completions.create(
model="qwen2.5:7b",
messages=[
{"role": "user", "content": "介绍一下 base_url 的设置"}
]
)
print(response.choices[0].message.content)
这里的 model 参数必须是本地已通过 ollama pull 拉取到的模型名称,否则 Ollama 会返回 404 model not found。执行位置是任意可运行 Python 的目录,先通过 pip install openai 安装 SDK,再运行该脚本。验证方式是脚本能打印出模型生成的文本内容;如果出现连接错误或 404,优先检查 base_url 是否写错、Ollama 是否启动、模型名是否与 ollama list 输出一致。
请求失败时的检查顺序
当调用不通时,不要先怀疑 api_key。Ollama 的兼容层不校验 api_key,所以常见的失败原因集中在三类:服务地址、模型名称、路径写法。先用 curl 测试 http://127.0.0.1:11434/v1/models 是否返回 JSON;再执行 ollama list 确认模型准确名称;最后检查代码中 base_url 是否漏了 /v1,以及 SDK 是否因为环境变量 OPENAI_BASE_URL 或 OPENAI_API_KEY 而覆盖了你在代码里的设置。某些运行环境中如果预先设置了 OPENAI_BASE_URL,SDK 会优先读取环境变量,导致你显式写的 base_url 不生效。可以在脚本开头打印 client.base_url 来确认实际生效的地址。
关于 api_key 的常见误解
OpenAI SDK 要求 api_key 参数存在且为字符串,但 Ollama 不会对这个字符串做真实校验。因此你不需要去 Ollama 生成或配置任何 key。有人习惯用 api_key="ollama",也有人用 api_key="EMPTY",都可以工作。真正的边界是:不要把本地 Ollama 服务暴露到公网,因为兼容接口虽然没有 key 校验,但一旦暴露,任何人都能调用你本机的模型,可能造成资源占用或数据泄露。如果需要在局域网共享,建议通过反向代理加访问控制,而不是直接开放端口。
不同语言 SDK 的通用性边界
除 Python 外,Node.js 的 openai 包也支持同样的两个参数:baseURL 和 apiKey。还有 LangChain 中通过 ChatOpenAI(base_url=..., api_key=...) 调用本地 Ollama 的方式,本质上都是指向同一个兼容接口。需要注意的是,并非所有 OpenAI SDK 功能都能被 Ollama 兼容层支持,例如函数调用(function calling)在 Ollama 的 /v1 接口上的行为取决于具体模型能力。如果业务依赖某个 OpenAI 特有参数,需要先看 Ollama 官方对该接口的支持范围,或通过最小请求验证。这里只讨论 base_url 与 api_key 的通用设置,不涉及每个 SDK 的全部参数。
建议的验证流程
- 启动 Ollama 服务,并在终端确认
ollama list能看到目标模型。 - 用
curl http://127.0.0.1:11434/v1/models验证 HTTP 接口可达。 - 在代码中设置 base_url 为
http://127.0.0.1:11434/v1,api_key 为任意非空字符串。 - 发送一个最简单的 chat completion 请求,观察返回内容。
- 若失败,检查环境变量是否覆盖了代码中的 base_url,并核对模型名。
这个配置路径适用于本地开发、调试、单机脚本等场景。Ollama 服务所在机器与调用代码所在机器不同时,只需把 base_url 中的 127.0.0.1 换成 Ollama 所在机器的实际 IP,同时确认防火墙允许对应端口访问。但在修改监听地址或放开端口前,先明确这是否真的是需求,避免为一个本地调试需求引入不必要的网络暴露面。