多模态检索测试：向量索引、嵌入质量与召回评估的验证工程

- 跨模态对齐：文字 query ↔ 图片 / 图片 ↔ 文字 的相似语义
- 模态内变体：同物不同图（角度/光照/风格）、同义不同词
- 嵌入漂移：模型升级后向量分布变化，旧索引全部失效
- 检索+生成耦合：RAG 里检索错了，生成也会跟着错

检索质量指标：
  召回率（Recall@K）：真实相关结果里，Top-K 命中了多少
  精确率（Precision@K）：Top-K 里有多少是真相关的
  MRR（Mean Reciprocal Rank）：第一个相关结果的排位
  NDCG：考虑相关等级与位置的加权质量
  MAP：平均精确率（跨查询平均）

评估依赖 ground truth：
  - 标注集：query → 相关结果列表（人工标注/专家标注）
  - 基准集：标准评测集（如 MS-COCO 图文检索、自然图像检索基准）

# 伪代码：检索指标计算
def evaluate_retrieval(queries, golden, retriever, k=10):
    recalls, mrr_sum = [], 0
    for q in queries:
        hits = retriever.search(q, k=k)         # Top-K 结果
        rel_ids = golden[q]                      # 真实相关集
        hit_rel = [r for r in hits if r in rel_ids]
        recalls.append(len(hit_rel) / len(rel_ids))
        for i, r in enumerate(hits, start=1):
            if r in rel_ids:                     # 首个相关的倒排位
                mrr_sum += 1 / i; break
    return {
        "recall@10": mean(recalls),
        "mrr": mrr_sum / len(queries),
        "precision@10": ...,                    # 同理
    }

评估集要覆盖：
  - 简单正例：明确相关的查询（基线）
  - 难例：歧义、长尾、同义改写、跨语言
  - 负例：易混淆但不相关的（考验精确率）
  - 分布对齐：评估集的 query 分布接近线上真实查询

评估集维护：
  - 新标注定期补充（覆盖新模态/新类目）
  - 线上反馈回流（搜索无点击 → 弱负例）
  - 评估集版本化：指标基线随集版本演进

索引测试要点：
  - 召回率对比：近似索引 vs 暴力精确检索（brute force）
    对同一查询集，近似召回与精确召回的差异（recall@k 掉多少）
  - 参数敏感性：HNSW 的 efSearch / M、IVF 的 nprobe 对召回的影响
  - 边界向量：稀疏向量、全零向量、超长维度向量的稳定性

召回完整性的工程含义：
  efSearch 越大召回越全但越慢 → 测试要给出「参数-召回-延迟」曲线

# 伪代码：近似索引召回对比
def test_index_recall():
    queries = sample_queries(1000)
    exact = brute_force_index(all_vectors)
    approx = HNSWIndex(all_vectors, ef_search=64)
    recalls = []
    for q in queries:
        exact_hits = {v.id for v in exact.knn(q, k=10)}
        approx_hits = {v.id for v in approx.knn(q, k=10)}
        recalls.append(len(exact_hits & approx_hits) / 10)
    assert mean(recalls) >= 0.95, f"近似索引召回仅 {mean(recalls):.3f}"

索引生命周期：
  - 增量更新：新向量插入后查询可命中
  - 删除：向量删除后不再被召回
  - 重建：索引重建后查询结果一致
  - 一致性：多副本索引查询结果一致
  - 脏数据：损坏/重复向量不破坏查询

CRUD 测试：
  插入 1 万 → 查命中；删 5 千 → 查不中；重建 → 结果同前

嵌入质量维度：
  - 语义相近 → 向量相近：同义句对距离应小于无关句对
  - 语义包含/排除：上下位、类比关系在向量空间可表达
  - 粒度：区分细粒度差异（「蓝色跑鞋」vs「白色跑鞋」）
  - 尺度稳定性：文本长度变化不影响语义距离（归一化）

方法：构造「正负样本对」（siamese 评估）：
  正对 = 语义相同，负对 = 语义不同 → 余弦距离应正确分离

# 伪代码：嵌入距离评估
def evaluate_embeddings(model, pairs):
    pos_dist, neg_dist = [], []
    for anchor, pos, neg in pairs:               # 三元组
        d_pos = cosine(model(anchor), model(pos))
        d_neg = cosine(model(anchor), model(neg))
        pos_dist.append(d_pos); neg_dist.append(d_neg)
    # 正对距离应明显小于负对（margin）
    assert mean(neg_dist) - mean(pos_dist) > 0.2, "嵌入未区分语义"

跨模态（图文）对齐评估：
  - 图文匹配：文字 query 检索图片，相关图排前
  - 图图匹配：相似图片检索（角度/光照/风格变化）
  - 跨模态难例：图中有多物、文字含糊时的判断
  - 模态偏差：是否偏科（文字检索好但图片检索差）

评估：
  图文配对标注集 → 双向检索（t2i / i2t）算 Recall@1 / Recall@5

管线各层回归：
  ① 预处理：query 清洗/分词 → 输出稳定（黄金样本）
  ② 嵌入：同一 query 前后版本嵌入稳定（漂移检测）
  ③ 召回：Top-K 结果集合的变化（新增/丢失）
  ④ 重排：重排后前几名的合理变化

每个版本变更做「结果 diff」：
  新旧版本对同一查询集的结果差异 → 有差异要人工/自动评估是好是坏

# 伪代码：检索结果回归 diff
def regression_diff(old, new, queries):
    for q in queries:
        old_top = old.search(q, k=20)
        new_top = new.search(q, k=20)
        added = [r for r in new_top if r not in old_top]
        removed = [r for r in old_top if r not in new_top]
        if added or removed:
            # 记录变化，供评估：变好（召回相关）/变坏（引入噪声）
            report_change(q, added, removed)

RAG 检索层验证：
  - 检索相关文档 → 生成答案依赖检索结果
  - 检索错误传导：坏检索 → 生成错误答案
  - 空检索/检索不足：无相关文档时生成行为（拒绝 vs 瞎编）
  - 检索+生成端到端：query → 答案，答案质量受检索质量影响

验证手段：
  - 检索层用召回/精确率独立评估
  - 端到端用答案质量（正确率/RAGAS 类指标）联动评估
  - 故障注入：故意给错误检索 → 观察生成是否胡编

数据更新场景测试：
  - 删除后一致性：已删文档的向量不被召回（墓碑/重建）
  - 新增可见性：新插入文档立即可被检索到
  - 更新一致性：文档更新后旧向量被新向量替换
  - 过期数据：下架/失效数据从检索结果消失
  - 权限过滤：无权限数据不被检索（多租户检索隔离）

索引一致性的最终验证：
  数据总量核对 + 抽样 query 命中核对

CI 分层：
  L0（快，每次提交）：索引 CRUD、管线黄金样本、嵌入稳定性
  L1（中，每次提交/PR）：小评估集召回率/MRR 对比基线
  L2（慢，每日/合并）：全量标注集评估（recall/precision/NDCG）
  L3（发布前）：跨模态配对评估 + 参数-召回-延迟曲线

基线管理：
  每次全量评估结果入库 → 版本基线
  新版本必须「不劣化」基线（允许合理波动，超阈值拦截）

检索评估的稳定性处理：
  - 固定采样：评估查询集固定（不要随机抽取）
  - 索引确定性：评估前固定索引状态（避免增量差异）
  - 阈值余量：给指标留统计波动的余量，防门禁闪红
  - 慢速查询集：对线上高频 query 单独建「黄金集」优先跑