大模型应用开发 / 系统课时

排查 API 与流式连接问题

排查 API 与流式连接问题

学习目标

完成本课后,你将能够:

  • 根据 DNS、TCP、HTTP、代理和客户端解析层次定位连接故障
  • 识别监听地址、CORS、Nginx 缓冲和超时配置问题
  • 正确验证 NDJSON 流式响应的逐行边界和结束标记
  • 让客户端取消和错误处理能够释放服务端资源

分层定位模型 API

按以下顺序排查:

text
名称解析
→ TCP 连接
→ TLS 握手
→ 反向代理
→ Ollama HTTP
→ NDJSON 解析
→ 客户端展示

越靠前的层失败,越不应继续修改后面的模型参数。例如 TCP 连接被拒绝时,调整 temperature 没有意义。

验证本机服务

直接访问 Ollama:

bash
curl --verbose http://localhost:11434/api/tags

预期结果:

text
TCP 连接成功,HTTP 状态码 200,响应体包含 models 数组。

若本机失败:

  • 检查服务进程或容器
  • 检查端口监听
  • 检查日志
  • 检查端口冲突

只有本机成功后,才继续排查局域网或代理。

验证监听地址

Linux:

bash
ss -lntp | grep ':11434'

预期输出示例:

text
LISTEN ... 127.0.0.1:11434 ...

127.0.0.1 只允许本机访问。需要局域网访问时,应明确配置 OLLAMA_HOST,并配合防火墙、认证和代理。不要把裸端口直接开放到公网。

验证代理与上游

在 Nginx 主机上访问上游:

bash
curl --fail --silent --show-error http://127.0.0.1:11434/api/tags

预期结果:

text
状态码 200,返回 models 数组。

测试 Nginx 配置:

bash
sudo nginx -t

预期输出中应包含:

text
syntax is ok
test is successful

若上游成功而外部代理失败,重点检查 proxy_pass、TLS、认证、防火墙和 Nginx 错误日志。

流式响应必须逐行解析

生成接口默认返回 NDJSON。使用 curl --no-buffer 观察:

bash
curl --no-buffer http://localhost:11434/api/generate -d '{
  "model": "<MODEL>",
  "prompt": "依次输出 A、B、C。",
  "stream": true
}'

预期输出结构:

text
{"model":"<MODEL>","response":"<CHUNK>","done":false}
{"model":"<MODEL>","response":"<CHUNK>","done":false}
{"model":"<MODEL>","response":"","done":true,...}

每行是独立 JSON 对象。不能把多个数据块直接拼成一个 JSON 后再解析,也不能假设一个 TCP 数据包对应一行。

Nginx 流式代理要点

配置片段:

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 资源不继续增长。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 API 与流式连接问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通