Docker 安装与配置 pgvector1. Docker 安装 PostgreSQL 并启用 pgvector 扩展####方法一使用 Docker Compose推荐创建一个docker-compose.yml文件内容如下version: 3.8 services: postgres: image: pgvector/pgvector:pg17 # 使用官方pgvector镜像指定PostgreSQL版本 container_name: pgvector_db environment: POSTGRES_USER: admin POSTGRES_PASSWORD: your_password POSTGRES_DB: vector_db ports: 5432:5432 volumes: postgres_data:/var/lib/postgresql/data - ./init.sql:/docker-entrypoint-initdb.d/init.sql # 初始化脚本 restart: unless-stopped volumes: postgres_data:创建初始化脚本init.sql用于自动创建扩展-- 启用pgvector扩展 CREATE EXTENSION IF NOT EXISTS vector;启动服务docker-compose up -d方法二使用 Docker 命令直接运行docker run -d \ --name pgvector_db \ -e POSTGRES_USERadmin \ -e POSTGRES_PASSWORDyour_password \ -e POSTGRES_DBvector_db \ -p 5432:5432 \ -v postgres_data:/var/lib/postgresql/data \ pgvector/pgvector:pg17进入容器并手动启用扩展docker exec -it pgvector_db psql -U admin -d vector_db -- 在psql命令行中执行 CREATE EXTENSION vector;方法三基于官方 PostgreSQL 镜像安装扩展如果需要使用特定版本的 PostgreSQL可以使用以下 DockerfileFROM postgres:17-bookworm RUN apt-get update apt-get install -y postgresql-17-pgvector然后构建并运行容器 。2. 验证安装连接数据库后执行以下命令验证-- 检查扩展是否已安装 SELECT * FROM pg_extension WHERE extname vector; -- 查看pgvector版本 SELECT extversion FROM pg_extension WHERE extname vector;pgvector 语法详解与使用示例1. 向量数据类型pgvector 引入了vector类型用于存储高维向量。数据类型描述示例vector(n)n维向量n为维度数vector(128)vector动态维度向量vector-- 创建包含向量列的表 CREATE TABLE items ( id BIGSERIAL PRIMARY KEY, embedding VECTOR(3), -- 3维向量 text TEXT ); -- 插入向量数据 INSERT INTO items (embedding, text) VALUES ([1,2,3], item1), ([4,5,6], item2), ([7,8,9], item3);2. 向量操作符与距离函数pgvector 支持多种距离计算方式操作符函数描述距离公式-l2_distance()欧几里得距离L2√Σ(xᵢ - yᵢ)²#inner_product()内积负值-Σ(xᵢ × yᵢ)cosine_distance()余弦距离1 - (Σ(xᵢ × yᵢ) / (√Σxᵢ² × √Σyᵢ²))-- 使用操作符计算距离 SELECT text, embedding - [1,2,3] AS l2_distance, embedding [1,2,3] AS cosine_distanceFROM itemsORDER BY embedding - [1,2,3] LIMIT 5; -- 使用函数计算距离 SELECT text, l2_distance(embedding, [1,2,3]) AS l2_dist, cosine_distance(embedding, [1,2,3]) AS cos_dist FROM items;3. 相似性搜索最近邻搜索K-NN-- 查找与给定向量最相似的5个项 SELECT id, text, embedding - [3,1,2] AS distance FROM items ORDER BY embedding - [3,1,2] LIMIT 5; -- 带过滤条件的相似性搜索 SELECT id, text, embedding [0.1,0.2,0.3] AS similarity FROM items WHERE text LIKE %重要% ORDER BY embedding [0.1,0.2,0.3] LIMIT 10;距离阈值过滤-- 查找距离小于指定阈值的所有项 SELECT id, text, embedding - [1,1,1] AS distance FROM items WHERE embedding - [1,1,1] 5.0 ORDER BY distance;4. 向量索引为了提高相似性搜索性能pgvector 支持两种索引类型IVFFlat 索引适合中等规模数据集-- 创建IVFFlat索引 CREATE INDEX ON itemsUSING ivfflat (embedding vector_l2_ops) WITH (lists 100); -- 参数说明 -- lists: 聚类中心数量通常设置为 sqrt(行数) --适用于L2距离、内积、余弦距离HNSW 索引适合大规模数据集查询性能更好-- 创建HNSW索引 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m 16, ef_construction 64); -- 参数说明 -- m: 每个节点的最大连接数默认16 -- ef_construction: 构建时的动态候选列表大小默认64 -- ef_search: 查询时的动态候选列表大小默认40创建索引时不设置索引使用示例-- 创建不同距离度量的索引 -- 1. L2距离索引 CREATE INDEX items_embedding_l2_idx ON items USING hnsw (embedding vector_l2_ops); -- 2. 内积索引 CREATE INDEX items_embedding_ip_idx ON items USING hnsw (embedding vector_ip_ops); -- 3. 余弦距离索引 CREATE INDEX items_embedding_cosine_idx ON items USING hnsw (embedding vector_cosine_ops); -- 设置索引参数优化查询 SET hnsw.ef_search 100; -- 提高召回率但可能降低查询速度 -- 使用索引进行搜索 EXPLAIN ANALYZE SELECT id, text, embedding - [1,2,3] AS distance FROM items ORDER BY embedding - [1,2,3] LIMIT 10;5. 向量运算与函数向量算术运算-- 向量加减法 SELECT [1,2,3]::vector [4,5,6]::vector AS addition; -- 结果: [5,7,9] SELECT [5,7,9]::vector - [1,2,3]::vector AS subtraction; -- 结果: [4,5,6] -- 向量标量乘法 SELECT [1,2,3]::vector * 2 AS scalar_multiply; -- 结果: [2,4,6] -- 向量归一化单位向量 SELECT l2_normalize([1,2,3]::vector) AS normalized;向量聚合函数-- 计算向量平均值 SELECT avg(embedding) AS avg_embedding FROM items; -- 向量求和 SELECT sum(embedding) AS sum_embedding FROM items;6. 完整使用示例场景商品推荐系统-- 1. 创建商品表 CREATE TABLE products ( id SERIAL PRIMARY KEY, name VARCHAR(255), description TEXT, embedding VECTOR(384), -- 使用sentence-transformers生成的384维向量 category VARCHAR(100), price DECIMAL(10,2) ); -- 2. 插入示例数据 INSERT INTO products (name, description, embedding, category, price) VALUES (智能手机, 高性能智能手机, [0.1,0.2,0.3,...]::vector(384), 电子产品, 2999.00), (平板电脑, 轻薄便携平板, [0.2,0.3,0.4,...]::vector(384), 电子产品, 1999.00), (运动鞋, 专业跑步鞋, [0.5,0.6,0.7,...]::vector(384), 运动装备, 599.00); -- 3. 创建HNSW索引CREATE INDEX products_embedding_idx ON products USING hnsw (embedding vector_cosine_ops) WITH (m 16, ef_construction 64); -- 4. 基于用户历史查找相似商品 WITH user_history AS ( SELECT avg(embedding) AS user_vector FROM products WHERE id IN (1, 2) -- 用户购买过的商品ID ) SELECT p.id, p.name, p.category, p.price, 1 - (p.embedding uh.user_vector) AS similarity_score FROM products p, user_history uh WHERE p.id NOT IN (1, 2) -- 排除已购买商品 ORDER BY p.embedding uh.user_vector LIMIT 10; -- 5. 混合查询相似性 价格过滤 SELECT id, name, price, embedding [0.15,0.25,0.35,...] AS distance FROM products WHERE price BETWEEN 1000 AND 3000 AND category 电子产品 ORDER BY distance LIMIT 5;场景文本语义搜索-- 1. 创建文档表 CREATE TABLE documents ( id BIGSERIAL PRIMARY KEY, title TEXT, content TEXT, embedding VECTOR(768), -- BERT等模型生成的768维向量 created_at TIMESTAMP DEFAULT NOW() ); -- 2. 语义搜索函数 CREATE OR REPLACE FUNCTION semantic_search( query_vector VECTOR(768), similarity_threshold FLOAT DEFAULT 0.7, max_results INT DEFAULT 10 ) RETURNS TABLE ( doc_id BIGINT, title TEXT, similarity FLOAT, snippet TEXT ) AS $$ BEGIN RETURN QUERY SELECT d.id, d.title, 1 - (d.embedding query_vector) AS similarity, substring(d.content from 1 for 200) AS snippet FROM documents d WHERE 1 - (d.embedding query_vector) similarity_threshold ORDER BY d.embedding query_vector LIMIT max_results; END; $$ LANGUAGE plpgsql; -- 3. 使用函数进行搜索 SELECT * FROM semantic_search([0.1,0.2,0.3,...]::vector(768), 0.8, 5);7. 性能优化建议索引选择策略数据量 100万考虑 IVFFlat数据量 100万使用 HNSW内存充足时HNSW 通常性能更好索引参数调优-- 构建时优化召回率 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m 32, ef_construction 128); -- 查询时临时调整 SET hnsw.ef_search 200; -- 提高搜索精度 SET enable_seqscan off; -- 强制使用索引批量插入优化-- 禁用索引加速批量插入 DROP INDEX items_embedding_idx; -- 批量插入数据 INSERT INTO items (embedding, text) VALUES (...), (...), ...; -- 重新创建索引 CREATE INDEX items_embedding_idx ON items USING hnsw (embedding vector_l2_ops);查询性能分析-- 使用EXPLAIN ANALYZE分析查询计划 EXPLAIN ANALYZE SELECT id, embedding - [1,2,3] AS dist FROM items ORDER BY dist LIMIT 10;8. 注意事项维度限制pgvector 支持最多 2000 维的向量内存使用HNSW 索引会占用较多内存需根据服务器配置调整参数距离计算余弦距离返回的是 1 - 余弦相似度值越小越相似NULL处理向量列可以包含 NULL 值距离计算时 NULL 会返回 NULL版本兼容确保 pgvector 扩展版本与 PostgreSQL 版本兼容通过以上配置和示例您可以充分利用 pgvector 在 PostgreSQL 中实现高效的向量相似性搜索功能。参考来源2-PostgreSQL docker compose 安装教程-PgvectorLinux环境下基于Docker安装 PostgreSQL数据库并配置 pgvectordocker安装pgvector、age和postgisdocker安装的postgres同时安装postgis、pgvector 扩展pgvector docker部署测试