PostgreSQL笔记41：向量数据、向量化表示与pgvector扩展实践

关注

原创最新推荐文章于 2026-09-05 12:05:17 发布 366 阅读 AI 写同款· GEO 优化 ›

PostgreSQL pgvector：如何利用向量数据库提升搜索效率和精度随着基础模型的兴起，向量数据库的受欢迎程度也飙升。事实上，在大型语言模型环境中，向量数据库也很有用。在机器学习领域，我们经常处理的是向量嵌入。向量嵌入是通过特定的机器学习模型运行对象的特征，将对象的上下文信息投射到潜在空间中来创建的。为了在使用向量嵌入时能够表现得特别好，创建向量数据库是必要的。这方面的工作包括存储、更新和检索向量。当我们谈论检索时，通常是指检索与查询最相似的向量，这些向量与嵌入到同一潜在空间并传递到向量数据库中。这个检索过程被称为近似最近邻。阅读详情

概述

在人工智能与机器学习应用迅速普及的背景下，非结构化数据（文本、图像、音频等）的存储与检索需求日益增长。向量数据库作为AI时代的核心基础设施，其底层原理与技术实现备受关注。

PostgreSQL通过开源扩展 pgvector，将向量相似性搜索能力无缝集成到关系型数据库中。本文将从向量数据的基本概念出发，结合 pgvector 扩展，系统性地阐述向量化表示的技术原理与实践方法。

纲要

向量数据的基本概念
- 向量的数学定义与几何意义
- 向量化表示（Vector Embedding）的核心思想
- 多维度特征空间与事物区分
pgvector 扩展概述
- 扩展安装与启用
- 向量数据类型：vector、halfvec、sparsevec、bit
- 距离算子与相似性度量
向量数据的存储与操作
- 创建向量数据表
- 插入向量数据
- 向量检索（精确搜索与近似搜索）
向量索引与性能优化
- IVFFlat 索引
- HNSW 索引
- 索引调优与并发创建
向量嵌入（Embedding）生成与集成
- 非结构化数据到向量的转换流程
- 与外部嵌入模型（如OpenAI Embeddings API）的集成
API速览
Demo完整示例（Node.js + pg + pgvector）
项目难点与解决方案（可选）
官方文档与参考链接
总结

向量数据的基本概念

向量的数学定义

根据数学定义，向量（Vector）是同时具有数值（大小）和方向的几何对象，且满足平行四边形法则。在理论数学中，向量被定义为向量空间中的元素，通常以带箭头的符号表示。向量的长度（模）代表其大小，箭头的指向代表其方向。

向量化表示的核心思想

向量化表示（Vector Embedding）是将非结构化数据（文本、图像、音频等）转换为高维向量数值的过程。通过这种嵌入（Embedding）技术，任何数据对象都可以被表示为一个多维向量，从而将现实世界的语义关系转化为数学空间中的几何关系。

多维度特征空间与事物区分

人类识别不同事物的本质是通过提取事物的多个特征。以区分犬种为例：

单一维度（体型） ：仅凭体型难以区分体型相近的犬种（如哈士奇、金毛、拉布拉多）
二维特征空间（体型 + 毛发） ：增加毛发特征后，可以在二维坐标系中区分上述三种犬
高维特征空间 ：继续增加眼睛大小、鼻子长短、攻击性、服从性等特征，维度越高，区分能力越强

理论上，只要特征维度足够多，任何两个不同的事物都可以在高维空间中被区分开。这正是向量化表示的核心价值——将现实世界的复杂对象映射到高维向量空间，使得语义相近的对象在空间中彼此靠近，语义相远的对象在空间中彼此远离。

pgvector扩展概述

pgvector 是PostgreSQL的开源扩展，为数据库添加了向量数据类型和向量相似性搜索能力。该扩展支持精确最近邻搜索和近似最近邻搜索（ANN），并提供了多种距离度量方式。

扩展安装与启用

pgvector 扩展需要通过 CREATE EXTENSION 命令启用：

-- 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

若需要安装特定版本：

CREATE EXTENSION vector VERSION '0.7.4';

向量数据类型

pgvector 提供了多种向量数据类型以适应不同场景：

数据类型	精度	最大维度	适用场景
`vector`	单精度浮点数（float32）	2,000	通用场景，最常用
`halfvec`	半精度浮点数（float16）	4,000	内存敏感场景
`sparsevec`	稀疏向量	16,000	高维稀疏数据
`bit`	二进制向量	64,000	二进制嵌入

距离算子

pgvector 提供以下距离算子用于向量相似性度量：

算子	距离类型	说明	适用场景
`<->`	L2距离（欧几里得距离）	计算两点间的直线距离	通用场景，幅度重要时
`<=>`	余弦距离	比较向量间的夹角	文本嵌入，方向比幅度重要
`<#>`	负内积	返回负内积以便升序排列	归一化向量，推荐系统
`<+>`	L1距离（曼哈顿距离）	计算各维度绝对差之和	罕见场景

向量数据的存储与操作

创建向量数据表

创建包含向量列的数据表时，需指定向量的维度：

-- 创建一个3维向量存储表
CREATE TABLE items (
    id BIGSERIAL PRIMARY KEY,
    embedding VECTOR(3) NOT NULL,
    description TEXT
);

-- 创建一个1536维向量表（适配 OpenAI text-embedding-3-small 模型）
CREATE TABLE documents (
    id BIGSERIAL PRIMARY KEY,
    content TEXT,
    embedding VECTOR(1536)
);

插入向量数据

向量数据以数组形式插入：

-- 插入3维向量
INSERT INTO items (embedding, description) VALUES
    ('[0.1, 0.2, 0.3]', '样本A'),
    ('[0.5, 0.1, 0.8]', '样本B'),
    ('[0.3, 0.4, 0.2]', '样本C');

-- 批量插入使用 COPY 可获得更好的性能
COPY items (embedding, description) FROM STDIN;

向量检索

精确最近邻搜索

精确搜索逐一比较所有向量与查询向量的距离：

-- 使用 L2 距离查找与目标向量最相似的项
SELECT id, description, embedding <-> '[0.2, 0.1, 0.3]' AS distance
FROM items
ORDER BY embedding <-> '[0.2, 0.1, 0.3]'
LIMIT 5;

-- 使用余弦距离（适用于文本嵌入）
SELECT id, content, 1 - (embedding <=> query_embedding) AS similarity
FROM documents
ORDER BY embedding <=> query_embedding
LIMIT 5;

向量索引与性能优化

对于大规模向量数据集，精确搜索的线性扫描成本过高。pgvector 提供了两种近似最近邻（ANN）索引来加速查询。

IVFFlat索引

IVFFlat（Inverted File with Flat Compression）通过聚类将向量空间划分为多个倒排列表，查询时仅搜索与目标向量最近的几个列表。

-- 创建 IVFFlat 索引（需在表中已有数据后创建）
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops)
WITH (lists = 100);

-- 余弦距离的 IVFFlat 索引
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 1000);

IVFFlat 关键参数：

lists：倒排列表数量，通常设置为 rows / 1000，取值范围 100~1000
probes：查询时探测的列表数量（通过 SET ivfflat.probes = 10 调整），值越大召回率越高但查询越慢

HNSW索引

HNSW（Hierarchical Navigable Small World）构建多层图结构，查询时在图结构中导航而非扫描全表，通常作为默认首选。

-- 创建 HNSW 索引
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)
WITH (m = 16, ef_construction = 64);

-- 余弦距离的 HNSW 索引
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

HNSW 关键参数：

m：每个节点的最大连接数，默认16，值越大召回率越高但索引更大
ef_construction：构建时动态候选列表大小，默认64，值越大索引质量越高但构建更慢
ef_search：查询时动态候选列表大小（通过 SET hnsw.ef_search = 100 调整）

索引类型对比

特性	IVFFlat	HNSW
构建速度	快	慢
查询速度	较快（probes调优后）	快
召回率	中高（取决于lists和probes）	高
内存占用	低	高（存储图结构）
适用场景	超大规模数据集（亿级）	中小规模（千万级），追求召回率

索引创建注意事项：

IVFFlat 索引必须在表中已存在数据后创建，否则效果不佳
HNSW 索引可随时创建，但构建时间较长
两种索引都支持并行创建（PostgreSQL 11+），可通过 CREATE INDEX CONCURRENTLY 避免阻塞写入

-- 并发创建索引（不阻塞读写）
CREATE INDEX CONCURRENTLY idx_items_embedding ON items USING ivfflat (embedding vector_l2_ops);

向量嵌入（Embedding）生成与集成

实际应用中，需先将非结构化数据转换为向量。常见做法是调用外部嵌入模型API或使用本地模型。

转换流程

与OpenAI Embeddings API集成示例（Node.js）

import OpenAI from 'openai';
import { Client } from 'pg';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const pgClient = new Client({ connectionString: process.env.DATABASE_URL });

async function generateEmbedding(text: string): Promise<number[]> {
    const response = await openai.embeddings.create({
        model: 'text-embedding-3-small',
        input: text,
    });
    return response.data[0].embedding;
}

async function storeDocument(content: string) {
    const embedding = await generateEmbedding(content);
    await pgClient.query(
        'INSERT INTO documents (content, embedding) VALUES ($1, $2)',
        [content, `[${embedding.join(',')}]`]
    );
}

async function searchSimilar(query: string, limit: number = 5) {
    const queryEmbedding = await generateEmbedding(query);
    const result = await pgClient.query(
        `SELECT content, 1 - (embedding <=> $1::vector) AS similarity
         FROM documents
         ORDER BY embedding <=> $1::vector
         LIMIT $2`,
        [`[${queryEmbedding.join(',')}]`, limit]
    );
    return result.rows;
}

API速览

本博客涉及的核心API主要包括 pgvector 扩展的SQL操作符和函数，以及与向量嵌入相关的Node.js库。

1. 向量类型构造函数

vector 类型支持从字符串或数组字面量构造：

-- 字符串构造
SELECT '[0.1, 0.2, 0.3]'::vector;

-- 数组构造（PostgreSQL 数组）
SELECT ARRAY[0.1, 0.2, 0.3]::vector;

2. 距离操作符

所有操作符返回浮点数，用于 ORDER BY 子句：

操作符	签名	返回类型	示例
`<->`	`vector <-> vector`	`float8`	`SELECT embedding <-> '[1,2,3]'`
`<=>`	`vector <=> vector`	`float8`	`SELECT embedding <=> '[1,2,3]'`
`<#>`	`vector <#> vector`	`float8`	`SELECT embedding <#> '[1,2,3]'`
`<+>`	`vector <+> vector`	`float8`	`SELECT embedding <+> '[1,2,3]'`

3. 辅助函数

vector_dims(vector)：返回向量的维度
vector_norm(vector)：返回向量的L2范数
l2_distance(vector, vector)：等同于 <->
cosine_distance(vector, vector)：等同于 <=>
inner_product(vector, vector)：返回内积

4. 索引访问方法操作符类

索引方法	操作符类	距离类型
`ivfflat` / `hnsw`	`vector_l2_ops`	L2距离
`ivfflat` / `hnsw`	`vector_cosine_ops`	余弦距离
`ivfflat` / `hnsw`	`vector_ip_ops`	内积（负内积）

Demo完整示例

本节提供一个完整的Node.js应用，演示如何使用 pg 驱动连接PostgreSQL，创建带有 vector 列的表，插入数据，并进行相似性搜索。

运行说明

环境准备：
- PostgreSQL 14+ 安装并启动
- 安装 pgvector 扩展（参考官方文档）
- Node.js 18+

项目初始化：

mkdir pgvector-demo && cd pgvector-demo
npm init -y
npm install pg dotenv

数据库配置（.env 文件）：

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

启动脚本：运行 node demo.js

代码说明

demo.js 文件完成以下操作：

连接数据库并启用 vector 扩展
删除并创建 embeddings 表
插入三条样本向量（3维）
执行精确L2距离搜索和余弦距离搜索
展示结果

// demo.js
import { Client } from 'pg';
import dotenv from 'dotenv';
dotenv.config();

const client = new Client({
    connectionString: process.env.DATABASE_URL,
});

async function run() {
    await client.connect();
    console.log('Connected to PostgreSQL');

    // 1. 启用扩展
    await client.query('CREATE EXTENSION IF NOT EXISTS vector');
    console.log('pgvector extension enabled');

    // 2. 创建表（如果存在则删除重建）
    await client.query('DROP TABLE IF EXISTS items');
    await client.query(`
        CREATE TABLE items (
            id SERIAL PRIMARY KEY,
            embedding VECTOR(3) NOT NULL,
            label TEXT
        )
    `);
    console.log('Table "items" created');

    // 3. 插入示例数据
    const samples = [
        { label: 'Dog', vec: [0.9, 0.1, 0.2] },
        { label: 'Cat', vec: [0.2, 0.8, 0.1] },
        { label: 'Bird', vec: [0.1, 0.2, 0.9] },
        { label: 'Fish', vec: [0.3, 0.3, 0.3] },
    ];
    for (const s of samples) {
        await client.query(
            'INSERT INTO items (embedding, label) VALUES ($1, $2)',
            [`[${s.vec.join(',')}]`, s.label]
        );
    }
    console.log(`Inserted ${samples.length} items`);

    // 4. 精确 L2 距离搜索（查询向量 [0.8, 0.2, 0.1]）
    const queryVec = [0.8, 0.2, 0.1];
    console.log('\n--- L2 Distance Search ---');
    const resL2 = await client.query(
        `SELECT label, embedding <-> $1::vector AS distance
         FROM items
         ORDER BY embedding <-> $1::vector
         LIMIT 3`,
        [`[${queryVec.join(',')}]`]
    );
    resL2.rows.forEach(row => {
        console.log(`Label: ${row.label}, Distance: ${row.distance.toFixed(4)}`);
    });

    // 5. 余弦距离搜索
    console.log('\n--- Cosine Distance Search ---');
    const resCos = await client.query(
        `SELECT label, embedding <=> $1::vector AS cosine_dist
         FROM items
         ORDER BY embedding <=> $1::vector
         LIMIT 3`,
        [`[${queryVec.join(',')}]`]
    );
    resCos.rows.forEach(row => {
        console.log(`Label: ${row.label}, Cosine Dist: ${row.cosine_dist.toFixed(4)}`);
    });

    await client.end();
}

run().catch(console.error);

输出示例：

Connected to PostgreSQL
pgvector extension enabled
Table "items" created
Inserted 4 items

--- L2 Distance Search ---
Label: Dog, Distance: 0.1414
Label: Fish, Distance: 0.5385
Label: Bird, Distance: 1.2166

--- Cosine Distance Search ---
Label: Dog, Cosine Dist: 0.0059
Label: Fish, Cosine Dist: 0.1667
Label: Bird, Cosine Dist: 0.4079

技术点总结

使用 pg 原生驱动执行SQL，直接操作 vector 类型
展示了 CREATE EXTENSION、建表、插入和查询的完整流程
对比了L2距离和余弦距离在相同查询下的不同结果，体现度量选择的影响
所有SQL均可直接在psql中运行，便于调试

多语言示例

基于前文 Node.js 版本的完整示例，本节提供 Go、Python 和 Java 三种语言的等价实现，涵盖数据库连接、pgvector 扩展启用、向量表创建、数据插入以及 L2 距离与余弦距离的相似性搜索。所有示例均使用各自语言的官方或主流 PostgreSQL 驱动，并保持相同的测试数据与查询逻辑，便于横向对比。

Go 语言示例

使用 pgx 驱动（支持 pgvector 原生类型）和 dotenv 加载配置。

// demo.go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "strings"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/joho/godotenv"
)

type Item struct {
    Label string
    Vec   []float32
}

func main() {
    // 加载 .env
    if err := godotenv.Load(); err != nil {
        log.Println("No .env file found")
    }

    ctx := context.Background()
    connStr := os.Getenv("DATABASE_URL")
    if connStr == "" {
        connStr = "postgres://user:password@localhost:5432/mydb"
    }

    pool, err := pgxpool.New(ctx, connStr)
    if err != nil {
        log.Fatal("Unable to connect:", err)
    }
    defer pool.Close()

    // 1. 启用扩展
    _, err = pool.Exec(ctx, "CREATE EXTENSION IF NOT EXISTS vector")
    if err != nil {
        log.Fatal("Create extension failed:", err)
    }
    fmt.Println("pgvector extension enabled")

    // 2. 创建表
    _, err = pool.Exec(ctx, "DROP TABLE IF EXISTS items")
    if err != nil {
        log.Fatal("Drop table failed:", err)
    }
    _, err = pool.Exec(ctx, `
        CREATE TABLE items (
            id SERIAL PRIMARY KEY,
            embedding VECTOR(3) NOT NULL,
            label TEXT
        )
    `)
    if err != nil {
        log.Fatal("Create table failed:", err)
    }
    fmt.Println("Table 'items' created")

    // 3. 插入数据
    samples := []Item{
        {Label: "Dog", Vec: []float32{0.9, 0.1, 0.2}},
        {Label: "Cat", Vec: []float32{0.2, 0.8, 0.1}},
        {Label: "Bird", Vec: []float32{0.1, 0.2, 0.9}},
        {Label: "Fish", Vec: []float32{0.3, 0.3, 0.3}},
    }
    for _, s := range samples {
        vecStr := fmt.Sprintf("[%v,%v,%v]", s.Vec[0], s.Vec[1], s.Vec[2])
        _, err = pool.Exec(ctx,
            "INSERT INTO items (embedding, label) VALUES ($1, $2)",
            vecStr, s.Label,
        )
        if err != nil {
            log.Fatal("Insert failed:", err)
        }
    }
    fmt.Printf("Inserted %d items\n", len(samples))

    // 4. L2 距离搜索
    queryVec := []float32{0.8, 0.2, 0.1}
    queryStr := fmt.Sprintf("[%v,%v,%v]", queryVec[0], queryVec[1], queryVec[2])
    rows, err := pool.Query(ctx, `
        SELECT label, embedding <-> $1::vector AS distance
        FROM items
        ORDER BY embedding <-> $1::vector
        LIMIT 3
    `, queryStr)
    if err != nil {
        log.Fatal("L2 query failed:", err)
    }
    defer rows.Close()

    fmt.Println("\n--- L2 Distance Search ---")
    for rows.Next() {
        var label string
        var dist float64
        if err := rows.Scan(&label, &dist); err != nil {
            log.Fatal("Scan failed:", err)
        }
        fmt.Printf("Label: %s, Distance: %.4f\n", label, dist)
    }

    // 5. 余弦距离搜索
    rows2, err := pool.Query(ctx, `
        SELECT label, embedding <=> $1::vector AS cosine_dist
        FROM items
        ORDER BY embedding <=> $1::vector
        LIMIT 3
    `, queryStr)
    if err != nil {
        log.Fatal("Cosine query failed:", err)
    }
    defer rows2.Close()

    fmt.Println("\n--- Cosine Distance Search ---")
    for rows2.Next() {
        var label string
        var dist float64
        if err := rows2.Scan(&label, &dist); err != nil {
            log.Fatal("Scan failed:", err)
        }
        fmt.Printf("Label: %s, Cosine Dist: %.4f\n", label, dist)
    }
}

运行说明：

依赖：github.com/jackc/pgx/v5 和 github.com/joho/godotenv
初始化：go mod init demo && go get github.com/jackc/pgx/v5 github.com/joho/godotenv
启动：go run demo.go

Python 语言示例

使用 psycopg2（或 psycopg 3）和 python-dotenv。

# demo.py
import os
import psycopg2
from psycopg2.extras import execute_values
from dotenv import load_dotenv

load_dotenv()

def main():
    conn_str = os.getenv("DATABASE_URL", "postgresql://user:password@localhost:5432/mydb")
    conn = psycopg2.connect(conn_str)
    conn.autocommit = True
    cur = conn.cursor()

    # 1. 启用扩展
    cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
    print("pgvector extension enabled")

    # 2. 创建表
    cur.execute("DROP TABLE IF EXISTS items")
    cur.execute("""
        CREATE TABLE items (
            id SERIAL PRIMARY KEY,
            embedding VECTOR(3) NOT NULL,
            label TEXT
        )
    """)
    print("Table 'items' created")

    # 3. 插入数据
    samples = [
        ("Dog", [0.9, 0.1, 0.2]),
        ("Cat", [0.2, 0.8, 0.1]),
        ("Bird", [0.1, 0.2, 0.9]),
        ("Fish", [0.3, 0.3, 0.3]),
    ]
    for label, vec in samples:
        cur.execute(
            "INSERT INTO items (embedding, label) VALUES (%s, %s)",
            (f"[{','.join(map(str, vec))}]", label)
        )
    print(f"Inserted {len(samples)} items")

    # 4. L2 距离搜索
    query_vec = [0.8, 0.2, 0.1]
    query_str = f"[{','.join(map(str, query_vec))}]"
    cur.execute("""
        SELECT label, embedding <-> %s::vector AS distance
        FROM items
        ORDER BY embedding <-> %s::vector
        LIMIT 3
    """, (query_str, query_str))
    print("\n--- L2 Distance Search ---")
    for label, dist in cur.fetchall():
        print(f"Label: {label}, Distance: {dist:.4f}")

    # 5. 余弦距离搜索
    cur.execute("""
        SELECT label, embedding <=> %s::vector AS cosine_dist
        FROM items
        ORDER BY embedding <=> %s::vector
        LIMIT 3
    """, (query_str, query_str))
    print("\n--- Cosine Distance Search ---")
    for label, dist in cur.fetchall():
        print(f"Label: {label}, Cosine Dist: {dist:.4f}")

    cur.close()
    conn.close()

if __name__ == "__main__":
    main()

运行说明：

依赖：psycopg2-binary 和 python-dotenv
安装：pip install psycopg2-binary python-dotenv
启动：python demo.py

Java 语言示例

使用 JDBC 驱动（org.postgresql:postgresql）和 dotenv-java。

// Demo.java
import java.sql.*;
import java.util.*;
import io.github.cdimascio.dotenv.Dotenv;

public class Demo {
    public static void main(String[] args) throws SQLException {
        Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
        String url = dotenv.get("DATABASE_URL", "jdbc:postgresql://localhost:5432/mydb?user=user&password=password");
        try (Connection conn = DriverManager.getConnection(url)) {
            // 1. 启用扩展
            try (Statement st = conn.createStatement()) {
                st.execute("CREATE EXTENSION IF NOT EXISTS vector");
                System.out.println("pgvector extension enabled");
            }

            // 2. 创建表
            try (Statement st = conn.createStatement()) {
                st.execute("DROP TABLE IF EXISTS items");
                st.execute("""
                    CREATE TABLE items (
                        id SERIAL PRIMARY KEY,
                        embedding VECTOR(3) NOT NULL,
                        label TEXT
                    )
                """);
                System.out.println("Table 'items' created");
            }

            // 3. 插入数据
            String[][] samples = {
                {"Dog", "[0.9,0.1,0.2]"},
                {"Cat", "[0.2,0.8,0.1]"},
                {"Bird", "[0.1,0.2,0.9]"},
                {"Fish", "[0.3,0.3,0.3]"}
            };
            try (PreparedStatement pst = conn.prepareStatement(
                    "INSERT INTO items (embedding, label) VALUES (?::vector, ?)")) {
                for (String[] s : samples) {
                    pst.setString(1, s[1]);
                    pst.setString(2, s[0]);
                    pst.addBatch();
                }
                pst.executeBatch();
                System.out.println("Inserted " + samples.length + " items");
            }

            String queryVec = "[0.8,0.2,0.1]";

            // 4. L2 距离搜索
            try (PreparedStatement pst = conn.prepareStatement("""
                    SELECT label, embedding <-> ?::vector AS distance
                    FROM items
                    ORDER BY embedding <-> ?::vector
                    LIMIT 3
                """)) {
                pst.setString(1, queryVec);
                pst.setString(2, queryVec);
                ResultSet rs = pst.executeQuery();
                System.out.println("\n--- L2 Distance Search ---");
                while (rs.next()) {
                    System.out.printf("Label: %s, Distance: %.4f%n",
                        rs.getString("label"), rs.getDouble("distance"));
                }
            }

            // 5. 余弦距离搜索
            try (PreparedStatement pst = conn.prepareStatement("""
                    SELECT label, embedding <=> ?::vector AS cosine_dist
                    FROM items
                    ORDER BY embedding <=> ?::vector
                    LIMIT 3
                """)) {
                pst.setString(1, queryVec);
                pst.setString(2, queryVec);
                ResultSet rs = pst.executeQuery();
                System.out.println("\n--- Cosine Distance Search ---");
                while (rs.next()) {
                    System.out.printf("Label: %s, Cosine Dist: %.4f%n",
                        rs.getString("label"), rs.getDouble("cosine_dist"));
                }
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

运行说明：

依赖（Maven）：

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.3</version>
</dependency>
<dependency>
    <groupId>io.github.cdimascio</groupId>
    <artifactId>dotenv-java</artifactId>
    <version>3.0.0</version>
</dependency>

编译：javac -cp ".:postgresql-42.7.3.jar:dotenv-java-3.0.0.jar" Demo.java
运行：java -cp ".:postgresql-42.7.3.jar:dotenv-java-3.0.0.jar" Demo

多语言对比

维度	Node.js (参考)	Go	Python	Java
驱动/库	`pg` (npm)	`pgx/v5`	`psycopg2`	`postgresql` JDBC
向量类型处理	字符串拼接，由pgvector解析	字符串拼接	字符串拼接	字符串拼接（支持 `?::vector` 强制转换）
连接管理	`Client` 对象	`pgxpool.Pool`	`connection` + 游标	`Connection` + `PreparedStatement`
批量插入	循环单条	循环单条（可改用 `COPY`）	循环单条（可改用 `execute_values`）	使用 `addBatch()` + `executeBatch()`
参数化查询	使用 `$1` 占位符	使用 `$1` 占位符	使用 `%s` 占位符（需手动构造）	使用 `?` 占位符
错误处理	`try-catch` 异步	`if err != nil`	`try-except`	`try-catch`
环境变量加载	`dotenv`	`godotenv`	`python-dotenv`	`dotenv-java`
输出格式	`console.log`	`fmt.Printf`	`print`	`System.out.printf`
适用版本	PostgreSQL 14+ / pgvector 0.5+	PostgreSQL 14+ / pgvector 0.5+	PostgreSQL 14+ / pgvector 0.5+	PostgreSQL 14+ / pgvector 0.5+
性能特点	异步非阻塞，适合高并发	高并发，连接池内置	同步阻塞，适合脚本/中小应用	同步阻塞，企业级连接池（需额外配置）

核心共通点：

所有语言均通过字符串拼接生成 vector 字面量（如 [0.1,0.2,0.3]），并依赖 pgvector 的隐式类型转换。
SQL 查询逻辑完全一致：使用 <-> 和 <=> 操作符，结合 ORDER BY 和 LIMIT 实现最近邻搜索。
索引创建、扩展启用等 DDL 语句在各类驱动中均以普通 SQL 执行，无特殊差异。

推荐实践：

对于生产级 Go 应用，建议使用 pgx 的 pgtype 自定义类型或 pgvector 官方提供的 Go 类型（github.com/pgvector/pgvector-go）来避免字符串拼接，提升类型安全。
Python 可使用 pgvector 官方 Python 包（pgvector）提供 SQLAlchemy 或直接使用 psycopg2 的适配器。
Java 可使用 pgvector 提供的 JDBC 类型映射或自定义 ParameterizedType。

项目难点与解决方案

核心难点

高维向量存储与索引构建的内存开销：向量维度通常达数百至数千，索引构建时需大量内存，可能导致OOM
查询精度与速度的权衡：近似索引（IVFFlat/HNSW）需调优参数，否则召回率不达标
与现有关系型数据模型的融合：向量列与传统业务字段（如标签、时间戳）混合查询时的优化

解决方案

内存控制：调整PostgreSQL的 work_mem 和 maintenance_work_mem，对索引构建使用 CREATE INDEX CONCURRENTLY 并设置 max_parallel_workers 限制并行度
参数调优：通过测试集评估不同 lists/probes（IVFFlat）或 m/ef_construction（HNSW）组合下的召回率，使用 pgvector 的 ivfflat.probes 和 hnsw.ef_search 会话级设置动态调整
混合查询：利用PostgreSQL的索引组合能力，为向量列建ANN索引，同时为标量列建B-tree索引，查询时使用 WHERE 先过滤再排序，或采用 ORDER BY embedding <-> query LIMIT 100 后二次过滤

广度

涉及数据库扩展开发、向量索引理论（聚类与图搜索）、嵌入模型集成、性能调优、混合查询优化等多个领域。

深度

深入探讨了 pgvector 的内部实现机制，包括 IVFFlat 的聚类算法、HNSW 的图遍历策略，以及距离度量对搜索结果的影响。

复杂度

向量数据管理涉及数据科学（嵌入生成）、数据库运维（索引调优）、应用开发（API集成）三方面的协同，对团队技术栈要求较高。

官方文档与参考链接

官方文档

参考链接

总结

本文从向量数据的基础概念出发，系统阐述了向量化表示（Embedding）如何将现实世界的事物映射到高维数学空间，并利用距离度量实现语义检索。在此基础上，深入介绍了PostgreSQL的 pgvector 扩展，涵盖其数据类型、距离算子、精确与近似检索的SQL实现，以及 IVFFlat 和 HNSW 两种索引的原理与调优方法。

通过完整的Node.js Demo，展示了从嵌入生成到数据库存储与查询的全链路工程实践。向量数据库作为AI应用的关键基础设施，pgvector 凭借PostgreSQL的生态优势和SQL标准的兼容性，为开发者提供了低成本、高可靠性的向量管理解决方案。

收录于