安装postgresql & 安装 pgvector 扩展

Windows 下 PostgreSQL + pgvector 完整安装指南

在本地开发环境中快速搭建支持向量搜索的 PostgreSQL 数据库，解决 AI 应用开发中的向量存储需求。

📋 前言

在开发 AI 应用（如 RAG 检索增强生成、向量搜索、语义匹配等）时，我们经常需要使用向量数据库。pgvector 是 PostgreSQL 的一个开源扩展，它让 PostgreSQL 具备了向量存储和相似性搜索的能力，无需额外部署专门的向量数据库。

本文将详细介绍在 Windows 环境下：

1. 安装 PostgreSQL 数据库
2. 安装 pgvector 扩展
3. 验证安装并创建测试数据

---

🎯 为什么选择 pgvector？

优势对比

特性	pgvector	专用向量数据库
部署复杂度	⭐ 低（PostgreSQL 扩展）	⭐⭐⭐ 高（独立服务）
学习成本	⭐ 低（SQL 即可）	⭐⭐ 中（新 API）
事务支持	✅ 完整 ACID	❌ 部分支持
生态兼容	✅ 所有 PostgreSQL 工具	❌ 专用客户端
适用场景	中小规模向量数据	超大规模向量检索

适用场景：

• ✅ 中小型项目的向量搜索需求
• ✅ 已有 PostgreSQL 基础设施
• ✅ 需要事务一致性的向量操作
• ✅ 混合查询（向量 + 传统 SQL）

---

🚀 第一步：安装 PostgreSQL

方法一：使用官方安装包（推荐）

1. 下载安装包

访问 PostgreSQL 官网下载页面：

https://www.postgresql.org/download/windows/

💡 建议版本：PostgreSQL 15+（pgvector 0.5+ 需要 PostgreSQL 13+）

2. 运行安装程序

双击下载的 .exe 文件，按照向导操作：

1. 选择安装目录：默认 C:\Program Files\PostgreSQL\16
2. 选择组件：勾选以下项
   • ✅ PostgreSQL Server
   • ✅ pgAdmin 4（图形化管理工具）
   • ✅ Command Line Tools
   • ✅ Stack Builder（可选，用于后续安装扩展）
3. 设置数据目录：默认即可
4. 设置超级用户密码：⚠️ 务必记住此密码
5. 端口号：默认 5432
6. 区域设置：选择 Default locale 或 Chinese (Simplified)

3. 完成安装

安装完成后，系统会自动启动 PostgreSQL 服务。

方法二：使用 Chocolatey（命令行安装）

如果您已安装 Chocolatey，可以一键安装：

# 以管理员身份运行 PowerShell
choco install postgresql -y

安装完成后，初始化数据库：

# 切换到 PostgreSQL bin 目录
cd "C:\Program Files\PostgreSQL\16\bin"

# 初始化数据库集群
.\initdb.exe -D "C:\Program Files\PostgreSQL\16\data" -U postgres -W

# 注册为 Windows 服务
.\pg_ctl.exe register -N "postgresql-16" -D "C:\Program Files\PostgreSQL\16\data" -U postgres -w

# 启动服务
net start postgresql-16

---

🔧 第二步：验证 PostgreSQL 安装

1. 检查服务状态

# 查看 PostgreSQL 服务是否运行
Get-Service postgresql*

# 应该看到类似输出：
# Status   Name               DisplayName
# ------   ----               -----------
# Running  postgresql-x64-16  postgresql-x64-16

2. 连接数据库

# 使用 psql 命令行工具连接
psql -U postgres

# 输入安装时设置的密码

成功连接后，会看到提示符：

postgres=#

3. 查看版本信息

-- 在 psql 中执行
SELECT version();

-- 输出示例：
-- PostgreSQL 16.2, compiled by Visual C++ build 1916, 64-bit

4. 创建测试数据库

-- 创建数据库
CREATE DATABASE test_db;

-- 切换到新数据库
\c test_db

-- 创建测试表
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(100)
);

-- 插入测试数据
INSERT INTO users (name, email) VALUES 
    ('张三', 'zhangsan@example.com'),
    ('李四', 'lisi@example.com');

-- 查询数据
SELECT * FROM users;

-- 退出 psql
\q

---

📦 第三步：安装 pgvector 扩展

方法一：使用预编译包（最简单）

pgvector 提供了 Windows 预编译包，适用于 PostgreSQL 13-16。

1. 下载 pgvector

访问 GitHub Releases 页面：

https://github.com/andreiramani/pgvector_pgsql_windows/releases

根据您的 PostgreSQL 版本下载对应的文件：

• PostgreSQL 16: pgvector-pg16-windows.zip
• PostgreSQL 15: pgvector-pg15-windows.zip
• PostgreSQL 14: pgvector-pg14-windows.zip

2. 解压文件

解压后会看到以下文件：

pgvector-pg16-windows/
├── bin/
│   └── vector.dll
├── lib/
│   └── vector.dll
└── share/
    └── extension/
        ├── vector.control
        ├── vector--0.5.0.sql
        └── vector--0.5.0--0.6.0.sql

3. 复制文件到 PostgreSQL 目录

假设 PostgreSQL 安装在 C:\Program Files\PostgreSQL\16：

# 以管理员身份运行 PowerShell

# 复制 DLL 文件到 lib 目录
Copy-Item "path\to\pgvector\lib\vector.dll" "C:\Program Files\PostgreSQL\16\lib\"

# 复制扩展文件到 share/extension 目录
Copy-Item "path\to\pgvector\share\extension\*" "C:\Program Files\PostgreSQL\16\share\extension\"

4. 重启 PostgreSQL 服务

# 重启服务使扩展生效
Restart-Service postgresql-x64-16

# 或者通过服务管理器
services.msc
# 找到 "postgresql-x64-16"，右键 → 重新启动

方法二：从源码编译（高级用户）

如果您需要自定义版本或最新功能，可以从源码编译。

前置要求

1. 安装 Visual Studio Build Tools
2. 安装 CMake
3. 安装 Git

编译步骤

# 克隆仓库
git clone https://github.com/pgvector/pgvector.git
cd pgvector

# 创建构建目录
mkdir build
cd build

# 配置 CMake（替换为您的 PostgreSQL 路径）
cmake .. ^
  -DPostgreSQL_ROOT="C:/Program Files/PostgreSQL/16" ^
  -DCMAKE_BUILD_TYPE=Release

# 编译
cmake --build . --config Release

# 安装（需要管理员权限）
cmake --install . --config Release

方法三：使用 Docker（最省心）

如果不想在本地安装，可以使用包含 pgvector 的 Docker 镜像：

# docker-compose.yml
version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: postgres-vector
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your_password
      POSTGRES_DB: lobechat
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

启动服务：

docker-compose up -d

💡 推荐镜像：

• pgvector/pgvector:pg16 - 官方 pgvector 镜像
• paradedb/paradedb:latest-pg17 - ParadeDB（内置 pgvector + 全文搜索）

---

✅ 第四步：验证 pgvector 安装

1. 连接数据库

psql -U postgres -d test_db

2. 创建扩展

-- 创建 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

-- 验证扩展是否安装成功
\dx

-- 输出应该包含：
-- List of installed extensions
--   Name   | Version |   Schema   |         Description          
-- ---------+---------+------------+------------------------------
--  plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
--  vector  | 0.6.0   | public     | vector data type and functions

3. 查看可用函数

-- 查看 vector 扩展提供的所有函数
\df vector.*

-- 常见函数：
-- vector_dims(vector)      - 返回向量维度
-- vector_norm(vector)      - 返回向量范数
-- cosine_distance(v1, v2)  - 余弦相似度距离
-- l2_distance(v1, v2)      - L2 欧氏距离
-- inner_product(v1, v2)    - 内积

---

🧪 第五步：创建向量表并测试

1. 创建向量表

-- 创建文档表，包含向量字段
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title VARCHAR(200),
    content TEXT,
    embedding vector(3),  -- OpenAI text-embedding-ada-002 的维度是 1536
    created_at TIMESTAMP DEFAULT NOW()
);

-- 创建向量索引（加速相似性搜索）
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- 或者使用 HNSW 索引（更适合高维向量）
-- CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

2. 插入测试数据

-- 插入带向量的数据（这里使用随机向量作为示例）
INSERT INTO documents (title, content, embedding) VALUES 
('PostgreSQL 简介', 'PostgreSQL 是一个强大的开源关系型数据库...', '[0.1, 0.2, 0.3]'::vector), 
('pgvector 扩展', 'pgvector 为 PostgreSQL 添加了向量存储能力...', '[0.4, 0.5, 0.6]'::vector), 
('向量搜索原理', '向量搜索通过计算向量之间的距离来查找相似内容...', '[0.7, 0.8, 0.9]'::vector);

💡 提示：在实际应用中，您需要使用嵌入模型（如 OpenAI、HuggingFace）将文本转换为向量。

3. 执行相似性搜索

-- 使用余弦相似度搜索最相似的文档
SELECT 
    id,
    title,
    content,
    1 - (embedding <=> '[0.15, 0.25, 0.35]'::vector) AS similarity
FROM documents
ORDER BY embedding <=> '[0.15, 0.25, 0.35]'::vector
LIMIT 5;

-- 运算符说明：
-- <=>  : 余弦距离（cosine distance）
-- <->  : L2 欧氏距离（Euclidean distance）
-- <#>  : 负内积（negative inner product）

4. 结合全文搜索

-- 混合查询：同时使用向量相似度和关键词匹配
SELECT 
    id,
    title,
    content,
    1 - (embedding <=> '[0.15, 0.25, 0.35]'::vector) AS vector_score,
    ts_rank(to_tsvector('simple', content), plainto_tsquery('simple', 'PostgreSQL')) AS text_score
FROM documents
WHERE to_tsvector('simple', content) @@ plainto_tsquery('simple', 'PostgreSQL')
ORDER BY vector_score DESC, text_score DESC
LIMIT 5;

---

🔗 第六步：在应用中使用

Node.js 示例（使用 Drizzle ORM）

// schema.ts
import { pgTable, serial, varchar, text, timestamp, vector } from 'drizzle-orm/pg-core';

export const documents = pgTable('documents', {
  id: serial('id').primaryKey(),
  title: varchar('title', { length: 200 }),
  content: text('content'),
  embedding: vector('embedding', { dimensions: 1536 }),
  createdAt: timestamp('created_at').defaultNow(),
});

// query.ts
import { db } from './db';
import { documents } from './schema';
import { cosineDistance, desc, sql } from 'drizzle-orm';

// 相似性搜索
const queryEmbedding = [0.1, 0.2, 0.3, /* ... */];

const results = await db
  .select({
    id: documents.id,
    title: documents.title,
    content: documents.content,
    similarity: sql<number>`1 - (${cosineDistance(documents.embedding, queryEmbedding)})`,
  })
  .from(documents)
  .orderBy(desc(sql`${cosineDistance(documents.embedding, queryEmbedding)}`))
  .limit(5);

console.log(results);

Python 示例（使用 psycopg2）

import psycopg2
from psycopg2.extras import execute_values

# 连接数据库
conn = psycopg2.connect(
    dbname="test_db",
    user="postgres",
    password="your_password",
    host="localhost",
    port="5432"
)

cur = conn.cursor()

# 插入向量数据
embedding = [0.1, 0.2, 0.3]  # 您的嵌入向量
cur.execute(
    "INSERT INTO documents (title, content, embedding) VALUES (%s, %s, %s)",
    ("测试文档", "这是测试内容", embedding)
)

# 相似性搜索
query_embedding = [0.15, 0.25, 0.35]
cur.execute(
    """
    SELECT id, title, content, 
           1 - (embedding <=> %s::vector) AS similarity
    FROM documents
    ORDER BY embedding <=> %s::vector
    LIMIT 5
    """,
    (query_embedding, query_embedding)
)

results = cur.fetchall()
for row in results:
    print(f"ID: {row[0]}, Title: {row[1]}, Similarity: {row[3]}")

cur.close()
conn.close()

---

⚠️ 常见问题与解决方案

问题 1：could not open extension control file

错误信息：

ERROR:  could not open extension control file 
"C:/Program Files/PostgreSQL/16/share/extension/vector.control": No such file or directory

解决方案：

• 确认已将 vector.control 和 SQL 文件复制到正确的 share/extension 目录
• 检查文件权限，确保 PostgreSQL 用户可以读取
• 重启 PostgreSQL 服务

问题 2：undefined symbol: vector_in

错误信息：

ERROR:  could not load library 
"C:/Program Files/PostgreSQL/16/lib/vector.dll": 
The specified procedure could not be found.

解决方案：

• 确认下载的 pgvector 版本与 PostgreSQL 版本匹配
• 重新下载正确的预编译包
• 检查 vector.dll 是否正确复制到 lib 目录

问题 3：索引创建失败

错误信息：

ERROR:  data type vector has no default operator class for access method "ivfflat"

解决方案：

-- 确保使用正确的操作符类
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);

-- 或者
CREATE INDEX ON documents USING ivfflat (embedding vector_l2_ops);

问题 4：性能优化

提升向量搜索性能：

-- 1. 调整 IVFFlat 索引参数
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 100);  -- lists ≈ 行数 / 1000

-- 2. 使用 HNSW 索引（更快但占用更多内存）
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- 3. 调整查询时的 ef_search 参数
SET hnsw.ef_search = 40;  -- 值越大越准确但越慢

-- 4. 定期维护索引
REINDEX INDEX documents_embedding_idx;
VACUUM ANALYZE documents;

---

📊 pgvector 性能基准

数据集大小	索引类型	查询延迟	内存占用	适用场景
< 10万	无索引	~100ms	低	开发测试
10万 - 100万	IVFFlat	~10ms	中	中等规模应用
> 100万	HNSW	~5ms	高	大规模生产环境

---

🎓 进阶学习资源

官方文档

• pgvector GitHub: github.com/pgvector/pg…
• PostgreSQL 官方文档: www.postgresql.org/docs/

相关技术

• ParadeDB: github.com/paradedb/pa… + 全文搜索）
• LanceDB: 专为向量优化的数据库格式
• Chroma: 流行的向量数据库

嵌入模型

• OpenAI: text-embedding-ada-002（1536 维）
• HuggingFace: sentence-transformers（384/768 维）
• Cohere: embed-multilingual-v3.0（1024 维）

---

📝 总结

本文详细介绍了在 Windows 环境下安装 PostgreSQL 和 pgvector 扩展的完整流程：

✅ 三种安装方式：官方安装包、Chocolatey、Docker
✅ 三种 pgvector 安装方法：预编译包、源码编译、Docker 镜像
✅ 完整的验证流程：从连接到创建向量表
✅ 实际应用示例：Node.js 和 Python 代码
✅ 常见问题排查：4 个典型问题及解决方案

pgvector 让 PostgreSQL 具备了强大的向量处理能力，特别适合：

• 🤖 AI 应用的向量存储和检索
• 🔍 语义搜索和推荐系统
• 📊 混合查询（向量 + 传统 SQL）
• 💾 统一数据存储架构

希望这篇文章能帮助您快速搭建向量数据库环境！如有问题，欢迎在评论区交流。

---