使用向量嵌入

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

  • 基于模型生成和存储向量嵌入。

  • 使用 pgvector 扩展程序将嵌入编入索引并查询嵌入。

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

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

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

准备工作

有些要求因您是想使用 Cloud SQL 生成嵌入还是只想使用从其他来源存储在数据库中的嵌入而有所不同。

区域限制

如需使用 Cloud SQL 生成嵌入，您的实例必须位于 us-central1 区域。Cloud SQL 可用于嵌入的 Vertex AI 模型 textembedding-gecko 位于该区域。

必需的数据库扩展

如需使用嵌入，您需要在 Cloud SQL 实例上安装 google_ml_integration 扩展程序（1.2 版或更高版本）。

（可选）如果要存储这些嵌入，并将矢量函数和运算符与嵌入一起使用，那么您还需要 pgvector 扩展程序。

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

设置模型访问权限

在通过 Cloud SQL 实例生成嵌入之前，您必须先将 Cloud SQL 配置为使用文本嵌入模型。

如需使用基于云的 textembeddings-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，请指定 textembedding-gecko 或
    textembedding-gecko-multilingual。这些是 Cloud SQL 可用于文本嵌入的云端模型。如需了解详情，请参阅文本嵌入。

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

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

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

以下示例使用 textembedding-gecko 模型的版本 001，根据提供的字面量字符串生成嵌入：

SELECT embedding( 'textembedding-gecko@001', '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：模型支持的维度数量。

    如果您将其中一个 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，请指定 textembedding-gecko 或
    textembedding-gecko-multilingual。这些是 Cloud SQL 可用于文本嵌入的云端模型。如需了解详情，请参阅文本嵌入。

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

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

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

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

以下示例使用 textembedding-gecko 模型的版本 001，根据 messages.message 列的内容用嵌入填充 messages.message_vector 列：

UPDATE messages SET message_vector = embedding( 'textembedding-gecko@001', message);

使用 pgvector 查询和索引嵌入

借助 pgvector PostgreSQL 扩展程序，您可以在数据库中存储、索引和查询文本嵌入时，使用特定于向量的运算符和函数。Cloud SQL 具有自己的优化功能，可用于处理 pgvector，让您可以创建索引，从而加快涉及嵌入的查询的速度。

创建经过优化的最近邻索引

pgvector 支持通过索引编制进行近似最近邻搜索。Cloud SQL 通过在创建索引时指定标量量化功能来扩展此支持。启用此功能后，标量量化可以加快具有较大维度向量的查询的速度。此外，利用该功能，您还可以存储最多具有 8,000 个维度的矢量。

如需在基于 pgvector 的索引上启用标量量化，请将 ivf 指定为索引方法，并将 SQ8 指定为量化器：

CREATE INDEX ON TABLE
  USING ivf (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

进行以下替换：

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

  • EMBEDDING_COLUMN：存储 vector 数据的列。

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

    • L2 距离：vector_l2_ops

    • 内积：vector_ip_ops

    • 余弦距离：vector_cosine_ops

  • LIST_COUNT：要用于此索引的列表的数量。

要在使用 real[] 数据类型而不是 vector 的嵌入列上创建此索引，请将该列转换为 vector 数据类型：

CREATE INDEX ON TABLE
  USING ivf ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)))'}} DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

将 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，请指定 textembedding-gecko 或
    textembedding-gecko-multilingual。这些是 Cloud SQL 可用于文本嵌入的云端模型。如需了解详情，请参阅文本嵌入。

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

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

  • TEXT：您想要查找最近的存储的语义邻居所需的文本。

  • ROW_COUNT：要返回的行数。如果您只需要一个最佳匹配，请指定 1 作为此参数的值。

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

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

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

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

在调用 embedding() 函数时，如果未指定模型的版本标记，则语法上是有效的，但也容易出错。

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

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

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

后续步骤