# PostgreSQL 扩展与特性

> 版本: v1.0  
> 更新日期: 2026-02-27  
> 维护说明: 新增扩展或变更配置时更新此文档

---

## 1. 扩展总览

| 扩展 | 版本 | 用途 | 安装方式 | 依赖模块 |
|------|------|------|---------|---------|
| **pgvector** (vector) | 0.8.1 | 向量存储与相似度检索 | Docker 镜像内置 | EKB, IIT, SSA |
| **pg_bigm** | 1.2 | 中文/日文双字节全文检索 | Docker 镜像内置 | EKB |
| **plpgsql** | 1.0 | PostgreSQL 过程语言 | 系统内置 | 全局 |

---

## 2. pgvector — 向量搜索

### 2.1 基本信息

- **Docker 镜像**: `pgvector/pgvector:pg15`（本地开发基础镜像）
- **用途**: 存储文本 embedding 向量，支持语义相似度检索
- **算法**: 支持 L2 距离、内积、余弦相似度

### 2.2 使用表

| Schema | 表 | 列 | 维度 | 模型 | 用途 |
|--------|-----|-----|------|------|------|
| `ekb_schema` | `ekb_chunk` | `embedding` | 1024 | 通义千问 Embedding | 企业知识库 RAG 检索 |
| `iit_schema` | `conversation_history` | `embedding` | 1536 | OpenAI ada-002 | IIT 对话历史语义搜索 |
| `ssa_schema` | `ssa_tools_library` | `embedding` | 1024 | 通义千问 Embedding | SSA 工具语义匹配 |

### 2.3 Prisma 中的声明方式

pgvector 在 Prisma 中通过 `Unsupported` 类型声明：

```prisma
embedding  Unsupported("vector(1024)")?
```

> ⚠️ 已知限制：Prisma diff 引擎无法正确比较 `Unsupported` 类型，每次 diff 会产生假变更。详见 `03-技术债务追踪.md` TD-004。

### 2.4 索引建议

对于高频检索的向量列，建议创建 HNSW 索引：

```sql
CREATE INDEX idx_ekb_chunk_embedding ON ekb_schema.ekb_chunk
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
```

当前状态：暂未创建向量索引，数据量较小时顺序扫描即可满足性能要求。

---

## 3. pg_bigm — 中文全文检索

### 3.1 基本信息

- **用途**: 基于双字节 gram 的模糊搜索，特别适合中文、日文
- **优势**: 无需分词器，开箱即用，支持 LIKE '%关键词%' 加速

### 3.2 使用场景

| Schema | 表 | 列 | 用途 |
|--------|-----|-----|------|
| `ekb_schema` | `ekb_chunk` | `content` | 知识库文本块的关键词搜索 |

### 3.3 索引创建示例

```sql
CREATE INDEX idx_ekb_chunk_content_bigm ON ekb_schema.ekb_chunk
  USING gin (content gin_bigm_ops);
```

> 详细安装指南见 `docs/02-通用能力层/03-RAG引擎/06-pg_bigm安装指南.md`

---

## 4. pg-boss — PostgreSQL 原生任务队列

### 4.1 基本信息

- **类型**: Node.js 库（非 PostgreSQL 扩展），利用 PostgreSQL 实现任务队列
- **表位置**: `platform_schema` 下的 5 张表（job, job_common, queue, schedule, subscription）
- **用途**: 异步任务处理，替代 Redis + BullMQ

### 4.2 核心特性

| 特性 | 说明 |
|------|------|
| 延迟任务 | 支持定时执行 |
| 重试机制 | 失败自动重试，支持配置重试次数和退避策略 |
| 优先级 | 支持任务优先级 |
| 死信队列 | 超过重试次数的任务进入死信队列 |
| 定时调度 | 通过 schedule 表支持 cron 表达式 |

### 4.3 使用模块

| 模块 | 用途 |
|------|------|
| ASL | 文献筛选批处理、全文提取分发 |
| PKB | 文档批处理任务 |
| IIT | 定时质控任务（cron） |

> 详细运维指南见 `docs/07-运维文档/01-PgBoss队列监控与维护.md`  
> 架构设计见 `docs/02-通用能力层/Postgres-Only异步任务处理指南.md`

---

## 5. Docker 镜像配置

### 5.1 本地开发 (docker-compose.yml)

```yaml
services:
  postgres:
    image: pgvector/pgvector:pg15      # 内含 pgvector 扩展
    container_name: ai-clinical-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres123
      POSTGRES_DB: ai_clinical_research
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
```

> pg_bigm 需在 Docker 构建时额外安装，见项目根目录的 Docker 配置。

### 5.2 阿里云 RDS

- **实例类型**: RDS PostgreSQL 15 基础版
- **扩展管理**: 通过 RDS 控制台 → 插件管理启用
- **已启用**: pgvector, pg_bigm

---

## 6. 更新日志

| 日期 | 操作人 | 变更 |
|------|--------|------|
| 2026-02-27 | AI 助手 | 初始化文档，记录 3 个扩展 + pg-boss 特性 |