测量 ANN 召回率

本教程专注于 ANN 召回率：通过 recall@k 指标，衡量近似最近邻（ANN）搜索与精确 kNN 搜索的匹配程度。

前提条件。 一个已填充文档作为点（向量 + 可选负载）的 Qdrant 集合。

检索评估体系

ANN 召回率衡量近似搜索与精确 kNN 的匹配程度。它是四个评估层级中的第一层；每一层级都使用不同的工具衡量检索系统的不同属性。

• ANN 召回率（本教程）。近似索引是否接近精确的 kNN？
• 检索相关性（衡量检索相关性）。Top-k 结果是否符合查询意图？
• 管道输出质量（评估管道输出质量）。端到端管道（检索 + 生成器、重排序器或 UI）是否产生了正确的输出？
• 业务影响。业务关心的 KPI 是否有所提升？这是特定于应用程序的，超出了本教程的范围。

要获得较高层级的评分，需要下层具有可接受的得分。嵌入质量（通过 MTEB 等基准测试独立测量）决定了所有下游指标的上限。

通过 Web UI 测量 ANN 召回率

Qdrant 的 Web UI 包含一个 ANN 召回率选项卡，无需编写评估代码即可测量近似搜索与精确搜索之间的差距。打开控制面板 https://:6333/dashboard（或 Qdrant Cloud 上的集群控制面板），导航到您的集合，打开“ANN 召回率”选项卡，然后点击 检查索引质量 (Check Index Quality) 以运行对比。

该选项卡会报告平均 recall@k（1.0 表示完美重合；调优良好的 HNSW 通常可达到 0.95 以上）。

调优搜索召回率

在“ANN 召回率”选项卡中切换到 高级模式 (advanced mode)，可以内联调优搜索时参数。主要的参数是 hnsw_ef：搜索过程中评估的候选数量。增大该值会探索更多的图结构，从而提高召回率，但代价是查询延迟增加。要查看效果，请增大 hnsw_ef（例如设置为 256）并重新运行评估。

召回率应该会提高，但查询延迟也会随之增加。

如果仅靠 hnsw_ef 无法达到您的召回目标，则构建时参数 m 和 ef_construct 设定了近似搜索所能达到的召回率上限。更改这些参数需要重新构建 HNSW 索引。关于权衡及如何选择数值，请参阅 Qdrant 基础课程中的 HNSW 索引基础。

使用 Python 在 CI 中自动化

Web UI 是交互式检查召回率的最快方式。对于持续集成或脚本化回归测试，Qdrant 客户端通过 search_params=models.SearchParams(exact=True) 暴露了相同的精确搜索模式。您可以自行对比 ANN 和精确搜索的 Top-k 集合并计算 recall@k。

此辅助工具接收一系列查询向量并返回平均 recall@k。请使用工作负载中有代表性的查询向量样本（通常为 20–50 个，并使用与集合相同的模型进行嵌入）作为测试集。

from qdrant_client import QdrantClient, models


def avg_recall_at_k(
    client: QdrantClient,
    collection_name: str,
    test_vectors: list,
    k: int,
) -> float:
    recalls = []
    for vector in test_vectors:
        ann_ids = {
            p.id for p in client.query_points(
                collection_name=collection_name,
                query=vector,
                limit=k,
            ).points
        }
        knn_ids = {
            p.id for p in client.query_points(
                collection_name=collection_name,
                query=vector,
                limit=k,
                search_params=models.SearchParams(exact=True),
            ).points
        }
        recalls.append(len(ann_ids & knn_ids) / k)

    return sum(recalls) / len(recalls)

将其集成到 CI 中，当召回率低于目标阈值时使任务失败。这可以在嵌入模型更换或索引配置更改到达生产环境之前捕获回归问题。

后续步骤

一旦 ANN 召回率达到目标，请继续阅读 衡量检索相关性，以检查这些结果对用户意图的匹配程度。