第5节 pgvector 安装与配置#
在「上一节」内容中，我们通过本地 JSON 文件的形式实现了长期记忆的存储，不过它有一个弊端，那就是无法高效完成记忆的检索。因此，后续我们将基于 LangGraph 并借助 pgvector 来同时完成长期记忆的和短期记忆的存储。
在这之前，我们先通过本文来介绍如何完成 pgvector 的安装与配置。
5.1 从源码安装 pgvector#
PostgreSQL 是一种类似于 Mysql 的关系型数据库，不过由于其本身没有向量存储类型及距离运算逻辑，所以就必须给它加上一个扩展能力，而这个能力就来自于 pgvector 插件。而之所以我们选择 PostgreSQL 是因为 LangGraph 中对于记忆的持久化方式官方推荐的实现是 PostgresStore，这样既能够保存记忆的原内容还能够持久对应的向量化结果。
由于 pgvector 是 PostgreSQL 的本地扩展——所以在很多环境里，得先源码编译安装，再到数据库里 CREATE EXTENSION 启用，整个过程分为分为如下 4 步：
（1）下载源码
git clone https://github.com/pgvector/pgvector.git
cd pgvector（2）执行编译
make编译过程中会调用当前 PostgreSQL 实例对应的开发头文件与构建工具链。若编译成功，终端中通常会出现一系列 gcc 编译输出信息。
（3）执行安装
make install安装完成后，vector.so、vector.control 以及对应的 SQL 脚本会被复制到 PostgreSQL 的扩展目录中。例如，输出中通常会出现如下信息：
/usr/bin/install -c -m 755 vector.so '/app/pgsql/lib/vector.so'
/usr/bin/install -c -m 644 ./vector.control '/app/pgsql/share/extension/'这表明 pgvector 的动态库文件与扩展控制文件已经被安装到了目标 PostgreSQL 实例所使用的目录下。
5.2 pg_config 命令报错#
源码安装时最常见的报错是系统找不到 pg_config，长这样：
make: pg_config: Command not found
make: Nothing to be done for 'all'.pg_config 是 PostgreSQL 自带的小工具，专门用来告诉编译系统"当前这个 PG 实例的头文件在哪、库在哪、扩展该装哪"。如果机器上同时装了多个 PG 版本，或者 PG 没加进 PATH，编译就找不到正确的目标实例。
解决办法：手动指定 pg_config 的路径。
make PG_CONFIG=/app/pgsql/bin/pg_config
make install PG_CONFIG=/app/pgsql/bin/pg_config提醒：这里指定的 pg_config 必须跟实际跑着的 PG 实例是同一个版本，否则即使编译过了，也可能把扩展装到错误的版本目录里，后面到数据库里 CREATE EXTENSION 就会报"找不到"。
5.3 在数据库启用 pgvector 扩展#
在系统层面安装完 pgvector 以后还不会自动在所有数据库里生效，PostgreSQL 的扩展机制要求我们在每个具体数据库内部手动 CREATE EXTENSION，把扩展注册到当前库。
（1）先用管理员账户登录 PG。
psql -h 127.0.0.1 -p 5432 -U postgres（2）切到目标数据库。
\c mypg连上之后，在目标库里运行这一行：
CREATE EXTENSION vector;如果是在服务器终端中操作，上述流程通常通过 psql 完成；如果是使用 DBeaver 等可视化工具登录管理员账户，也可以直接在对应数据库的 SQL 执行窗口中运行 CREATE EXTENSION vector。
这里需要特别强调，CREATE EXTENSION vector; 是按数据库维度生效的。也就是说，即使操作系统层面已经完成 pgvector 安装，仍然需要在每一个实际使用向量能力的数据库中分别执行一次扩展创建命令。
5.4 验证 pg_extension 安装结果#
在当前库中执行完 CREATE EXTENSION 以后，可以去查系统表 pg_extension 就能验证有没有装上：
SELECT FROM pg_extension;若返回结果中出现类似如下记录：
oid | extname | extowner | extnamespace | extrelocatable | extversion
------+---------+----------+--------------+----------------+-----------
... | plpgsql | 10 | 11 | f | 1.0
... | vector | 10 | 2200 | t | 0.8.2说明当前数据库里 vector 扩展已经启用成功了。其中 extname = vector 的那一行，就是 pgvector 的安装结果。
验证通过以后，就可以开始建带 vector 字段的表、构建向量索引、做入库和相似度检索了。
5.5 快速上手：建表 + 查 Top-K#
pgvector 启用后，PostgreSQL 多了一个 vector 数据类型——可以理解为定长向量。比如某个文本向量模型输出 768 维 Embedding，建表就可以这么写：
CREATE TABLE documents (
id BIGINT PRIMARY KEY,
content TEXT,
embedding VECTOR(768)
);这里 VECTOR(768) 表示这一列存 768 维向量。应用把文本/图片/其他对象转成向量以后，直接写进 embedding 字段就行，后面就能拿来做相似度检索。
比如要从 docs 表里找跟查询向量最像的 5 条记录，SQL 长这样：
SELECT
FROM docs
ORDER BY embedding <-> '[0.1,0.2,0.3]'
LIMIT 5;这里的 <-> 是 L2 距离（欧氏距离）运算符——距离越小 = 越相似，配 LIMIT 5 直接拿到 Top-5。
不过在后续内容中我们并不会单独使用 pgvector ，而是配合 LangGraph 一起使用，因此并不会涉及到上面这些底层操作，此处仅做介绍。
5.6 pgvector 支持的距离类型#
向量检索的核心是“如何定义相似”。pgvector 提供了多种常见距离计算方式，开发者可以根据 Embedding 模型特性和业务场景进行选择。
（1）L2 Distance
L2 距离即欧氏距离，适用于直接衡量两个向量在几何空间中的直线距离：
embedding <-> query_vector（2）Inner Product
Inner Product 表示向量内积，常用于部分基于点积训练的向量模型：
embedding <#> query_vector（3）Cosine Distance
「Cosine Distance 表示余弦距离」，用于衡量两个向量方向上的相似程度，是 RAG 场景中最常见的选择：
embedding <=> query_vector在实际项目中，若词嵌入模型推荐使用余弦相似度，则数据库侧通常也应选择基于余弦距离的检索与索引配置，以保持召回行为与模型训练目标的一致性。
到此，对于 pgvector 的安装就介绍完了。
在下一节内容中，将会基于这一节装好的 pgvector，使用 PostgresStore 来完成 MiniChatGPT 的整个构建流程。