很多人本地已经把 Open WebUI 和 Ollama 跑起来了，界面里聊天一切正常，可一想让自己的脚本、后台或小工具也来调同一批模型，就卡在地址写哪个、端口对不对、流式怎么收这些问题上。这篇不重复讲协议兼容层和客户端怎么配，只按工程落地顺序，把调用前的确认、调用中的参数取舍、上线前后的排错与记录的清单列出来，照着走一遍就能少绕几圈。
很多人本地已经把 Open WebUI 和 Ollama 跑起来了，界面里聊天一切正常，可一想让自己的脚本、后台或小工具也来调同一批模型，就卡在地址写哪个、端口对不对、流式怎么收这些问题上。这篇不重复讲协议兼容层和客户端怎么配，只按工程落地顺序，把调用前的确认、调用中的参数取舍、上线前后的排错与记录的清单列出来。
照着走一遍，最少能少绕几圈：先分清自己打的到底是谁的接口，再把超时、流式、上下文这几项按业务需求定死，最后把并发和日志补上。每一步都给验收方式，不是看完就算，而是能自己判断「这步过了没」。上限不是绝对的，本地单机跑几个小工具和团队共享一台推理机，做法差别很大，下面会说明哪些情况下不适用。
动手前先把三件事确认掉
第一件是接口身份：你调的是 Open WebUI 自己那层的接口，还是直接打 Ollama 的原生接口，两条路的地址、端口和鉴权方式并不一样，选错就会一直连不上。判断方法很简单，看你打开的是哪个端口，以及请求发出去之后，日志是打在 Open WebUI 的进程里还是 Ollama 的进程里。对这个区别还没底的，先去站内看看两边各自适合什么场景，再决定走哪条。
- 确认 Ollama 监听在哪个地址上：只绑本机时，同机脚本能通但局域网里另一台设备调不通，「浏览器里能用、代码里不通」多半就是这个原因
- 确认端口有没有被别的服务占用，尤其是你同时跑着多个推理框架的时候，先看端口归属再改配置
- 用一条最小请求先验通，别一上来就写完整业务逻辑；连通性和响应基线，可以到 /tools/speed-test 先跑一遍再谈调优
- 把当前配置抄一份留底，包括环境变量和启动命令，改坏了能退回去
调用参数：哪些必须自己定，哪些别乱动
超时是最容易踩的坑。本地模型首次加载权重很慢，读超时给太短会表现成「请求失败」，实际上模型只是还在往内存里搬。建议把连接、读取、整体三段分开设，连接段可以短，读取段要留给首次加载，整体段兜底。流式还是非流式按用途选：要逐字上屏就用流式，要一次性拿到完整结构再解析就用非流式。
| 参数 | 建议怎么定 | 什么时候不适用 |
|---|---|---|
| 连接超时 | 设短，快速暴露地址或端口写错 | 网络本身不稳的跨机房调用要放宽 |
| 读取超时 | 留给首次加载和长输出，宁可偏长 | 交互式问答想快速失败时反而要收紧 |
| 流式开关 | 要逐字上屏开，要整体解析关 | 同段解析代码不要两种都吃 |
| 上下文长度 | 按业务最短够用写，别一上来顶满 | 需要长文档整体理解时另行评估 |
| 输出上限 | 按预期回答长度留一点余量 | 对格式敏感的解析型任务要卡上限 |
还有一条容易被忽略：同一个应用里流式和非流式混用没问题，但别指望同一段解析代码两边都能吃。流式收到的是分片，非流式收到的是完整对象，解析入口就要分开写。判断标准是：你要不要在生成过程中就给用户看东西，要就流式，不要就非流式，别为了「看起来高级」强行上流式。
并发与降级：本地跑和调云端不是一回事
本地推理是排队执行的，你开十个并发不等于快十倍，反而更容易把请求全拖成超时。做法是先压一个固定并发数，看平均耗时和失败率怎么变，再决定要不要加。假设一家 5 人小团队共用一台机器，两个人做交互问答、三个人跑离线批处理，这时候更要分档，不然批处理一上来，交互那两个人直接卡住。
- 先压单并发用一个固定请求连续打若干次，记下平均耗时和失败率，这是后面所有对比的基线。
- 逐步加压每次只加一点并发，观察耗时是缓慢上升还是突然崩掉，崩掉的点就是这台机器的实际上限。
- 按用途分档交互式问答给短超时快失败，离线批处理给长超时慢慢跑，两拨流量分开排队，别互相堵死。
- 设好降级条件把「切走」的判断写成指标，比如连续超时多少次或排队多久，切成别的入口继续跑，不要靠人盯。
降级路径要提前准备好，但触发条件必须写死成指标。人盯的降级等于没有降级，半夜排队爆了没人会切。如果你们的请求本身就是低频、可等待的，那这套降级可以先不做，等真的出现排队堵塞再加也不迟。
日志与验证：出问题时要能复盘
每条请求至少记下这几项：走的是哪个地址和模型、参数摘要、耗时、是否流式、结束状态。缺了其中一项，出问题基本查不动。尤其是模型名和地址，本地环境里经常同时存着好几份模型，不记清楚根本对不上。日志怎么分类、保留多久，可以按你们自己的合规要求定。
- 连不上：地址、端口、防火墙、服务有没有起，先排这一类
- 连上了被拒：鉴权、跨域、路径写错，属于配置层
- 连上了但没结果：模型在加载、上下文超限、输出被截断，属于推理层
- 结束状态要区分正常结束和超时中断，两者在日志里不能长一个样
报错先分层看，按连不上、连上了被拒、连上了但没结果这个顺序排，比盲目改配置快得多。改动配置或换模型之后，用同一组固定问题重跑一遍对比，别只凭一次体验说「好像快了」。想横向看不同入口在当前时间点的表现和价格，到 /rankings 和 /price-watch 核对当时的数字，不要凭记忆下结论。
下一步拿一条最小请求把链路打通，把基线记下来，再按上面的清单逐项补齐参数、并发和日志。想先看别人踩过的坑和当前入口表现，去这几个页面翻一翻再动手。→常见问题
Open WebUI 里能聊天，为什么我的代码调不通？
最常见的是地址和端口没对上：界面走的是容器内或本机回环地址，你的代码在另一台机器或另一个容器里，解析到的是完全不同的位置。先确认 Ollama 实际监听的地址和端口，再用同一台机器上的一条最小请求验证，能通再往外扩。
调用本地模型需要填 API Key 吗？
默认情况下本地 Ollama 不做鉴权，不填也能调；一旦你把它暴露到局域网或公网，就建议在中间加一层带鉴权的转发，不要让裸接口直接对外。具体要不要、怎么加，取决于你的部署边界，公网可访问就必加。
返回内容断了一半或者卡住不动怎么办？
先分清是流式连接被中途掐断，还是模型本身生成太慢。流式场景把读超时放宽、并确认中间没有代理缓冲；非流式场景看总耗时是不是超过了你的超时设置。断流的具体分层排查思路可以对照站内流式输出相关的文章走一遍。
