使用向量嵌入

本页介绍了如何使用 Cloud SQL for PostgreSQL 执行以下操作：

  • 根据模型生成和存储向量嵌入。

  • 使用 pgvector 扩展程序对嵌入进行索引编入和查询。

如需了解详情，请参阅使用 Cloud SQL 构建生成式 AI 应用。

借助 Cloud SQL，您可以使用由 Vertex AI 托管的嵌入模型将文本字符串转换为嵌入，这是模型将给定文本的语义含义表示为数值向量的方法。

Cloud SQL 将嵌入实现为 real 值的数组。这样，您就可以将生成的嵌入作为 pgvector 扩展函数的输入。

准备工作

某些要求因您是想使用 Cloud SQL 生成嵌入，还是只需处理存储在数据库中的其他来源的嵌入而异。

区域限制

如需使用 Cloud SQL 生成 Vertex AI 嵌入，您的实例必须位于 generative AI foundational models are supported 的区域。Cloud SQL 可用于嵌入的 Vertex AI 模型 text-embedding 和 textembedding-gecko 位于该区域。

必需的数据库扩展

如需处理嵌入，请在 Cloud SQL 实例上安装 google_ml_integration 扩展程序。对于 Vertex AI 模型，请安装版本 1.2 或更高版本。对于第三方或自定义模型，请安装 1.4.2 或更高版本。

（可选）如果您想存储这些嵌入，并将向量函数和运算符与嵌入搭配使用，则还需要 pgvector 扩展。

Cloud SQL 同时支持这两种扩展。您可以在实例中的任何数据库中安装它们。如需了解详情，请参阅配置 PostgreSQL 扩展程序。

设置模型访问权限

您必须先将 Cloud SQL 配置为使用文本嵌入模型，然后才能通过 Cloud SQL 实例生成嵌入。

如需使用基于云的 text-embedding 或 textembedding-gecko 模型，您需要将 Cloud SQL 与 Vertex AI 集成。

向数据库用户授予生成嵌入的权限

向数据库用户授予使用 embedding 函数运行预测的权限：

  1. 按照使用 psql 客户端连接中所述，将 psql 客户端连接到主实例。

  2. 在 psql 命令提示符下，连接到数据库并授予权限：

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    请替换以下内容：

    • DB_NAME：您要授予其权限的数据库的名称

    • USER_NAME：您要为其授予权限的用户的名称

生成嵌入

Cloud SQL 提供了一个函数，可让您将文本转换为向量嵌入。然后，您可以将该嵌入作为向量数据存储在数据库中，并可选择使用 pgvector 函数对其运行查询。

生成嵌入

如需使用 Cloud SQL 生成嵌入，请使用 google_ml_integration 扩展程序提供的 embedding() 函数：

SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');

进行以下替换：

  • MODEL_ID：要查询的模型的 ID。

    如果您使用的是 Vertex AI Model Garden，请指定 text-embedding-004 或
    text-multilingual-embedding-002。这些是 Cloud SQL 可用于文本嵌入的云端模型。如需了解详情，请参阅文本嵌入。

  • VERSION_TAG（可选）：要查询的模型的版本标记。对于 text-embedding-004 或 text-multilingual-embedding-002 之前的 textembedding-gecko 版本，请Prepend the tag with@`。

    如果您将某个 textembedding-gecko 模型与 Vertex AI 搭配使用，请指定模型版本中列出的某个版本标记。

  • TEXT：要转换为向量嵌入的文本。

以下示例使用 text-embedding-004 模型根据提供的字面量字符串生成嵌入：

SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

存储生成的嵌入

embedding() 函数的返回值是 real 值的数组。如需将此值存储在表中，请添加 real[] 列：

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

进行以下替换：

  • TABLE：表名称

  • EMBEDDING_COLUMN：新嵌入列的名称

  • DIMENSIONS：模型支持的维度数。

    如果您将 text-embedding 或 textembedding-gecko 模型之一与 Vertex AI 搭配使用，请指定 768。

（可选）如果您已安装 pgvector 扩展程序，则可以将嵌入存储为 vector 值：

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

创建用于存储嵌入的列后，您可以根据同一表中其他列中已存储的值来填充该列：

UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);

进行以下替换：

  • TABLE：表名称。

  • EMBEDDING_COLUMN：嵌入列的名称。

  • MODEL_ID：要查询的模型的 ID。

    如果您使用的是 Vertex AI Model Garden，请指定 text-embedding-004 或
    text-multilingual-embedding-002。这些是 Cloud SQL 可用于文本嵌入的云端模型。如需了解详情，请参阅文本嵌入。

  • VERSION_TAG（可选）：要查询的模型的版本标记。对于 text-embedding-004 或 text-multilingual-embedding-002 之前的 textembedding-gecko 版本，请Prepend the tag with@`。

    如果您将某个 textembedding-gecko 模型与 Vertex AI 搭配使用，请指定模型版本中列出的某个版本标记。

  • SOURCE_TEXT_COLUMN：存储文本的列的名称。您将此文本转换为嵌入。

上述命令适用于 real[] 和 vector 嵌入列。如果您的嵌入列的类型为 vector，则 Cloud SQL 会将 embedding() 的返回值从 real 数组隐式转换为 vector 值。

以下示例使用 text-embedding-004 模型，根据 messages.message 列的内容在 messages.message_vector 列中填充嵌入：

UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);

使用 pgvector 查询嵌入并编入索引

借助 pgvector PostgreSQL 扩展程序，您可以在数据库中存储、编入索引和查询文本嵌入时使用特定于矢量的运算符和函数。Cloud SQL 针对使用 pgvector 进行了自己的优化，可让您创建索引来加快涉及嵌入的查询的速度。

创建最近邻索引

pgvector 支持通过编制索引进行近似最近邻搜索。

如需使用 hnsw 作为索引方法创建基于 pgvector 的索引，请使用以下示例：

CREATE INDEX ON TABLE
  USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

进行以下替换：

  • TABLE：要向其中添加索引的表。

  • EMBEDDING_COLUMN：用于存储 vector 数据的列。

  • DISTANCE_FUNCTION：要与此索引搭配使用的距离函数。请按以下方式之一操作：

    • L2 距离：vector_l2_ops

    • 内积：vector_ip_ops

    • 余弦距离：vector_cosine_ops

  • M（可选）：图表中与相邻数据点的最大连接数。我们建议将范围设为 5 到 48，因为 16 是 pgvector 的默认值。

  • EF_CONSTRUCTION（可选）：在构建索引时，用于存储图遍历过程中最近候选项的列表的大小。值越高，算法会考虑的候选项就越多，从而创建更好的索引。默认大小为 64。

如需在使用 real[] 数据类型（而非 vector）的嵌入列上创建此索引，请将该列转换为 vector 数据类型：

CREATE INDEX ON TABLE
  USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS))) DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

将 DIMENSIONS 替换为嵌入列的维度宽度。

下一部分将演示此类索引的示例。

使用给定文本执行最近邻查询

在数据库中存储和编入嵌入后，您就可以使用 pgvector 查询功能的全部功能。

如需查找一段文本的最近邻语义，请使用 embedding() 函数将文本转换为向量。在同一查询中，将此矢量应用于 pgvector 最近邻运算符 <->，以查找语义上最相似的嵌入的数据库行。

由于 embedding() 会返回 real 数组，因此您必须将 embedding() 调用转换为 vector，才能将这些值与 pgvector 运算符搭配使用。

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

进行以下替换：

  • RESULT_COLUMNS：要从语义相似的行中显示的列。

  • TABLE：包含要与文本进行比较的嵌入的表。

  • EMBEDDING_COLUMN：包含存储的嵌入的列。

  • MODEL_ID：要查询的模型的 ID。

    如果您使用的是 Vertex AI Model Garden，请指定 text-embedding-004 或
    text-embedding-multilingual-002。这些是 Cloud SQL 可用于文本嵌入的云端模型。如需了解详情，请参阅文本嵌入。

  • VERSION_TAG（可选）：要查询的模型的版本标记。在该标记前面加上 @。

    如果您将某个 textembedding-gecko 模型与 Vertex AI 搭配使用，请指定模型版本中列出的某个版本标记。

  • TEXT：您要查找的文字，以便找到最近的存储的语义邻居。

  • ROW_COUNT：要返回的行数。如果您只希望获得单个最佳匹配，请将 1 指定为此参数的值。

如需使用使用 real[] 数据类型（而非 vector）的存储嵌入列运行此查询，请将该列转换为 vector 数据类型：

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN::vector
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

使用模型版本标记以避免错误

Google 强烈建议您始终使用所选嵌入模型的稳定版本。对于大多数模型，这意味着需要明确设置版本标记。

在不指定模型的版本标记的情况下调用 embedding() 函数在语法上是有效的，但也容易出错。

如果您在 Vertex AI Model Garden 中使用模型时省略版本标记，Vertex AI 会使用该模型的最新版本。这可能不是最新的稳定版本。如需详细了解可用的 Vertex AI 模型版本，请参阅模型版本。

给定 Vertex AI 模型版本对给定文本输入始终返回相同的 embedding() 响应。如果您在对 embedding() 的调用中未指定模型版本，则新发布的模型版本可能会突然更改给定输入的返回矢量。这可能会导致应用出现错误或其他意外行为。

为避免出现这些问题，请始终指定模型版本。

后续步骤