Open Notebook 聊天回复特别慢或超时怎么排查？

在 Open Notebook 里使用 Chat 时，回复要等几分钟甚至直接超时，通常由三类原因造成：上下文太大、模型本身慢、或者系统/接口被压满。如果你用的是 Docker 部署，排查路径是固定的：先确认当前用的什么模型，再缩小上下文，然后看日志和资源占用，最后才动 .env 里的超时参数。本文按这条路径给出项目文档中对应的操作与验证方式。

判断慢的类型：模型慢、超时还是限流

开始操作前，先确认你遇到的是哪种现象，因为文档给的处理方式不同：

• 回复本身很慢（要等几分钟才出字）：文档归因为 large context（上下文过大）、slow model（模型慢）或 overloaded API（接口过载）。
• 直接报超时 / "API call failed"：文档归因为 Provider API 故障、网络问题或服务端慢；本地 Ollama 场景还包括 CPU 跑模型慢、以及首次请求要加载模型导致的额外耗时。
• 提示 "Rate limit exceeded" / "Too many requests"：这是撞到了 Provider 的 API 限流，不是慢本身，处理方式是等待而不是加参数。

Open Notebook 现在会对 AI provider 失败显示具体错误信息（例如 "Rate limit exceeded. Please wait a moment and try again."），而不是统一的 "An unexpected error occurred"，先读一下界面上的具体报错可以少走弯路。

第一步：确认并切换更快的默认聊天模型

打开 Settings → Models，查看 "Default Models" 区域的 "Default Chat Model" 当前选的是什么。

项目文档给出了一份模型速度参考（引自 AI & Chat Issues）：

速度档位	模型
最快	Groq（任意模型）
快	OpenAI gpt-4o-mini
中	Anthropic claude-3-5-haiku
慢	Anthropic claude-3-5-sonnet

如果当前默认聊天模型是档位靠后的模型，在 Settings → Models 中切换为更快的模型后，重新发一条同样的消息对比耗时。这一步不需要改任何配置文件。

第二步：缩小进入对话的上下文

文档指出上下文过大是慢的首要原因之一，操作路径为：

1. 在 Chat 中点击 Select Sources；
2. 取消勾选当前用不到的来源；
3. 对只作背景参考的来源，把模式从 "Full Content" 改为 "Summary Only"；
4. Save 后重新提问。

如果来源很多且都很长，文档同时建议把大文档拆分成更小的片段，再让模型处理。

第三步：查日志和系统负载，判断是否被压满

如果换模型、减上下文后仍然慢，在服务器上检查日志和资源占用：

# 看 API 日志里的错误
docker compose logs api | grep -i "error"

# 专门过滤慢操作和超时
docker compose logs api | grep "slow\|timeout"

# 看各容器 CPU/内存占用
docker stats

文档给出的判断标准：如果 CPU 占用超过 80% 或内存超过 90%，说明容器资源吃紧，此时应降低数据库并发任务数来换取稳定（副作用是整体处理会变慢，但冲突减少）：

# 在 .env 中设置
SURREAL_COMMANDS_MAX_TASKS=2

# 重启使配置生效（会重启服务，短暂不可用）
docker compose restart

改完 .env 或执行重启后，用健康检查确认服务恢复：

# 预期返回
curl http://localhost:5055/health
# {"status":"ok"}

如果健康检查本身都要很久才返回，说明瓶颈在 API/网络这一侧而不是模型，可参考 Connection Issues 中 "Timeout / Slow Connection" 一节，用 time curl http://localhost:5055/health 直接测 API 延迟（文档示例预期 < 100ms）。

第四步：调整超时参数

前三步做完后仍超时的，才需要调超时。文档给出的两个变量（见 Environment Reference）：

• API_CLIENT_TIMEOUT：客户端等待 API 响应的秒数，默认 300；
• ESPERANTO_LLM_TIMEOUT：模型推理超时，默认 60。

两者要满足的关系是 API_CLIENT_TIMEOUT 大于 ESPERANTO_LLM_TIMEOUT 加一段缓冲，文档中的示例是：

ESPERANTO_LLM_TIMEOUT=120
API_CLIENT_TIMEOUT=180  # 120 + 60 秒缓冲

FAQ 中还按部署方式给了一份 API_CLIENT_TIMEOUT 建议值表（引自 FAQ）：

部署方式	API_CLIENT_TIMEOUT
云端 API（OpenAI、Anthropic）	300（默认）
本地 Ollama + GPU	600
本地 Ollama + CPU	1200
远程 LM Studio	900

对慢速本地环境，FAQ 给出的完整示例是：

# 在 .env 中
API_CLIENT_TIMEOUT=600  # 10 分钟
ESPERANTO_LLM_TIMEOUT=180  # 3 分钟给模型推理

修改后执行 docker compose restart 生效（会重启全部容器）。注意本地 Ollama 的首个请求还要额外承担模型加载时间，文档把它列为超时的常见原因之一，所以 CPU 部署下超时参数给得更长。

排除限流：Provider 侧的问题按限流处理

如果报错是 "Rate limit exceeded" 或 "Too many requests"，文档的处理顺序是：

1. 立即：等 1–2 分钟再重试；
2. 短期：换更小/更便宜的模型、减少并发操作、拉开请求间隔；
3. 长期：升级账户、换 Provider，或改用本地 Ollama（无速率限制）。

云账户配额可以到对应 Provider 的 usage/billing 页面核对（文档列出了 OpenAI 与 Anthropic 的地址）。这种情况下调大 API_CLIENT_TIMEOUT 没有意义，因为它不是响应慢，而是请求被拒绝。

什么时候算排查完成

• 同样一条消息在换模型/减上下文后明显变快——原因是模型或上下文，保持新配置即可；
• 日志里有 slow/timeout 记录且 docker stats 显示高占用——降低 SURREAL_COMMANDS_MAX_TASKS 后重启，健康检查返回 {"status":"ok"} 且请求恢复；
• 本地 Ollama 环境调大超时后不再超时但首条消息仍慢——属于文档说明的模型加载耗时，后续请求会快一些。

如果按上述路径都无效，文档给出的下一步是完整查看日志（docker compose logs）并按 Troubleshooting Index 中 "How to Report an Issue" 的要求附上精确报错、复现步骤和日志去社区反馈。相关文档入口：AI & Chat Issues、Quick Fixes、Advanced Configuration。