性能分析方法

性能问题定位的核心是「把黑盒拆成链路」，用数据说话，而不是凭直觉加缓存。

定位方法论

graph TD
  A[问题现象] --> B[分段埋点<br/>拆链路]
  B --> C[trace 找最长 span]
  C --> D{最长 span 在哪?}
  D -->|前端| E[渲染/网络/资源]
  D -->|网关| F[路由/鉴权/限流]
  D -->|应用| G[CPU/IO/阻塞]
  D -->|检索/工具| H[向量/rerank/外部 API]
  D -->|LLM| I[TTFT/TPOT/模型档位]
  D -->|DB| J[索引/连接池/慢查询]

四类高频陷阱

1. async 里放阻塞调用：FastAPI async def 端点里用同步 DB 查询 / requests，卡死事件循环——最高频事故
2. 同步锁竞争：如 Qdrant local 单进程锁，需要 threading.Lock + --workers 1
3. 重复计算 / 重复请求：相似请求没有缓存，重复向量化、重复调用 LLM
4. 索引缺失 / 全表扫描：数据库慢查询拖垮整体

决策树定位

遇到「线上变慢」，按顺序排查：

1. 先看监控：是整体变慢还是局部？哪个 span 最长？
2. 再看资源：CPU 打满（计算密集）？内存泄漏？连接池耗尽？
3. 再看依赖：上游 LLM 慢？向量库慢？数据库慢查询？
4. 最后看代码：最近的变更引入的性能回退？

瓶颈定位 Checklist

• 分段埋点是否完整？每个 span 有耗时吗？
• trace 能否定位到最长 span？
• 是 CPU 密集、IO 密集，还是等待上游？
• 有没有缓存缺失导致的重复计算？
• 数据库有没有索引缺失、慢查询？
• 连接池是否配置合理？