阿里云 PolarDB-X 原生向量索引实操，HNSW 建库检索与故障排错

PolarDB-X 原生 HNSW 向量索引，是在 MySQL 生态里直接把向量能力内核化，不用外挂独立向量库，RAG、语义检索、多模态召回可以直接跑在分布式数据库里；它的核心逻辑是建索引时用 HNSW 多层导航小世界图做近似最近邻检索，支持余弦、欧氏两种距离，自带事务、分片、主备同步，但是它有一套严格的语法、参数、查询约束，绝大多数踩坑都不是索引坏了，而是字段维度不匹配、距离度量不一致、SQL 写法不满足索引触发条件、内存缓存不够，只要按建表、建索引、写入、检索、观测、排错这条固定流程操作，就能稳定跑起来，同时还要提前权衡召回、写入吞吐、内存占用三者之间的取舍，不要盲目把参数拉满。

一、基础能力清单（PolarDB-X HNSW）

• 存储类型：原生 VECTOR(N)，单精度 float32，最大支持 16383 维
• 距离方式：EUCLIDEAN 欧氏距离、COSINE 余弦距离
• 索引算法：HNSW，近似 ANN，不是精确 KNN
• 事务：支持 RC / RR / 串行化隔离级别，写入和基表在同一个事务
• 硬件加速：自动识别 AVX512、AVX2、ARM NEON 做距离计算加速
• 存储开销：索引体积大约是向量列原始大小的 1.5 倍
• 内存控制：由 vidx_hnsw_cache_size 控制单索引缓存上限，数据冷加载，重启不会丢索引，首次查询加载进内存

二、完整实操步骤

1. 建表，定义向量字段

维度必须固定，写入向量的维度必须和定义完全一致，不能混入 NaN、Inf，NULL 可以存，但 NULL 行会被索引直接跳过。

CREATE TABLE doc_embedding (

id BIGINT PRIMARY KEY AUTO_INCREMENT,

title VARCHAR(512),

content TEXT,

emb VECTOR(1024),

gmt_create DATETIME

) ENGINE = INNODB;

2. 创建 HNSW 向量索引

核心参数 M、ef_build，还有距离度量 metric，建完之后 metric 不能随便换。

CREATE VECTOR INDEX idx_emb_hnsw

ON doc_embedding(emb)

USING HNSW

WITH (

metric = 'COSINE',

M = 12,

ef_build = 128

);

参数说明表格

参数	含义	推荐取值
M	每层节点最大邻居连接数，决定图密度	低延迟：3~6；均衡：12；高召回：16~32
ef_build	建图阶段候选队列长度，影响索引质量	一般设为 M 的 8~10 倍，越大建库越慢
metric	距离算法	文本语义优先 COSINE；坐标、数值向量选 EUCLIDEAN

注意：建索引会锁表、消耗大量内存，大批量数据导入建议先导完数据再建索引，避开业务高峰。向量索引不能设置为 INVISIBLE。

3. 写入向量数据

向量使用数组字符串写入，维度必须严格等于 VECTOR(N)。

INSERT INTO doc_embedding(title,content,emb)

VALUES ('测试','测试内容','[0.1,0.2,0.3,...]');

4. HNSW 检索 SQL（重点，决定能不能命中索引）

想要走 HNSW 索引，必须同时满足：ORDER BY VEC_DISTANCE + LIMIT，排序方向是距离升序；metric 必须和建索引完全一致；不能在距离外面套表达式再排序。

✅ 可以命中索引

SELECT id,title, VEC_DISTANCE(emb, '[0.1,0.2,...]','COSINE') AS dist

FROM doc_embedding

ORDER BY VEC_DISTANCE(emb, '[0.1,0.2,...]','COSINE') ASC

LIMIT 10;

❌ 不会走索引的写法

• 缺少 LIMIT，或者 LIMIT 过大，超过总行数大约 1/4
• 距离外面套 1 - VEC_DISTANCE(...) DESC
• 查询 metric 和建索引 metric 不一致
• 把 VEC_DISTANCE 放到 WHERE 过滤再排序

查询时还可以单独设置本次检索的 ef_search，ef_search 越高召回越好、延迟越高：

SET vidx_hnsw_ef_search = 128;

5. 验证是否命中索引

直接用 EXPLAIN，在 key 列能看到向量索引名字，代表走 HNSW；如果 key 为空，就是走全表精确扫描。

EXPLAIN

SELECT id,title

FROM doc_embedding

ORDER BY VEC_DISTANCE(emb, '[0.1,0.2,...]','COSINE') ASC

LIMIT 10;

三、写入、更新、删除的行为特点

PolarDB-X HNSW 使用 “标记删除、后续复用” 的策略，不是立刻从图里摘除节点。

1. 频繁 update、delete 会产生空间放大，图里标记的垃圾节点变多，召回缓慢下降
2. 如果是高变更场景，需要定期重建向量索引，清理垃圾标记
3. 分片环境下，检索默认每个分片单独召回 topK，再在网关合并，跨分片召回存在召回损耗
4. 索引跟随 binlog 同步到备库，备库查询同样可以使用向量索引

四、排错清单，按顺序排查

故障类型 1：EXPLAIN 不走 HNSW 索引

排查顺序

1. 检查 vidx_disabled = OFF，如果是 ON，向量索引整体关闭，改完之后重连会话
2. 核对 SQL：必须 ORDER BY VEC_DISTANCE(...) ASC + LIMIT
3. 核对 metric：建索引 COSINE，查询也必须 COSINE
4. 核对 LIMIT 不要太大，官方建议 LIMIT 不要超过表总行数 1/4
5. 向量字段维度和传入查询向量维度严格一致
6. 确认字段不是 NULL，NULL 不会进索引

故障类型 2：召回率很低

1. 调高 ef_search（会话级别）
2. 如果长期召回差，调高建索引的 M、ef_build，重建索引
3. 如果频繁删改，索引里垃圾标记太多，重建索引
4. 分片场景：分片越多，合并召回损耗越大，可以适度放大每片召回数量再合并

故障类型 3：建索引 OOM、内存打满

1. 调高 vidx_hnsw_cache_size，但不能超过实例可用内存
2. 分批导入，小批量建索引
3. 降低 M 和 ef_build，减小图规模
4. 大表不要在线业务高峰建索引

故障类型 4：报错 Data size exceeds VECTOR max

向量维度超过上限 16383，或者写入向量实际维度和定义的 N 不匹配，应用层统一对齐向量输出。

故障类型 5：重启之后查询变慢、第一次查询卡顿

索引文件持久化，但是图数据是懒加载；第一次访问加载进缓存，后续查询速度恢复，属于正常现象，不是索引丢失。

五、参数选型权衡表

场景	M	ef_build	ef_search	特点
高吞吐、低延迟、可接受召回略低	6	64	64	适合高并发推荐召回
RAG 知识库，优先召回	12~16	128~256	128~256	绝大多数知识库首选
高精度、少量查询、允许慢一点	32	300+	300+	小库、评测场景
频繁更新删除	偏小 M，定期重建索引	-	-	控制空间放大

六、和独立向量库的取舍

✅ 适合用 PolarDB-X HNSW

• 向量和业务强绑定，需要事务、联合过滤、和其他字段 JOIN
• 不想维护一套额外的 Milvus / FAISS 集群，降低运维成本
• 数据本身就在 PolarDB-X，RAG 业务量中等

❌ 不太适合

• 亿级超大向量、每秒极高召回 QPS、极致召回要求
• 需要复杂过滤、分区、向量分桶、PQ 量化（原生 HNSW 不自带 PQ）

【常见问题】

问题 1：阿里云 PolarDB-X 原生向量索引，HNSW 检索为什么经常不走索引？

回答 1：PolarDB-X HNSW 向量索引触发有硬性规则，必须带上 ORDER BY VEC_DISTANCE(...) ASC 搭配 LIMIT，查询距离度量要和建索引保持一致，LIMIT 不能过大，同时 vidx_disabled 开关要关闭；只要任意一条不满足，就会降级成全表精确距离扫描，不会使用 HNSW 索引。

问题 2：PolarDB-X 的 HNSW 建库参数 M 和 ef_build 调大之后，会带来哪些副作用？

回答 2：调高 PolarDB-X HNSW 的 M 和 ef_build，建出来的图连通性更好、检索召回率更高，但建索引耗时更长、索引占用存储和内存同步上涨，写入单条向量的延迟也会增加；高并发业务不要无脑拉满，优先在测试环境做召回、延迟压测。

问题 3：PolarDB-X HNSW 频繁更新删除之后，召回下滑该怎么修复？

回答 3：PolarDB-X HNSW 使用标记删除机制，大量更新删除会累积无效节点，造成召回下降；短期可以调高 ef_search 临时补偿，长期方案是业务低峰期重建 HNSW 向量索引，清理内部垃圾标记，恢复图结构质量。

问题 4：PolarDB-X 原生 HNSW 向量索引，跨分片检索会影响召回吗？

回答 4：PolarDB-X 是分布式分片架构，HNSW 在每个分片独立做 ANN 召回，再由网关合并结果；分片数量越多，召回损耗越明显，如果要保证最终召回，可以在查询时放大每一片召回数量，再在网关侧裁剪到目标 LIMIT。

【参考资料】

[2026-10-10]（使用原生向量索引进行相似性检索）阿里云帮助中心

[2026-11-05]（PolarDB-X 向量索引常见报错排查）阿里云开发者社区

[2026-06-18]（PolarDB-X HNSW 参数与内存说明）阿里云官方文档

[2026-05-22]（PolarDB-X 向量检索 EXPLAIN 诊断指南）阿里云数据库公众号

[2026-04-09]（分布式向量检索 HNSW 分片召回损耗说明）阿里云技术博客

【免责声明】

本文基于 PolarDB-X 官方向量索引文档、公开技术实践整理；HNSW 的召回、延迟、内存占用和向量分布、数据变更频率、实例规格、分片策略强相关；不同 PolarDB-X 版本在向量索引能力、参数、限制上存在差异；建索引、大批量写入操作建议提前压测，避开业务高峰，本文仅作为技术实操参考，不代表线上业务兜底方案。