关联：语义检索 · 降级与熔断

发生条件

  • 匹配/召回路径「Qdrant 优先，本地余弦兜底」
  • 客户端默认 QDRANT_URL=http://127.0.0.1:6333，每次请求先 GET /healthz
  • 健康检查超时按秒计（源系统 2s），失败结果缓存很短或没有

症状

  • 本机没跑 Qdrant 时，一次 /api/match 多等 1–2 秒才走本地扫描
  • 集成测试套件里十几次匹配测试被探活拖成几十秒
  • 日志里周期性出现 connection refused，功能却「看起来正常」（因为有兜底）

根因

「有默认 URL」被实现成「默认认为服务可能在」。TCP 探活的失败路径比成功路径更常见：开发机、CI、单测夹具通常没有 Qdrant。把失败探活放在热路径上，等于给每个未部署向量库的环境加固定延迟。

处理

  • 未配置 URL 就不探活，直接本地扫描。要启用 Qdrant 时显式设 RF_QDRANT_URL / JOB_SYSTEM_QDRANT_URL
  • 若必须默认 localhost：健康检查 connect timeout 要到百毫秒级，并且对失败结果做进程级缓存（至少数秒）
  • Qdrant 调用失败按每个学生标签回退本地扫描，把原因写入 meta.degradation，不要 500

下次怎么认

看到向量服务「默认 localhost + 先 healthz」，先问：没起服务时热路径要付多少超时。测试变慢但断言仍绿，多半是探活而不是算法。

项目证据

rolefit-rs 匹配召回：源 qdrant_store.is_available() 默认探 127.0.0.1:6333/healthz（2s，缓存 5s）。Rust 侧改为 URL 未设置则本地扫描；设置后优先 Qdrant，出错记入 meta.degradation 再按标签回退。

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Web