本地 ollama 跑通了,代码一改成 OpenAI SDK 就报错——这种场景太常见。多半不是 SDK 版本问题,而是你把它当成真 OpenAI 在用:地址少了 /v1,key 随便填了个空的,模型名写成了官方名字。这篇按调用链顺序捋一遍,卡在哪一步就翻到哪一段,最后给一份上线前能照着打勾的清单。
本地 ollama 跑得好好的,代码一换成 OpenAI SDK 就报错,这种场景太常见了。多数人第一反应是怀疑 SDK 版本、怀疑网络、怀疑模型坏了,实际排查下来,十有八九是地址和鉴权这两格填得不对。说白了,你把它当真 OpenAI 在用了。
这篇按调用链的顺序捋:先地址、再 key、再模型名、最后才是参数和流式。卡在哪一步就翻到哪一段,末尾有一份上线前能照着打勾的清单。别从头看到尾,那样浪费时间。
先解决地址和鉴权,这两格填错占了大半
ollama 的 OpenAI 兼容层挂在 /v1 下面,不是根路径。很多人 base_url 只写到主机加端口,代码一跑就是 404,然后开始怀疑人生。正确写法是把 /v1 带上,路径拼完整。不确定服务活没活,先别动代码,用 curl 打一次模型列表接口,能拿到 JSON 就说明服务端没问题,问题在客户端配置。
curl http://127.0.0.1:11434/v1/modelskey 这块有个坑:ollama 本身不校验 key,但多数 OpenAI SDK 会检查这个字段非空,留空字符串直接抛异常。随便填一个占位串就行,别用真空值。真要给局域网里多人用、想加点门槛,那得在前面挂反向代理做鉴权,ollama 自己不管这事。鉴权相关的名词解释可以去 /ai-dict 翻词条,那里讲得比我细。
还有本机和容器是两种地址。容器里的 localhost 指的是容器自己,不是你的宿主机,得换成宿主地址或者 compose 里的服务名。跨机器访问的情况,ollama 默认只监听本地回环,不改监听地址外面根本连不上,这一步漏了会表现为连接超时而不是报错。
| 现象 | 大概率原因 | 先查什么 |
|---|---|---|
| 404 Not Found | base_url 少了 /v1 | curl 打 /v1/models 看通不通 |
| 401 或 SDK 直接抛异常 | api_key 是空字符串 | 填个占位串再试 |
| 连接超时 | 容器里写了 localhost / 没监听对外网卡 | 换成宿主地址或服务名 |
| 能连上但没反应 | 流式开关和服务端返回方式不一致 | 先关流式跑一次 |
模型名对不上,报的是「找不到模型」不是「连不上」
这个错误的信号很明确:报的是模型不存在,不是网络问题。调用时用的名字必须是 ollama list 里那一列原样的字符串,带 tag 就带上 tag,别自作主张补 :latest,也别顺手改成官方模型名。名字对不上,服务端就是找不到。
- 列一遍本地模型跑 ollama list,把输出的名字整列复制出来,别手打,大小写和 tag 都容易错。
- 确认模型真的拉下来了如果列表里没有,先 ollama pull 拉一次;列表里有但调用仍报找不到,检查是不是连到了另一台机器。
- 把名字挪进配置写死在代码里的字符串换台机器就失效,建议做成环境变量,部署时改一处就够。
参数能过但结果怪,通常出在这几处
请求能通、有返回,但结果不对劲,问题一般落在流式和采样参数上。流式这块最典型:客户端开了 stream,服务端却按非流式一次性返回,表现为一直干等;反过来就是本该逐段吐的结果一口气全出来。排查顺序是先关掉流式,用非流式跑通一次短请求,确认链路没问题再接流式,别一上来就两个变量一起调。
采样参数的默认值各家不一样。同一份代码从 ollama 换到官方 API,温度、top_p 这些不显式写死,结果就会漂。做对比测试的时候把参数全部显式给定,不然你分不清是模型差异还是默认值差异。
还有一类不报错的坑:OpenAI 那边的一些专有字段,比如特定的工具调用写法、结构化输出参数,ollama 不认,但它不会报错,直接忽略。你以为设置生效了,其实压根没起作用。这种最麻烦,只能靠对比输出内容反推。
能通不代表对,参数被静默忽略比直接报错更费时间。
上线前照着打一遍勾
- 能直连 /v1/models 并拿到完整模型列表;
- 同一份 SDK 代码跑通一次非流式短请求;
- 流式请求能正常逐段返回,不是一次性吐完;
- 把 base_url 和模型名从配置里换一遍,代码不用动仍然能跑;
- 超时和重试显式设了值,别用 SDK 默认,默认值在网络抖动时很难看;
- 给局域网多人用的话,确认前面挂了鉴权,别裸奔。
这份清单不覆盖所有情况:如果你是在做多模型对比、或者要接工具调用和结构化输出,那还得单独验一遍字段兼容性,清单打勾不代表这些高级特性一定可用。另外延迟基线最好单独量,别等用户反馈慢了你才发现。
下一步想先量个延迟基线、看看本地这套跑起来到底快不快,去 /tools/speed-test 跑一次,比凭感觉猜靠谱。配置跑通后要挑中转站或者核对价格,站内 /sites 和 /price-watch 有现成的对照,数字以页面当时显示的为准。→常见问题
ollama 需要单独生成 API key 吗?
默认不需要,本地服务不校验 key。但 OpenAI SDK 一般要求这个字段非空,随便填个占位串就能跑。如果要把服务开放给局域网里其他人用,就别只靠这个占位串,得在前面加一层带鉴权的反向代理,否则等于没有访问控制。
为什么官方 OpenAI 能跑的代码,换到 ollama 就报 404?
八成是 base_url 少了 /v1。很多人只填了 http://主机:端口,SDK 会在这个地址后面直接拼 /chat/completions,路径就对不上。补成 http://主机:端口/v1 再试,如果还不行,手动 curl 一次 /v1/models,分清是服务没起来还是路径写错。
流式输出一直不出字或者一次性全出来,怎么排查?
先在代码里把 stream 关掉,确认非流式能正常拿到完整回复;能拿到再开流式。开流式后如果一次性全出来,多半是中间有反向代理做了缓冲,把缓冲关掉或者换直连。如果一直不出字,检查请求体里 stream 字段有没有真的传过去,别只是在 SDK 参数里写了但被上层覆盖。