# pgvector 向量表与 DuckDB 临时数据源
**本文引用的文件**
- [knowledge_base.sql](file://sql/knowledge_base.sql)
- [chat_attachment.sql](file://sql/chat_attachment.sql)
- [ai_clean.sql](file://sql/ai_clean.sql)
- [application.yaml](file://ai-server/src/main/resources/application.yaml)
- [KnowledgeVectorMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java)
- [AttachmentVectorMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java)
- [RagVectorMapper.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java)
- [AiCleanTemplateVectorIndex.java](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java)
- [RagSchemaService.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/rag/RagSchemaService.java)
- [OnnxEmbeddingEngine.java](file://ai-server/src/main/java/com/zsjz/ai/module/embedding/core/OnnxEmbeddingEngine.java)
- [AiDuckDb.java](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/exec/AiDuckDb.java)
- [DuckdbSnapshot.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java)
- [CaseDataSourceRegistry.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java)
- [CaseDataSourceReaper.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java)
## 目录
1. [引言](#引言)
2. [项目结构中的数据库边界](#项目结构中的数据库边界)
3. [核心数据源与使用场景](#核心数据源与使用场景)
4. [pgvector 向量表设计](#pgvector-向量表设计)
5. [DuckDB 临时数据源设计](#duckdb-临时数据源设计)
6. [两种数据源对比](#两种数据源对比)
7. [向量检索参数与索引策略](#向量检索参数与索引策略)
8. [生命周期、清理与备份恢复](#生命周期清理与备份恢复)
9. [性能调优建议](#性能调优建议)
10. [常见问题排查](#常见问题排查)
11. [结论](#结论)
## 引言
本项目存在两类职责完全不同的持久化层:
- **PostgreSQL + pgvector**:用于存储需要长期保留的向量嵌入,包括 Agent RAG、知识库相似检索和意图识别相关的模板语义索引。
- **DuckDB 单文件数据库**:作为每个案件的本地临时数据源,承载清洗中间表、分析结果、非表格文件的 AI 识别档案等短期或过程数据。
文档目标不是把所有业务表都写出来,而是聚焦“哪些数据进入 pgvector”“哪些数据留在 DuckDB”,以及两者在类型、索引、生命周期和运维上的差异。
## 项目结构中的数据库边界
从脚本和实现看,持久化数据主要落在 PostgreSQL;向量能力依赖 pgvector 扩展;案件级临时计算和数据清洗走 DuckDB JDBC。
```mermaid
graph TB
PG["PostgreSQL
主库"] --> KB["知识库元数据
knowledge_base / knowledge_doc"]
PG --> ATT_META["附件元数据
chat_attachment"]
PG --> TPL_META["模板元数据
ai_clean_template / ai_clean_field"]
PG --> PLAT["平台与治理表
table_info / table_field 等"]
PG --> KB_VEC["知识库向量表
kb_vec_{kbId}{tag}_d{dims}"]
PG --> ATT_VEC["附件向量表
chat_att_vec_{caseId}_d{dims}"]
PG --> SCHEMA_VEC["统一表结构向量表
rag_tpl{tag}_d{dims}"]
DUCK["DuckDB 单文件库
每案一个 .ddb"] --> CASE_TABLES["案件动态表
ai_clean_* 生成表"]
DUCK --> FILE_AI_PROFILE["非表格文件 AI 识别档案
file_ai_profile"]
APP["AI Server 应用"] --> PG
APP --> DUCK
```
**图表来源**
- [knowledge_base.sql:1-70](file://sql/knowledge_base.sql#L1-L70)
- [chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39)
- [ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214)
- [ApplicationConfig: application.yaml](file://ai-server/src/main/resources/application.yaml)
**章节来源**
- [knowledge_base.sql:1-70](file://sql/knowledge_base.sql#L1-L70)
- [chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39)
- [ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214)
## 核心数据源与使用场景
### PostgreSQL + pgvector
PG 在本项目中承担三类任务:
1. **知识库与附件的业务元数据**:记录文档归属、路径、字符数、块数、状态、下载日志等。
2. **模板元数据**:既有 `table_info` / `table_field` 和 AI 侧 `ai_clean_template` / `ai_clean_field`。
3. **向量嵌入**:通过 pgvector 的 `vector(n)` 列存储文本、模板、表结构的嵌入向量,并执行余弦相似度检索。
向量写入由 Java Mapper 直接拼接动态表名,并通过 `::vector` 类型转换把 Java 端生成的字面量字符串传给 PostgreSQL。
**章节来源**
- [KnowledgeVectorMapper.java:1-64](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L1-L64)
- [AttachmentVectorMapper.java:1-60](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L1-L60)
- [RagVectorMapper.java:1-113](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java#L1-L113)
### DuckDB 临时数据源
DuckDB 在本项目中是**每案一库**的嵌入式分析引擎,而不是共享事务型数据库。它的主要用途包括:
- 按 AI 清洗模板动态建表并批量写入清洗结果。
- 流式读取 Excel、CSV 等大文件。
- 保存非表格文件的 AI 识别档案 `file_ai_profile`。
- 为 Python 子进程提供只读快照副本,避免多进程争用同一 DuckDB 文件锁。
DuckDB 连接通过 `org.duckdb.DuckDBDriver` 以 JDBC 方式打开,并由 `CaseDataSourceRegistry` 按案件注册到动态数据源路由中。
**章节来源**
- [AiDuckDb.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/exec/AiDuckDb.java#L1-L200)
- [CaseDataSourceRegistry.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L1-L200)
- [DuckdbSnapshot.java:1-144](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java#L1-L144)
## pgvector 向量表设计
### 向量表命名约定
代码中存在三组不同的向量表命名模式:
| 向量用途 | 物理表名模式 | 隔离维度 | 说明 |
|---|---|---|---|
| 知识库文档 RAG | `kb_vec_{kbId}{tag}_d{dims}` | 知识库 ID + 模型标签 + 维度 | 每个知识库一张向量表,检索时再强制过滤 `payload->>'kbId'` |
| 附件大文档 RAG | `chat_att_vec_{caseId}_d{dims}` | 案件 ID + 维度 | 同案件不同会话之间靠 payload 中的 `sessionId` 隔离 |
| 统一表结构语义索引 | `rag_tpl{tag}_d{dims}` | 模型标签 + 维度 | 全局一张表,同时服务 Agent 选表和 AI 模板匹配召回 |
其中 `{tag}` 来自当前使用的嵌入模型标签(例如本地 bge-m3),`{dims}` 是配置声明的向量维度,默认值为 1024。
**章节来源**
- [knowledge_base.sql:14-20](file://sql/knowledge_base.sql#L14-L20)
- [KnowledgeVectorMapper.java:15-21](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L15-L21)
- [AttachmentVectorMapper.java:13-19](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L13-L19)
- [AiCleanTemplateVectorIndex.java:98-110](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java#L98-L110)
- [application.yaml:66-90](file://ai-server/src/main/resources/application.yaml#L66-L90)
### 向量表字段设计
三种 Mapper 中的向量表基本结构一致,都是“文档标识 + 原文片段 + 结构化负载 + 向量列”。
| 字段 | 类型 | 作用 |
|---|---|---|
| `doc_id` | `VARCHAR(128)` 主键 | 唯一标识一个向量片段或模板条目 |
| `content` | `TEXT` | 分块后的正文、模板摘要或表结构描述 |
| `payload` | `JSONB` | 存储业务隔离键,如 `kbId`、`sessionId`、`attachmentId`、`docId`、`tableId` 等 |
| `embedding` | `vector(${dims})` | pgvector 稠密向量列 |
知识库和附件向量表使用 `ON CONFLICT (doc_id) DO NOTHING` 去重;统一表结构索引则使用 `ON CONFLICT (doc_id) DO UPDATE`,因为模板可能增量更新。
**章节来源**
- [KnowledgeVectorMapper.java:22-64](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L22-L64)
- [AttachmentVectorMapper.java:20-60](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L20-L60)
- [RagVectorMapper.java:20-113](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java#L20-L113)
### 向量来源与维度约束
向量来源于两个通道:
1. **本地 ONNX 模型**:默认使用 bge-m3,输出 1024 维向量,CLS 池化后做 L2 归一化。
2. **在线 embedding 模型**:当本地开关关闭时,回退到系统中配置的 `type='embedding'` 活跃模型。
配置中声明的 `dimensions` 用于建表和状态展示;运行时还会校验实际输出维度是否与声明一致,避免错维向量写入 pgvector。
**章节来源**
- [application.yaml:66-90](file://ai-server/src/main/resources/application.yaml#L66-L90)
- [OnnxEmbeddingEngine.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/embedding/core/OnnxEmbeddingEngine.java#L1-L200)
## DuckDB 临时数据源设计
### 每案一库的数据源注册
`CaseDataSourceRegistry` 把每个案件映射到一个物理 key,形如 `case{caseId}`,由动态数据源路由在当前案件上下文下返回对应的 DuckDB 实例。开案时它会:
- 检查是否超过最大同时打开案件数。
- 校验 DuckDB 文件存在且大小大于零。
- 根据预算配置计算内存上限和线程数。
- 创建 `DuckdbUnpooledDataSource`。
- 幂等补建 `file_ai_profile` 表。
- 将数据源注册到路由表。
**章节来源**
- [CaseDataSourceRegistry.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L1-L200)
### 清洗数据写入 DuckDB
`AiDuckDb` 是 AI 清洗链路中面向案件 DuckDB 的读写通道。它与通用加载器共用同一个动态数据源路由,但不会继承基类,因为 AI 侧表名在运行期才确定。
关键行为包括:
- 顺序执行建表 SQL,一条语句一个 Statement,便于定位 CTAS 失败。
- 按 AI 模板字段动态生成 `CREATE TABLE IF NOT EXISTS`。
- 使用批大小为 2000 的流式写入器,避免一次性 collect 导致堆溢出。
- 写入失败时中断并抛出异常,让上层任务标记失败并可按 job 清理半写行。
**章节来源**
- [AiDuckDb.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/exec/AiDuckDb.java#L1-L200)
### DuckDB 快照与多进程隔离
DuckDB 单文件库在同一时刻只允许一个进程以写方式打开;即使另一个进程以只读方式打开,也可能因文件锁失败。为此项目提供了 `DuckdbSnapshot`:
- 使用 `ATTACH` + `COPY FROM DATABASE` 导出完整库副本。
- 先写 `.tmp-*` 临时文件,成功后原子替换目标文件。
- 导出别名每次随机,避免并发 ATTACH 冲突。
- 最终删除临时文件。
这使 Python 子进程可以连独立副本,而不与 Java 主进程持有的写锁冲突。
**章节来源**
- [DuckdbSnapshot.java:1-144](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java#L1-L144)
## 两种数据源对比
| 维度 | PostgreSQL + pgvector | DuckDB 临时数据源 |
|---|---|---|
| 部署形态 | 外部关系数据库,通常常驻 | 进程内嵌入式数据库,每案一个单文件 |
| 主要用途 | 长期保留的业务元数据和向量嵌入 | 案件清洗中间结果、分析结果、临时快照 |
| 典型表 | `knowledge_base`、`knowledge_doc`、`chat_attachment`、`ai_clean_template`、向量表 | 动态 `ai_clean_*` 清洗表、`file_ai_profile` |
| 数据类型 | JSONB、TEXT、BIGINT、TIMESTAMP、`vector(n)` | VARCHAR、INTEGER、BIGINT、TIMESTAMP、原生 DuckDB 类型 |
| 索引策略 | pgvector 向量列 + 业务二级索引;向量检索基于余弦距离 | 未看到显式 pgvector 或全文索引;适合列存扫描和聚合 |
| 隔离方式 | 业务字段过滤 + 向量表命名隔离 | 每案一个库文件 + 动态数据源路由 |
| 生命周期 | 随业务实体生命周期增长,需手动或定时清理 | 随案件打开而创建资源,退出/登出/过期回收 |
| 并发访问 | 客户端连接多个会话,PG 负责并发控制 | 单文件写锁限制;Python 子进程必须用快照 |
| 备份恢复 | 由 PG 备份工具处理 | 可复制 `.ddb` 文件或用 `DuckdbSnapshot` 导出 |
| 是否参与向量检索 | 是 | 否,向量索引不扫描 DuckDB 案件库 |
**章节来源**
- [knowledge_base.sql:1-70](file://sql/knowledge_base.sql#L1-L70)
- [chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39)
- [ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214)
- [RagSchemaService.java:1-181](file://ai-server/src/main/java/com/zsjz/ai/module/agent/rag/RagSchemaService.java#L1-L181)
- [CaseDataSourceRegistry.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L1-L200)
## 向量检索参数与索引策略
### 相似度计算
所有向量检索都使用 pgvector 的 `<=>` 操作符计算余弦距离,并把分数表示为 `1 - distance`。因此:
- 分数越高越相似。
- 阈值过滤发生在 SQL 层:只有 `score >= threshold` 的结果才返回。
- 返回条数由 `LIMIT` 控制。
```mermaid
flowchart TD
Start["输入查询向量"] --> Threshold["应用相似度阈值"]
Threshold --> ScoreCalc["计算 1 - 余弦距离"]
ScoreCalc --> Filter{"分数是否大于等于阈值"}
Filter -->|否| Drop["丢弃该候选"]
Filter -->|是| Rank["按分数降序排序"]
Rank --> Limit["取 top-k"]
Limit --> Return["返回 content、payload 和 score"]
```
**图表来源**
- [KnowledgeVectorMapper.java:44-56](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L44-L56)
- [AttachmentVectorMapper.java:38-54](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L38-L54)
- [RagVectorMapper.java:42-52](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java#L42-L52)
### 关键配置项
| 配置项 | 默认值 | 含义 |
|---|---:|---|
| `zsjz.embedding.dimensions` | 1024 | 向量维度,用于建表和状态展示 |
| `zsjz.embedding.enabled` | false | 本地 ONNX 模型开关;false 时回退在线 embedding 模型 |
| `zsjz.ai-clean.vector.top-k` | 12 | AI 模板向量召回候选数 |
| `zsjz.ai-clean.vector.score-threshold` | 0.30 | 模板向量召回相似度阈值 |
| `etl.rag.top-k` | 5 | Agent 表结构语义检索默认返回条数 |
| `etl.rag.score-threshold` | 0.3 | Agent 表结构检索相似度阈值 |
| `zsjz.chat-attachment.chunk-size` | 1000 | 附件 RAG 分块大小 |
| `zsjz.chat-attachment.max-chunks` | 500 | 单个附件最大分块数 |
| `zsjz.chat-attachment.top-k` | 8 | 附件 RAG 检索条数 |
**章节来源**
- [application.yaml:66-160](file://ai-server/src/main/resources/application.yaml#L66-L160)
### 索引重建注意事项
项目没有看到显式的 HNSW 或 IVFFLAT 索引管理脚本,向量检索主要依赖 `<=>` 全表扫描加 LIMIT。因此重建索引时需要特别注意:
1. **维度必须一致**:pgvector 的 `vector(n)` 会拒绝错误维度的向量。如果嵌入模型输出维度变化,必须重建对应向量表。
2. **模型标签变化也要重建**:表名包含 `{tag}`,本地模型和在线模型、bge-m3 与其他模型应隔离在不同表中。
3. **知识库和附件向量表不支持覆盖更新**:它们使用 `ON CONFLICT ... DO NOTHING`,文档内容变更后应先删除旧 `doc_id` 再重新插入。
4. **统一模板索引支持 upsert**:`rag_tpl{tag}_d{dims}` 使用 `ON CONFLICT ... DO UPDATE`,模板字段更新后可增量覆盖。
5. **重建可能很慢**:全量重建有 `max-documents-per-rebuild` 限制,防止模板库异常膨胀时打爆内存或嵌入额度。
**章节来源**
- [AiCleanTemplateVectorIndex.java:98-110](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java#L98-L110)
- [RagVectorMapper.java:70-113](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java#L70-L113)
- [KnowledgeVectorMapper.java:31-64](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L31-L64)
- [application.yaml:116-145](file://ai-server/src/main/resources/application.yaml#L116-L145)
## 生命周期、清理与备份恢复
### 持久化业务数据(PostgreSQL)
持久化数据包括知识库元数据、附件元数据、模板元数据和向量嵌入。这类数据不是按“临时会话”自动清理的,应该由以下策略维护:
- **知识库**:删除知识库时调用 `deleteByKb` 清理其全部向量行;删除文档时调用 `deleteByDoc`。
- **附件向量**:孤儿附件清理时按 `attachmentId` 删除向量行。
- **模板向量**:模板下线或删除时按 `doc_id` 精确删除。
- **业务表**:知识库、附件、模板等业务表的生命周期由各自业务逻辑管理。
**章节来源**
- [KnowledgeVectorMapper.java:58-64](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L58-L64)
- [AttachmentVectorMapper.java:56-60](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L56-L60)
- [RagVectorMapper.java:90-113](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java#L90-L113)
### 临时数据(DuckDB)
DuckDB 数据的生命周期围绕“案件”展开:
| 事件 | 行为 |
|---|---|
| 用户打开案件 | 校验文件存在且非空,分配内存和线程预算,注册数据源 |
| 清洗写入失败 | 已 flush 的行保留,但带 `ai_job_id`,可用撤销接口清理 |
| 用户主动退出案件 | 释放数据源 |
| 用户登出或被顶下线 | 释放数据源 |
| 会话自然过期 | 兜底回收器定期扫描并释放 |
| 导出快照 | 使用 `COPY FROM DATABASE` 生成独立副本供其他进程读取 |
**章节来源**
- [CaseDataSourceRegistry.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L1-L200)
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
- [AiDuckDb.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/exec/AiDuckDb.java#L1-L200)
- [DuckdbSnapshot.java:1-144](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java#L1-L144)
### 备份与恢复
- **PostgreSQL**:应由系统级备份方案处理,包括业务表和向量表。向量表与普通表一样受 PG 备份机制保护。
- **DuckDB**:可以直接复制 `.ddb` 文件,但要注意单文件写锁;更安全的方式是使用 `DuckdbSnapshot.export` 导出副本后再备份。
- **快照副作用**:导出期间会创建临时文件,成功替换后删除;失败时会尝试清理临时文件。
**章节来源**
- [DuckdbSnapshot.java:60-144](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java#L60-L144)
## 性能调优建议
### PostgreSQL + pgvector
- **合理设置阈值**:`score-threshold` 过低会引入无关候选,过高可能导致召回为空。模板召回默认 0.30,Agent 选表也使用相近阈值。
- **控制 top-k**:模板召回默认 12,Agent 选表默认 5,附件 RAG 默认 8。top-k 越大,提示词越长,成本越高。
- **避免跨模型混用**:向量表名包含模型标签和维度,切换本地/在线模型时应重建对应表。
- **监控向量表大小**:知识库和附件向量表按业务实体增长,需要关注单表大小和检索延迟。
- **注意 pgvector 全表扫描**:仓库中没有显式 HNSW/IVFFLAT 索引管理,大规模向量表应考虑后续扩展 pgvector 索引策略。
**章节来源**
- [application.yaml:116-160](file://ai-server/src/main/resources/application.yaml#L116-L160)
- [KnowledgeVectorMapper.java:44-56](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L44-L56)
- [AttachmentVectorMapper.java:38-54](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L38-L54)
- [RagVectorMapper.java:42-52](file://ai-server/src/main/java/com/zsjz/ai/module/agent/mapper/RagVectorMapper.java#L42-L52)
### DuckDB 临时数据源
- **限制并发案件数**:默认最多同时打开 8 个案件,避免 N 倍叠加内存和线程。
- **分摊内存预算**:每个案件实例的 `SET GLOBAL memory_limit` 和 `threads` 由 `DuckdbBudgetProperties` 分摊,不要无界放大。
- **使用流式写入**:AI 清洗使用批大小 2000 的流式写入器,避免一次性收集大量行。
- **谨慎开启 Python 子进程**:子进程不能直接连主库,必须用 `DuckdbSnapshot` 导出副本。
- **关注回收器**:兜底回收器按 token 有效性判断,保守跳过失败查询,防止误关正在使用的案件。
**章节来源**
- [application.yaml:31-58](file://ai-server/src/main/resources/application.yaml#L31-L58)
- [DuckdbUnpooledDataSource.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/common/config/DuckdbUnpooledDataSource.java#L1-L200)
- [AiDuckDb.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/exec/AiDuckDb.java#L1-L200)
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
## 常见问题排查
### 向量维度不一致
现象:写入向量时报错,或 pgvector 拒绝写入。
原因:嵌入模型输出维度与 `vector(n)` 列声明维度不一致。
处理:确认 `zsjz.embedding.dimensions` 与实际模型输出一致;本地模型由 `OnnxEmbeddingEngine` 首次推理探测维度,在线模型也有类似校验。
**章节来源**
- [OnnxEmbeddingEngine.java:140-200](file://ai-server/src/main/java/com/zsjz/ai/module/embedding/core/OnnxEmbeddingEngine.java#L140-L200)
- [application.yaml:66-90](file://ai-server/src/main/resources/application.yaml#L66-L90)
### 向量检索结果为空
现象:Agent 选表或知识库检索返回空列表。
可能原因:
- 向量索引尚未重建。
- 向量索引开关关闭。
- 嵌入模型不可用。
- 相似度阈值过高。
- 知识库/附件 payload 过滤条件不匹配。
处理:先检查索引状态接口,必要时调用重建接口;调整 `score-threshold`;确认 payload 中 `kbId` 或 `sessionId` 与检索参数一致。
**章节来源**
- [RagSchemaService.java:80-181](file://ai-server/src/main/java/com/zsjz/ai/module/agent/rag/RagSchemaService.java#L80-L181)
- [KnowledgeVectorMapper.java:44-56](file://ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java#L44-L56)
- [AttachmentVectorMapper.java:38-54](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentVectorMapper.java#L38-L54)
### 多进程连接 DuckDB 失败
现象:Python 子进程无法打开案件 DuckDB 文件。
原因:Java 主进程持有写锁,DuckDB 单文件不允许其他进程写,甚至某些情况下只读也失败。
处理:使用 `DuckdbSnapshot.export` 导出副本后,让子进程连接副本。
**章节来源**
- [DuckdbSnapshot.java:1-144](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java#L1-L144)
### 案件数据源无法释放
现象:多人开案后达到 `max-open-cases` 上限。
可能原因:用户关闭浏览器后会话过期但没有触发监听器,导致数据源残留。
处理:兜底回收器会定期扫描;检查 `reaper-initial-delay-ms` 和 `reaper-interval-ms`;确认归属 token 是否失效、是否有在途任务探针阻止回收。
**章节来源**
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
- [application.yaml:31-58](file://ai-server/src/main/resources/application.yaml#L31-L58)
## 结论
本项目的数据分层比较清晰:
- **PostgreSQL + pgvector** 负责长期业务数据和向量嵌入,支撑 Agent RAG、知识库相似检索和模板语义识别。
- **DuckDB** 负责每案临时分析和清洗,强调本地计算、流式写入和进程内生命周期管理。
- 两者不是替代关系,而是互补关系:模板元数据进 pgvector 向量索引,但不扫描 DuckDB 案件库;清洗结果留在 DuckDB,不做向量检索。
- 运维重点在于:向量维度与模型标签一致性、阈值与 top-k 调参、pgvector 表生命周期管理、DuckDB 并发与内存预算控制、以及案件数据源的回收与快照导出。