你本地已经跑起 Ollama，也想省掉重写一套调用代码，直接用现成的 OpenAI SDK 打过去。结果十有八九卡在同一处：地址填了官方域名、或者路径少写一段、或者干脆没开兼容入口，报错翻来覆去就那几种，却不知道是网络问题还是配置问题。这篇不重复讲协议和客户端通识，只按工程落地的顺序，把该改的配置、该验的连通、该设的超时和降级列成一份可照着做的清单。
你本地已经在跑 Ollama，手上又是一套写好的 OpenAI SDK 调用代码，最省事的做法当然是不动业务层，只把地址换成本机。但真实情况是十次有九次卡在同一个地方：地址填了官方域名、路径少写一段、或者兼容入口压根没打开。报错翻来覆去就那几种，可你分不清是网络问题还是配置问题。
这篇不讲协议通识，也不重复客户端怎么用，只按工程落地的顺序排一份清单：先开入口，再指 SDK，然后设超时和降级，最后给一套固定的排查顺序。照着走一遍，基本能把「连不上」压缩成一个具体环节，而不是到处乱猜。
先把兼容入口打开，再谈地址
Ollama 默认暴露的是它自己的原生接口，兼容层是另一条独立路径。没启用时用 OpenAI SDK 打过去，只会拿到 404，这时候别急着怀疑 SDK 版本或网络，先确认入口状态。启用后本机同时存在两条可用地址，客户端要指到兼容那条，而不是把官方域名简单换成本机端口。
- 确认兼容入口已启用，未启用时任何 SDK 调用都会撞 404，这是最容易被误判的一步
- 区分两条地址：原生接口和兼容接口路径不同，客户端必须指到兼容那条
- 检查服务监听范围，只监听回环地址时同机能通、容器或另一台设备一定不通
- 跨机调用要显式放开监听地址，只改端口不改监听等于白改
- 改完重启服务，用浏览器或命令行轻量探一次，能返回模型列表说明入口活着
- 启用兼容层按当前服务版本提供的开关方式启用兼容入口，改完必须重启服务，配置不会热生效。
- 探活入口用浏览器或一条最简单的命令行请求打兼容路径的模型列表接口，能返回模型名列表就算入口正常；返回 404 就是没开或路径写错。
- 确认监听范围本机调用没问题但容器或别的设备连不上，九成是监听地址只绑了回环，按部署方式放开监听地址后再重试。
SDK 侧要改的就三个字段
入口通了以后，SDK 侧真正要动的只有三个字段，成套改，别只改一个。很多人只把 base_url 换成本机，模型名却还留着官方默认值，结果拿到一个看着像鉴权失败的连接错误，其实只是模型名不在本地列表里。
| 字段 | 填什么 | 常见误填 |
|---|---|---|
| base_url | 本地兼容入口地址，含兼容路径前缀 | 只填主机加端口，漏掉兼容路径 |
| api_key | 任意非空占位串 | 留空，部分 SDK 会直接抛错 |
| model | 本地已拉取的模型名 | 沿用官方默认模型名，或名字拼错 |
- api_key 本地服务通常不校验，但很多 SDK 对空值会直接报错，填个占位串最稳
- model 名字拼错和模型没下载的报错很像，先确认它确实在本机模型列表里
- 先跑一次最短的非流式请求，成功后再切流式，避免两个变量一起动导致定位不了
- 不同语言的 SDK 对 base_url 是否自动补路径的处理不一致，以实际请求地址为准
超时、重试和换回来怎么设
本地推理的首字延迟和总耗时跟模型体量、机器算力强相关，别照抄云端默认值，先量一版基线再定。想拿到当前这台机器上的真实延迟数字，到 跑一次，用测出来的量级去反推超时阈值，而不是拍脑袋。
| 调用类型 | 超时怎么定 | 重试怎么定 |
|---|---|---|
| 短问答、单轮 | 按基线延迟上浮一档 | 失败即返回，不重投 |
| 长文档、批量 | 单独放宽，和短请求分开配置 | 最多一次，且加退避 |
| 流式输出 | 按首字时间设，不按总时长 | 流中断后按业务决定是否续 |
重试要谨慎。本地显存吃紧时，重试只会加剧排队，长任务建议失败即返回，把错误抛给上层处理。另外一定留一条降级路径：本地服务没起来、或者模型被换掉时，客户端能整体切到远端地址，而不是改代码重新发版。这些开关从环境变量读，别写死在业务代码里。
- 超时按调用类型分档，短请求和长任务不要共用一个值
- 重试次数压到最低，本地资源紧张时重试是有害的
- 降级目标地址、模型名、超时全部走环境变量，方便整体切换
- 具体分几档、每档多少，可对照 的清单来定
连不上时的排查顺序
排查顺序反了会绕远路。固定成三步：先看服务在不在、端口通不通；再看是不是打到了兼容路径上；最后才看 SDK 报错内容。前两步能过，问题基本就锁定在客户端配置上。
- 查服务与端口确认服务进程活着、端口在监听，用最简单的连通性检查打一次，不通就先修服务，别看 SDK。
- 查请求地址把客户端实际发出的完整地址打印出来，看是否命中了兼容路径，漏路径前缀是高频错误。
- 用命令行复现用 curl 打一次同样的地址和参数，能通说明问题在 SDK 配置，不通说明在服务侧，这一步比反复改参数快得多。
- 看日志四项日志至少记下请求地址、模型名、耗时、状态码，只写「失败了」等于没记。
日志字段怎么排、怎么按这四项复盘，可参考 的字段清单。另外本地开发常见的代理劫持和环境变量残留，会让现象看起来像服务挂了，排查思路见 。
下一步先用测速页拿到本机真实延迟，再回填超时和降级配置，比凭感觉设值靠谱得多。→常见问题
不改代码，直接用原来的 OpenAI 客户端能连吗？
大多数情况下可以，前提是客户端允许自定义 base_url、api_key 和模型名。这三个字段里只要有一个被硬编码在库里或者插件内部，就改不动，这时候要么换成能配的调用方式，要么在本机起一层转发把地址固定下来。先确认客户端是否把地址开放成配置项，再决定走哪条路。
为什么模型列表能拉到，实际对话却报错？
列表接口和推理接口走的逻辑不一样，列表能通只说明兼容入口活着，不代表模型加载成功。常见原因是模型名对不上、显存不够导致加载失败、或者参数里带了本地不支持的字段。把请求精简到只剩模型名和一句用户消息再试，能快速区分是参数问题还是模型问题。
本地这条链路适不适合放到生产？
要看并发量和可用性要求。本地服务通常是单实例、没有横向扩容和故障转移，适合个人开发、内网工具、对数据不出机器有硬要求的场景。对外可用的产品建议把它当作降级选项或开发环境，生产主链路还是走稳定托管，两类地址都留在配置里，随时可切。
