5.7 pgvector 配置安装#
在前面章节关于 RAG 的实现中，我们已经采用了 Milvus 作为向量数据库，用于承载知识库文档的向量化存储与语义检索。而在本节中转向 pgvector，并不意味着前面的技术路线发生变化，而是因为当前讨论的重点已经从外部知识检索转向了 Agent 长期记忆管理，为了实现记忆的语义检索就必须进行向量化处理。
下面将围绕 pgvector 的基本作用、常用距离类型、安装过程以及数据库内启用方法进行系统介绍，帮助读者完成从安装到验证的完整配置过程。
5.7.1 pgvector 与 Milvus 区别#
Milvus 与 pgvector 的定位并不完全相同，Milvus 是专门面向大规模向量检索场景设计的向量数据库，更适合知识库召回、海量向量检索以及高吞吐的相似度搜索任务；而 pgvector 则仅仅是 PostgreSQL 的一个扩展模块，它在关系型数据库内部补充了向量字段、向量距离计算和向量索引能力，因此更适合那些既包含结构化字段、又需要附带向量检索能力的数据管理场景。
对于 LangGraph 的长期记忆而言，记忆内容本身并不只是单纯的向量数据。它通常既包含用户 ID、命名空间、时间戳、记忆类型等结构化字段，也包含需要进行语义检索的文本内容及其向量表示。因此，这类数据天然更接近附带向量检索能力的关系型记录，而不是纯粹的向量集合。更重要的是，在 LangGraph 当前的长期记忆持久化方案中，官方提供的数据库型实现主要是 PostgresStore。这意味着如果希望沿用框架已有的长期记忆存储抽象，那么基于 PostgreSQL 及其扩展 pgvector 来实现，通常会比继续引入 Milvus 更直接，也更方便与结构化记忆数据统一管理。
因此，pgvector 的目标并不是替代 RAG 场景下使用的 Milvus，而是为 LangGraph 的长期记忆检索能力提供一个更贴合框架实现方式、也更适合混合型记忆数据管理的底层存储方案。
5.7.2 pgvector 源码安装#
pgvector 本质上是 PostgreSQL 的本地扩展，因此在许多环境下需要先完成源码编译与安装，再进入数据库内部执行扩展创建命令。其基本流程如下。
（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.7.3 异常处理方式#
在源码安装过程中，一个较常见的问题是系统无法自动找到 pg_config。例如，编译时可能出现如下提示：
make: pg_config: Command not found
make: Nothing to be done for 'all'.pg_config 是 PostgreSQL 提供的一个工具，用于输出当前实例的头文件目录、库目录和扩展目录等构建信息。若系统中安装了多个 PostgreSQL 版本，或者 PostgreSQL 并未被加入环境变量，编译过程就可能无法自动定位正确的目标实例。
此时可以手动指定 pg_config 的路径：
make PG_CONFIG=/app/pgsql/bin/pg_config
make install PG_CONFIG=/app/pgsql/bin/pg_config需要注意的是，这里指定的 pg_config 必须与实际运行中的 PostgreSQL 实例保持一致，否则即便编译通过，也可能把扩展安装到错误的版本目录中，导致后续在数据库内部无法成功创建扩展。
5.7.4 启用 pgvector#
完成系统层面的安装后，pgvector 还没有自动在所有数据库中生效。PostgreSQL 的扩展机制要求开发者在具体数据库内部执行 CREATE EXTENSION，从而将扩展注册到当前数据库。
通常应先使用管理员账户登录 PostgreSQL：
psql -h 127.0.0.1 -p 5432 -U postgres随后切换到目标数据库，例如：
\c mypg连接成功后，在目标数据库中执行如下命令：
CREATE EXTENSION vector;如果是在服务器终端中操作，上述流程通常通过 psql 完成；如果是使用 DBeaver 等可视化工具登录管理员账户，也可以直接在对应数据库的 SQL 执行窗口中运行 CREATE EXTENSION vector;。
这里需要特别强调，CREATE EXTENSION vector; 是按数据库维度生效的。也就是说，即使操作系统层面已经完成 pgvector 安装，仍然需要在每一个实际使用向量能力的数据库中分别执行一次扩展创建命令。
5.7.5 安装结果验证#
在当前数据库中完成扩展启用后，可以通过查询系统表 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.7.6 pgvector 使用示例#
pgvector 是 PostgreSQL 的一个扩展模块。安装完成后，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 即可返回最相近的 5 条记录。
不过在后续内容中我们并不会单独使用 pgvector ，而是配合 LangGraph 一起使用，因此并不会涉及到上面这些底层操作，此处仅做介绍。
5.7.7 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在实际项目中，若词嵌入模型推荐使用余弦相似度，则数据库侧通常也应选择基于余弦距离的检索与索引配置，以保持召回行为与模型训练目标的一致性。
5.7.8 小结#
pgvector 为 PostgreSQL 提供了完整的向量存储与检索能力，使得开发者能够在保留关系型数据库生态的同时，完成 RAG 与长期记忆系统中常见的向量召回任务。它的安装过程可以分为两个层次：首先是在操作系统层面完成源码编译与扩展安装；其次是在具体数据库内部执行 CREATE EXTENSION vector; 使其真正生效。只有这两个步骤都完成以后，PostgreSQL 才能正式具备向量类型、距离计算以及向量索引能力。
对于已经采用 PostgreSQL 作为核心数据存储的项目而言，pgvector 提供了一条从传统关系型应用平滑过渡到向量检索应用的可行路径。在后续实践中，读者即可基于本节完成的安装结果，将向量数据写入数据库，并在应用层实现真正可用的语义检索能力。