使用原生向量索引进行相似性检索

功能简介

向量索引底层基于业界主流的 HNSW（Hierarchical Navigable Small World）算法，并复用 InnoDB 的事务、持久化、崩溃恢复与主备复制能力，让您像使用普通索引一样使用向量索引。

向量索引解决的核心问题是：在海量高维向量中，快速找到与目标向量最相似的 Top-N 条记录。

核心特性

PolarDB-X向量索引的主要特性如下：

适用范围

您的实例需满足以下版本要求：

• 产品系列：标准版或企业版。

• 引擎版本：MySQL 8.0。

• 存储节点版本：V2.6.0.8.4.21-20260605 及以上版本。

  说明

  • 实例版本的规则说明，请参见版本说明。

  • 实例版本的查看方式，请参见查看实例版本。

• 向量数据的写入、更新、删除与基表在同一事务内自动同步，无需手动维护索引，使用体验与普通索引一致。不同实例产品系列支持能力有所不同：

  能力	标准版（集中式）	企业版（分布式）
  向量存储与ANN检索	支持	支持
  主备复制/高可用	支持	支持
  事务	支持	支持

使用限制

• 存储引擎：仅支持在InnoDB引擎表上创建向量索引。

• 索引数量：同一张表当前仅支持创建一个向量索引。

• 分区表 ：暂不支持在标准版分区表上创建向量索引，企业版分区表支持创建向量索引。

• DDL算法：创建、修改、删除向量索引使用COPY算法（非INPLACE），对大表会有较长的执行时间与锁定期，建议在业务低峰期操作。

• INVISIBLE索引：向量索引不支持设置为INVISIBLE。

• 向量数据约束：写入向量的维度必须与建表时 VECTOR(N) 的 N 严格一致，且不允许包含 NaN 或 Inf 值。

• NULL 向量：向量列允许为 NULL。值为 NULL 的行不会被纳入向量索引，检索时不会被返回。

• 空间膨胀：UPDATE / DELETE 采用“标记删除 + 新增”方式维护图结构，高频更新或删除场景下辅助表会逐渐膨胀、召回率下降，需定期执行 OPTIMIZE TABLE 重建。

开启向量索引功能

向量索引功能由系统变量 vidx_disabled 控制，默认值为 ON（即默认关闭）。出于资源隔离考虑，需先显式开启后才能创建和使用向量索引。

-- ON = 关闭，OFF = 开启
SET GLOBAL vidx_disabled = OFF;

使用向量索引

CREATE TABLE articles (
    id        INT PRIMARY KEY AUTO_INCREMENT,
    title     VARCHAR(200),
    embedding VECTOR(128)        -- 128 维向量字段
) ENGINE=InnoDB;

CREATE TABLE articles (
    id        INT PRIMARY KEY AUTO_INCREMENT,
    title     VARCHAR(200),
    embedding VECTOR(128)        -- 128 维向量字段
) ENGINE=InnoDB
PARTITION BY KEY(id);

-- 查看索引定义（向量索引以 VECTOR KEY 形式展示）
SHOW CREATE TABLE articles;

CREATE TABLE `articles` (
  `id` int NOT NULL AUTO_INCREMENT,
  `title` varchar(200) DEFAULT NULL,
  `embedding` vector(128) DEFAULT NULL,
  PRIMARY KEY (`id`),
  VECTOR INDEX `vi`(`embedding`) M=16 DISTANCE=COSINE
) ENGINE = InnoDB

-- 删除向量索引
ALTER TABLE articles DROP INDEX vi;

向量函数

系统变量与参数调优

-- 提高搜索精度（牺牲一些延迟）
SET SESSION vidx_hnsw_ef_search = 100;

-- 降低延迟（牺牲一些精度）
SET SESSION vidx_hnsw_ef_search = 10;

监控与运维

您通过以下命令查看向量索引运行状态：

SHOW GLOBAL STATUS LIKE 'Vidx%';

返回示例：

+----------------------------------+----------+
| Variable_name                    | Value    |
+----------------------------------+----------+
| Vidx_cache_usage                 | 1048576  |
| Vidx_insert_count                | 5        |
| Vidx_load_node_hits              | 14       |
| Vidx_load_node_misses            | 10       |
| Vidx_load_vec_hits               | 6        |
| Vidx_load_vec_misses             | 6        |
| Vidx_query_count                 | 1        |
| Vidx_update_count                | 0        |
| ...                              | ...      |
+----------------------------------+----------+

常用监控指标

运维建议

• 缓存命中率 = （Vidx_load_node_hits + Vidx_load_vec_hits）/（Vidx_load_node_hits + Vidx_load_node_misses + Vidx_load_vec_hits + Vidx_load_vec_misses，若低于 90%，可适当调大vidx_hnsw_cache_size。

• 定期执行 OPTIMIZE TABLE 可清理因更新/删除产生的冗余节点，控制空间增长。

• 高精度需求时优先调大 vidx_hnsw_ef_search，并保证其不小于查询的 LIMIT。

端到端示例

以下示例演示一个“商品语义搜索”完整流程：

1. 开启功能

   SET GLOBAL vidx_disabled = OFF;

2. 创建表并定义5维向量字段

   标准版

   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);

3. 创建向量索引（余弦距离）

   ALTER TABLE products ADD VECTOR INDEX vi_embedding (embedding) M=6 DISTANCE=COSINE;

4. 写入商品数据

   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]'));

5. 检索与“蓝牙耳机”最相似的3个商品

   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;

   返回示例：

   +----+--------------+----------+------------------------+
   | id | name         | category | distance               |
   +----+--------------+----------+------------------------+
   |  2 | 降噪头戴耳机   | 数码      | 0.005887877200042468   |
   |  1 | 无线蓝牙耳机   | 数码      | 0.006059869516314431   |
   |  3 | 运动蓝牙耳机   | 运动      | 0.09631679001555782    |
   +----+--------------+----------+------------------------+

常见问题

• 如何确认实例是否支持并已开启向量索引？

  确认实例存储节点版本不低于V2.6.0.8.4.21-20260605，并通过以下命令确认功能已开启，返回OFF表示已开启。

  SHOW GLOBAL VARIABLES LIKE 'vidx_disabled';

  返回示例：

  +-----------------+-------+
  | Variable_name   | Value |
  +-----------------+-------+
  | vidx_disabled   | OFF   |
  +-----------------+-------+

• 为什么向量检索没有走索引？

  请依次确认：

  1. vidx_disabled = OFF 且已重新建立连接。

  2. SQL 包含 ORDER BY VEC_DISTANCE(...) LIMIT N。

  3. LIMIT 值未超过表行数的 1/4。

  可通过 EXPLAIN 验证，命中时 key 列会显示向量索引名。

• 检索召回率不达预期怎么办？

  可调大会话变量 vidx_hnsw_ef_search（如 50~100），或在建索引时增大 M（如 16）。可使用 FORCE INDEX(PRIMARY) 做全表精确检索作为对比基准。

• 创建向量索引为什么比较慢？

  向量索引使用 COPY 算法构建，需要为存量数据逐条建立 HNSW 图结构，大表耗时较长，建议在业务低峰期执行。

• 向量索引会增加多少存储和内存？

  • 存储：索引大小约为基表向量列大小的 1.5 倍。

  • 内存：由 vidx_hnsw_cache_size 控制单个索引的缓存上限。

  • 缓存：主要由行数、向量维度和 M 决定，可用以下经验公式估算（单位：字节）：

    vidx_hnsw_cache_size ≈ 行数 × (维度 × 2 + M × 16 + 60)

    • 维度 × 2：向量经量化压缩后的大小（每维 2 字节）。

    • M × 16：图节点邻居连接的开销。

    • 60：节点对象等固定开销。

    估算示例：

    行数	维度	M	建议缓存
    100 万	128	6	≈ 700 MB
    100 万	768	16	≈ 1.8 GB
    1000 万	128	6	≈ 7 GB

  说明

  缓存超过上限后会触发整体重建、影响查询性能。建议在估算值基础上适当上调；若监控发现缓存命中率偏低，可再调大。

• 向量索引支持主备复制和高可用吗？

  支持。向量数据的写入与基表在同一事务内同步，通过Binlog复制到备库，主备数据保持一致，同时支持XA事务。在企业版（分布式）下，向量索引还支持分布式事务，跨分片的向量数据写入与检索可在分布式事务中保证一致性。