超时治理的工程悖论

工具调用（Tool Calling）是 LLM 落地的关键能力，但超时问题常被低估。DeepSeek API 的默认工具调用超时为 30 秒，实际场景中开发者常遇到两类矛盾： 1. 过早放弃：复杂计算任务（如爬取动态页面）未完成即超时 2. 无限阻塞：下游服务宕机导致 LLM 线程池耗尽

分层超时策略

第一层：工具级超时

# DeepSeek API 工具调用示例（显式超时覆盖）
response = client.chat.completions.create(
    tools=[{"type": "web_search", "timeout_sec": 45}],  # 覆盖默认30秒
    tool_choice="auto"
)

- 适用场景：已知特定工具需要更长时间（如 PDF 解析） - 风险：单个长超时会拖累整体会话延迟 - 实施建议： - 根据历史日志统计各工具 P99 耗时 - 超时设置 = P99 * 1.5（留有缓冲但不过度） - 对关键工具（如支付）设置独立超时

第二层：会话级熔断

当连续 3 次工具调用超过 P99 延迟（建议基准值 8 秒）时： 1. 自动降级为纯文本响应 2. 标记该工具为「不稳定」状态 5 分钟 3. 触发告警通知人工检查

实现细节： - 使用滑动窗口计数（如 Redis INCR + EXPIRE） - 熔断状态存储在分布式缓存中 - 恢复时采用渐进式流量放行（10%→30%→100%）

第三层：分布式超时补偿

对于必须完成的工具调用（如支付操作）： 1. 采用异步任务队列 + 幂等ID 2. 超时后记录中间状态到 Redis 3. 通过定时任务补偿执行

关键设计： - 补偿任务需校验上游状态（如支付是否已成功） - 设置最大补偿次数（通常 3 次） - 最终失败转人工处理通道

反面模式

1. 无差别的重试：HTTP 500 错误重试会加剧下游压力
2. 解决方案：对 5xx 错误立即熔断，对 4xx 错误不重试
3. 全局超时设置：timeout=60 会掩盖具体工具的问题
4. 正确做法：为每类工具设置独立超时（通过工具元数据定义）
5. 忽略上下文长度：长会话中的工具调用延迟会累积
6. 缓解方案：
   • 监控总会话耗时（sum(工具耗时) + LLM 处理时间）
   • 超过阈值（如 60s）主动结束会话

DeepSeek 最佳实践

工具分类治理

工具类型	典型耗时	建议超时	熔断策略
快速查询	<3s	5s	错误率>5%熔断5分钟
文档处理	10-30s	45s	连续超时3次熔断10分钟
外部API调用	5-15s	25s	错误率>10%立即熔断

超时与上下文窗口联动

• 16k 上下文：
• 单个工具超时 ≤15s
• 总会话耗时 ≤45s
• 128k 上下文：
• 单个工具超时 ≤30s
• 总会话耗时 ≤120s

熔断指标看板

需要监控的核心指标： 1. 工具调用成功率（按工具类型分组） 2. 平均耗时与 P99 耗时 3. 熔断触发次数/恢复次数 4. 补偿任务执行情况

何时不该用工具调用

当出现以下情况时，建议改用传统 API 编排： 1. 事务一致性要求高：如订单创建→支付→库存扣减 - 替代方案： - 使用Saga模式编排微服务 - 提供明确的回滚接口 2. 下游服务SLA低：如依赖第三方API且SLA<99% - 应对策略： - 前置缓存层 - 兜底数据本地化 3. 调用链路过深：工具A→工具B→工具C - 优化方法： - 合并工具功能 - 改为单次调用+批量处理

实施检查清单

1. [ ] 为每类工具设置独立超时
2. [ ] 实现滑动窗口熔断机制
3. [ ] 配置补偿任务+告警
4. [ ] 监控会话总耗时
5. [ ] 针对关键工具设计降级方案

总结

工具调用超时不是独立问题，需要与会话管理、流量控制协同设计。DeepSeek 的 max_tool_retries 参数（默认3次）应配合业务容忍度调整： - 金融场景：设为1次并立即转人工 - 客服场景：可放宽至5次但增加超时提示 - 数据分析场景：允许长耗时但需进度反馈

最终建议通过压力测试确定各阈值，典型测试案例应包括： - 下游服务响应延迟波动 - 突发流量冲击 - 网络分区模拟