ANN 算法:HNSWPQ
更新时间:2026-09-11
HNSW_PQ 利用分层可导航小世界(HNSW)图与乘积量化(PQ),创建了一种先进的向量索引方法,提供了可控的大小与准确性权衡。
使用条件
- 向量列必须是
ARRAY<FLOAT>。 - ANN 索引只能作用于一个列。
dimension必须等于向量实际维度,范围为1到 FE 配置的max_ann_dimension,当前默认上限为4096。distance支持l2、ip、cosine。- 索引名称不能为空,长度最多为 64 个字符。
- HNSWPQ 支持 Top-K 和距离范围检索。
建立 HNSWPQ 索引
建表时创建
除三个基础属性外,可同时指定 HNSWPQ 专属属性 hnswpq_m、hnswpq_efConstruction 和 hnswpq_sampleRate,参数含义见“构建参数”。
SQL
1CREATE TABLE hnswpq_documents (
2 `id` BIGINT NOT NULL,
3 `content` STRING,
4 `embedding` ARRAY<FLOAT> NOT NULL,
5 INDEX idx_hnswpq(embedding) USING ANN PROPERTIES(
6 'algorithm' = 'hnswpq',
7 'dimension' = '4',
8 'distance' = 'cosine',
9 'hnswpq_m' = '16',
10 'hnswpq_efConstruction' = '200',
11 'hnswpq_sampleRate' = '0.25'
12 )
13)
14DUPLICATE KEY(`id`)
15DISTRIBUTED BY HASH(`id`) BUCKETS 4;
为已有表后建
SQL
1CREATE INDEX idx_hnswpq
2ON hnswpq_documents (embedding)
3USING ANN
4PROPERTIES(
5 'algorithm' = 'hnswpq',
6 'dimension' = '4',
7 'distance' = 'cosine',
8 'hnswpq_m' = '16',
9 'hnswpq_efConstruction' = '200',
10 'hnswpq_sampleRate' = '0.25'
11);
后建索引会启动一个异步构建索引任务,请按以下顺序操作:
- 执行前确认历史数据中的向量类型和维度正确。
- 执行
SHOW ALTER TABLE COLUMN;查看索引构建进度。 - 等索引构建完成后再进行检索和性能测试。
检索示例
设置查询候选数
hnswpq_ef_search 控制检索时的候选数,必须大于等于查询的 LIMIT,因此建议在检索前先确认该值。会话级设置:
SQL
1SET hnswpq_ef_search = 100;
也可以使用语句级 Hint,只对当前查询生效:
SQL
1SELECT /*+ SET_VAR(hnswpq_ef_search=100) */
2 id, content, __DISTANCE
3FROM hnswpq_documents
4ORDER BY ann_distance(embedding, [0.10, 0.20, 0.30, 0.40])
5LIMIT 10;
增大 hnswpq_ef_search 通常会提高召回率,但也会增加查询延迟和资源消耗。
Top-K 查询
SQL
1SELECT id, content, __DISTANCE
2FROM hnswpq_documents
3ORDER BY ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
4LIMIT 10;
距离范围查询
HNSWPQ 支持距离范围查询,必须同时给出上下界:
SQL
1SELECT id, content, __DISTANCE
2FROM hnswpq_documents
3WHERE ann_distance(embedding, '[0.10, 0.20, 0.30, 0.40]')
4 BETWEEN 0.0 AND 0.5
5ORDER BY __DISTANCE
6LIMIT 100;
索引参数
构建参数
在建表或后建索引的 PROPERTIES 中指定。
| 参数 | 说明 | 默认值 | 取值范围 | 调整建议 |
|---|---|---|---|---|
algorithm |
索引算法 | 无 | 固定为 hnswpq |
不调整 |
dimension |
向量维度 | 无 | 1 至 max_ann_dimension(默认最大 4096) |
必须与实际向量维度一致 |
distance |
距离类型 | 无 | l2、ip、cosine |
按 embedding 模型和业务度量选择 |
hnswpq_m |
图连接数 | 16 |
4 至 1000 |
召回率不足时增大;会增大索引和构建开销 |
hnswpq_efConstruction |
构建候选数 | 200 |
1 至 2000 |
召回率不足时增大;会延长构建时间 |
hnswpq_sampleRate |
PQ 训练采样比例 | 0.25 |
0.0 至 1.0 |
量化误差较大时增大;会增加训练成本 |
hnswpq_nsq |
量化子空间数 | dimension |
1 至 4096,且 dimension % nsq = 0 |
优先使用默认值;调整后需重新评估召回率 |
上述取值范围的默认上限可由 FE 配置调整。
检索参数
通过会话变量或语句级 Hint 指定。
| 参数 | 说明 | 默认值 | 取值范围 | 调整建议 |
|---|---|---|---|---|
hnswpq_ef_search |
查询候选数 | 待确认 | 正整数,且 >= LIMIT |
召回率不足时增大;会增加查询延迟 |
使用限制
hnswpq_ef_search < LIMIT时查询会被拒绝。dimension必须能被hnswpq_nsq整除。- 查询向量必须与索引维度一致。
评价此篇文章
