# https://github.com/postgresml/postgresml 项目说明书

生成时间：2026-07-07 14:57:59 UTC

## 目录

- [Overview and System Architecture](#page-1)
- [Core Extension: pgml-extension Internals](#page-2)
- [RAG Pipeline, Transformers & LLM Integration](#page-3)
- [Deployment, SDKs & Operations](#page-4)

<a id='page-1'></a>

## Overview and System Architecture

### 相关页面

相关主题：[Core Extension: pgml-extension Internals](#page-2), [RAG Pipeline, Transformers & LLM Integration](#page-3), [Deployment, SDKs & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/postgresml/postgresml/blob/main/README.md)
- [docker/Dockerfile](https://github.com/postgresml/postgresml/blob/main/docker/Dockerfile)
- [docker/entrypoint.sh](https://github.com/postgresml/postgresml/blob/main/docker/entrypoint.sh)
- [pgml-extension/Cargo.toml](https://github.com/postgresml/postgresml/blob/main/pgml-extension/Cargo.toml)
- [pgml-extension/build.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/build.rs)
- [pgml-dashboard/Cargo.toml](https://github.com/postgresml/postgresml/blob/main/pgml-dashboard/Cargo.toml)
</details>

# Overview and System Architecture

PostgresML 是一个将机器学习与 AI 推理能力直接嵌入 PostgreSQL 数据库的开源扩展。它通过 SQL 接口让用户能够训练、部署模型并执行推理，无需将数据迁出数据库或构建独立的服务栈，从而简化了 ML 工作流并消除了 ETL 过程中的数据泄露风险。

## 核心设计目标

PostgresML 的设计遵循"数据不动，模型动"的理念。模型训练、推理以及向量化（embedding）操作全部在数据库进程内完成，训练数据无需离开 PostgreSQL。

资料来源：[README.md:1-40]()

这种架构带来了几个关键优势：

- **数据安全性**：敏感数据不需要导出到外部系统即可完成 ML 处理
- **运维简化**：避免了维护独立 Python ML 服务栈的复杂性
- **性能优化**：通过 pgrx 将 Rust 扩展直接编译进 PostgreSQL，避免了跨进程通信开销
- **SQL 原生体验**：分析师和数据科学家可以在熟悉的 SQL 环境中完成全部工作

## 系统分层架构

PostgresML 整体由三个紧密耦合的子系统组成，它们共同部署在同一个容器或主机环境中。

### Rust 扩展层（pgml-extension）

这是系统的核心，使用 pgrx 框架将 Rust 代码编译为 PostgreSQL 共享库（`pgml.so`），由 PostgreSQL 后台进程加载。该扩展通过 SQL 函数暴露 ML 功能，包括模型训练、推理、转换器调用和向量化操作。

资料来源：[pgml-extension/Cargo.toml:1-30]()

资料来源：[pgml-extension/build.rs:1-50]()

扩展通过 `pgrx_pg_config` 工具链与 PostgreSQL 版本对齐。在 v2.10.0 版本中，pgrx 已升级到 0.12.6 以支持 PostgreSQL 17，社区正在跟进该迁移工作。

资料来源：[README.md:42-80]()

### Python 运行时与 ML 后端

扩展层在需要执行实际 ML 计算时，会通过嵌入式 Python 运行时调用 scikit-learn、XGBoost、LightGBM、CatBoost、PyTorch 以及 HuggingFace Transformers 等框架。Python 环境在容器构建阶段预装好，通过 Docker 镜像统一分发以避免本地依赖冲突。

资料来源：[docker/Dockerfile:1-60]()

### Web Dashboard（pgml-dashboard）

仪表盘是基于 Actix Web 框架构建的 Rust 应用，提供 SQL 笔记本、模型部署查看、查询计划等 Web UI。它与 PostgreSQL 通过标准 SQL 接口通信，自身不存储业务数据。

资料来源：[pgml-dashboard/Cargo.toml:1-30]()

## 部署与启动流程

官方推荐使用 Docker 镜像进行部署，镜像内同时打包了 PostgreSQL、pgml 扩展和 Dashboard。`entrypoint.sh` 负责初始化数据库、注册扩展并启动后台服务。

资料来源：[docker/entrypoint.sh:1-40]()

典型启动命令将主机端口映射到容器的 PostgreSQL 端口（5432）与 Dashboard 端口（8000）：

```bash
docker run -d --name postgresml \
  -p 5433:5432 \
  -p 8089:8000 \
  ghcr.io/postgresml/postgresml:latest
```

社区用户在端口冲突、Ubuntu 24.04 兼容性与 ROCm GPU 支持等场景中报告过问题，主要与基础镜像版本绑定相关，建议根据硬件平台选择匹配的镜像。

资料来源：[docker/Dockerfile:60-120]()

## 模块边界与数据流

下表总结了各层之间的通信方向与职责划分：

| 子系统 | 实现语言 | 主要职责 | 通信方式 |
|--------|----------|----------|----------|
| pgml-extension | Rust + pgrx | SQL 接口、模型元数据存储、调用 ML 后端 | PostgreSQL 共享库 |
| Python ML Runtime | Python | 模型训练、推理、向量化计算 | 进程内嵌入式调用 |
| pgml-dashboard | Rust + Actix | Web UI、SQL 笔记本、可视化 | 通过 SQL 连接 PostgreSQL |
| Docker Container | - | 一体化打包与依赖管理 | 容器内进程间协作 |

## 模型生命周期与社区关注点

完整的模型生命周期包括：训练（`pgml.train`）、部署（`pgml.deploy`）、推理（`pgml.predict`）与归档。社区目前关注两个改进方向：

1. **Export/Load API**：当前需要手动选择模型行完成跨库迁移，用户希望提供按名称导出的接口
2. **离线模式**：HF 模型下载在受限网络中失败，需要支持本地缓存与离线推理

资料来源：[README.md:80-140]()

此外，社区也报告了 CatBoost 推理路径的异常以及在没有已训练模型时仍可"部署"无效模型的边界缺陷，这些都与扩展的 SQL 入口校验逻辑相关。

资料来源：[docker/entrypoint.sh:40-80]()

## 小结

PostgresML 的系统架构将 PostgreSQL 的数据管理、Rust 扩展的高性能接口与 Python 生态的 ML 库紧密结合在一起，形成一个"一站式"的数据 + AI 平台。理解 `pgml-extension`、`pgml-dashboard` 与 Docker 容器三层之间的职责边界，是排查部署问题（例如端口冲突、依赖缺失）与扩展功能（例如模型生命周期管理）的基础。

---

<a id='page-2'></a>

## Core Extension: pgml-extension Internals

### 相关页面

相关主题：[Overview and System Architecture](#page-1), [RAG Pipeline, Transformers & LLM Integration](#page-3), [Deployment, SDKs & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pgml-extension/src/lib.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/lib.rs)
- [pgml-extension/src/api.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/api.rs)
- [pgml-extension/src/config.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/config.rs)
- [pgml-extension/src/metrics.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/metrics.rs)
- [pgml-extension/src/vectors.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/vectors.rs)
- [pgml-extension/src/orm/mod.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/orm/mod.rs)
</details>

# Core Extension: pgml-extension Internals

## 概述与定位

`pgml-extension` 是 PostgresML 的核心 PostgreSQL 扩展，使用 Rust 编写并基于 [pgrx](https://github.com/pgcentralfoundation/pgrx) 框架构建，把机器学习与 AI 推理能力直接嵌入到 PostgreSQL 数据库进程内。它与同仓库下的 Python 包 `pgml` 协同工作：Rust 侧负责 SQL 暴露、GIL 管理、PostgreSQL 内存管理；Python 侧承担实际的 scikit-learn、transformers、catboost、xgboost 等库的训练与推理。这种"双语言"架构避免了传统方案中将数据搬运到外部 Python 服务的序列化与网络开销。

扩展的主要职责包括：

- 通过 `pg_extern` 宏注册用户可调用的 SQL 函数（如 `pgml.train`、`pgml.predict`、`pgml.embed`）
- 启动时初始化嵌入式 Python 解释器，并加载 `pgml` Python 包
- 管理项目（project）、快照（snapshot）、部署（deployment）的完整生命周期
- 通过自定义复合类型与数组桥接 PostgreSQL 与 numpy/pandas 数据结构

`资料来源：[pgml-extension/src/lib.rs:1-50]()`

## 模块划分与入口

`pgml-extension/src/` 目录按职责进行划分：`lib.rs` 是入口与 `pg_module_magic!` 注册点；`api.rs` 把底层的 ORM 调用包装为面向 SQL 用户的高级接口；`config.rs` 处理超参数 JSONB 的反序列化；`metrics.rs` 负责分类/回归评估指标；`vectors.rs` 实现向量嵌入与相似度运算；`orm/mod.rs` 是数据库对象的强类型映射层。

Rust 函数通过 `#[pg_extern]` 宏暴露给 SQL 调用方，参数与返回值由 pgrx 自动转换为 PostgreSQL 类型系统。例如 `pgml.train` 接收项目名、任务名、超参数 JSON 等，并在内部组装为 `orm::Project` 实体。

`资料来源：[pgml-extension/src/lib.rs:50-120](), [pgml-extension/src/api.rs:1-60]()`

## Python ↔ Rust ↔ SQL 数据流

扩展的核心运行模式是 "SQL 触发 → Rust 编排 → Python GIL 内执行 → 回写 PostgreSQL"。典型训练流程的数据走向如下：

```mermaid
flowchart LR
  SQL[SQL: pgml.train] --> Rust[Rust pg_extern 入口]
  Rust --> ORM[orm/mod.rs 实体]
  ORM --> Cfg[config.rs 超参数]
  ORM --> GIL[Python::with_gil]
  GIL --> Sk[sklearn/transformers]
  Sk --> GIL
  GIL --> Met[metrics.rs 评估]
  Met --> ORM
  ORM --> DB[(pgml.snapshots)]
  DB --> Rust
  Rust --> SQL[返回结果行]
```

训练产生的结果（指标、模型二进制、状态）通过 `pg_largeobject` 存储在数据库内部，部署阶段再读取并加载到内存中用于推理。这一设计使模型完全"伴随数据"，但也对 Rust/Python 边界的内存与错误传递提出了较高要求。

`资料来源：[pgml-extension/src/api.rs:30-90](), [pgml-extension/src/orm/mod.rs:1-100]()`

## 向量、指标与配置

### 向量运算（vectors.rs）

提供 PostgreSQL 数组与 numpy `ndarray` 之间的低开销转换，支撑 `pgml.embed` 与 `pgml.vector_distance` 等函数，是 RAG 与相似度检索场景的基础。社区曾反馈在受限网络下访问 Hugging Face 失败（issue #1682、#625），向量子系统的离线缓存能力因此成为关注点。

`资料来源：[pgml-extension/src/vectors.rs:1-80]()`

### 评估指标（metrics.rs）

封装 accuracy、f1、R²、logloss 等分类与回归常用指标。Rust 侧把真实标签与预测结果转换为 Python `dict`，调用 scikit-learn 的 `metrics` 模块，再把结果回填到 `pgml.models.metrics` JSONB 字段。

`资料来源：[pgml-extension/src/metrics.rs:1-60]()`

### 配置（config.rs）

负责解析 `pgml.train(...)` 调用中传入的 JSONB 超参数。配置在 `config.rs` 中被反序列化为强类型 Rust 结构体，再下发至 Python 训练脚本；超参数缺失或类型不匹配时返回明确的 PostgreSQL 错误。

`资料来源：[pgml-extension/src/config.rs:1-70]()`

## ORM 与已知限制

`orm/mod.rs` 定义了与 `pgml.projects`、`pgml.snapshots`、`pgml.deployments` 三张核心表一一对应的 Rust 结构体，所有 SQL 操作都通过该 ORM 层进行，避免散落的 `SPI_*` 调用带来的脆弱性。模型快照包含训练超参数、评估指标、模型二进制（通过 `pg_largeobject` 存储）以及与项目、部署的多对多关系。

社区曾报告在异常路径下可以"部署"一个并不存在的快照（issue #628），这正是 ORM 状态校验需要加强的典型案例。其他与扩展内部强相关的社区痛点还包括：

- **平台构建**：扩展依赖 Rust 与 C++ 工具链，在 Windows 上无 Docker/WSL 时构建困难（issue #1697）。
- **架构错包**：v2.10 的 amd64 `.deb` 包曾内嵌 ARM 二进制（issue #1674）。
- **导出/加载**：希望在 ORM 层补充 Export & Load API，便于跨库迁移模型（issue #1686）。
- **PostgreSQL 17 支持**：社区推动升级至 pgrx 0.12.6 以兼容 PG 17（issue #1640）。

`资料来源：[pgml-extension/src/orm/mod.rs:1-100](), [pgml-extension/src/lib.rs:1-30]()`

## 小结

`pgml-extension` 是 PostgresML 整个系统的运行时基座：以 Rust + pgrx 在 PostgreSQL 进程内暴露 ML 能力，以嵌入式 Python 承担实际训练/推理，以 ORM 层管理模型生命周期。理解 `lib.rs → api.rs → orm → Python GIL` 这条主链路，是排查训练失败、推理异常、模型不可用等问题的关键切入点。

---

<a id='page-3'></a>

## RAG Pipeline, Transformers & LLM Integration

### 相关页面

相关主题：[Core Extension: pgml-extension Internals](#page-2), [Deployment, SDKs & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pgml-extension/src/bindings/transformers/mod.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/bindings/transformers/mod.rs)
- [pgml-extension/src/bindings/transformers/transform.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/bindings/transformers/transform.rs)
- [pgml-extension/src/bindings/transformers/whitelist.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/bindings/transformers/whitelist.rs)
- [pgml-extension/src/bindings/transformers/transformers.py](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/bindings/transformers/transformers.py)
- [pgml-extension/src/bindings/langchain/mod.rs](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/bindings/langchain/mod.rs)
- [pgml-extension/src/bindings/langchain/langchain.py](https://github.com/postgresml/postgresml/blob/main/pgml-extension/src/bindings/langchain/langchain.py)
</details>

# RAG Pipeline、Transformers 与 LLM 集成

PostgresML 通过 `pgml-extension` 子模块，把 HuggingFace Transformers 与 LangChain 嵌入到 PostgreSQL 内部，使数据库既能完成传统机器学习任务，也能支撑检索增强生成（RAG）与大语言模型推理。整套体系以 Rust 调用 Python 解释器为核心，将深度学习模型作为 SQL 函数暴露给用户。

## 体系结构总览

Transformers 与 LangChain 的绑定都遵循同一套 pgrx + Python 子解释器模式。Rust 端通过 `pyo3` 创建隔离的 Python 子解释器，加载预编译的 Python 包并调用其中的函数，再把结果以 PostgreSQL 数据类型（数组、`jsonb`、自定义复合类型等）返回。

| 模块 | 职责 | 关键文件 |
| --- | --- | --- |
| Transformers 绑定 | 文本转换、嵌入生成、微调 | `bindings/transformers/mod.rs`、`transform.rs`、`transformers.py` |
| LangChain 绑定 | RAG 链路、LLM 编排、检索问答 | `bindings/langchain/mod.rs`、`langchain.py` |
| 模型白名单 | 控制可加载的 HuggingFace 模型与任务 | `bindings/transformers/whitelist.rs` |

Rust 端的 `mod.rs` 负责初始化 Python 子解释器并向 PostgreSQL 注册 SQL 函数（如 `pgml.transform`、`pgml.embed`、`pgml.chat` 等），Python 端的同名模块则承担真正的模型加载与推理逻辑。资料来源：[pgml-extension/src/bindings/transformers/mod.rs:1-120]()、资料来源：[pgml-extension/src/bindings/langchain/mod.rs:1-120]()。

## Transformers 绑定：转换、嵌入与微调

`transformers.py` 是整个生态的“重型模块”，社区已经提出需要将其拆分为 `transform.py`、`embed.py`、`finetune.py` 等独立文件以便独立迭代（参考 Issue #1378 “Refactor transformers.py file”）。从源码目录可以看出该模块至少承担三类任务：

- **文本转换（Transform）**：封装 `transformers.pipeline`，覆盖翻译、摘要、问答、文本分类、命名实体识别等任务。`transform.rs` 把输入文本包装为 Python 列表，调用对应管线后把预测结果序列化回 PostgreSQL。资料来源：[pgml-extension/src/bindings/transformers/transform.rs:1-80]()。
- **嵌入生成（Embed）**：使用 `transformers` 的 `AutoModel` + `AutoTokenizer` 输出稠密向量，并结合 PostgreSQL 的 `pgvector`/`vchord` 扩展实现相似度检索，这是 RAG 的检索侧基础。资料来源：[pgml-extension/src/bindings/transformers/transformers.py:1-160]()。
- **任务型 LLM 调用**：以 `transformers.pipeline("text-generation", ...)` 或 `text2text-generation` 形式提供聊天/补全能力，作为 LangChain 调用 LLM 时的本地后端。

`whitelist.rs` 通过静态枚举限制可调用的模型与任务组合，避免用户随意加载未经验证的大模型导致资源耗尽。资料来源：[pgml-extension/src/bindings/transformers/whitelist.rs:1-80]()。社区中关于 HuggingFace 离线模式（Issue #625）和网络受限地区访问 `huggingface.co`（Issue #1682）的讨论，提示该模块的初始化流程需要支持本地缓存与镜像替换。

## LangChain 绑定：RAG 编排入口

LangChain 子模块是 PostgresML 官方推荐的 RAG 入口。`langchain.py` 实现典型的“检索 → 提示词组装 → LLM 生成”三段式：

1. **检索**：调用 `pgml.embed` 把用户问题转为向量，然后通过 SQL 中的向量相似度算子从已建立索引的文档表中取出 Top-K 片段。
2. **提示词组装**：把检索结果与用户问题拼接为 LangChain 的 `PromptTemplate` 或 `ChatPromptTemplate`。
3. **生成**：调用本地 Transformers 管线或远程 LLM API，得到回答后回写到数据库。资料来源：[pgml-extension/src/bindings/langchain/langchain.py:1-160]()。

Rust 端的 `mod.rs` 把上述流程封装为 SQL 接口，例如 `pgml.rag(...)`，允许用户在单条 SQL 中完成端到端的检索增强问答；同时它也负责初始化 LangChain 使用的 Python 环境，并保证与 Transformers 子解释器互不干扰。资料来源：[pgml-extension/src/bindings/langchain/mod.rs:1-160]()。

## 数据流与典型调用链

下面以一次 RAG 查询为例，说明从 SQL 进入到 Python 模型再到结果返回的完整路径：

```mermaid
flowchart LR
    A[客户端 SQL] --> B[Rust pgml.rag / pgml.embed]
    B --> C[Python 子解释器]
    C --> D[transformers.py 加载模型]
    D --> E[向量检索 pgvector]
    E --> F[langchain.py 拼装 Prompt]
    F --> G[LLM 推理生成回答]
    G --> H[jsonb / text 返回客户端]
```

## 运维与社区关注点

- **离线与镜像**：在受限网络环境下，需要把 HuggingFace 缓存目录挂载进容器并通过 `/etc/hosts` 指向镜像（参考 Issue #1682）。Rust 端的 Transformers 初始化应当支持 `TRANSFORMERS_OFFLINE=1` 和 `HF_ENDPOINT` 变量。
- **模型生命周期**：社区已提出希望补齐“模型导出/导入”API（Issue #1686），未来 `transformers.py` 中的 `load` / `save` 流程有望通过 SQL 直接暴露。
- **重构与拆分**：由于 `transformers.py` 同时承担转换、嵌入与微调逻辑，#1378 提议拆分文件，使 RAG 相关的代码更聚焦于嵌入与生成。
- **平台兼容性**：在 Windows 原生（非 WSL/Docker）构建仍受限（Issue #1697），推荐使用官方 Docker 镜像以获得一致的 Transformers 与 LangChain 运行时。

---

<a id='page-4'></a>

## Deployment, SDKs & Operations

### 相关页面

相关主题：[Overview and System Architecture](#page-1), [Core Extension: pgml-extension Internals](#page-2), [RAG Pipeline, Transformers & LLM Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docker/Dockerfile](https://github.com/postgresml/postgresml/blob/main/docker/Dockerfile)
- [docker/entrypoint.sh](https://github.com/postgresml/postgresml/blob/main/docker/entrypoint.sh)
- [docker/dashboard.sh](https://github.com/postgresml/postgresml/blob/main/docker/dashboard.sh)
- [docker/local_dev.conf](https://github.com/postgresml/postgresml/blob/main/docker/local_dev.conf)
- [docker/pg_hba.conf](https://github.com/postgresml/postgresml/blob/main/docker/pg_hba.conf)
- [packages/README.md](https://github.com/postgresml/postgresml/blob/main/packages/README.md)
- [README.md](https://github.com/postgresml/postgresml/blob/main/README.md)
</details>

# Deployment, SDKs & Operations

PostgresML 提供多层次的部署形态：以 Docker 镜像为主的容器化交付、以 `.deb` 为代表的系统级包安装，以及通过 SQL 接口直接与 PostgreSQL 集成的客户端 SDK。本页汇总仓库中与发布、运维和 SDK 调用相关的源码与配置，并结合社区中反馈的常见问题说明各路径的边界。

## Docker 部署

Docker 是社区最常用的部署方式。镜像通过 `docker/Dockerfile` 构建，最终暴露 PostgreSQL 端口（默认 5432）和 Dashboard 端口（默认 8000）。`docker/entrypoint.sh` 在容器启动时调用 `pg_ctl` 启动数据库，并按需初始化 `pgml` 扩展；`docker/dashboard.sh` 负责在后台拉起基于 Rust 的管理面板进程。`docker/local_dev.conf` 与 `docker/pg_hba.conf` 分别配置 PostgreSQL 的运行时参数与客户端认证策略，容器外的客户端通过 5432/8000 端口访问。

```bash
docker run -d --name postgresml --restart always \
  -v postgresml_data:/var/lib/postgresql \
  -p 5433:5432 \
  -p 8089:8000 \
  ghcr.io/postgresml/postgresml:2.10.0
```

资料来源：[docker/Dockerfile]()、[docker/entrypoint.sh]()、[docker/dashboard.sh]()。

社区反馈显示：Docker 端口冲突（如 #1392 中 5432 被宿主机占用）、Ubuntu 24.04 上的镜像兼容性（#1680）、以及 `huggingface.co` 在受限网络下的拉取失败（#1682）是最常见的三类问题。前者可通过端口映射规避；后两者通常需要更换镜像或通过 `/etc/hosts` 重定向 DNS。

## 系统包与本地编译

除 Docker 外，仓库提供面向 Ubuntu/Debian 的 `.deb` 包，安装路径详见 `packages/README.md`。包结构将 `pgml.so` 扩展放入 PostgreSQL 的 `lib` 目录，使 DBA 可以像普通扩展那样 `CREATE EXTENSION pgml;` 加载。社区问题 #1674 反映出 2.10 amd64 包曾错误打包了 ARM 架构的二进制，验证步骤建议使用 `dpkg -I` 和 `file` 检查包内容与目标架构是否一致。

源码级编译依赖 Rust 工具链与 `pgrx`，`README.md` 顶层给出 `cargo build --release` 形式的说明。社区 #1697 指出 Windows（无 WSL/Docker）构建路径仍未官方支持，目前推荐使用 Ubuntu/macOS 或 Docker 方案。

资料来源：[packages/README.md]()、[README.md]()。

## SDK 接入与 SQL API

PostgresML 没有传统意义上的独立 SDK——模型训练、推理、部署全部以 SQL 函数形式暴露（参见 `pgml.transform`、`pgml.train`、`pgml.predict`、`pgml.deploy`）。客户端可以是任何支持 PostgreSQL 协议的工具：`psql`、Python `psycopg`、Node.js `pg`、JDBC 等。这种"以 SQL 为 SDK"的设计意味着 SDK 的发布节奏与 `pgml` 扩展版本一致，部署包中已包含相应函数签名。

资料来源：[docker/local_dev.conf]()（说明 `shared_preload_libraries = 'pgml'` 加载机制）、[README.md]()。

## 运维与生命周期管理

| 运维主题 | 关键点 | 相关源码/Issue |
|---|---|---|
| 扩展加载 | `shared_preload_libraries` 需包含 `pgml` | `docker/local_dev.conf` |
| 客户端认证 | 容器内默认信任本地连接 | `docker/pg_hba.conf` |
| 模型部署 | `pgml.deploy` 写入 `pgml.deployed_models` | Issue #628（无效模型可被部署） |
| 模型迁移 | Issue #1686 提议导出/加载 API | 暂无原生支持 |
| HuggingFace 离线 | 需预先缓存或镜像 | Issue #625、#1682 |
| 仪表盘 | `dashboard.sh` 守护 Rust 进程 | `docker/dashboard.sh` |

资料来源：[docker/pg_hba.conf]()、[docker/local_dev.conf]()。

运维层面有若干已记录的限制需提前规划：

1. **网站/云控制台下线**：由于项目运营方进入解散流程，`postgresml.org` 自 #1684 起不可用，#1690 显示云环境注册入口也已失效；文档需从仓库内 `pgml-cms/docs` 与 `pgml-cms/blog` 本地访问（#1695）。
2. **Windows 原生支持**：当前无官方 Windows 构建路径，推荐 Docker/WSL（#1697）。
3. **模型生命周期**：仓库暂未提供跨数据库的"导出—加载"API，迁移模型需要直接操作 `pgml.models` 与 `pgml.deployed_models` 表行（#1686）。
4. **离线/受限网络**：HuggingFace 模型缓存默认位于容器内，可通过环境变量或 DNS 重写解决受限网络问题（#625、#1682）。

```mermaid
flowchart LR
  A[客户端 psql/psycopg/JDBC] --> B[PostgreSQL :5432]
  B --> C[pgml 扩展 pgml.so]
  C --> D[(pgml.models / pgml.deployed_models)]
  D --> E[Python 运行时 transformers/scikit-learn]
  C --> F[Dashboard :8000 Rust UI]
```

资料来源：[docker/Dockerfile]()、[docker/entrypoint.sh]()、[docker/dashboard.sh]()。

## 小结

- 部署首选 Docker 镜像；`.deb` 包适合与既有 PostgreSQL 集群融合。
- SDK 实际即 SQL API，无需额外客户端库，安装 PostgreSQL 驱动即可。
- 运维中需重点关注扩展加载、模型部署有效性校验以及离线环境下的 HuggingFace 缓存策略。
- 当前官方云服务与外部文档站已不可用，应以仓库内源码与本地文档为准。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：postgresml/postgresml

摘要：发现 19 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Invalid pgml.so binary for version 2.10 amd64 .deb package。

## 1. 安装坑 · 来源证据：Invalid pgml.so binary for version 2.10 amd64 .deb package

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Invalid pgml.so binary for version 2.10 amd64 .deb package
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1674 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Issues with Docker container on port 5432

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Issues with Docker container on port 5432
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1392 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：Performing embedding inference as part of an UPDATE crashes the server within the docker container with an "illegal ins…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Performing embedding inference as part of an UPDATE crashes the server within the docker container with an "illegal instruction"
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1515 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Working docker image for latest release for ubuntu 24

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Working docker image for latest release for ubuntu 24
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1680 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 来源证据：Invalid model can be "deployed", if there is no prior trained model for a project

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Invalid model can be "deployed", if there is no prior trained model for a project
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/628 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 运行坑 · 来源证据：Add model Export & Load as part of the full model lifecycle

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Add model Export & Load as part of the full model lifecycle
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1686 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 安全/权限坑 · 安装或运行可能执行高权限 shell

- 严重度：high
- 证据强度：source_linked
- 发现：项目文本出现 postinstall/sudo/curl pipe/shell 等关键词。
- 对用户的影响：用户本机文件、凭证或环境可能受影响，需要先隔离验证。
- 证据：packet_text.keyword_scan | https://github.com/postgresml/postgresml | matched postinstall / sudo / curl pipe / shell keyword

## 8. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -it -v postgresml_data:/var/lib/postgresql -p 5433:5432 -p 8000:8000 ghcr.io/postgresml/postgresml:2.10.0 sudo -u postgresml psql -d postgresml
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -it -v postgresml_data:/var/lib/postgresql -p 5433:5432 -p 8000:8000 ghcr.io/postgresml/postgresml:2.10.0 sudo -u postgresml psql -d postgresml`
- 证据：identity.distribution | https://github.com/postgresml/postgresml | docker run -it -v postgresml_data:/var/lib/postgresql -p 5433:5432 -p 8000:8000 ghcr.io/postgresml/postgresml:2.10.0 sudo -u postgresml psql -d postgresml

## 9. 安装坑 · 来源证据：Best way to install postgresML on windows

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Best way to install postgresML on windows
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1697 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 10. 安装坑 · 来源证据：OSError: We couldn't connect to 'https://huggingface.co'

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OSError: We couldn't connect to 'https://huggingface.co'
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1682 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 11. 安装坑 · 来源证据：Unable to make predictions using catboost model with either classification or regression

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unable to make predictions using catboost model with either classification or regression
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1681 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 12. 安装坑 · 来源证据：postgresml.org website origin DNS error

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：postgresml.org website origin DNS error
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1684 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 13. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/postgresml/postgresml | README/documentation is current enough for a first validation pass.

## 14. 运行坑 · 来源证据：https://postgresml.org is down

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：https://postgresml.org is down
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/postgresml/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。

## 15. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/postgresml/postgresml | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/postgresml/postgresml | no_demo; severity=medium

## 17. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/postgresml/postgresml | no_demo; severity=medium

## 18. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/postgresml/postgresml | issue_or_pr_quality=unknown

## 19. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/postgresml/postgresml | release_recency=unknown

<!-- canonical_name: postgresml/postgresml; human_manual_source: deepwiki_human_wiki -->