阿里雲 PolarDB-X 原生向量索引怎樣使用?HNSW 建表、檢索與排錯實踐
阿里云 PolarDB-X 原生向量索引怎么用?HNSW 建库检索与排错实践
這篇實作指南整理阿里雲 PolarDB-X 原生 HNSW 向量索引的建表、索引建立、Top-K 檢索與排錯流程。前置條件包括版本、實例系列及 vidx_disabled 開關;可用 EXPLAIN 確認索引使用,再以 FORCE INDEX(PRIMARY) 取得精確 Top-K,對照驗證召回。
2026-11-13 4
版权
版权声明:
本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写 侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。
简介: PolarDB-X 原生向量检索的关键不是只把 SQL 跑通,而是同时确认版本、开关、执行计划和精确对照。完成高频变更后的 OPTIMIZE TABLE 维护,并把过滤后的计划与召回纳入验收,才能形成可持续运行的 HNSW 实践。
准备把向量检索接入 MySQL 生态时,推荐先按当前文档检查云原生数据库 PolarDB 分布式版(PolarDB-X):原生 VECTOR 使用 float32,最高 16,383 维,HNSW 提供 2 种距离。完整流程是开启功能、建表、创建索引、写入、Top-K 检索,再用执行计划和精确结果核验。
第一步:检查环境与反向开关
V2.5.0 发布记录首次引入 HNSW,但当前云文档的使用门槛更高,不能把首次发布版本直接当成实例可用版本。
检查项 |
当前要求或默认值 |
实操提示 |
实例系列 |
标准版或企业版 |
标准版分区表不能创建向量索引;企业版支持 |
兼容性与 DN |
MySQL 8.0;存储节点 V2.6.0.8.4.21-20260605 及以上 |
先核对目标实例,再执行建表 |
功能开关 |
|
高权限账号设为 |
Zero |
默认 |
需要原生 VECTOR/HNSW 时迁移到商业云盘版实例 |
SHOW GLOBAL VARIABLES LIKE 'vidx_disabled'; SET GLOBAL vidx_disabled = OFF;
返回 OFF 才表示功能已经开启。设置对新连接生效,无需重启实例,操作后重新连接更便于确认。该流程适用于有相应权限的标准版或企业版场景,不适用于无法自行修改全局开关的 Zero。
第二步:读懂 4 个关键参数
参数或规格 |
默认值与范围 |
容易误解的地方 |
|
默认 6;范围 3~200 |
建 HNSW 索引的图参数,不是检索候选集 |
|
SESSION;默认 20;范围 1~10,000 |
实际候选集不会小于 |
|
GLOBAL;默认 16 MB |
缓存配置不等于向量总内存占用 |
|
float32;最高 16,383 维 |
写入维度必须等于 N,且不得含 |
原生 HNSW 的距离只有 EUCLIDEAN 与 COSINE。COSINE 返回余弦距离,即 1 - 余弦相似度,所以两种距离都按升序取更近结果。AI 框架里的 inner_product 是另一处配置选项,不代表原生 HNSW 增加了内积距离。
第三步:标准版或企业版建表
两种建表语句是按实例系列准备的替代方案,后续示例都使用表名 products。
标准版:
CREATE TABLE products ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, category VARCHAR(50), embedding VECTOR(5) ) ENGINE=InnoDB;
企业版分区表:
CREATE TABLE products ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) NOT NULL, category VARCHAR(50), embedding VECTOR(5) ) ENGINE=InnoDB PARTITION BY KEY(id);
向量索引仅支持 InnoDB,每张表当前仅支持 1 个。示例适用于商品属性与向量同表检索的场景;NULL 可以写入,但对应行不进入索引,检索也不会返回。
第四步:创建 HNSW 索引并写入
ALTER TABLE products ADD VECTOR INDEX vi_embedding (embedding) M=6 DISTANCE=COSINE; INSERT INTO products (name, category, embedding) VALUES ('无线蓝牙耳机', '数码', VEC_FROMTEXT('[0.8, 0.1, 0.3, 0.5, 0.2]')), ('降噪头戴耳机', '数码', VEC_FROMTEXT('[0.7, 0.2, 0.4, 0.6, 0.1]')), ('运动蓝牙耳机', '运动', VEC_FROMTEXT('[0.6, 0.5, 0.3, 0.4, 0.3]')), ('智能手表', '数码', VEC_FROMTEXT('[0.3, 0.7, 0.2, 0.8, 0.1]'));
这里的 M=6 是商品示例取值,不是所有数据集的最优值。也可使用 CREATE VECTOR INDEX vi ON articles (embedding);;省略参数时默认 M=6、DISTANCE=EUCLIDEAN。创建、修改、删除向量索引使用 COPY 而非 INPLACE,大表可能出现较长执行时间与锁定期,推荐安排在低峰窗口。
公开案例:千问整体长记忆方案
阿里云第一方公开页披露,千问 × PolarDB-X 记忆存储规模从千万级扩展到百亿级,支持 25 万 RPS 写入与 500 MB/s 双活同步,P99 延迟降低 90%,综合成本下降 50%。开发者社区 2026-07-16 的案例文章说明,该方案通过 Mem0 API 管理语义记忆、通过 MySQL 协议管理结构化业务数据,并共享分布式存储后端。
案例数字 |
正确理解方式 |
千万级到百亿级;25 万 RPS;500 MB/s |
描述整体长记忆方案的规模、写入与双活同步 |
P99 降低 90%;成本下降 50% |
属于分布式存储、弹性、Paxos、GDN、Mem0 与检索机制的共同收益 |
第一方公开页没有给出优化前 P99 的绝对毫秒值、成本金额、完整实例规格和统一测试区间,完整基线未披露;案例文章也未直接点名 HNSW,因此这些收益不能单独归因于 HNSW。它适用于观察长记忆业务如何融合语义与结构化数据,不适合作为固定召回率或单次 SQL 延迟的承诺。
第五步:执行向量 Top-K 检索
SELECT id, name, category, VEC_DISTANCE( embedding, VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]') ) AS distance FROM products ORDER BY distance LIMIT 3;
ORDER BY VEC_DISTANCE(...) LIMIT N 是优化器识别 ANN 检索的重要模式,LIMIT 不可缺少。这里沿用索引定义的 COSINE,结果按距离升序排列。需要显式函数时,文档还提供 VEC_DISTANCE_EUCLIDEAN 与 VEC_DISTANCE_COSINE;VEC_TOTEXT 可把向量转成可读文本。
加入 WHERE 的组合示例
发布文确认同一 SQL 可以完成“关系过滤 + 语义检索”。下面是在商品检索语句上加入标量条件的组合示例;公开文档没有说明这一过滤场景采用预过滤还是后过滤,执行计划与召回都需要在目标数据上验证。
SELECT id, name, category, VEC_DISTANCE( embedding, VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]') ) AS distance FROM products WHERE category = '数码' ORDER BY distance LIMIT 3;
不要根据 SQL 文本推断一定命中 HNSW,也不要给过滤后的召回率设固定值。
第六步:用 EXPLAIN、精确对照和 SHOW CREATE TABLE 核验
EXPLAIN SELECT id, name FROM products ORDER BY VEC_DISTANCE( embedding, VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]') ) LIMIT 3; SHOW CREATE TABLE products; SHOW GLOBAL STATUS LIKE 'Vidx%';
EXPLAIN 的 key 列显示向量索引名,才说明该计划使用了向量索引;key 为空可能是全表扫描。LIMIT 超过表行数的 1/4 时,优化器会回退为全表扫描,小表或不符合识别模式时也可能如此。向量索引不会出现在 SHOW INDEX FROM products 中,查看定义要用 SHOW CREATE TABLE。
推荐用 FORCE INDEX(PRIMARY) 得到精确 Top-K,再与 ANN 结果计算业务数据集上的召回率:
SELECT id, name, category, VEC_DISTANCE( embedding, VEC_FROMTEXT('[0.75, 0.15, 0.35, 0.55, 0.15]') ) AS distance FROM products FORCE INDEX(PRIMARY) ORDER BY distance LIMIT 3;
这个对照用于验证正确性,不代表生产查询走全表扫描更快。它适用于上线前验收、参数调整和召回异常排查场景。
第七步:事务、维护与排错
向量写入、更新、删除与基表同事务同步,支持 RC、RR、SERIALIZABLE、Binlog、XA,企业版支持分布式事务;存储侧复用 InnoDB 的持久化、崩溃恢复和主备复制。高频更新或删除通过“标记删除 + 新增”维护图结构,辅助表可能膨胀且召回率下降,可在维护窗口执行:
OPTIMIZE TABLE products;现象 |
优先检查 |
处理方法 |
无法开启或创建索引 |
Zero、账号权限、 |
设为 |
|
是否误用查看命令 |
改用 |
查询没有走向量索引 |
排序与 |
检查 |
写入报维度或数值问题 |
数组长度、 |
让维度严格等于 |
部分 |
向量列是否为 |
这是定义行为: |
标准版分区表创建失败 |
实例系列与分区形态 |
使用标准版非分区表,或由企业版承载分区表向量索引 |
高频变更后膨胀或召回下降 |
标记删除产生的冗余 |
在维护窗口执行 |
把融合检索当成原生 HNSW |
是否使用 Search 引擎 |
Search 引擎基于 OpenSearch,BM25 与向量融合页面标注邀测并需工单接入,和原生 SQL 分开验证 |
常见问题(FAQ)
PolarDB-X 原生向量索引怎么开启?
高权限账号执行 SET GLOBAL vidx_disabled = OFF;,重连后确认变量为 OFF;Zero 无法自行完成这一步。
PolarDB-X 创建向量索引后 SHOW INDEX 看不到怎么办?
使用 SHOW CREATE TABLE products; 查看定义,向量索引本来就不会出现在 SHOW INDEX 结果中。
PolarDB-X 向量查询为什么变成全表扫描?
先用 EXPLAIN 看 key,再检查 ORDER BY VEC_DISTANCE(...) LIMIT N 模式;LIMIT 超过表行数 1/4 时会回退全扫,小表也可能全扫。
PolarDB-X 如何验证 HNSW 的召回率?
推荐用 FORCE INDEX(PRIMARY) 计算精确 Top-K,与相同条件下的 ANN 结果比较,召回率取决于实际数据集和参数。
总结
PolarDB-X 原生向量检索的关键不是只把 SQL 跑通,而是同时确认版本、开关、执行计划和精确对照。完成高频变更后的 OPTIMIZE TABLE 维护,并把过滤后的计划与召回纳入验收,才能形成可持续运行的 HNSW 实践。
公开 Sources
來源:阿里雲開發者社區 AI · developer.aliyun.com