ollama 转 openai api常见问题:照着这份清单核对一遍

模型与算力

把 Ollama 伪装成 OpenAI 接口时最容易出错的几处——地址、鉴权、路径、模型名、流式——按顺序核对一遍就能定位。

本地 Ollama 跑通了,接着想让现成的 OpenAI SDK 或某个工具直接连上来,多数人第一次都会在这一步卡住:报错五花八门,但八成不是代码写错。这篇不讲原理,只给一份按顺序核对的清单,从最外层地址一直查到最里层的流式返回,每一步都告诉你看到什么现象该往哪调。

本地 Ollama 装好、命令行里跑通了,接着想让现成的 OpenAI SDK 或某个第三方工具直接连上来。多数人第一次在这一步都会卡住:报错五花八门,看着像代码写错,实际上八成是地址、鉴权或者模型名对不上。这篇不讲原理,只给一份按顺序核对的清单,从最外层地址一直查到最里层的流式返回,每一步都告诉你看到什么现象该往哪调。

顺序很关键。别一上来就怀疑代码,先分清是「连不上」还是「连上了但被拒」,这两类问题的排查方向完全相反。下面按从外到里走一遍。

先分清是连不上,还是连上了但被拒

最外层是 base_url。OpenAI SDK 的写法通常要求填到以 /v1 结尾,只填主机和端口、让它自己再拼一次路径,结果就会变成两段 v1,请求打到一个根本不存在的路由上。这一步用 curl 单独打一次就够,只验证链路和鉴权,先别上业务代码,把变量收紧再谈别的。

curl http://127.0.0.1:11434/v1/models

返回一份模型列表,说明链路通了;连接被拒或者超时,就是服务没起或者地址不对。还有个坑:127.0.0.1 只对本机有效,客户端跑在容器里、或者换另一台机器连,得让 Ollama 监听在 0.0.0.0,然后用宿主机 IP 去访问。改完监听地址记得重启服务,改环境变量不重启是最常见的白折腾。

api key 这一格:填什么都行,但不能空着

Ollama 自身不做 key 校验,但 OpenAI SDK 和不少工具在 api_key 为空时会直接抛错,根本走不到发请求那一步。随便填一串占位字符即可。如果有反向代理或网关挡在前面,key 的校验就发生在那一层,这时得按代理那边配的来,不能拿 Ollama 的行为套。

模型名与路径:报 404 多半是这两个

到了这一层,现象是链路通、有响应,但请求被拒。model 字段要填 ollama list 里看到的名字,带不带 :latest 视客户端而定,两边对不上就会 404。另一个常见误判是把 /v1/chat/completions 和 Ollama 原生的 /api/chat 混着抄,参数名和返回结构都是两套东西,抄串了自然报错。

现象最可能的原因先查什么
连接被拒 / 超时服务没起,或监听地址只对本机curl 打一次 /v1/models,看监听配置
401key 为空,或代理层校验没过确认请求打到哪一层,key 是否占位填了
404模型名对不上,或路径写错ollama list 里的名字与请求路径逐字对
能返回但解析失败流式或字段结构不匹配关掉 stream 再跑一次对比

工具里如果只支持老的 completions 接口,要先确认这个模型在 Ollama 这边有没有被映射过去。拿不准各家兼容层支持到什么程度,可以到站内的模型资料库页面看当时的说明,别凭印象猜。

流式与参数:能返回但内容乱、或者工具报解析失败

走到这里说明前面都通了,问题只剩返回体。最快的判断动作是把 stream 关掉跑一次:能拿到完整 JSON,说明问题只在流式解析,不在链路。这时候别急着改服务端,先看客户端是怎么按块切数据的。

  1. 关流式复跑把 stream 设为 false 发一次,拿到完整响应体,确认内容本身没问题
  2. 对原始响应把这次返回的字段逐项和客户端期望的字段对一遍,缺哪个补哪个,比看报错文案快
  3. 参数取舍多数兼容层是「认得就转、不认得就忽略」,超时和重试交给客户端那一层设置更稳

参数这块不用追求全量兼容。带过去的温度、最大长度这些,兼容层认就生效、不认就静默忽略,不会报错,所以别拿「参数没报错」当成「参数生效了」。真要确认,把同一个请求发两次对比返回,看设置有没有实际起作用。

最后补一句判断标准:如果按上面四层走完,请求能通、内容也对,只是某个工具偶发解析失败,多半是那个工具对流式的假设和 Ollama 的返回节奏不一致,换回非流式或者换个客户端试,比硬改服务端省事。

下一步想确认自己用的中转或代理层是否可靠,可以到站内的中转站可信度检测页面按项核对;各家接口兼容性的现状,去工具目录里对着看当时的记录。

常见问题

Ollama 需要单独生成一个 api key 吗?

不需要,它本身不校验 key。但调用方的 SDK 往往要求这个参数非空,随便填一个占位字符串就行。真正需要配 key 的是中间那层代理或网关,那种情况按代理那边的规则来。

为什么同样的地址,浏览器能打开、代码里却报连接被拒?

浏览器在宿主机上跑,代码可能跑在容器或另一台机器里。先确认 Ollama 的监听地址不是只绑本机回环,再换成对方能路由到的那个 IP,两边都改完记得重启服务。

换了个客户端就调不通,是不是 Ollama 的问题?

多数时候不是。不同客户端拼 base_url 的方式、要求的模型名格式、对返回字段的容忍度都不一样。把同一个请求先用 curl 打通,再回头对照客户端实际发出去的地址和参数。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。