ollama:本地大模型 webapi 调用

本地模型能跑起来，不代表后端能顺利调通。很多人在这一步卡住：端口和地址记混、请求体字段写错、流式响应解析出一堆半截 JSON、上下文一超就静默截断。这篇按后端视角，把 Ollama 的 HTTP 调用拆成确认服务、发请求、读响应、排错四步，每步给可执行动作和判断标准，不讲原理堆砌。

本地模型能跑起来，不代表后端能顺利调通。很多后端同学卡在调用这一步：端口和地址记混、请求体字段写错、流式响应解析出一堆半截 JSON、上下文一超就静默截断，报错信息还含糊不清。

这篇按后端视角，把 Ollama 的 HTTP 调用拆成确认服务、发请求、读响应、排错四步，每步给可执行的动作和判断标准。不讲原理堆砌，只讲你怎么把它接进现有后端。判断标准是通用口径，具体参数和数值随着版本会变，去站内页面核对当时的数字。

第一步：先确认服务真的在监听

别急着写业务代码。先用一条最简请求验证服务活着，地址和端口认准本地回环与默认端口，别照抄别人博客里的主机名。验证这一步的意义在于把「网络问题」和「代码问题」切开，否则后面每一步排查都要同时怀疑两个层。

• 用最简请求先探活，能返回信息再往下写业务逻辑
• 确认监听范围：只绑本地回环时，容器内或局域网其他机器调不通，要显式改绑定地址
• 后端跑在 Docker 里时，本地回环指的是容器自己，不是宿主机，需要换成宿主机可达地址或走同一网络
• 接口地址与可用端点的完整清单，到 /ollama-api-endpoint-guide 和 /ollama-api-endpoints-2 对一遍

第二步：请求体怎么写才不出错

先分清两类入口：Ollama 原生接口和兼容 OpenAI 风格的接口。两者字段名不一样，混着写必然报参数错。如果你已经有一套基于 OpenAI SDK 的代码，优先考虑走兼容层而不是重写，改造成本和坑位都更少，参考 /ollama-openai-api-bridge。

必填字段通常是模型名加消息或提示词。可选字段里影响最大的是是否流式、采样温度、上下文长度上限，先只调这几个。模型名要和本地已有的标签一字不差，大小写和冒号后的后缀都算数。

1. 定入口先决定走原生接口还是兼容层，两套字段不能混用，选定后按对应文档写
2. 填必填模型名加消息或提示词，模型名和本地标签逐字对齐
3. 控可选只先设是否流式、温度、上下文上限三个，其他先留默认
4. 验证用一条非流式请求打底，确认字段正确后再开流式

第三步：流式响应的解析与超时处理

流式返回是一行一个 JSON 对象，不是一整段合法 JSON。用整体反序列化会直接抛错，要按行切分再逐条解析。这是新手最常踩的一脚：本地手动 curl 看着有输出，一进代码就崩。

• 按行切分再逐条解析，不要对整段响应做一次反序列化
• 客户端要处理三种结束情形：正常收到结束标记、连接被中断、长时间没有新分片
• 给读超时设一个上限，别用无限等待，否则卡死的连接会占满连接池
• 首字节延迟和整体耗时是两码事，前者决定用户觉得卡不卡，后者决定贵不贵
• 要不要把流式直接透传给前端要想清楚：透传省事但难加日志和审计，中间拦一层则要处理分片边界

调优前后都用 /tools/speed-test 量一遍基线再改参数，别凭感觉调。没有基线，你无法判断一次改动到底是变快还是变慢。

第四步：按顺序排查常见失败

排查要有顺序：先看服务是否可达，再看模型是否已下载，再看请求体字段，最后看资源是否够。不要一上来就怀疑模型质量，大部分失败跟模型本身没关系。

连接类报错优先查地址、端口、绑定范围和代理设置；代理变量没清干净会让本地请求绕到外网，表现就是莫名其妙的超时。响应慢或中途断流，多数是显存或内存被挤满，参考 /ollama-api-connection-fail 与 /chatbox-ollama-connect-fail 的排查思路。如果持续不稳定，评估换推理框架，对照 /vllm-vs-ollama-selection。

上生产前过一遍这张清单

本地调通和能上生产是两件事。上线前把下面这些过一遍，能挡掉大部分后期救火。哪一条不适用，取决于你的调用量和部署形态，小团队单机跑和多人共享一台机器要求完全不同。

• 给调用加一层薄封装：统一超时、重试、日志和降级，别让业务代码直接裸调
• 明确并发上限：本地单实例并发能力有限，排队策略要在应用侧做，别指望服务端兜
• 把模型名、地址、超时做成配置项，换模型和换机器时不用改代码
• 调用量、失败率、延迟分位数要有监控，接口是否稳定可对照 /ai-status 与 /tools/quality-monitor 的口径

先把服务探活、再对齐字段、最后按顺序排错，比一上来调参数省的时间多得多。