本地 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,看监听配置 |
| 401 | key 为空,或代理层校验没过 | 确认请求打到哪一层,key 是否占位填了 |
| 404 | 模型名对不上,或路径写错 | ollama list 里的名字与请求路径逐字对 |
| 能返回但解析失败 | 流式或字段结构不匹配 | 关掉 stream 再跑一次对比 |
工具里如果只支持老的 completions 接口,要先确认这个模型在 Ollama 这边有没有被映射过去。拿不准各家兼容层支持到什么程度,可以到站内的模型资料库页面看当时的说明,别凭印象猜。
流式与参数:能返回但内容乱、或者工具报解析失败
走到这里说明前面都通了,问题只剩返回体。最快的判断动作是把 stream 关掉跑一次:能拿到完整 JSON,说明问题只在流式解析,不在链路。这时候别急着改服务端,先看客户端是怎么按块切数据的。
- 关流式复跑把 stream 设为 false 发一次,拿到完整响应体,确认内容本身没问题
- 对原始响应把这次返回的字段逐项和客户端期望的字段对一遍,缺哪个补哪个,比看报错文案快
- 参数取舍多数兼容层是「认得就转、不认得就忽略」,超时和重试交给客户端那一层设置更稳
参数这块不用追求全量兼容。带过去的温度、最大长度这些,兼容层认就生效、不认就静默忽略,不会报错,所以别拿「参数没报错」当成「参数生效了」。真要确认,把同一个请求发两次对比返回,看设置有没有实际起作用。
最后补一句判断标准:如果按上面四层走完,请求能通、内容也对,只是某个工具偶发解析失败,多半是那个工具对流式的假设和 Ollama 的返回节奏不一致,换回非流式或者换个客户端试,比硬改服务端省事。
下一步想确认自己用的中转或代理层是否可靠,可以到站内的中转站可信度检测页面按项核对;各家接口兼容性的现状,去工具目录里对着看当时的记录。→常见问题
Ollama 需要单独生成一个 api key 吗?
不需要,它本身不校验 key。但调用方的 SDK 往往要求这个参数非空,随便填一个占位字符串就行。真正需要配 key 的是中间那层代理或网关,那种情况按代理那边的规则来。
为什么同样的地址,浏览器能打开、代码里却报连接被拒?
浏览器在宿主机上跑,代码可能跑在容器或另一台机器里。先确认 Ollama 的监听地址不是只绑本机回环,再换成对方能路由到的那个 IP,两边都改完记得重启服务。
换了个客户端就调不通,是不是 Ollama 的问题?
多数时候不是。不同客户端拼 base_url 的方式、要求的模型名格式、对返回字段的容忍度都不一样。把同一个请求先用 curl 打通,再回头对照客户端实际发出去的地址和参数。