使用向量嵌入

MySQL | PostgreSQL | SQL Server

本页面详细介绍了如何与 Cloud SQL 交互以构建使用向量嵌入的应用。

Cloud SQL for MySQL 支持存储向量嵌入。您随后可以创建向量搜索索引，并对这些向量嵌入以及您存储在 Cloud SQL 中的其余数据执行相似性搜索。

向量嵌入存储

您可以使用 Cloud SQL for MySQL 在表中创建向量嵌入列，以便存储向量嵌入。特殊的向量嵌入列会映射到 VARBINARY 数据类型。与表中的其他关系型数据一样，您可以使用现有事务保证来访问表中的向量嵌入。具有向量嵌入列的表是常规 InnoDB 表，因此符合原子性、一致性、隔离性和持久性 (ACID) 属性。仅当进行向量搜索索引查找时，才不会符合 ACID 属性。

您最多可以在一个表中创建一个向量嵌入列，并对每个表创建一个向量搜索索引。存储在同一列中的每个向量嵌入的维度必须与您在定义该列时指定的维度完全相同。向量嵌入的维度上限为 16,000 个。如果您有足够的可用存储空间和内存，则可以在同一实例中拥有包含不同向量嵌入列和向量搜索索引的单独表。

虽然系统对可以存储在表中的向量嵌入数量没有硬性限制，但向量搜索索引需要内存。因此，我们建议您在表中存储的向量嵌入不超过 1000 万个。

向量嵌入列的复制方式与其他 MySQL InnoDB 列相同。

相似性搜索

Cloud SQL 支持使用 K 最近邻 (KNN) 和近似最近邻 (ANN) 搜索查询进行相似性搜索。您可以在 Cloud SQL 实例中使用这两种类型的向量搜索。您可以为 ANN 搜索创建向量搜索索引。

K 最近邻 (KNN) 搜索

Cloud SQL 支持使用 KNN 向量搜索（也称为精确最近邻搜索）进行查询。执行 KNN 向量搜索可提供完美的召回率。您不必创建向量搜索索引即可执行 KNN 搜索。KNN 搜索的基础是执行表扫描算法。

对于 KNN 搜索，Cloud SQL 还支持以下向量距离搜索函数：

余弦
点积
L2 平方距离

如需详细了解如何使用向量搜索距离函数，请参阅查询向量嵌入的距离。

近似最近邻 (ANN) 搜索

Cloud SQL 支持通过创建向量搜索索引来创建和查询 ANN 搜索。借助 ANN 向量搜索索引，您可以为实现快速性能（而不是完美召回率）来进行优化。对于 ANN 搜索，Cloud SQL 支持以下索引类型：

BRUTE_FORCE：行数少于 10,000 的基表的默认向量搜索索引类型。此类型最适合在原始数据集的较小子集中进行搜索。索引使用的内存等于数据集的大小。此索引类型不会持久保存在磁盘中。
TREE_SQ：具有 10,000 行或更多行的基表的默认向量搜索索引类型。此类型使用最少的内存量，或使用大约为数据集大小的 25% 的内存量。TREE_SQ 索引会持久保存在磁盘中。
TREE_AH：提供非对称哈希搜索类型算法的向量搜索索引类型。如 Cloud SQL 中实现的那样，此索引类型未针对内存占用进行优化，也不会持久保存。

更新向量搜索索引

Cloud SQL for MySQL 会实时更新向量搜索索引。对基表执行数据操纵语言 (DML) 操作的任何事务还会将更改传播到关联的向量搜索索引。向量搜索索引中的更改会立即对所有其他事务可见，这意味着隔离级别为 READ_UNCOMMITTED。

如果回滚事务，则向量搜索索引中也会发生对应的回滚更改。

向量搜索索引的复制

Cloud SQL for MySQL 会将向量搜索索引复制到所有读取副本。不支持复制过滤条件以及将向量搜索索引复制到级联副本。

配置实例以支持向量嵌入

本部分介绍如何配置 Cloud SQL 实例以支持向量嵌入的存储、索引和查询。

Cloud SQL 企业版和 Cloud SQL 企业 Plus 版实例都支持向量嵌入。

准备工作

您的实例必须运行 Cloud SQL for MySQL 8.0.36.R20240401.03_00 或更高版本。
您的实例必须具有足够的磁盘可用空间和内存，以便为实例中的向量嵌入总数分配内存。

启用对向量嵌入的支持

如需启用对向量嵌入的支持，您必须配置 MySQL 数据库标志。

gcloud sql instances patch INSTANCE_NAME \
  --database-flags=FLAGS

将 INSTANCE_NAME 替换为要启用向量嵌入支持的实例的名称。

在 FLAGS 中，对实例配置以下 MySQL 标志：

cloudsql_vector：将此标志设置为 on 以启用向量嵌入存储和搜索支持。您可以在实例中创建新的向量嵌入列和向量搜索索引。
cloudsql_vector_max_mem_size：可选。为实例中的所有向量搜索索引指定最大内存分配（以字节为单位）。如果未指定此标志，则默认内存分配为 1 GB，这是最小内存分配。如需详细了解如何计算要指定的内存量，请参阅为向量搜索索引配置内存分配。

此专用内存来自分配给 innodb_buffer_pool_size 的内存。您的可用缓冲区池会按相同的量减少。此标志允许的最大值是总 innodb_buffer_pool_size 的 50%。

如果您指定的值大于总 innodb_buffer_pool_size 的 50%，则 Cloud SQL 会将有效值减少到可用大小的 50%，并针对实例记录警告消息。

配置相关标志后，您的命令可能类似于以下内容：

gcloud sql instances patch my-instance \
  --database-flags=cloudsql_vector=on,cloudsql_vector_max_mem_size=4294967296

用于在 Cloud SQL for MySQL 中配置向量嵌入支持的标志是静态标志。使用相关标志更新实例后，实例会自动重启，以便使配置更改生效。

如需详细了解如何为 MySQL 配置数据库标志，请参阅配置数据库标志。

停用对向量嵌入的支持

如需停用对向量嵌入的支持，请将 cloudsql_vector 标志设置为 off。

例如：

gcloud sql instances patch INSTANCE_NAME \
  --database-flags=cloudsql_vector=off

将 INSTANCE_NAME 替换为要停用向量嵌入支持的实例的名称。

将 cloudsql_vector 设置为 off 会阻止您创建新的向量嵌入列和向量搜索索引。配置此静态标志后，实例会自动重启，以便使配置更改生效。

实例重启后，Cloud SQL for MySQL 会执行以下操作：

从永久性磁盘中移除所有持久保存的 TREE_SQ 向量搜索索引。
保留已构建的向量搜索索引的数据字典表条目。但是，Cloud SQL for MySQL 不会重建索引，并且对这些索引进行的任何搜索查询都会返回错误。
继续将向量嵌入存储在基表中。向量嵌入仍然可供访问。

如果您稍后为实例重新启用 cloudsql_vector 标志，则 Cloud SQL 会尝试基于数据字典表中的条目，在实例重启时重建索引。

为向量搜索索引配置内存分配

Cloud SQL 会在内存中构建和维护向量搜索索引。TREE_SQ 索引类型在正常关停时会持久保存，并在实例重启后重新加载。在运行时，所有向量搜索索引都需要保留在内存中。

如需确保 Cloud SQL 具有足够的可用内存以将所有向量搜索索引保留在内存中，请使用 cloudsql_vector_max_mem_size 数据库标志配置 Cloud SQL 实例。cloudsql_vector_max_mem_size 控制 Cloud SQL 实例专门用于向量搜索索引的内存量。为该标志配置值时，请注意以下事项：

默认值和最小值为 1 GB。上限为缓冲区池大小的 50%。
设置此标志后，您的实例会自动重启，以便使配置更改生效。
如果实例已用完其所有配置的内存，您便无法创建或更改任何向量搜索索引。

如需对实例更新为向量搜索索引分配的内存，请更改 cloudsql_vector_max_mem_size 标志的值。

gcloud sql instances patch INSTANCE_NAME \
  --database-flags= cloudsql_vector_max_mem_size=NEW_MEMORY_VALUE

替换以下内容：

INSTANCE_NAME：您要对其更改内存分配的实例的名称。
NEW_MEMORY_VALUE：向量搜索索引更新后的内存分配（以字节为单位）

此更改会自动重启实例，以便使更改生效。

计算所需内存

索引所需的内存量取决于索引类型、向量嵌入的数量以及嵌入的维度。您需要考虑以下两个内存要求：

构建时内存：索引构建期间所需的内存
索引内存：索引在构建后占用的内存

对于给定索引，其数据集大小是读取内存中的所有向量嵌入所需的内存。鉴于每个维度都由使用 4 字节内存的浮点数表示，您可以按如下方式确定 dataset_size：

dataset_size = <num_embeddings> * (4 * <dimensions>)

例如，如果您有 100 万个具有 768 个维度的嵌入，则 dataset_size 为 3 GB。

根据前面的示例，针对不同索引类型的内存要求如下所示：

索引类型	构建时内存	索引内存
`TREE_SQ`	4 GB	1 GB
`TREE_AH`	3.5 GB	3.5 GB
`BRUTE_FORCE`	3 GB	3 GB

如果您使用的是 TREE_SQ 向量搜索索引，则还必须考虑在运行时实现持久化所需的内存。可将最大活跃 TREE_SQ 向量搜索索引使用的索引内存量与配置中的总内存量相加。

每当存储向量嵌入的基表进行 DML 操作时，向量搜索索引便会实时更新。这些更新会更改索引的内存占用（可能会缩小或扩大，具体取决于 DML 操作）。您可以通过查询 information_schema.innodb_vector_indexes 表来监控索引的内存占用。如需了解如何监控向量搜索索引的大小，请参阅监控向量搜索索引。

读取副本配置

如果实例满足维护版本和标志启用条件，则 Cloud SQL 完全支持只读副本上的向量嵌入。

如果您从已启用向量嵌入支持的主实例创建副本，则读取副本会从主实例继承向量嵌入支持设置。您必须对已有的读取副本实例单独启用向量嵌入支持。

在对复制延迟时间的影响方面，向量搜索索引的创建和维护操作方式与常规 MySQL 索引相同。

级联副本不支持向量搜索索引。

示例：简单的 ANN 向量搜索索引和查询

以下示例演示提供了在 Cloud SQL 中创建基于 ANN 的向量搜索索引和查询的步骤。

生成向量嵌入。您可以手动创建向量嵌入，也可以使用自己选择的文本嵌入 API。如需查看使用 Vertex AI 的示例，请参阅根据行数据生成向量嵌入。

在 Cloud SQL for MySQL 中创建一个表，其中包含一个具有三个维度的向量嵌入列。

CREATE TABLE books (
id   INTEGER PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(60),
embedding VECTOR(3) USING VARBINARY
);

在该列中插入一个向量嵌入。

INSERT INTO books VALUES (
1,
'book title',
 string_to_vector('[1,2,3]')
);

提交更改。
```
commit;
```

创建向量搜索索引。如果要创建 TREE_SQ 或 TREE_AH 索引，则表必须至少具有 1,000 行。

CALL mysql.create_vector_index('vectorIndex',
                               'dbname.books',
                               'embedding',
                               'index_type=BRUTE_FORCE, distance_measure=L2_SQUARED'
                               );

获取最近邻。

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'));

根据行数据生成向量嵌入

您可以使用文本嵌入 API（例如 Vertex AI 或 OpenAI）针对给定行的数据生成向量嵌入。您可以将任何文本嵌入 API 与 Cloud SQL 向量嵌入搭配使用。但是，您必须使用相同的文本嵌入 API 进行查询字符串向量生成。您不能将不同的 API 组合用于源数据和查询向量化。

例如，您可以通过 Vertex AI 生成向量嵌入：

from vertexai.language_models import TextEmbeddingModel

def text_embedding() -> list:
    """Text embedding with a Large Language Model."""
    model = TextEmbeddingModel.from_pretrained("textembedding-gecko@001")
    embeddings = model.get_embeddings(["What is life?"])
    for embedding in embeddings:
        vector = embedding.values
        print(f"Length of Embedding Vector: {len(vector)}")
    return vector

if __name__ == "__main__":
    text_embedding()

存储向量嵌入

本部分提供了用于在 Cloud SQL 中存储向量嵌入的示例语句。

创建包含向量嵌入列的新表

CREATE TABLE books (
  id INTEGER PRIMARY KEY AUTO_INCREMENT,
  title VARCHAR(60),
  embedding VECTOR(3) USING VARBINARY
  );

将向量嵌入列添加到现有表中

ALTER TABLE books
ADD COLUMN embedding
VECTOR(3) USING VARBINARY;

插入向量嵌入

INSERT INTO books (
  title,
  embedding
  ) VALUES (
    'book title',
    string_to_vector('[1,2,3]')
);

插入多个向量嵌入

INSERT INTO books (
  title,
  embedding
  ) VALUES (
    'book title',
    string_to_vector('[1,2,3]')),
     ('book title', string_to_vector('[4,5,6]')
);

更新/插入向量嵌入

INSERT INTO books (
  id,
  title,
  embedding
  ) VALUES (
    1,
    'book title',
     string_to_vector('[1,2,3]')
     )
ON DUPLICATE KEY UPDATE embedding = string_to_vector('[1,2,3]');

更新向量嵌入

UPDATE books
SET embedding = string_to_vector('[1,2,3]')
WHERE id = 1;

删除向量嵌入

DELETE FROM books
WHERE embedding = string_to_vector('[1,2,3]');

使用向量搜索索引

默认情况下，您可以执行精确最近邻搜索，这可提供完美的召回率。您还可以添加索引以使用 ANN 搜索，这可用一定的召回率来换取速度。与典型索引不同，添加近似索引后，您会看到不同的查询结果。

建议

本部分介绍使用向量搜索索引的最佳实践。每种工作负载各不相同，您可能需要进行相应的调整。

创建向量搜索索引之前，您必须将数据加载到表中。您的基表必须至少具有 1,000 行。这些要求仅适用于 TREE_SQ 和 TREE_AH 搜索索引类型。如果可用的数据点较多，则可以更好地对索引进行分区和训练。
监控索引的内存用量。如果实例的内存不足，则您无法创建或构建任何索引。对于现有索引，在达到阈值后，Cloud SQL 会定期将警告写入 MySQL 错误日志。您可以在 information_schema.innodb_vector_indexes 表中查看内存用量。
如果底层基表进行了重大 DML 更改，请重建向量搜索索引。如需获取构建时索引的初始大小和索引的当前大小，请查询 information_schema.innodb_vector_indexes 表。
通常，将分区数量留在内部计算是可以接受的。如果您具有需要指定分区数量的应用场景，则每个分区必须至少有 100 个数据点。

向量搜索索引操作期间的只读基表

在所有三个向量搜索索引操作（创建、更改和删除）执行期间，基表都会处于只读模式。在这些操作执行期间，不允许对基表执行 DML 操作。

持久性、关停以及对维护的影响

只有使用 TREE_SQ 类型的向量搜索索引才会在实例正常关停时持久保存在磁盘中。使用 TREE_AH 和 BRUTE_FORCE 类型的向量搜索索引仅处于内存中。

实例正常关停后，Cloud SQL 会在实例重启时重新加载向量搜索索引。但是，在崩溃或异常关停后，Cloud SQL 必须重建向量搜索索引。例如，只要实例发生崩溃并通过备份和恢复、时间点恢复 (PITR) 或高可用性 (HA) 故障切换进行恢复，Cloud SQL 便会重建向量搜索索引。对于这些事件，会发生以下情况：

重建会在后台自动进行。
在重建期间，基表处于只读模式。
如果自动重建无法在特定超时时间段内获取表的锁定，则重建会失败。您可能需要改为手动重建索引。

索引重建所需的时间可能会增加关停所需的时间，这还可能会增加实例所需的维护和更新时间。

创建向量搜索索引

用于创建向量搜索索引的语句使用以下语法：

CALL mysql.create_vector_index('INDEX_NAME',
                                'DB_NAME.TABLE_NAME',
                                'COLUMN_NAME',
                                'PARAMETERS'
                              );

例如：

CALL mysql.create_vector_index('vectorIndex',
                                'db.books',
                                'embedding',
                                'index_type=TREE_SQ, distance_measure=l2_squared'
                               );

您指定的索引名称在数据库中必须是唯一的。

向量搜索索引参数

创建搜索索引（和更改搜索索引）函数支持多个参数，您可以使用以逗号分隔的键值对指定这些参数。所有搜索索引创建函数参数都是可选的。如果您指定空字符串或 NULL，则系统会为索引配置默认参数值。

distance_measure：支持的值包括：L2_SQUARED、COSINE 和 DOT_PRODUCT。默认值为 L2_SQUARED。
num_neighbors：在 ANN 查询期间默认返回的相邻项数量。您还可以在执行搜索查询时替换此参数。默认值为 10。
index_type：指定要构建的索引的类型。有效值包括：BRUTE_FORCE、TREE_SQ 和 TREE_AH。
- BRUTE_FORCE 是用于行数少于 10,000 的表的默认值
- TREE_SQ 是用于具有 10,000 或更多行的表的默认值
如需指定 TREE_AH 或 TREE_SQ 索引类型，基表的大小必须大于 1,000 行。
num_parititions：指定要构建的 k-means 聚类数量。仅当您配置了 index_type 时，才允许使用此参数。此选项不适用于 BRUTE_FORCE。如果您指定 TREE_SQ 或 TREE_AH 索引类型，则基表的大小必须大于或等于 num_partitions * 100。

更改向量搜索索引

CALL mysql.alter_vector_index('DB_NAME.INDEX_NAME', 'PARAMETERS');

alter_vector_index 函数用于明确重建向量搜索索引。如需使用此函数，索引必须已存在。您可能需要为以下应用场景重建索引：

您希望使用不同的选项重建索引。例如，您可能希望使用其他索引类型或不同的距离衡量方式。
您希望重建索引，因为基表进行了重大 DML 更改。例如，您需要根据基表中的当前数据重新训练向量搜索索引。

用于重建索引的所有参数与可用于创建索引的参数相同，也是可选的。如果在重建索引时指定空字符串或 NULL，则系统会根据创建索引时指定的参数重建索引。如果在创建索引时未提供参数，则系统会使用默认参数值。

现有向量搜索索引在更改操作期间可供使用。您仍然可以对索引执行搜索查询。

删除向量搜索索引

您无法对具有向量搜索索引的表执行 DDL 操作。对表执行 DDL 操作之前，您必须删除向量搜索索引。

CALL mysql.drop_vector_index('DB_NAME.INDEX_NAME');

查询向量嵌入

本部分提供了可用于查询向量嵌入的不同方式的示例。

查看向量嵌入

SELECT vector_to_string(embedding) FROM books;

获取向量嵌入的精确邻搜索

SELECT id,cosine_distance(embedding,
   string_to_vector('[1,2,3]')) dist
FROM books
ORDER BY dist
LIMIT 10;

获取向量嵌入的近似邻搜索

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'), 'num_neighbors=10');

执行 ANN 搜索支持两个参数。这两个参数都是可选的。

num_partitions：指定要为 ANN 向量搜索探测的分区数量。如果您未指定分区数量，则搜索会使用根据表大小、向量搜索索引中的分区数量以及其他因素生成的值。
num_neighbors：指定要返回的相邻项数量。此值会替换在创建向量搜索索引时设置的值。

过滤向量嵌入

使用额外的列作为谓词，来微调向量嵌入查询结果的过滤。例如，如果您添加 printyear 列，则可以将特定年份值作为过滤条件添加到查询中。

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'))
AND printyear > 1991;

查询向量嵌入的距离

本部分提供了可用于 KNN 搜索的向量距离函数的示例。

获取余弦距离

SELECT cosine_distance(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

获取点积距离

SELECT dot_product(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

获取 L2 平方距离

SELECT l2_squared_distance(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

获取特定距离内的行

SELECT * FROM books
WHERE l2_squared_distance(embedding, string_to_vector('[1,2,3]')) < 10;

您可以与 ORDER BY 和 LIMIT 组合使用。

SELECT id, vector_to_string(embedding),
       l2_squared_distance(embedding, string_to_vector('[1,2,3]')) dist
FROM books ORDER BY dist LIMIT 10;

监控向量搜索索引

如需获取有关实例中所有向量搜索索引的实时信息，请使用 information_schema.innodb_vector_indexes 表。

如需查看该表，请运行以下命令：

SELECT * FROM information_schema.innodb_vector_indexes;

示例输出可能如下所示：

*************************** 1. row ***************************
       INDEX_NAME: test.t4_index
       TABLE_NAME: test.t4_bf
       INDEX_TYPE: BRUTE_FORCE
     DIST_MEASURE: SquaredL2Distance
           STATUS: Ready
            STATE: INDEX_READY_TO_USE
       PARTITIONS: 0
SEARCH_PARTITIONS: 0
     INITIAL_SIZE: 40000
     CURRENT_SIZE: 40000
          QUERIES: 0
        MUTATIONS: 0
     INDEX_MEMORY: 160000
   DATASET_MEMORY: 0

在 information_schema.innodb_vector_indexes 表中，您可以查看以下内容：

可能生成的选项。即 num_partitions 或要为查询探测的分区数量。
STATE 和 STATUS 列可提供索引的当前状态。在构建阶段，状态列可提供有关向量搜索索引在构建阶段中的进展的信息。
INITIAL_SIZE 列可提供索引创建期间的表大小。您可以将此大小与 CURRENT_SIZE 进行比较，以了解索引自创建以来，由于对基表执行的 DML 操作而发生了多大变化。
QUERIES 和 MUTATIONS 列可让您实时了解索引的繁忙程度。
INDEX_MEMORY 和 DATASET_MEMORY 列可提供有关索引内存消耗的信息。INDEX_MEMORY

表示索引消耗的内存量，DATASET_MEMORY 表示构建时消耗的额外内存量。

如需获取对实例创建的搜索向量索引的列表，您可以查看 mysql.vector_indexes 数据字典表。