SpringAI实战-6.1-PGVector安装

写在前面：

众所周知，现在其实已经很流行AI辅助代码生成了

如果你是联网环境建议直接使用

1.claudecode

2.opencode

3.openclaw

等等cli或者类似软件安装这个东西真的不需要自己搞

交给ai省心省力

那么下面是正文：

文档定位: 本文档详细记录在Windows环境下为PostgreSQL安装pgvector扩展的全过程，为后续向量检索和RAG应用搭建基础设施
学习建议: 按照步骤操作即可完成安装，重点理解向量存储的基本概念和操作

一、为什么需要pgvector？

1.1 向量检索在AI应用中的作用

在Spring AI和RAG（检索增强生成）应用中，我们需要：

•将文本转换为向量（Embedding）•存储大量向量数据•快速查找相似的向量（语义搜索）

1.2 pgvector的核心功能

pgvector是PostgreSQL的扩展，提供：

•向量数据类型：存储高维向量（如1024维、1536维）• 相似度运算：欧氏距离、余弦相似度、内积•高效索引：IVFFlat、HNSW索引加速检索•与PostgreSQL生态无缝集成：ACID事务、备份恢复、权限管理

1.3 技术栈定位

文本 → Embedding模型 → 向量 → PostgreSQL + pgvector → 相似度搜索 → RAG应用

二、环境准备

2.1 系统环境

组件	版本	说明
操作系统	Windows 11	管理员权限执行安装
PostgreSQL	18.3	安装在 D:\Tools\Postgres
pgvector	0.8.2	预编译二进制版本
数据库	spring_ai_learn	目标数据库

2.2 验证环境

# 查看PostgreSQL版本"D:/Tools/Postgres/bin/psql" --version# 查看数据库列表PGPASSWORD=123456 "D:/Tools/Postgres/bin/psql" -U postgres -c "\l"

三、安装步骤详解

3.1 方法选择：预编译二进制（推荐）

为什么选择此方法：

•无需安装Visual Studio和CMake•无需编译，节省时间•稳定可靠，避免编译错误

3.2 步骤1：下载预编译二进制

从GitHub下载pgvector Windows版本：

# 在用户目录创建临时文件夹mkdir -p temp_pgvectorcd temp_pgvector# 下载pgvector v0.8.2 for PostgreSQL 18curl -L -o vector.zip "https://github.com/andreiramani/pgvector_pgsql_windows/releases/download/0.8.2_18.0.2/vector.v0.8.2-pg18.zip"# 解压文件unzip vector.zip -d extracted

文件结构：

extracted/├── lib/vector.dll                    # 核心库文件├── share/extension/vector*.sql       # SQL扩展文件├── share/extension/vector.control    # 控制文件└── include/server/extension/vector/*.h  # 头文件（开发用）

3.3 步骤2：停止PostgreSQL服务

# 以管理员身份运行命令提示符执行net stop postgresql-x64-18

注意事项：

•确保没有应用连接到数据库•服务停止后才能复制文件

3.4 步骤3：复制文件到PostgreSQL目录

# 复制DLL文件到lib目录cp "temp_pgvector/extracted/lib/vector.dll" "D:/Tools/Postgres/lib/"# 复制扩展文件到share/extension目录cp temp_pgvector/extracted/share/extension/* "D:/Tools/Postgres/share/extension/"# （可选）复制头文件，用于开发mkdir -p "D:/Tools/Postgres/include/server/extension/vector"cp temp_pgvector/extracted/include/server/extension/vector/*.h "D:/Tools/Postgres/include/server/extension/vector/"

3.5 步骤4：启动PostgreSQL服务

net start postgresql-x64-18

四、验证安装

4.1 检查扩展是否可用

# 连接到数据库PGPASSWORD=123456 "D:/Tools/Postgres/bin/psql" -U postgres -d spring_ai_learn -c "\dx"

预期输出：

已安装扩展列表  名称  | 版本  | Default version | 管理模式 |              描述--------+-------+-----------------+----------+-------------------------------------- plpgsql| 1.0   | 1.0             | pg_catalog | PL/pgSQL procedural language vector | 0.8.2 | 0.8.2           | public     | vector data type and ivfflat and hnsw access methods

4.2 创建向量扩展

-- 在目标数据库中执行CREATE EXTENSION vector;

执行结果：CREATE EXTENSION

五、创建向量表与索引

5.1 设计文档表结构

CREATE TABLE IF NOT EXISTS documents (    id SERIAL PRIMARY KEY,    content TEXT,                    -- 文档内容    metadata JSONB,                  -- 元数据（来源、时间等）    embedding vector(1024)           -- 向量列，1024维（根据模型调整）);

列说明：

•id：自增主键•content：原始文本内容•metadata：JSON格式的元数据，灵活存储附加信息•embedding：1024维向量，适用于大多数现代Embedding模型

5.2 创建索引加速查询

CREATE INDEX documents_embedding_idxON documents USING ivfflat (embedding vector_cosine_ops);

索引类型说明：

•ivfflat：倒排索引，适合大规模数据集•vector_cosine_ops：余弦相似度操作符类

重要警告：

注意:  ivfflat index created with little data警告: This will cause low recall.提示: Drop the index until the table has more data.

最佳实践：

1.先积累数据（至少数千条）2.删除索引：DROP INDEX documents_embedding_idx;3.重新创建索引，提高召回率

5.3 验证表结构

PGPASSWORD=123456 "D:/Tools/Postgres/bin/psql" -U postgres -d spring_ai_learn -c "\d documents"

输出示例：

数据表 "public.documents"   列       |     类型      | 校对规则 | 可空  |                   默认-----------+--------------+----------+-------+--------------------------------------- id        | integer      |          | not null | nextval('documents_id_seq'::regclass) content   | text         |          |        | metadata  | jsonb        |          |        | embedding | vector(1024) |          |        |索引：    "documents_pkey" PRIMARY KEY, btree (id)    "documents_embedding_idx" ivfflat (embedding vector_cosine_ops)

六、测试向量操作

6.1 插入测试数据

-- 插入测试文档（全0向量和全1向量）INSERT INTO documents (content, metadata, embedding) VALUES('测试文档1', '{"source": "test", "timestamp": "2024-03-26"}', array_fill(0, ARRAY[1024])::vector),('测试文档2', '{"source": "test", "timestamp": "2024-03-26"}', array_fill(1, ARRAY[1024])::vector);

6.2 相似度搜索测试

-- 欧氏距离搜索（距离越小越相似）SELECT    id,    content,    embedding <-> array_fill(0, ARRAY[1024])::vector as distanceFROM documentsORDER BY distanceLIMIT 5;

预期结果：

 id |     content     | distance----+-----------------+----------  1 | 测试文档1       |        0  2 | 测试文档2       |       32

6.3 支持的向量运算

运算符	说明	示例
`<->`	欧氏距离	`SELECT embedding <-> '[1,2,3]'`
`<=>`	余弦距离	`SELECT embedding <=> '[1,2,3]'`
`<#>`	负内积	`SELECT embedding <#> '[1,2,3]'`

实际应用公式：

-- 余弦相似度（值越大越相似，范围[-1, 1]）SELECT 1 - (embedding <=> query_vector) as cosine_similarityFROM documentsORDER BY cosine_similarity DESCLIMIT 10;

九、性能优化建议

9.1 索引选择策略

索引类型	适用场景	特点
IVFFlat	大规模数据集（百万级）	查询快，召回率可调
HNSW	高召回率要求	召回率高，内存占用大

9.2 创建HNSW索引

-- 创建HNSW索引（PostgreSQL 16+）CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)WITH (m = 16, ef_construction = 64);

9.3 向量维度选择

模型	推荐维度	说明
OpenAI text-embedding-ada-002	1536	通用性最好
通义千问Embedding	1024或1536	中文优化
BERT-base	768	传统模型

9.4 批量插入优化

-- 使用COPY命令批量插入（性能最佳）COPY documents(content, metadata, embedding)FROM '/path/to/data.csv'WITH (FORMAT csv);

10.3 参考资料

1.pgvector官方文档：https://github.com/pgvector/pgvector^[1]2.PostgreSQL向量检索指南：https://www.postgresql.org/docs/current/pgvector.html^[2]3.Spring AI Embedding：https://docs.spring.io/spring-ai/reference/api/embeddings.html^[3]

十一、总结

11.1 安装要点回顾

1.选择预编译二进制：避免编译复杂性2.管理员权限操作：确保文件复制权限3.服务启停顺序：安装前停止，安装后启动4.验证安装：检查扩展是否可用

11.2 核心配置

-- 最小可用配置CREATE EXTENSION vector;CREATE TABLE documents(embedding vector(1024));CREATE INDEX ON documents USING ivfflat(embedding vector_cosine_ops);

操作建议：按照本文步骤操作，遇到问题查看第七节故障排除。安装成功后，即可开始向量检索的开发学习。

References

[1]: https://github.com/pgvector/pgvector
[2]: https://www.postgresql.org/docs/current/pgvector.html
[3]: https://docs.spring.io/spring-ai/reference/api/embeddings.html
[4] SpringAI实战-6-Embedding向量基础: ./SpringAI实战-6-Embedding向量基础.md