索引层的高频问题
索引层的问题常常静默发生：度量与索引类型不匹配、删除后未整理、分片或参数配置不当、过滤字段没有索引导致退化、批量写入后未 flush 造成数据不可见。排查时要按「数据可见性」与「召回质量」两层分开定位：先确认能搜到，再评估搜得准不准，把两类问题混在一起查会越查越乱。
基本信息
| 可见性层 | 写入是否已 flush 或 refresh，一致性级别是否允许延迟可见 |
|---|---|
| 质量层 | 度量方式、索引参数、模型版本是否被改动过 |
| 过滤层 | 过滤字段是否有索引，是否退化为先检索后过滤 |
| 排查工具 | 集合统计接口、索引参数打印、固定查询的冒烟测试 |
典型使用场景
- 刚导入查不到：判断是可见性延迟还是数据没写进去
- 召回突然变差：核对索引参数、模型版本与语料快照是否被改
- 过滤后结果为空：检查过滤字段索引与条件写法
- 重建期间服务异常：确认是否做了双写或别名切换
- 上线前体检：用固定查询跑冒烟测试，作为发布前置检查
排查入口示例
排查入口示例
print(client.get_collection_stats("kb")) # 文档数是否等于预期
print(index.nprobe, index.ntotal) # FAISS 参数与向量总量
# 用固定查询跑冒烟测试：把结果与上次记录对比，确认索引可用
# 指标记入巡检脚本，异常时第一时间告警而不是等用户反馈
症状与排查方向
| 症状 | 先查什么 | 常见根因 |
|---|---|---|
| 刚写入就搜不到 | 是否已 flush 或 refresh，可见性是否延迟 | 一致性级别与写入确认机制 |
| 偶发召回骤降 | 重建是否进行中、分片是否异常 | 索引参数被改或分片不可用 |
| 过滤后结果为空 | 过滤字段是否有索引 | 字段类型不匹配或条件写错 |
| 分数整体变差 | 度量方式与模型版本是否被改动 | 归一化或模型升级导致分布变化 |
数据可见性与召回质量要分开排查：先确认能搜到，再评估搜得准不准，两件事的修法完全不同。
把冒烟测试做成例行任务：固定几条查询、记录返回条数与分数区间，指标越界就告警，比等着用户报告问题更早发现问题。