IVF-PQ 向量索引构建和查询参数 - 数据湖构建

本文介绍 IVF-PQ 向量索引的构建参数、查询参数和常见调优方法。

注意事项

索引构建： DLF 根据表配置在后台构建索引，无需单独提交索引构建作业。
构建参数： 构建参数只影响后续生成的索引文件，修改参数不会改变已有索引。如果需要将新参数应用于已有数据，请按照附录中的步骤删除旧索引，并等待 DLF 根据新配置自动重建。
查询参数： 修改查询参数无需重建索引。查询选项优先于同名表属性；查询中未设置参数时，可能回退到表属性或版本默认值。
检查周期： 修改 morax.paimon-vector-index.check-interval 后，新周期从后续检查任务开始生效，不改变已有索引。

IVF-PQ 参数

必需参数

使用 DLF 自动构建 IVF-PQ 索引时，需要完成以下配置。表的行级追踪、数据演化等基础配置，请参见构建 Global Index 实现查询加速和向量搜索。

参数	配置要求	说明
`morax.paimon-vector-index.enabled`	必须设置为 `true`	开启 Paimon 向量索引的后台构建。
`global-index.ivf-pq.index-columns`	必须设置	指定一个 IVF-PQ 向量字段，例如 `image_embedding`。配置多个字段时，使用英文逗号（`,`）分隔。
`ivf-pq.dimension`	`ARRAY<FLOAT>` 字段必须设置	指定向量的实际维度，例如 `768`。配置值必须与写入数据一致。
`ivf-pq.distance.metric`	建议显式设置	距离类型默认为 `inner_product`。应根据 Embedding 模型选择 `cosine`、`inner_product` 或 `l2`。

除以上配置外，其他参数可以先使用默认值或自动配置。

构建参数

说明

如果一张表包含多个向量字段，并且各字段使用的模型、维度或调优目标不同，可以使用 fields.{字段名}.{参数名} 设置字段级参数，例如 fields.image_embedding.dimension、fields.image_embedding.nlist、fields.image_embedding.train.sample-ratio 和 fields.image_embedding.global-index.row-count-per-shard。字段级配置优先于表级配置。如果多个向量字段使用相同配置，无需设置字段级参数。

索引质量与压缩参数

参数	默认值	作用	建议调整条件
`ivf-pq.dimension`	`128`	指定 `ARRAY<FLOAT>` 向量维度。	`ARRAY<FLOAT>` 字段必须显式设置；`128` 仅是底层默认值，不能替代真实维度配置。该参数不是性能调优项。
`ivf-pq.distance.metric`	`inner_product`	决定向量距离的计算方式。	根据 Embedding 模型确定。距离类型不匹配会直接影响相似度排序。
`ivf-pq.train.sample-ratio`	`1.0`	指定参与索引训练的非空向量比例，取值范围为 `(0,1]`。	通常保持默认值。仅当数据量较大且训练时间明显较长时适当调低，并重新验证 Recall@K。
`ivf-pq.nlist`	自动	指定 IVF 分组数量。DLF 构建索引时会根据索引分片中的非空向量数量自动计算。	查询耗时超过目标，或在可接受的查询耗时下召回率仍未达到目标时，再对比不同的 `nlist`。
`ivf-pq.pq.code-ratio`	`0.0625`	指定 PQ 编码大小与原始 `FLOAT` 向量大小的目标比例。使用前，请确认当前 Paimon/Morax 版本支持该参数。	增大 `nprobe` 并使用原始向量重排后，Recall@K 仍低于目标时，可以逐步增大。通常不需要主动调整。
`ivf-pq.pq.m`	自动	指定 PQ 子向量数量。DLF 构建索引时可自动计算。显式设置后优先于 `pq.code-ratio`。	仅在需要精确控制 PQ 编码长度，并已完成代表性召回测试时设置。通常使用 `pq.code-ratio` 即可。默认配置下，768 维向量自动得到 `m=192`。
`ivf-pq.pq.use-opq`	自动	控制是否在 PQ 压缩前应用 OPQ 旋转。内置默认值为 `false`。`target-recall>=0.9` 时可以自动启用。	增大 `pq.code-ratio` 后 Recall@K 仍低于目标，且可以接受额外训练和查询开销时评估启用。
`ivf-pq.target-recall`	未设置	向构建策略提供目标召回率。使用前，请确认当前 Paimon/Morax 版本支持该参数。	已有明确 Recall@K 目标，并希望系统据此选择构建策略时设置。该参数不能替代实际召回测试。

索引分片与更新参数

参数	默认值	作用	建议调整条件
`global-index.row-count-per-shard`	动态计算	指定每个向量索引分片的目标行数；未显式配置时，DLF 根据索引类型、向量维度和资源规格动态计算。	通常保留默认值。仅当单个分片构建较慢，或分片数量过多时调整。
`global-index.build.max-shard`	`32`	指定一次索引构建优先使用的最大分片数。数据量较大时，系统可以增加分片数以满足每个分片的目标行数。	通常保留默认值。需要控制单次构建的分片规模时再调整。
`morax.paimon-vector-index.check-interval`	`1h`	指定 DLF 检查新增数据并提交索引构建任务的时间间隔。	要求新增数据在 1 小时内可被检索时调小；任务提交过于频繁时调大。

查询参数

不同查询引擎传递查询参数的方式不同。本节仅说明参数含义和调整条件。仅当前计算引擎支持的参数会生效，不支持的参数将被忽略。

参数	默认值	作用	建议调整条件
`ivf.nprobe`	自动	指定查询扫描的 IVF 分组数量。DLF 查询时会根据索引信息、Top K 和过滤条件自动计算。	默认查询的 Recall@K 低于目标时逐步增大；查询耗时超过目标且召回率有余量时，可以测试较小的固定值。通常优先保留自动模式。
`ivf.max_initial_filter_expansion_factor`	不限制	带过滤条件时，限制自动 `nprobe` 在首次查询中的扩张倍数。设置为 `1` 表示首次不因过滤条件扩大扫描范围。	仅在带过滤条件的查询延迟明显升高，并确认原因是首次扫描范围扩张时设置。该参数仅在自动 `nprobe` 模式下生效，不能与显式设置的 `ivf.nprobe` 同时使用。
`ivf.refine_factor`	不启用	先召回 `Top K × refine_factor` 个候选，再读取原始向量重新计算距离并排序。	增大 `nprobe` 后召回率提升有限，且可以接受额外数据读取和计算开销时设置。设置为 `1` 也会执行原始向量重排。
`ivf_pq.batch_table_reuse`	`auto`	控制批量 IVF-PQ 查询是否复用距离计算表，支持 `auto`、`on` 和 `off`。	批量查询吞吐未达到目标且内存充足时测试 `on`；出现明显内存压力时测试 `off`。单条向量查询无需设置。
`ivf_pq.batch_table_reuse.max_bytes`	`536870912`	限制距离计算表复用允许使用的最大内存，默认为 512 MiB。	批量查询出现内存压力或并发增加时调低；希望扩大可复用批次且内存充足时调高。超过上限时，系统使用普通计算方式。

参数调优

开始调优前，建议先确定可以接受的召回率和查询耗时，并准备具有代表性的查询集。不同向量模型、数据规模、过滤条件和 Top K 对参数的敏感程度不同，同一组参数不一定适用于所有数据集。本文中的 Recall@K 指近似检索 Top K 与精确检索 Top K 的重合比例。

建议先使用默认值或自动配置建立性能基线，再根据 Recall@K 和 P95/P99 查询耗时调整参数。

召回率低于目标

建议先调整查询参数，提升有限时再调整构建参数。

优先调整查询参数

使用自动配置记录 Recall@K 和查询耗时，作为对比基线。
逐步增大 ivf.nprobe。如果召回率明显提升，说明原扫描范围不足。
如果提升有限，设置 ivf.refine_factor，使用原始向量重新排序候选结果。
同时记录 P95/P99，避免扫描范围过大导致查询延迟明显升高。

必要时调整构建参数

确认 distance.metric 和向量归一化方式与 Embedding 模型一致。
确认训练数据具有代表性，避免将 train.sample-ratio 设置得过低。
增大 nprobe 并使用 refine_factor 后 Recall@K 仍低于目标时，逐步增大 pq.code-ratio。
增大 pq.code-ratio 后仍未达到目标时，评估是否启用 OPQ。
如果提升仍然有限，使用相同查询集对比不同的 nlist。

调整构建参数后，按照附录步骤删除旧索引并等待新索引生成，再使用同一查询集验证效果。

查询耗时超过目标

建议先区分耗时来自向量扫描、结构化过滤还是原始向量重排。

优先调整查询参数

分别测试无过滤条件和带过滤条件的查询，定位主要耗时来源。
优先使用自动 nprobe，避免设置过大的固定值。显式设置后，同时验证 Recall@K。
仅带过滤条件的查询耗时明显升高时，评估 ivf.max_initial_filter_expansion_factor。
检查是否启用了不必要的原始向量重排，适当降低或取消 refine_factor。

必要时调整构建参数

单个 IVF 分组扫描数据过多时，对比不同的 nlist。
单个索引分片过大时，评估 global-index.row-count-per-shard。
PQ 编码较大导致候选计算成本较高时，在召回率允许的范围内测试较小的 pq.code-ratio。

调整 nlist、分片或 PQ 压缩参数后，按照附录步骤删除旧索引并等待新索引生成，再重新测试查询性能。

新增数据进入索引较慢

DLF 按检查周期发现新增数据并提交索引构建任务。
如果时效要求低于 1 小时，可以调小 morax.paimon-vector-index.check-interval。
缩短检查周期会提高任务检查和提交频率，应结合数据写入频率设置。

批量查询吞吐或内存不满足要求

优先使用 ivf_pq.batch_table_reuse=auto。
批量查询吞吐不足且内存充足时，测试 on。
出现明显内存压力时，测试 off，或调低 ivf_pq.batch_table_reuse.max_bytes。
同时记录批量吞吐、P95/P99 和峰值内存。

这些参数只影响批量查询，无需重建索引。

验证调优结果

每次只修改一个参数或一组强相关参数，并使用相同的数据快照和查询集进行对比。建议记录：

Recall@K。
P50、P95 和 P99 查询耗时。
带过滤条件与不带过滤条件的查询差异。

附录：重建 IVF-PQ 索引

构建参数修改后不会改变已有索引。如果需要让已有数据使用新参数，应删除旧索引，再由 DLF 根据当前表配置自动重建。

按新参数重建索引

记录基线：保存当前表配置，以及 Recall@K、P95/P99 等测试结果。
修改参数：更新构建参数，并通过 SHOW CREATE TABLE 确认配置已经生效。
预览删除范围：执行 drop_global_index，设置 dry_run=true，确认目标表、字段、索引类型和文件数量。
删除旧索引：确认预览结果后，将 dry_run 设置为 false。删除后到新索引提交前，查询可能无法使用向量索引，建议在低流量时段操作。
等待自动重建：保留索引构建开关。DLF 会按照当前参数自动提交构建任务，任务可能需要等待一个检查周期。不要手工调用 create_global_index。
验证结果：确认新索引已经生成，再使用相同查询集对比 Recall@K 和查询耗时。

如果构建任务失败，不要重复删除索引。修复失败原因后，等待或重新触发构建任务。

删除 Global Index 不会删除 Paimon 表数据。