评估召回率

在向量搜索中，召回率（recall）是指索引返回的近似最近邻中真实最近邻所占的比例。例如，如果索引检索出 $100$ 个近似最近邻，其中有 $97$ 个属于真实最近邻，那么召回率就是 $\frac{97}{100} = 0.97$。

召回率评估

召回率衡量的是搜索返回的相关结果占全部应返回真实结果的比例。在使用索引时，您通常希望了解不同参数配置所对应的召回率和 QPS。vchordrq_evaluate_query_recall 函数正是为评估召回率而设计的：它接收一条返回行标识符的查询语句，并返回对应的召回率。

vchordrq_evaluate_query_recall 函数内部依赖 ctid 将查询结果与基准真相（ground truth）进行比对。因此，传入的 query 参数必须以 SELECT ctid 开头。

SET vchordrq.probes = '100';
SET vchordrq.epsilon = 1.0;
SELECT vchordrq_evaluate_query_recall(query => $$
  SELECT ctid FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10
$$);

默认情况下，该函数通过执行另一次高精度索引扫描来生成估算的基准真相，并据此评估召回率。如果您希望通过全表扫描（table scan）生成精确的基准真相来评估召回率，请将函数参数 exact_search 设置为 true。

SET vchordrq.probes = '100';
SET vchordrq.epsilon = 1.0;
SELECT vchordrq_evaluate_query_recall(query => $$
  SELECT ctid FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10
$$, exact_search => true);

查询采样

为了方便评估生产或测试中的查询召回率，VectorChord 内置了查询采样方法。

SET vchordrq.query_sampling_enable = on;
SET vchordrq.query_sampling_max_records = 1000;
SET vchordrq.query_sampling_rate = 1;

假设您已经执行了一条示例向量搜索：SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10。

在查询执行并被采样后，您可以检查捕获到的查询要素，包括模式名（schema）、索引名、表名、列名、操作符以及目标向量。

SELECT * from vchordrq_sampled_queries('items_embedding_idx');
-- schema_name | index_name          | table_name | column_name | operator |    value
---------------+---------------------+------------+-------------+----------+--------------
-- public      | items_embedding_idx | items      | embedding   | <->      | [0.5,0.25,1]

要测量已记录查询的平均召回率，您可以构造目标查询语句并调用评估函数：

SELECT AVG(recall_value) FROM (
    SELECT vchordrq_evaluate_query_recall(
            format(
                'SELECT ctid FROM %I.%I ORDER BY %I OPERATOR(%s) %L LIMIT 10',
                lq.schema_name,
                lq.table_name,
                lq.column_name,
                lq.operator,
                lq.value
            )
    ) AS recall_value
    FROM vchordrq_sampled_queries('items_embedding_idx') AS lq
) AS eval_results;

如果您正在使用包含主库（primary）和备库（standby）的流复制（replication）功能，请注意：采样到的查询不会通过复制或备份进行同步。相反，每台服务器都会根据自己实际处理的查询独立维护各自的采样查询集合。

参考

vchordg 和多向量检索不支持此功能。

搜索参数（vchordrq）

vchordrq.query_sampling_enable

• 说明：启用或禁用 vchordrq 索引扫描的查询采样。
• 类型：布尔值（boolean）
• 默认值：off

vchordrq.query_sampling_max_records

• 说明：控制每个索引最多记录的查询数量。该设置仅在 vchordrq.query_sampling_enable 开启时生效。
• 类型：整数（integer）
• 默认值：0
• 取值范围：[0, 10000]
• 示例：
  • vchordrq.query_sampling_max_records = 0 将为每个索引保留 0 条查询。
  • vchordrq.query_sampling_max_records = 1000 将为每个索引最多保留最近 1000 条查询。

vchordrq.query_sampling_rate

• 说明：控制记录查询的采样率。该设置仅在 vchordrq.query_sampling_enable 开启时生效。
• 类型：实数（real）
• 默认值：0
• 取值范围：[0, 1]
• 示例：
  • vchordrq.query_sampling_rate = 0 不记录任何查询。
  • vchordrq.query_sampling_rate = 0.01 记录约 1% 的查询。
  • vchordrq.query_sampling_rate = 1 记录每一条查询（仅用于测试目的）。

函数（vchordrq）

vchordrq_sampled_queries

• 说明：检索指定 vchordrq 索引已记录的查询集合。
• 返回值：table
  • schema_name: text，查询中表的模式名
  • index_name: text，查询中使用的索引名称
  • table_name: text，查询中的表名
  • column_name: text，参与索引扫描的列名
  • operator: text，查询中使用的距离操作符
  • value: text，查询中目标向量的文本表示
• 参数：
  • regclass，vchordrq 索引的对象标识符
• 示例：
  • SELECT vchordrq_sampled_queries('items_embedding_idx');

vchordrq_sampled_values

• 说明：检索指定 vchordrq 索引已记录查询中的目标向量。
• 返回值：text，查询中目标向量的文本表示。
• 参数：
  • regclass，vchordrq 索引的对象标识符
• 示例：
  • SELECT vchordrq_sampled_values('items_embedding_idx');
• 注意：该函数仅用于调试目的。

vchordrq_evaluate_query_recall

• 说明：评估给定 vchordrq 查询的召回率。
• 返回值：real
• 参数：
  • query: text，待评估召回率的查询语句
  • exact_search: boolean，是否使用精确基准真相代替估算的基准真相
  • accu_probes: text，用于生成估算基准真相的 vchordrq.probes
  • accu_epsilon: real，用于生成估算基准真相的 vchordrq.epsilon
• 示例：
  • SELECT vchordrq_evaluate_query_recall(query => $$ SELECT ctid FROM t ORDER BY val <-> '[0.5, 0.25, 1.0]' LIMIT 10 $$);
  • SELECT vchordrq_evaluate_query_recall(query => $$ SELECT ctid FROM t ORDER BY val <-> '[0.5, 0.25, 1.0]' LIMIT 10 $$, exact_search => true);
  • SELECT vchordrq_evaluate_query_recall(query => $$ SELECT ctid FROM t ORDER BY val <-> '[0.5, 0.25, 1.0]' LIMIT 10 $$, accu_probes => '9999', accu_epsilon => 4.0);

视图（vchordrq）

vchordrq_sampled_queries

• 说明：检索所有 vchordrq 索引已记录的查询集合。
• 示例：
  • SELECT * from vchordrq_sampled_queries;
• 注意：该视图仅用于调试目的。