CoPaw 调用本地 LLM 超时问题排查

凌晨两点，运维群里又一张截图飞过来：”CoPaw 调本地大模型又超时了，整个工作流卡死，麻烦看下。”——这是最近半年我们团队内部、外部用户群里几乎每周都会出现的求救信号。无论是 Ollama、vLLM、LM Studio，还是直接跑 llama.cpp server，超时几乎是本地 LLM 部署绕不开的”成年礼”。但有意思的是，根因往往不在模型本身，而在客户端配置、代理链路、并发治理与服务端启动策略这四个层面。下面按”现象 → 可能原因 → 解决步骤”的顺序，把这一类问题完整拆开，方便读者按图索骥。

顺带说一句，这篇文章是基于 2026 年 8 月当下主流工具链（Ollama、vLLM V1、Caddy 2.x、Traefik 3.x、CoPaw 最新版本）整理的，如果你用的是更老的版本，可能有个别参数位置不一样，老实讲思路是通用的。

一、典型超时现象：先看清错误形态

错误日志通常表现为以下几类，对应不同的失败阶段：

• context deadline exceeded（Go 客户端常见）
• Read timed out / Request timeout（Python requests / urllib3）
• openai.error.Timeout（OpenAI SDK）
• httpx.ReadTimeout / asyncio.TimeoutError（异步 Python）
• 任务在 60s 或 120s 整点断开，且首次推理一定超时，连续请求偶发成功
• 流式模式下，前几秒看到首个 token 之后就再也不动了

关键是先区分连接超时（connect 阶段就失败）与读取超时（连接已建立，等模型返回）。本地 LLM 的瓶颈几乎全部集中在读取阶段——连接一般是直连或同网段，几毫秒内就能完成；而模型推理才是真正吃时间的大头，尤其是冷启动时。区分清楚这一步，后面的排查方向才不会跑偏。

二、超时的常见根因：从经验出发的命中排序

下面这张表是我整理出来的”超时根因 × 排查命令 × 修复手段”对照，建议收藏后下次出问题直接对着看：

命中排序	根因分类	典型征兆	一键排查命令	修复手段
1	客户端超时阈值过短	整点断开（30/60/120s）	看 CoPaw timeout 配置	调到 300s+，区分 connect/connect_total
2	反向代理缓冲与超时	流式首 token 后无响应	nginx -T | grep proxy_buffering	proxy_buffering off + read_timeout 600s
3	冷启动权重加载	首次必超时，后续偶发	OLLAMA_DEBUG=1 看 load duration	warmup 脚本 + OLLAMA_KEEP_ALIVE=24h
4	服务端并发打满	日志 Waiting in queue	nvidia-smi pmon -s u -c 1	调 --max-num-seqs 或加 semaphore
5	DNS / IPv6 回环	::1 连接被拒	curl -4 http://localhost:11434	base_url 写死 127.0.0.1
6	显存不足 CPU 回退	慢得离谱但不报错	nvidia-smi 看显存占用	量化降级 / 换模型 / 升级卡

1. 客户端超时阈值过短

CoPaw 默认 HTTP 超时常为 30s 或 60s。本地 7B+ 模型首 token 推理 + 长 prompt 解析超过该阈值的概率非常高，尤其在冷启动加载模型权重时，30s 完全不够用。这是最常见的超时根因，没有之一。

2. 冷启动与上下文加载

首次调用或切换模型时，Ollama / vLLM 需要把权重从磁盘加载到显存/内存，耗时可达 30~90s。后续调用如果 context 过长，也可能因 KV cache 重算（prefill）而超时。冷启动对消费级显卡尤其明显，因为模型权重往往几十 GB，从 NVMe 加载到显存就要十几秒。

3. 反向代理缓冲与超时

本地 LLM 走 Nginx / Caddy / Traefik 反代时，proxy_read_timeout、proxy_send_timeout 默认 60s，且默认开启响应缓冲，导致首 token 延迟被进一步放大——上游还没生成完，下游已经等不及了。

4. 模型服务端并发打满

vLLM / Ollama 在高并发或长 context 下排队，单次请求可能等几分钟才返回。CoPaw 这种带工作流编排的工具，一次任务常常并发调多次 LLM，极易把服务端打满。

5. DNS 与 IPv6 回落

localhost 在某些环境会先解析到 ::1，但服务只监听 127.0.0.1，出现连接级超时。容器环境下尤其常见。

6. 资源争抢与显存不足

模型权重超出显存，Ollama 自动回退 CPU 推理；或者同一张卡上跑着多个模型/Embedding/重排序服务，互相抢资源。这种”软超时”最难定位——服务端没崩，但慢到客户端放弃。

三、排查与解决步骤：六步二分法

Step 1：直连验证，排除代理层

跳过 CoPaw，直接用 curl 测一次：

time curl -sS http://127.0.0.1:11434/api/generate \
  -d '{"model":"qwen2.5:7b","prompt":"hi","stream":false}'

• 如果直连都超时，问题在服务端（模型/资源），继续 Step 2
• 如果直连快，CoPaw 调用慢 → 客户端或代理问题，跳到 Step 4

这一招看似朴素，但能瞬间砍掉 50% 的误诊。说白了，做二分排查，永远比直接读代码高效。

Step 2：核对服务端监听地址与端口

ss -tlnp | grep -E '11434|8000|1234'
# Ollama:    0.0.0.0:11434
# vLLM:      0.0.0.0:8000
# LM Studio: 127.0.0.1:1234

127.0.0.1 只允许本机访问；CoPaw 部署在另一容器/机器时，必须改为 0.0.0.0 或指定内网 IP。Ollama 修改 OLLAMA_HOST=0.0.0.0:11434 并重启。Docker 部署还要注意 --network host 或者正确端口映射。

Step 3：观察服务端耗时分布

Ollama 启用 verbose 日志：

OLLAMA_DEBUG=1 ollama serve

看 total duration 与 load duration。若 load duration 接近超时阈值 → 模型未常驻内存。处理方式：

• 启动时预热一次（warmup 请求）
• OLLAMA_KEEP_ALIVE=24h 防止自动卸载
• 7B+ 模型确保显存放得下，否则会回退到 CPU 推理，速度慢一个数量级

vLLM 检查 GPU 利用率与排队：

nvidia-smi
# 关注显存占用与 utilization
nvidia-smi pmon -s u -c 1   # 看每个进程的 GPU 利用率

vLLM 日志中 Waiting in queue 频繁出现 → 调大 --max-num-seqs 或降低并发。LM Studio 可以在 GUI 的 Developer 面板看每次请求的 token/s。

Step 4：调高客户端与代理超时

4.1 CoPaw 自身超时配置

很多读者只改了 OpenAI SDK 的超时，结果发现 CoPaw 内部还有一层自己的超时兜底。这里给一份比较完整的 CoPaw YAML 配置，覆盖 timeout / connect_timeout / stream 三个字段的优先级关系：

# CoPaw llm 配置（OpenAI 兼容模式）
llm:
  provider: openai_compatible
  base_url: http://127.0.0.1:11434/v1
  timeout: 300          # 总请求超时（秒），覆盖 SDK 默认
  connect_timeout: 10   # 仅控制 TCP/握手阶段，不影响读取阶段
  stream: true          # 强烈建议开启，见 Step 5
  # 高级：流式场景下的 chunked 读取超时
  stream_read_timeout: 60
  # 失败重试策略
  retry:
    max_attempts: 2
    backoff: exponential

字段优先级说明（实测下来）：timeout 是硬上限，超时立即断开；connect_timeout 只作用于建立连接；stream_read_timeout 是流式场景下两个 chunk 之间的最大间隔。如果不区分设置，connect_timeout 太长反而会拖慢”快速失败”逻辑。

4.2 Nginx 反代关键参数

location /v1/ {
    proxy_pass http://127.0.0.1:11434/v1/;
    proxy_http_version 1.1;
    proxy_buffering off;            # 关键：关闭缓冲，边生成边回传
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    keepalive_timeout 75s;
    proxy_set_header Connection "";
    # 关闭 proxy_cache，否则流式响应会被缓存
    proxy_cache off;
}

proxy_buffering off 是流式响应（streaming）下消除”假超时”的关键。SSE/stream 模式下，即便上游慢，客户端也能持续收到心跳，HTTP 长连接保持活性。

4.3 Caddy 反代写法

reverse_proxy 127.0.0.1:11434 {
    transport http {
        dial_timeout 10s
        response_header_timeout 600s
        read_timeout 600s
    }
    flush_interval -1
}

flush_interval -1 是 Caddy 里对标 Nginx proxy_buffering off 的关键参数，含义是”立刻 flush，不等待”。

4.4 Traefik 配置

Traefik 则需要在 dynamic config 中关闭 buffering：

middlewares:
  llm-strip-buffering:
    retryframework: {}
http:
  routers:
    ollama:
      middlewares: [llm-strip-buffering]

Step 5：启用流式输出

非必要不要用 stream:false。本地模型生成 500 token 可能要 30s+，流式输出把首 token 延迟压到 1~3s，体感完全不同。CoPaw 侧设置：

llm:
  stream: true

流式还带来两个额外好处：1）KV cache 可以边算边给用户看，节省重算；2）用户可以中途打断任务，节省 GPU 时间。说白了，流式对本地 LLM 几乎是一个”白嫖”的优化，真香。

Step 6：IPv6 / DNS 兜底

# 显式指定 IPv4，避免 ::1 回环失败
curl -4 http://localhost:11434/v1/models

或在 CoPaw base_url 直接写 http://127.0.0.1:11434/v1，不要依赖 DNS。生产环境推荐把 LLM 服务绑到内网 IP（如 192.168.1.10:11434），完全绕开 DNS 解析。

四、进阶优化：让本地 LLM 跑得更稳

排查完基础超时之后，还可以在以下几个方向做深度优化。这一节之前在群里发的时候被截断过，这次补齐。

1. 模型常驻与预热

写一个开机自启的脚本，启动后立即发一次 warmup 请求：

#!/bin/bash
# /usr/local/bin/llm-warmup.sh
sleep 30  # 等服务起来
curl -s http://127.0.0.1:11434/api/generate \
  -d '{"model":"qwen2.5:7b","prompt":"hello","stream":false}' > /dev/null
echo "warmup done"

放进 systemd timer 或者 crontab 的 @reboot，确保服务重启后立刻预热。如果你在用 systemd，强烈建议用 After=ollama.service 这种依赖关系，而不是裸 cron，免得服务还没起 warmup 就跑了。

2. 显存监控与告警

写一个简单的监控脚本，超阈值时触发告警：

import pynvml, time, requests
pynvml.nvmlInit()
while True:
    h = pynvml.nvmlDeviceGetHandleByIndex(0)
    mem = pynvml.nvmlDeviceGetMemoryInfo(h)
    util = pynvml.nvmlDeviceGetUtilizationRates(h)
    if mem.used / mem.total > 0.95:
        requests.post("http://alert-manager/webhook", json={
            "msg": f"GPU OOM risk: {mem.used}/{mem.total} util={util.gpu}%"
        })
    time.sleep(30)

进阶一点的话，可以把这个脚本做成 systemd service，并加 Restart=always，避免脚本本身挂了没人在意。

3. 并发控制

CoPaw 工作流如果一次调 5 个 LLM，可以在 CoPaw 侧加个 semaphore，把并发压到 2~3。或者用专门的网关（如 LiteLLM、SGLang Router）做请求合并、优先级队列、限流。

vLLM 的 --max-num-seqs 调优经验：

• 7B 模型 + 24GB 显存卡：并发 8~16 比较稳
• 32B 模型 + 24GB 显存卡：建议压到 2~4
• 长 context（>8k）场景：并发再砍一半

Ollama 侧则可以通过 OLLAMA_NUM_PARALLEL 控制并发数，默认是 1（即同一时刻只处理一个请求），多卡环境可以按显存比例放大。

4. 模型量化与硬件匹配

模型规模	INT4 量化体积	推荐显存	备注
7B	~4 GB	8 GB+	1080Ti/3060 可跑
13B~14B	~8 GB	12 GB+	3080/4070 起步
32B~34B	~20 GB	24 GB+	4090/A5000
70B	~35~40 GB	48 GB+	A100/H100/双卡

选错硬件是”软超时”的隐形杀手——能跑，但是慢到没法用。2026 年的主流本地模型里，Qwen3-32B-Q4 和 DeepSeek-R1-Distill-32B-Q4 都是比较”甜点”的级别，一张 4090 就能跑出不错的体感。

5. KV cache 与上下文管理

长 context 下 KV cache 重算极慢。vLLM 启用 chunked prefill、prefix caching；Ollama 用 --num-ctx 控制最大上下文长度，避免模型在不必要的超长 context 上浪费算力。

如果你在用 DeepSeek-R1 这种 reasoning 模型，注意它的思维链输出本身就长，KV cache 占用会比同规模的常规 dense 模型高不少，–num-ctx 建议默认就好，不要瞎调到 32k 以上。

6. 排查决策树（收束）

最后把整个排查路径压成一张决策树，方便贴工位：

超时
├─ curl 直连也超时？─Y─> 服务端
│   ├─ load duration 高？─Y─> 预热 + KEEP_ALIVE
│   ├─ Waiting in queue 高？─Y─> 降并发 / 升硬件
│   ├─ 显存满？─Y─> 量化 / 换模型 / 加卡
│   └─ 监听 127.0.0.1？─Y─> 改 0.0.0.0
└─ curl 直连正常？─Y─> 客户端/代理
    ├─ 走反代？─Y─> 关 buffering + read_timeout ≥ 600s
    ├─ timeout < 60s？─Y─> 调到 300s+
    ├─ ::1 解析失败？─Y─> base_url 写死 127.0.0.1
    └─ stream:false？─Y─> 改成 true

五、实战案例：一次典型的”假超时”

某用户反馈：CoPaw 调本地 Qwen2.5-14B，每次都超时。

排查过程：

1. 直连 curl：12s 返回，模型推理没问题
2. 看 CoPaw 日志：报 context deadline exceeded，超时阈值 30s
3. 进一步抓包发现，CoPaw 走的是 Nginx 反代 → Nginx proxy_read_timeout 默认 60s → 流式响应被 Nginx 缓冲，等模型生成完才回传给 CoPaw → CoPaw 侧看像是”超时”
4. 解决：Nginx 加 proxy_buffering off、proxy_read_timeout 600s、CoPaw 侧 timeout: 300
5. 改完后首 token 延迟从 12s 压到 1.5s，整体任务从超时变成 20s 完成

这种”假超时”几乎每周都在各个团队重复上演——根因永远是反代缓冲。

六、常见 FAQ（精选摘要向）

七、小结与排查清单

CoPaw 调本地 LLM 超时的高频根因，按命中概率排序：客户端超时阈值过短（最常见）→ 反向代理缓冲/超时 → 服务端冷启动与并发排队 → 监听地址与 DNS 问题 → 显存不足导致 CPU 回退。

附一份 5 分钟快速排查清单：

• ✅ curl 直连是否成功？耗时多久？
• ✅ 服务端监听地址是 0.0.0.0 还是 127.0.0.1？
• ✅ 客户端 timeout 是否 ≥ 300s？connect_timeout 是否 ≥ 10s？
• ✅ 反代是否关闭 buffering？read_timeout ≥ 600s？
• ✅ stream 是否开启？
• ✅ 模型是否常驻显存？显存占用率？
• ✅ 是否走 IPv4？是否避开了 DNS 解析？
• ✅ 日志中是否有 Waiting in queue？并发是否打满？

如果你们在 CoPaw 里调本地 LLM 时还遇到其他诡异超时（比如 TLS 握手、HTTP/2 并发限制、proxy_pass 的 upstream 502），欢迎评论区贴日志一起拆。