大模型应用开发 / 系统课时
排查 API 与流式连接问题
排查 API 与流式连接问题
学习目标
完成本课后,你将能够:
- 根据 DNS、TCP、HTTP、代理和客户端解析层次定位连接故障
- 识别监听地址、CORS、Nginx 缓冲和超时配置问题
- 正确验证 NDJSON 流式响应的逐行边界和结束标记
- 让客户端取消和错误处理能够释放服务端资源
分层定位模型 API
按以下顺序排查:
名称解析
→ TCP 连接
→ TLS 握手
→ 反向代理
→ Ollama HTTP
→ NDJSON 解析
→ 客户端展示越靠前的层失败,越不应继续修改后面的模型参数。例如 TCP 连接被拒绝时,调整 temperature 没有意义。
验证本机服务
直接访问 Ollama:
curl --verbose http://localhost:11434/api/tags预期结果:
TCP 连接成功,HTTP 状态码 200,响应体包含 models 数组。若本机失败:
- 检查服务进程或容器
- 检查端口监听
- 检查日志
- 检查端口冲突
只有本机成功后,才继续排查局域网或代理。
验证监听地址
Linux:
ss -lntp | grep ':11434'预期输出示例:
LISTEN ... 127.0.0.1:11434 ...127.0.0.1 只允许本机访问。需要局域网访问时,应明确配置 OLLAMA_HOST,并配合防火墙、认证和代理。不要把裸端口直接开放到公网。
验证代理与上游
在 Nginx 主机上访问上游:
curl --fail --silent --show-error http://127.0.0.1:11434/api/tags预期结果:
状态码 200,返回 models 数组。测试 Nginx 配置:
sudo nginx -t预期输出中应包含:
syntax is ok
test is successful若上游成功而外部代理失败,重点检查 proxy_pass、TLS、认证、防火墙和 Nginx 错误日志。
流式响应必须逐行解析
生成接口默认返回 NDJSON。使用 curl --no-buffer 观察:
curl --no-buffer http://localhost:11434/api/generate -d '{
"model": "<MODEL>",
"prompt": "依次输出 A、B、C。",
"stream": true
}'预期输出结构:
{"model":"<MODEL>","response":"<CHUNK>","done":false}
{"model":"<MODEL>","response":"<CHUNK>","done":false}
{"model":"<MODEL>","response":"","done":true,...}每行是独立 JSON 对象。不能把多个数据块直接拼成一个 JSON 后再解析,也不能假设一个 TCP 数据包对应一行。
Nginx 流式代理要点
配置片段:
location /api/ {
proxy_pass http://127.0.0.1:11434;
proxy_http_version 1.1;
proxy_buffering off;
proxy_cache off;
proxy_connect_timeout 10s;
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}这是 Nginx 片段。proxy_buffering off 避免代理收集大量响应后再一次性发送。超时应覆盖模型冷启动和最长允许生成时间,但不能无限增大。
浏览器跨域问题
浏览器请求包含 Origin 时会受到同源策略限制。常见表现:
- 命令行
curl成功,浏览器失败 - 控制台提示 CORS
- 预检
OPTIONS请求失败 - 允许来源与实际协议、域名或端口不一致
优先让浏览器访问同源业务后端,由后端调用 Ollama。确需浏览器直连时,再精确配置 OLLAMA_ORIGINS,不要使用无限制来源并同时携带敏感凭证。
客户端超时与取消
超时应拆分:
- 连接超时
- 首字超时
- 数据块空闲超时
- 总请求超时
用户取消时,客户端应关闭下游连接,代理应传递断开,业务后端应停止读取和处理。否则模型可能继续生成并占用资源。
重试只适合尚未产生副作用且没有开始向用户输出的请求。流式回答已经输出一半后自动重试,可能产生重复内容。
常见 HTTP 结果
| 状态或现象 | 优先方向 |
|---|---|
| Connection refused | 服务未启动、地址或端口错误 |
| Connection timed out | 网络、防火墙、路由 |
| 401/403 | 认证或授权 |
| 404 | 代理路径或端点错误 |
| 413 | 请求体超过代理限制 |
| 429 | 应用限流 |
| 502 | 代理无法连接上游或上游异常 |
| 503 | 服务过载、队列已满或不可用 |
| 504 | 代理等待上游超时 |
| 200 但一次性显示 | 代理或客户端缓冲 |
| JSON parse error | 未按 NDJSON 行解析 |
端到端排查记录
每次故障记录:
- 请求时间
- 客户端 URL
- DNS 结果
- TCP/TLS 结果
- HTTP 状态码
- 代理 request ID
- 上游响应时间
- Ollama 日志时间段
- 是否流式
- 收到的最后一个完整 JSON 行
- 客户端是否取消
- 修复动作与复验结果
有时间线才能关联代理、应用和 Ollama 的同一次请求。
本课练习
练习 1:定位 curl 成功但浏览器失败
任务目标:识别同源与 CORS 问题。输入或初始条件:同一 URL 在终端返回 200,浏览器控制台报跨域。实现要求:检查 Origin、预检和允许来源。验收条件:通过同源后端或精确 CORS 配置解决。
练习 2:修复流式变完整返回
任务目标:识别代理缓冲。输入或初始条件:直连 Ollama 逐块输出,经 Nginx 后等待结束才显示。实现要求:对比两条链路并调整缓冲。验收条件:代理链路也能持续收到数据块。
练习 3:处理客户端取消
任务目标:避免用户离开后模型继续计算。输入或初始条件:前端有停止生成按钮。实现要求:设计取消信号、连接关闭和后端清理。验收条件:取消后 Ollama 资源不继续增长。