PostgresML 自托管完全指南：从 APT 安装到 GPU 加速与 pgvector 实战-平芜编程栈

后端
人工智能
机器学习
RAG
向量数据库

【免费下载链接】postgresml

Postgres with GPUs for ML/AI apps.

项目地址：https://gitcode.com/gh_mirrors/po/postgresml

PostgresML 本质上是 PostgreSQL 的一个扩展，因此自托管 PostgresML 与自托管一台 PostgreSQL 数据库服务器并无本质区别：你依然拥有主库、副本与连接池的经典拓扑，只是数据库内多出了一整套面向机器学习的 SQL 能力。本文将以 Ubuntu 22.04 为基线，带你走完从添加 APT 源、安装扩展、验证CREATE EXTENSION pgml，到为 LLM 与 XGBoost/LightGBM/Catboost 配置 CUDA 与 GPU 驱动，再到编译安装 pgvector 的完整自托管流程，并基于仓库内真实打包与配置实现，说明每个安装步骤背后的包结构与运行机制。

自托管架构：它就是一台 PostgreSQL，只是更"聪明"

PostgresML 不会改变你熟悉的 PostgreSQL 运维模型。官方自托管指南给出的典型架构是三层：

主库（Primary）：承担所有读写流量，也是所有机器学习训练、模型存储与在线预测的执行者；
可选副本（Replicas）：用于横向扩展读能力，把只读查询与预测压力从主库上分流；
连接池（Pooler）：在应用与数据库之间做连接负载均衡，避免大量短连接拖垮主库。

也就是说，你并不需要为"机器学习"额外搭建一套独立服务，模型训练与预测都作为 SQL 函数直接运行在数据库进程内。这一点从仓库的包结构上也能得到印证：真正的功能载体是postgresql-pgml这个 PostgreSQL 扩展包，其 Debian 控制文件（packages/postgresql-pgml/DEBIAN/control）将扩展描述为"用 Rust 基于 tcdi/pgrx 编写，并用 Python 与 PlPython 补充实现"的数据库内机器学习引擎，它可以直接对表或视图训练算法，也可以仅用 SQL 对新的数据点做预测。

操作系统选择：为什么是 Ubuntu 22.04

PostgresML 团队偏好 Ubuntu，理由是它拥有最广泛的硬件架构支持、软件包生态与驱动程序覆盖。官方指南的后续所有命令都假设你运行在Ubuntu 22.04（Jammy，当前 LTS 版本）上，但文档也明确指出：PostgresML 可以非常容易地在任何其他 Linux 发行版上运行。

如果查阅仓库中的打包脚本（packages/postgresml/release.sh），可以看到当前构建体系覆盖了多个 Ubuntu LTS 版本，代码名映射表包括：

Ubuntu 版本	代码名
20.04	focal
22.04	jammy
24.04	noble

这意味着即使你的宿主机版本与 22.04 略有差异，仓库也提供了面向多个 LTS 的构建路径；不过为了与本文及官方文档的命令完全一致，建议在 22.04 上操作。

通过 APT 安装 PostgresML：无需编译源码

自托管 PostgresML 最省力的方式是从官方 APT 仓库直接安装，无需额外安装依赖、更无需从源码编译。整个过程只有三步。

第一步：添加 APT 源

将官方仓库写入系统源列表：

echo "deb [trusted=yes] https://apt.postgresml.org jammy main" | \ sudo tee -a /etc/apt/sources.list

注意源声明中的[trusted=yes]：PostgresML 团队没有对 Debian 包做 GPG 签名，而是依赖 HTTPS 来保证二进制的真实性与完整性。

第二步：更新软件源

sudo apt update

第三步：安装主包

sudo apt install -y postgresml-14

关于包名中的14：Ubuntu 22.04 自带 PostgreSQL 14。如果你系统里安装的是其他 PostgreSQL 主版本，只需把包名中的14换成对应版本号。官方指南声明支持社区维护的所有版本，即Postgres 12 到 15。而从当前仓库的打包脚本（packages/postgresml/release.sh 中的for pg in {11..17}循环）可以看到，构建体系已进一步扩展到 PostgreSQL 11 至 17，你可以按自己系统实际安装的版本选择。

一个安装命令背后：元包与依赖链

postgresml-14并不是一个孤立的包，而是一个元包（meta package）。它的 Debian 控制文件（packages/postgresml/DEBIAN/control）揭示了完整依赖链：

Depends: postgresml-python (>= 2.7.13), postgresql-pgml-${PGVERSION} (>= ${PACKAGE_VERSION})

即安装postgresml-14会自动拉入两个组件：

postgresql-pgml-14：真正的 PostgreSQL 扩展本体。其控制文件（packages/postgresql-pgml/DEBIAN/control）显示它还依赖libopenblas-dev（BLAS 线性代数库）与postgresql-server-dev-${PGVERSION}等编译期/运行期组件。文档（packages/README.md）特别说明该扩展之所以独立分发，是因为它内含大量不依赖 Python的算法（即 Rust runtime），且部分系统习惯在虚拟环境之外管理 Python 依赖，官方不希望强制绑定。
postgresml-python：预构建的 Python 虚拟环境，包含 HuggingFace、PyTorch、Scikit-learn、XGBoost 等全部 Python 侧依赖。其控制文件（packages/postgresml-python/DEBIAN/control）描述它为"安装使用 PostgresML 所必需的 Python 依赖"。它体积庞大，因此独立分发——扩展的更新频率远高于 Python 依赖。

装完包后，postinst脚本（packages/postgresml/DEBIAN/postinst）会自动完成两项关键配置并重启 PostgreSQL：

ln -sf /etc/postgresml/postgresml.conf /etc/postgresql/${PGVERSION}/main/conf.d/01-postgresml.conf sudo service postgresql restart

被软链进 PostgreSQL 配置目录的 packages/postgresml/etc/postgresml/postgresml.conf 内容如下，这就是扩展能正常运行的核心配置：

shared_preload_libraries = 'pgml,pg_stat_statements' pgml.venv = '/var/lib/postgresml-python/pgml-venv'

shared_preload_libraries要求 PostgreSQL 在共享内存中预加载pgml（以及用于监控的pg_stat_statements），这是扩展必须被加载进预加载库的原因；
pgml.venv指向postgresml-python包安装的虚拟环境路径，扩展的 Python 运行时（HuggingFace 模型、Scikit-learn 算法等）都从这个 venv 加载。

如果你的场景不需要扩展附带的 Python 依赖、想自行管理 Python 环境，也可以只安装扩展本体：

sudo apt install -y postgresql-pgml-14

验证安装：创建扩展

安装完成后，以 postgres 系统用户连接数据库并创建扩展：

sudo -u postgres psql

在 psql 中执行：

postgres=# CREATE EXTENSION pgml; INFO: Python version: 3.10.6 (main, Nov 2 2022, 18:53:38) [GCC 11.3.0] INFO: Scikit-learn 1.1.3, XGBoost 1.7.1, LightGBM 3.3.3, NumPy 1.23.5 CREATE EXTENSION

创建成功时返回的CREATE EXTENSION信息表明扩展已注册进当前数据库。日志中的两行INFO会汇报 PostgreSQL 进程内 Python 解释器版本，以及已就绪的机器学习库版本——这说明 Python runtime 与各算法库已全部加载成功。

从扩展的控制文件（pgml-extension/pgml.control）可以看到它的元信息：trusted = true（普通用户也可创建）、schema = 'pgml'（对象统一放在pgmlschema 下）、superuser = true（仅超级用户可安装）。这也解释了为什么官方文档要求用postgres超级用户执行CREATE EXTENSION。

GPU 支持：为 LLM 与梯度提升库启用 CUDA

如果你手头有 NVIDIA GPU，希望用它加速 LLM 推理或 XGBoost/LightGBM/Catboost 的训练与预测，就需要安装 CUDA 与匹配的显卡驱动。

安装 CUDA

NVIDIA 官方提供了可直接加入系统的 APT 源，先下载并安装 keyring 包：

curl -LsSf \ https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.0-1_all.deb \ -o /tmp/cuda-keyring.deb sudo dpkg -i /tmp/cuda-keyring.deb sudo apt update sudo apt install -y cuda

注意 URL 中的ubuntu2204与x86_64要和你的系统版本、架构匹配。

验证 GPU 是否就绪

装完后用nvidia-smi检查显卡、驱动与 CUDA 是否协同工作：

$ nvidia-smi Fri Oct 6 09:38:19 2023 +---------------------------------------------------------------------------------------+ | NVIDIA-SMI 535.54.04 Driver Version: 536.23 CUDA Version: 12.2 | |-----------------------------------------+----------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | | | | MIG M. | |=========================================+======================+======================| | 0 NVIDIA GeForce RTX 3070 Ti On | 00000000:08:00.0 On | N/A | | 0% 41C P8 28W / 290W | 1268MiB / 8192MiB | 5% Default | | | | N/A | +---------------------------------------------------------------------------------------+

上方的Driver Version与CUDA Version是两套体系，必须彼此兼容。官方还给出一个常见提醒：首次安装 CUDA 时，经常需要重启系统后驱动与 CUDA 才能同时被正确检测到，因此nvidia-smi一时显示异常不必惊慌，先重启再验证。

作为参考，仓库的 Docker 构建文件（docker/Dockerfile）展示了团队自己使用的 GPU 基线组合：基于nvidia/cuda:12.6.3-devel-ubuntu24.04镜像，并安装了postgresml-python、postgresml-17与postgresml-dashboard——可以看到 CUDA devel 基础镜像 + APT 安装扩展正是官方认可的 GPU 部署路径之一。

pgvector：面向 CPU 指令集优化的向量扩展

pgvector 是 PostgresML 存储与检索 embedding 时使用的向量扩展，官方"很喜欢也经常使用它"。它的一个关键特性是针对机器的 CPU 架构做了优化（如利用 AVX-512 等向量化指令加速），因此最佳实践是直接在最终使用它的那台机器上从源码编译，而不是复用别处编译好的二进制。

安装编译依赖

pgvector 的依赖极少，只需标准构建链与 PostgreSQL 开发头文件：

sudo apt install -y \ build-essential \ postgresql-server-dev-14

同样，postgresql-server-dev-14中的14要替换为你实际的 PostgreSQL 版本。

从源码编译安装

git clone https://github.com/pgvector/pgvector /tmp/pgvector git -C /tmp/pgvector checkout v0.5.0 echo "trusted = true" >> "/tmp/pgvector/vector.control" make -C /tmp/pgvector sudo make install -C /tmp/pgvector

注意其中的echo "trusted = true" >> vector.control：追加trusted = true会让vector扩展成为可信扩展，普通（非超级）用户也能在自己的数据库中CREATE EXTENSION vector，不必每次都找管理员。

这一流程同样体现在仓库的 Dockerfile（docker/Dockerfile）与本地开发入口（docker/entrypoint.sh）中——entrypoint 在启动时会直接执行CREATE EXTENSION vector，说明在标准部署中，pgml与vector两个扩展是配套使用的最小集合。

在目标数据库中启用

编译安装完成后，在任何你想要使用向量能力的数据库中创建扩展：

postgresml=# CREATE EXTENSION vector; CREATE EXTENSION

成功返回CREATE EXTENSION后，vector类型、<->距离运算符等就绪，你便可以在 PostgreSQL 中存储 embedding 并做向量检索了。

从安装到运行：一条完整的自托管路径

把上面的步骤串起来，一台可运行的 PostgresML 自托管节点通常包含四件事：

PostgreSQL 主库：安装postgresql-14并承载扩展；
postgresql-pgml-14+postgresml-python（或元包postgresml-14）：提供机器学习能力，shared_preload_libraries预加载pgml，pgml.venv指向 Python 虚拟环境；
CUDA + 驱动（可选）：当需要 GPU 加速 LLM、XGBoost/LightGBM/Catboost 时安装，并用nvidia-smi验证兼容性；
pgvector（推荐）：从源码编译到目标机器，作为 embedding 存储与检索的基础。

如果你的节点还要承担只读扩展或连接负载均衡，再按本文开头的架构图追加副本与连接池即可。对于希望快速体验而非完整自托管的场景，也可以直接参考仓库中 Docker 化的部署方式（docker/entrypoint.sh），它以极少的步骤完成 PostgreSQL 启动、角色创建、vector与pgml扩展初始化，并顺带拉起管理面板，是理解"扩展如何被装进数据库"的最短路径。