在 Cloud SQL for PostgreSQL 上启用 pgvector

本文档记录了如何在 Google Cloud SQL (PostgreSQL 13+) 实例上启用 pgvector 扩展，以支持向量数据库功能（如向量存储和相似度搜索）。

1. 简介

pgvector 是 PostgreSQL 的一个开源扩展，用于存储和查询向量嵌入（Vector Embeddings）。Google Cloud SQL 已经内置了对该扩展的支持。

此外，Google 还提供了专有的性能优化（ScaNN 索引），可以通过配置 Flags 开启。

2. 操作步骤

启用过程分为两个部分：基础设施配置（Terraform）和数据库内部配置（SQL）。

2.1 步骤一：启用 Google 向量辅助优化 (Terraform)

为了获得更好的向量搜索性能（特别是支持 ScaNN 索引），建议在 Cloud SQL 实例级别启用 cloudsql.enable_vector_assist 标志。

操作： 修改 Terraform 代码 (instance.tf)，在 google_sql_database_instance 的 settings 块中添加 database_flags。

hcl 复制代码

resource "google_sql_database_instance" "main" {
  # ... 其他配置 ...
  
  settings {
    # ... 其他配置 ...

    # 添加以下 Flag
    database_flags {
      name  = "cloudsql.enable_vector_assist"
      value = "on"
    }
  }
}

应用更改：

执行 terraform apply。

⚠️ 注意 ：修改数据库 Flags 通常会触发 Cloud SQL 实例重启，请在维护窗口进行操作。

2.2 步骤二：安装扩展 (SQL)

基础设施配置完成后，还需要在具体的数据库中"安装"扩展。这一步必须通过连接数据库执行 SQL 命令来完成，无法直接通过 Terraform 资源（除非使用专门的 postgresql provider）完成。

连接数据库：

你可以通过 Cloud SQL Auth Proxy、Bastion Host 或配置好的 Envoy 代理连接到数据库。

bash 复制代码

psql -h [DB_IP] -p 5432 -U [USERNAME] -d [DB_NAME]

执行安装命令：

在 psql 提示符下执行：

sql 复制代码

CREATE EXTENSION IF NOT EXISTS vector;

验证安装：

执行 \dx 查看已安装的扩展：

复制代码

default_db=> \dx
                                      List of installed extensions
  Name   | Version |   Schema   |                     Description
---------+---------+------------+------------------------------------------------------
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
 vector  | 0.8.0   | public     | vector data type and ivfflat and hnsw access methods
(2 rows)

看到 vector 出现在列表中即表示成功。

3. 常见问题 (FAQ)

Q: 我需要下载 pgvector 的安装包吗？
A: 不需要。Cloud SQL 的系统镜像中已经预装了 pgvector 的二进制文件。你只需要执行 CREATE EXTENSION 命令来在你的数据库中启用它。

Q: cloudsql.enable_vector_assist 是必须的吗？
A: 不是强制的，但强烈推荐。它启用了 Google 对向量搜索的底层优化（如 ScaNN 索引支持），能显著提升查询性能。如果不开启，你只能使用标准的 HNSW 或 IVFFlat 索引。

Q: 支持哪些 PostgreSQL 版本？
A: pgvector 支持 PostgreSQL 11+，但 Google 的 vector_assist 优化通常在较新的版本（如 PG 13, 14, 15+）中支持更好。本项目使用的是 PostgreSQL 13。