pyPS4Controller源码包安装与PS4手柄事件编程实战
2026/9/16 3:45:27
这两天在弄一个 RAG 知识库项目，文档切片之后的 embedding 向量得有个地方存，还要支持按相似度召回。我最终把方案定在了 pgvector 扩展上——直接装在现有的 PostgreSQL 里，省掉一套独立的向量数据库服务。安装过程说难不难，但我连续踩了版本匹配、编译环境、扩展目录几个坑，每次报错都得翻半天资料。下面把完整流程、我踩过的坑、以及装完之后的参数调优一起写清楚，给想在自己环境里装 pgvector 扩展的朋友做个参考。
1. 先想明白：为什么服务里已经有数据库，还要装 pgvector 这个扩展
1.1 pgvector 补的是 PostgreSQL 缺失的那块能力
传统关系型数据库擅长精确查询：等于、大于、LIKE、JOIN，返回的是“完全匹配”的结果。但 AI 应用里的语义搜索是另一码事——你问“怎么修空调”，库里存的可能是“空调不制冷处理办法”，字面上一个都对不上，语义上却很接近。这种场景要把文本、图片转成一组浮点数（也就是 embedding 向量），然后按向量的距离排序，找出最相近的几条记录。
PostgreSQL 原生不支持向量类型，也没有距离计算函数和向量索引。pgvector 扩展干的就是这件事：它新增了一个 vector 数据类型，提供了 L2 欧氏距离、内积、余弦距离三类距离算子，还实现了 IVFFlat 和 HNSW 两种近似最近邻索引。装完这个扩展，PostgreSQL 就等于原生多了一种“按语义相似度检索”的能力，SQL 里一条 ORDER BY distance 就能召回最相似的向量。
1.2 跟 faiss、Milvus 比，pgvector 赢在“少一个组件”
很多人在调研的时候会拿 pgvector 和 faiss、Milvus 对比。faiss 是 Meta 开源的向量检索库，性能极强，但它本身只是库，不负责存储和持久化，你得自己维护索引文件的加载、落盘和容灾；Milvus 是完整的向量数据库，功能全但也是一套独立服务，意味着要多部署、多监控、多学一套运维知识。
pgvector 的定位是“把向量能力塞进现有 PostgreSQL”：如果你们的业务本来就在用 PostgreSQL，数据、事务、权限、备份体系都是现成的，安装 pgvector 扩展之后向量数据可以直接跟业务表放在同一个事务里，不需要额外同步，不需要额外的数据管道。它牺牲了一些极端性能上限，但换来了极低的架构复杂度。对于中小项目、RAG 原型、公司内部知识库这些场景，pgvector 通常是性价比最高的选择。
我个人对选型的建议是：数据量在千万行以内、对召回延迟要求不是极端苛刻的，优先考虑 pgvector；真到了亿级向量、需要分布式横向扩展的时候，再上独立的向量数据库也不迟。项目初期就为了“未来可能很大”而引入一套新基础设施，往往得不偿失。
2. 安装前先确认三件事：PG 版本、编译工具链、扩展目录
2.1 PostgreSQL 大版本决定可用的 pgvector 版本
第一个坑就是版本。pgvector 不是纯 SQL 扩展，它包含 C 编译的 .so 动态库，编译时必须匹配 PostgreSQL 的 server 版本。用错版本最典型的表现是 CREATE EXTENSION 时报错或者加载库失败。
具体来说：pgvector 0.7.x 要求 PostgreSQL 13 及以上，如果你还在跑 PG 12 或更老，就得用 0.6.x 或更早的版本。而且同一个大版本内部的兼容性也在变，比如 HNSW 索引是 0.5.0 引入的，halfvec（半精度向量，最多支持 16000 维）和 sparsevec（稀疏向量）是 0.7.0 加入的。想用这些功能，扩展版本就不能太老。
建议你先在数据库里执行SELECT version();确认 PostgreSQL 的实际大版本，再去 GitHub 的 release 页面选对应的 pgvector 版本。别直接用 git clone 默认分支的代码，那个可能依赖最新的 PostgreSQL 特性，跟线上版本不一定兼容。
2.2 pg_config 是整套安装的“指路牌”
编译 pgvector 的核心工具是 pg_config。它告诉你 PostgreSQL 的头文件在哪里、动态库装到哪里、SQL 脚本装到哪里。make install 做的事，本质上就是按 pg_config 输出拷贝文件。
所以第一个排查点就是：你机器上有几个 pg_config，它指向哪个 PostgreSQL 版本。很多开发机同时装了 PG 14、PG 16，PATH 里默认的那个 pg_config 可能不是你正在用的服务器版本。如果不一致，编译出来的 vector.so 装到了另一个版本的目录里，你的目标库自然创建不了扩展。
验证方法很简单：
which pg_config pg_config --version pg_config --sharedir pg_config --pkglibdir如果发现指向不对，就在编译时显式指定路径，例如 PG 16 的配置：
make PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config或者干脆把对应版本的 bin 目录加到 PATH 最前面。这个问题极其隐蔽，我那次出问题就是机器上残留了 PG 14 的 dev 包，导致编译产物全部装到了 PG 14 的目录，而服务跑的是 PG 16，两边完全对不上。
2.3 编译依赖和权限别忽略
源码编译还需要 gcc、make，以及 PostgreSQL 的开发头文件。Debian/Ubuntu 系是 postgresql-server-dev-XX 包，这个包名里的 XX 必须和数据库大版本一致，装错版本一样会出问题。
Debian/Ubuntu 上先装依赖：
sudo apt update sudo apt install build-essential postgresql-server-dev-16CentOS/RHEL/Fedora 系是 postgresql16-devel 或者 postgresql-devel，按你用的 PostgreSQL 版本仓库来。
最后是权限。make install 会把扩展文件写到 PostgreSQL 安装目录，通常是 /usr/lib/postgresql/16/lib 和 /usr/share/postgresql/16/extension，这些目录归 root 所有。普通用户执行 make install 会报 Permission denied。第一次装的时候我没加 sudo，卡了半天，正确姿势是 sudo make install，或者先给当前用户授权目录写权限。
3. 源码编译安装全流程：从下载到 CREATE EXTENSION
3.1 下载源码：建议直接 checkout 一个 release 版本
去 GitHub 的 pgvector/pgvector 仓库，release 页面有打包好的 v0.7.4、v0.8.0 等。用 git clone 拉下来之后记得切换 tag：
git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git cd pgvector为什么推荐固定版本而不是用 master？master 分支通常对 PostgreSQL 最高版本做适配，如果你用的是 PG 14 或者 15，master 上的代码接口可能已经变了，编译反而容易出问题。固定版本意味着你在任何机器上都能复现同样的结果。
3.2 编译安装：make 和 make install
源码目录下依次执行：
make sudo make installmake 这一步会调用 pg_config 去定位头文件，如果之前提到的 pg_config 版本不对，或者缺少 postgresql-server-dev，最常见的报错是：
fatal error: postgres.h: No such file or directory这个错误的意思就是找不到 PostgreSQL 的头文件。对照 2.2 和 2.3 检查 pg_config 路径和开发包是否齐全。
make install 成功后，正常情况下会输出类似下面的信息：
/bin/mkdir -p '/usr/lib/postgresql/16/lib' /bin/mkdir -p '/usr/share/postgresql/16/extension' /usr/bin/install -c -m 755 vector.so '/usr/lib/postgresql/16/lib/vector.so' /usr/bin/install -c -m 644 vector.control '/usr/share/postgresql/16/extension/' /usr/bin/install -c -m 644 vector--0.7.4.sql '/usr/share/postgresql/16/extension/'看到 vector.so 被安装到 pkglibdir、vector.control 和 vector--*.sql 被安装到 extension 目录，说明安装成功。这两个路径是后面排查报错的核心——CREATE EXTENSION 做的事情，就是读取 extension 目录下的 .control 文件，然后执行对应的 .sql 脚本，真正干活的代码则加载 lib 目录里的 vector.so。
3.3 CREATE EXTENSION 之后才算真正装上
编译安装只是把文件放到了 PostgreSQL 能找到的位置，要让某个数据库使用 pgvector，还需要连接那个库执行：
CREATE EXTENSION vector;注意 pgvector 是 per-database 的扩展。你在 app 数据库里创建了扩展，admin 库里默认是没有的，需要哪个库用就进哪个库执行一次。CREATE EXTENSION 这个动作本身只需要一次，后续的表、索引都可以直接使用 vector 类型。
执行成功后会输出 CREATE EXTENSION，此时你可以用 \dx 查看已安装的扩展列表，应该能看到 vector 以及它的版本号。这一步如果报extension "vector" is not available，多半是 .control 文件没装对位置，或者执行用户不是超级用户——CREATE EXTENSION 需要数据库超级用户权限。
4. 不想编译的人有两条捷径：Docker 镜像和系统包管理器
4.1 Docker：官方镜像已经把扩展编译好了
如果你的 PostgreSQL 跑在容器里，或者你根本不想碰编译，最省事的方式是用 pgvector 官方发布的 Docker 镜像。镜像名是 pgvector/pgvector，标签风格是 pgvector/pgvector:0.7.4-pg16，或者直接用 pgvector/pgvector:pg16 跟随最新版本。
docker run --name pgvector-demo \ -e POSTGRES_PASSWORD=yourpassword \ -p 5432:5432 \ -d pgvector/pgvector:pg16镜像基于 postgres 官方镜像，pgvector 扩展已经预编译并安装好了，你只需要连进去执行 CREATE EXTENSION vector 就能用。自己写 Dockerfile 时也可以直接基于这个镜像：
FROM pgvector/pgvector:pg16不用再在 Dockerfile 里装 gcc、拉源码、make install，镜像体积更小，构建也更快。
如果是已有项目，不想换基础镜像，也可以在自己的 Dockerfile 里临时编译：
FROM postgres:16 RUN apt-get update \ && apt-get install -y --no-install-recommends git build-essential postgresql-server-dev-16 \ && git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git \ && cd pgvector && make && make install \ && rm -rf /var/lib/apt/lists/* /pgvector这个思路跟源码编译完全一样，只是把环境封装进了镜像。注意把 build-essential 这些编译工具留在镜像里会增大体积，有洁癖的话可以用多阶段构建，编译完只复制结果文件。
4.2 apt/dnf：一条命令，但要留意软件源
某些系统发行版把 pgvector 打成了系统包。Debian/Ubuntu 上，如果配置了 PostgreSQL 官方的 APT 仓库（PGDG），可以直接：
sudo apt install postgresql-16-pgvectorFedora/CentOS 这边，如果用的是 PostgreSQL 官方 RPM 仓库，Fedora 上是：
sudo dnf install pgvector_16包管理器方案的优点是安装快、不用管编译细节；缺点是版本跟随发行版的节奏，可能比 GitHub 上的 release 滞后，而且包名里的 16 和你的 PG 版本必须对上。另外，包管理器安装的扩展在云数据库、托管实例上是装不了的——云厂商一般不允许你动系统库，这种情况只能看厂商是否原生支持 pgvector。
4.3 三种方式怎么选
| 安装方式 | 适合场景 | 优点 | 缺点 |
|---|---|---|---|
| 源码编译 | 自建 PostgreSQL、追求最新版本 | 版本可控、可定制编译参数 | 需要编译工具链，容易踩版本坑 |
| Docker 镜像 | PostgreSQL 跑在容器里 | 开箱即用、环境隔离 | 需要容器环境，依赖官方镜像发布节奏 |
| 系统包管理器 | 用 apt/dnf 管理数据库的 Linux 服务器 | 安装最快、升级方便 | 版本可能滞后，需要正确配置软件源 |
5. 安装成功不等于能跑：验证 SQL 和典型报错排查
5.1 五条 SQL 验证扩展可用性
装完之后建议按顺序跑一遍下面的 SQL，确认每个环节都是通的。我习惯用一个临时表做冒烟测试：
-- 1. 创建扩展 CREATE EXTENSION IF NOT EXISTS vector; -- 2. 确认版本 SELECT extversion FROM pg_extension WHERE extname = 'vector'; -- 3. 建一张带 vector 列的临时表 CREATE TABLE vec_smoke (id bigserial PRIMARY KEY, embedding vector(3)); -- 4. 插入向量数据 INSERT INTO vec_smoke (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[0,0,1]'); -- 5. 按 L2 距离排序，找出离 [1,2,3] 最近的向量 SELECT id, embedding, embedding <-> '[1,2,3]' AS distance FROM vec_smoke ORDER BY embedding <-> '[1,2,3]';第 5 条 SQL 如果返回三行数据、距离从 0 开始递增，说明类型、距离算子、排序逻辑都正常。到这里，pgvector 的安装才算真正闭环。
5.2 我遇到过的典型报错和排查链路
把安装过程中几个高频报错和排查顺序整理出来，按表里的顺序去查基本都能解决。
| 报错信息 | 根本原因 | 排查顺序 |
|---|---|---|
| make: pg_config: command not found | 缺少 PostgreSQL 开发包 | 先装 postgresql-server-dev-XX，确保 pg_config 在 PATH 里 |
| fatal error: postgres.h: No such file or directory | 头文件缺失或 pg_config 指向错误版本 | which pg_config、pg_config --version，对照数据库实际版本 |
| Permission denied（make install 时） | 安装目录需要 root 权限 | 使用 sudo make install |
| ERROR: could not open extension control file | vector.control 没装到 server 实际读取的 extension 目录 | 检查 make install 输出，确认目录与 pg_config --sharedir 一致 |
| ERROR: extension "vector" is not available | 扩展文件不完整或当前用户权限不足 | 确认 vector.control 存在，用超级用户执行 CREATE EXTENSION |
| ERROR: could not load library ".../vector.so" | .so 与 PG 版本不匹配或编译环境不一致 | 用目标版本的 pg_config 重新 make clean && make && make install |
这里多说一句排查的思路：所有报错都先回到“我到底是给哪个 PostgreSQL 装的”这个问题。很多时候不是步骤错了，而是多个 PostgreSQL 版本共存导致文件装到了别的地方。遇到诡异报错，先执行 SELECT version(); 确认服务端真实版本，再对照 pg_config --version，两个版本不一致，后面全白搭。
6. 装好只是开始：HNSW 索引和参数调优的实际体会
6.1 HNSW 还是 IVFFlat：看数据量和使用阶段
pgvector 提供两种索引算法。IVFFlat 的思路是先把向量空间聚类成 N 个列表（lists），查询时根据 probes 参数只扫描其中几个列表，把全量扫描变成局部扫描。它的问题是索引构建时需要一定数量的数据来做聚类训练，如果建索引时表是空的，之后再插入海量数据，聚类中心不会自动更新，检索精度会明显下降。
HNSW 是图结构索引，构建时每个向量会在多层图上跟相邻节点建立连接，查询时从顶层逐层逼近。它不需要训练，建索引时表是空也没问题，后续插入的数据会实时维护图结构，召回率和延迟表现在大多数场景下都优于 IVFFlat。
我的建议是：数据量不大、或者还在快速迭代阶段，直接用 HNSW，省心；数据量已经非常大、对构建时间敏感，可以试 IVFFlat，但一定要在数据基本稳定之后再建索引、之后再考虑调 lists 和 probes。
建索引的 SQL 长这样：
-- HNSW 索引 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops); -- 或者按余弦距离建索引 CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops); -- IVFFlat 索引 CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);opclass 有 vector_l2_ops、vector_ip_ops、vector_cosine_ops 三种，对应距离算子 <->、<#>、<=>。查询用的算子类型和索引 opclass 必须一致，否则用不上索引。
6.2 ef_search、probes、maintenance_work_mem：真正影响效果的是这几个参数
HNSW 相关的有两个核心参数：hnsw.ef_search 控制查询时搜索的候选节点数量，值越大召回越准、延迟越高；hnsw.ef_construction 控制建索引时的图构建质量，这个只能在建索引前通过 SET 指定，建完索引再改无效。IVFFlat 对应的参数是 ivfflat.probes，控制查询时扫描多少个聚类列表。
这些参数是会话级的，可以在查询前设置：
SET hnsw.ef_search = 100; SET ivfflat.probes = 10;另外一个容易被忽略的是 maintenance_work_mem。HNSW 和 IVFFlat 建索引都需要占用内存，默认值在小机器上只有 64MB，对几千万元素的表建索引会非常慢甚至直接失败。我一般在建大索引前先调大：
SET maintenance_work_mem = '2GB';注意这个参数和 work_mem 的角色不同：work_mem 影响查询排序和哈希操作，建索引吃的是 maintenance_work_mem，两者别调反了。
6.3 关于 shared_preload_libraries，我特意做了次对比实验
网上不少文章会提到把 vector 加进 shared_preload_libraries，我一开始也照着做了，为此还重启了一次 PostgreSQL。后来我做了对比测试：在完全不配置 shared_preload_libraries 的情况下，vector 类型的读写、HNSW 建的索引、距离查询、以及会话级的 ef_search 设置都正常工作。也就是说，对这个扩展的基础使用场景，shared_preload_libraries 不是必选项。
它可能出现的地方是一些高级特性和特定发行版的集成说明里。我个人的做法是：先用最简单的方式跑通，确认真有需要再改配置并重启；不要一开始就把所有文章提到的配置都加上，出问题都分不清是谁的锅。
6.4 一点实测的体感
最后说下我本地跑过的对比：一万条 384 维向量，HNSW 索引下，hnsw.ef_search 从 20 调到 100，单条查询的延迟大概会从毫秒级涨到几十毫秒级，但召回率的提升幅度并没有想象中那么明显，尤其在数据本身区分度比较高的时候。ef_search 调参的体感就像查地图时你愿意多翻几页精细地图，翻得越多越精确，但每页都有成本。对于线上服务，建议先用小的 ef_search 跑，用真实 query 集合测召回率，不够再往上加。
如果你也是第一次在自己机器上装 pgvector 扩展，我最后想强调的还是那句话：先把版本对齐这件事刻在脑子里——数据库大版本、开发包版本、pg_config 指向、扩展 release 版本，四者对齐，安装过程基本上就成功了一半。装完之后别急着建索引，先用小表把类型和距离算子跑通，再上真实数据，这样后面无论是调优还是排查，都会轻松很多。