Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(rag): Complete RAG engine implementation with pgvector

Browse Source 
Major Features:
- Created ekb_schema (13th schema) with 3 tables: KB/Document/Chunk
- Implemented EmbeddingService (text-embedding-v4, 1024-dim vectors)
- Implemented ChunkService (smart Markdown chunking)
- Implemented VectorSearchService (multi-query + hybrid search)
- Implemented RerankService (qwen3-rerank)
- Integrated DeepSeek V3 QueryRewriter for cross-language search
- Python service: Added pymupdf4llm for PDF-to-Markdown conversion
- PKB: Dual-mode adapter (pgvector/dify/hybrid)

Architecture:
- Brain-Hand Model: Business layer (DeepSeek) + Engine layer (pgvector)
- Cross-language support: Chinese query matches English documents
- Small Embedding (1024) + Strong Reranker strategy

Performance:
- End-to-end latency: 2.5s
- Cost per query: 0.0025 RMB
- Accuracy improvement: +20.5% (cross-language)

Tests:
- test-embedding-service.ts: Vector embedding verified
- test-rag-e2e.ts: Full pipeline tested
- test-rerank.ts: Rerank quality validated
- test-query-rewrite.ts: Cross-language search verified
- test-pdf-ingest.ts: Real PDF document tested (Dongen 2003.pdf)

Documentation:
- Added 05-RAG-Engine-User-Guide.md
- Added 02-Document-Processing-User-Guide.md
- Updated system status documentation

Status: Production ready
This commit is contained in:
HaHafeng
2026-01-21 20:24:29 +08:00
parent 1f5bf2cd65
commit 40c2f8e148
338 changed files with 11014 additions and 1158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

275
docs/02-通用能力层/03-RAG引擎/01-知识库引擎架构设计.md
View File

@@ -1,6 +1,6 @@
# 知识库引擎架构设计
> **文档版本：** v1.1
> **文档版本：** v1.2
> **创建日期：** 2026-01-20
> **最后更新：** 2026-01-20
> **能力定位：** 通用能力层
@@ -22,6 +22,8 @@
│ │
│ ✅ 提供基础能力（乐高积木） │
│ ❌ 不做策略选择（组装方案由业务模块决定） │
│ ⚡️ 入库必须异步（防止 HTTP 超时） │
│ 💰 提取按需开启（控制 LLM 调用成本） │
│ │
│ 原因： │
│ • 不同业务场景需要不同的知识库使用策略 │
@@ -37,15 +39,16 @@
| 能力分类 | 基础能力 | 说明 |
|----------|----------|------|
| **文档入库** | `ingestDocument()` | 文档解析 → 切片 → 向量化 → 存储 |
| | `ingestBatch()` | 批量入库 |
| **文档入库** | `submitIngestTask()` | ⚡️ 异步入库，返回 taskId |
| | `getIngestStatus()` | 获取入库任务状态和进度 |
| **全文获取** | `getDocumentFullText()` | 获取单个文档全文 |
| | `getAllDocumentsText()` | 获取知识库所有文档全文 |
| **摘要获取** | `getDocumentSummary()` | 获取单个文档摘要 |
| | `getAllDocumentsSummaries()` | 获取知识库所有文档摘要 |
| **向量检索** | `vectorSearch()` | 基于向量的语义检索 |
| **关键词检索** | `keywordSearch()` | 基于 PostgreSQL FTS 的关键词检索 |
| **向量检索** | `vectorSearch()` | 基于 pgvector 的语义检索 |
| **关键词检索** | `keywordSearch()` | 基于 pg_bigm 的中文精确检索 |
| **混合检索** | `hybridSearch()` | 向量 + 关键词 + RRF 融合 |
| **重排序** | `rerank()` | 🆕 基于 Qwen-Rerank 的精排序 |
| **管理操作** | `deleteDocument()` | 删除文档 |
| | `clearKnowledgeBase()` | 清空知识库 |
@@ -245,6 +248,85 @@ async function rvwPlagiarismCheck(manuscriptText: string, kbId: string) {
---
## 🏗️ 关键技术决策
### 1. ⚡️ 入库异步化（Postgres-Only 架构）
文档入库是耗时操作（10-60秒），**必须异步处理**以避免 HTTP 超时。
```typescript
// 提交入库任务（立即返回 taskId）
const { taskId } = await kbEngine.submitIngestTask({
kbId: 'kb-123',
file: pdfBuffer,
filename: 'research.pdf',
});
// 轮询任务状态
const status = await kbEngine.getIngestStatus(taskId);
// { status: 'processing', progress: 45, error: null }
```
**技术实现**：基于 pg-boss 队列，详见 [Postgres-Only异步任务处理指南](../Postgres-Only异步任务处理指南.md)
### 2. 💰 成本控制策略
| 行为 | 默认 | LLM 调用 | 成本 |
|------|------|----------|------|
| 解析 + 切片 + 向量化 | ✅ 开启 | ❌ 无 | 低（仅 Embedding API） |
| 摘要生成 | ❌ 关闭 | ✅ 有 | 中 |
| 临床要素提取（PICO） | ❌ 关闭 | ✅ 有 | 高 |
```typescript
// 默认行为：只做向量化（零 LLM 成本）
await kbEngine.submitIngestTask({ kbId, file, filename });
// ASL 智能文献场景：开启完整提取
await kbEngine.submitIngestTask({
kbId, file, filename,
options: {
enableSummary: true, // 💰 可选
enableClinicalExtraction: true // 💰 可选
}
});
```
### 3. 🔧 中文关键词检索方案
PostgreSQL 默认分词对中文支持不佳，采用 **pg_bigm（Bigram）** 方案：
| 方案 | 原理 | 中文效果 | 说明 |
|------|------|----------|------|
| `tsvector` | 分词 | 差 | 需额外中文分词插件 |
| `pg_trgm` | 3-gram | 一般 | 英文为主 |
| **`pg_bigm`** ✅ | 2-gram | **优秀** | 专为 CJK 文字优化 |
```sql
-- 开启插件
CREATE EXTENSION IF NOT EXISTS pg_bigm;
-- 创建索引
CREATE INDEX bigm_idx ON "ekb_schema"."EkbChunk"
USING gin (content gin_bigm_ops);
-- 查询（支持中文精确匹配）
SELECT * FROM "EkbChunk" WHERE content LIKE '%帕博利珠%';
-- 可匹配："帕博利珠单抗"、"帕博利珠注射液" 等
-- 相似度查询
SELECT *, bigm_similarity(content, '帕博利珠单抗') as score
FROM "EkbChunk"
WHERE content LIKE '%帕博利珠%'
ORDER BY score DESC;
```
**优势**：
- 对医学专有名词召回率高
- 不需要复杂语义评分（向量检索已做语义互补）
- 追求"查全率"和"精确匹配"
---
## 📦 代码结构
### 目录规划
@@ -257,11 +339,15 @@ backend/src/common/rag/
├── services/
│ ├── ChunkService.ts # 文档切片服务
│ ├── EmbeddingService.ts # 向量化服务（阿里云 DashScope）
│ ├── SummaryService.ts # 摘要生成服务
│ ├── VectorSearchService.ts # 向量检索服务
│ ├── KeywordSearchService.ts # 关键词检索服务（PostgreSQL FTS）
│ ├── SummaryService.ts # 摘要生成服务（💰 可选）
│ ├── ClinicalExtractionService.ts # 临床要素提取（💰 可选）
│ ├── VectorSearchService.ts # 向量检索服务（pgvector）
│ ├── KeywordSearchService.ts # 关键词检索服务（pg_trgm）
│ ├── HybridSearchService.ts # 混合检索服务（RRF 融合）
│ └── ClinicalExtractionService.ts # 临床要素提取（可选）
│ └── RerankService.ts # 🆕 重排序服务（Qwen-Rerank）
│
├── workers/
│ └── ingestWorker.ts # ⚡️ 异步入库 Worker（pg-boss）
│
├── types/
│ ├── index.ts # 类型定义
@@ -286,28 +372,33 @@ backend/src/common/rag/
export class KnowledgeBaseEngine {
constructor(private prisma: PrismaClient) {}
// ==================== 文档入库 ====================
// ==================== 文档入库（异步） ====================
/**
* 入库文档（完整流程：提取 → 切片 → 向量化 → 存储）
* ⚡️ 提交入库任务（立即返回 taskId）
* 详见：Postgres-Only异步任务处理指南
*/
async ingestDocument(params: {
async submitIngestTask(params: {
kbId: string;
userId: string;
file: Buffer;
filename: string;
options?: {
extractClinicalData?: boolean;
generateSummary?: boolean;
enableSummary?: boolean; // 💰 默认 false
enableClinicalExtraction?: boolean; // 💰 默认 false
chunkSize?: number;
chunkOverlap?: number;
};
}): Promise<IngestResult>;
}): Promise<{ taskId: string; documentId: string }>;
/**
* 批量入库
* 获取入库任务状态
*/
async ingestBatch(documents: IngestParams[]): Promise<IngestResult[]>;
async getIngestStatus(taskId: string): Promise<{
status: 'pending' | 'processing' | 'completed' | 'failed';
progress: number; // 0-100
error?: string;
}>;
// ==================== 内容获取（全文） ====================
@@ -355,7 +446,7 @@ export class KnowledgeBaseEngine {
): Promise<SearchResult[]>;
/**
* 关键词检索（PostgreSQL FTS）
* 关键词检索（pg_bigm 中文精确匹配）
*/
async keywordSearch(
kbIds: string[],
@@ -377,6 +468,15 @@ export class KnowledgeBaseEngine {
}
): Promise<SearchResult[]>;
/**
* 🆕 重排序（Qwen-Rerank API）
*/
async rerank(
documents: SearchResult[],
query: string,
topK?: number
): Promise<SearchResult[]>;
// ==================== 管理操作 ====================
/**
@@ -482,90 +582,15 @@ export class KnowledgeBaseEngine {
## 🗄️ 数据模型
### Prisma Schema
```prisma
// schema.prisma
model EkbDocument {
id String @id @default(uuid())
kbId String // 所属知识库
userId String // 上传用户
// 基础信息
filename String
fileType String
fileSizeBytes BigInt
fileUrl String // OSS 地址
extractedText String? @db.Text // 提取的 Markdown 全文
summary String? @db.Text // 文档摘要（200-500字）
// 临床数据（JSONB，可选）
pico Json? // { P, I, C, O }
studyDesign Json? // { design, sampleSize, ... }
regimen Json? // [{ drug, dose, ... }]
safety Json? // { ae_all, ae_grade34 }
criteria Json? // { inclusion, exclusion }
endpoints Json? // { primary, secondary }
// 状态
status String @default("pending") // pending | processing | completed | failed
errorMessage String? @db.Text
// 统计信息
tokenCount Int? // 文档 token 数量
chunks EkbChunk[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([kbId])
@@index([status])
@@schema("ekb_schema")
}
model EkbChunk {
id String @id @default(uuid())
documentId String
content String @db.Text // 切片文本
pageNumber Int? // 来源页码
sectionType String? // 章节类型
// pgvector 字段
embedding Unsupported("vector(1024)")?
document EkbDocument @relation(fields: [documentId], references: [id], onDelete: Cascade)
createdAt DateTime @default(now())
@@index([documentId])
@@schema("ekb_schema")
}
```
### 索引设计
```sql
-- HNSW 向量索引（高性能近似最近邻）
CREATE INDEX IF NOT EXISTS ekb_chunk_embedding_idx
ON "ekb_schema"."EkbChunk"
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
-- 全文检索索引
CREATE INDEX IF NOT EXISTS ekb_chunk_content_idx
ON "ekb_schema"."EkbChunk"
USING gin (to_tsvector('simple', content));
-- JSONB GIN 索引（临床数据查询）
CREATE INDEX IF NOT EXISTS ekb_document_pico_idx
ON "ekb_schema"."EkbDocument" USING gin (pico);
CREATE INDEX IF NOT EXISTS ekb_document_safety_idx
ON "ekb_schema"."EkbDocument" USING gin (safety);
```
> 📌 **数据模型详见**：[04-数据模型设计.md](./04-数据模型设计.md)
>
> 本文档不再重复定义数据模型，请以上述文档为准。该文档包含：
> - 四层架构设计原则
> - EkbDocument / EkbChunk 完整 Prisma Schema
> - 索引设计（HNSW、pg_bigm、GIN）
> - contentType 枚举定义
> - metadata / structuredData JSONB 结构
> - 各类型使用示例
---
@@ -600,7 +625,13 @@ ON "ekb_schema"."EkbDocument" USING gin (safety);
┌─────────────────────────────────────────────────────────────┐
│ 知识库引擎 (本模块) │
│ │
│ 依赖: │
│ 平台依赖: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ⚡️ 异步任务处理（pg-boss） │ │
│ │ • 入库任务队列 │ │
│ │ • 详见：Postgres-Only异步任务处理指南 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 文档处理引擎 │ │
│ │ • 调用 DocumentProcessor.toMarkdown() │ │
@@ -608,9 +639,9 @@ ON "ekb_schema"."EkbDocument" USING gin (safety);
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ LLM 网关 │ │
│ │ • 调用 LLMFactory.getAdapter('deepseek-v3') │ │
│ │ • 用于摘要生成、临床要素提取 │ │
│ │ LLM 网关（💰 可选调用） │ │
│ │ • 摘要生成（enableSummary: true） │ │
│ │ • 临床要素提取（enableClinicalExtraction: true） │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
@@ -623,7 +654,7 @@ ON "ekb_schema"."EkbDocument" USING gin (safety);
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 阿里云 DashScope API │ │
│ │ • text-embedding-v3 (向量化) │ │
│ │ • gte-rerank (重排序，可选) │ │
│ │ • qwen-rerank (重排序) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
@@ -632,21 +663,29 @@ ON "ekb_schema"."EkbDocument" USING gin (safety);
## 📅 开发计划
详见：[02-pgvector替换Dify计划.md](./02-pgvector替换Dify计划.md)
### 分阶段实施（推荐）
### 里程碑
详见：[03-分阶段实施方案.md](./03-分阶段实施方案.md)
| 阶段 | 内容 | 工期 | 状态 |
|------|------|------|------|
| **M1** | 数据库设计 + 核心服务 | 5 天 | 🔜 待开始 |
| **M2** | PKB 模块接入 + 测试 | 3 天 | 📋 规划中 |
| **M3** | 数据迁移 + 上线 | 2 天 | 📋 规划中 |
| **Phase 1 MVP** | 入库 + 向量检索 + 全文获取 | 3 天 | 🔜 待开始 |
| **Phase 2 增强** | + 关键词检索 + 混合检索 + rerank | 2 天 | 📋 规划中 |
| **Phase 3 完整** | + 异步入库 + 摘要 + PICO | 3 天 | 📋 规划中 |
**核心原则**：先跑通 MVP，让业务走起来，再逐步完善。
### 技术实现参考
详见：[02-pgvector替换Dify计划.md](./02-pgvector替换Dify计划.md)
---
## 📚 相关文档
- [pgvector 替换 Dify 开发计划](./02-pgvector替换Dify计划.md)
- [分阶段实施方案](./03-分阶段实施方案.md) - 🆕 MVP → 增强 → 完整
- [pgvector 替换 Dify 技术方案](./02-pgvector替换Dify计划.md) - 详细技术实现
- [Postgres-Only异步任务处理指南](../Postgres-Only异步任务处理指南.md) - 异步架构参考
- [文档处理引擎设计方案](../02-文档处理引擎/01-文档处理引擎设计方案.md)
- [LLM 网关](../01-LLM大模型网关/README.md)
- [通用能力层总览](../README.md)
@@ -655,6 +694,16 @@ ON "ekb_schema"."EkbDocument" USING gin (safety);
## 📅 更新日志
### v1.2 (2026-01-20)
**架构审核优化：**
- ⚡️ **入库异步化**：`ingestDocument()` → `submitIngestTask()` + `getIngestStatus()`，基于 pg-boss 队列
- 💰 **成本控制**：摘要生成、临床要素提取默认关闭，按需开启
- 🔧 **中文检索**：关键词检索从 `tsvector` 改为 `pg_bigm`，专为 CJK 文字优化
- 🆕 **新增能力**：独立暴露 `rerank()` 重排序能力（Qwen-Rerank API）
- 📦 **代码结构**：新增 `workers/ingestWorker.ts` 和 `RerankService.ts`
- 📋 **分阶段实施**：新增 MVP → 增强 → 完整 三阶段方案
### v1.1 (2026-01-20)
**设计原则重大更新：**