M2-04 Ingestion & Indexing Module #24

New Issue

wangdl · 2026-05-22T21:09:49+08:00

wangdl commented

2026-05-22 21:09:49 +08:00

目标

设计知习文档导入与索引模块，负责将用户上传的资料解析、清洗、切片、生成 embedding 并写入 Qdrant 索引。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

用户上传的 PDF/DOCX/TXT/MD 等文件需要经过解析才能变成可检索的数据。Ingestion 模块是资料从"文件"到"知识"的加工流水线：DocumentImport 管理导入任务的状态机，解析生成 parsed.md，切片生成 chunk，调用 AI Gateway 生成 embedding，写入 Qdrant 索引。

注意：Vision 在本阶段只做 fallback 预留——仅用于 OCR 失败或复杂图片页，不做完整多模态文档理解。

模块职责

本模块负责：
- DocumentImport 任务管理（创建、状态机、重试、取消）
- PDF/DOCX/TXT/MD 解析
- 图片 OCR（百度 OCR 通过 AI Gateway）
- Vision fallback（仅 OCR 失败或复杂图片页时使用，预留）
- 文本清洗（去噪、格式化）
- 切片策略（按段落/按语义/固定长度，请判断）
- Embedding 生成（通过 AI Gateway 调用）
- Qdrant upsert（通过 Vector & Retrieval Module）
- 导入步骤日志（ImportStepLog）
- 失败重试和 heartbeat
本模块不负责：
- 文件上传和 COS 操作（走 File Storage）
- Material 元数据管理（走 Material & Source）
- 知识点生成（走 Artifact Module）
- Qdrant 的运维管理（走 Vector & Retrieval 和 Knowledge Ops）

候选数据对象

DocumentImport（导入任务）
ImportStepLog（步骤日志）
ParseResult（解析结果）
ChunkingJob（切片任务）
EmbeddingJob（Embedding 生成任务）
IndexingJob（索引任务）

解析流程设计

请设计完整的导入流水线：

从 COS 拉取文件 → 文件类型判断 → 选择解析器
→ PDF：提取文本 + 图片 OCR（如有图片）
→ DOCX：提取文本 + 内嵌图片 OCR
→ TXT/MD：直接读取
→ 文本清洗 → 切片
→ 每个 chunk 调用 AI Gateway 生成 embedding
→ 批量写入 Qdrant（通过 Vector & Retrieval Module）
→ 更新 DocumentImport 状态为完成
→ 回写 parsed.md 到 COS（通过 File Storage）

基础设施依赖判断

MySQL：是（导入任务和步骤日志）
Redis：否
BullMQ：是（导入任务异步执行）
Qdrant：是（通过 Vector Module 写入）
AI Gateway：是（OCR、Vision、Embedding）
COS：是（通过 File Storage 拉取和回写）
File Storage：是
Vector & Retrieval：是
Content Safety：是（解析后文本需要审核）

API 设计

CAPI：
- 创建导入任务
- 查询导入任务状态
- 导入任务列表
IAPI（Worker 消费）：
- 拉取待处理导入任务
- 更新任务步骤状态
- 上报 heartbeat
AAPI：
- 导入任务监控列表
- 失败任务详情和重试

Domain Event 设计

DocumentImportCreated
DocumentImportStepCompleted
DocumentImportCompleted
DocumentImportFailed
ChunksGenerated
EmbeddingsGenerated

交付检查

路由归属：CAPI + IAPI + AAPI
是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：否
是否需要 BullMQ：是
是否需要 Qdrant：是（通过 Vector Module）
是否需要 AI Gateway：是
是否需要 File Storage：是
是否需要 Vector & Retrieval：是
是否需要 Content Safety：是
是否需要 Cost 记录：是（OCR/Vision/Embedding 消耗）
是否需要 Admin 视图：是

验收标准

DocumentImport 状态机设计
多格式解析器方案（PDF/DOCX/TXT/MD）
切片策略设计（含策略选择理由）
完整流水线设计（从 COS 拉取到 Qdrant 写入）
ImportStepLog 方案（可追踪每一步）
失败重试和 heartbeat 方案
Admin 导入监控视图设计
集成测试覆盖完整导入流程

禁止事项

禁止 Vision 做全量多模态文档理解（仅 fallback 预留）
禁止解析器在主线程同步执行大量文档（必须异步通过 BullMQ）
禁止 chunk 不关联 KnowledgeSource 和 CitationAnchor
禁止导入失败不留详细步骤日志
禁止 embedding 调用绕过 AI Gateway

不建议当前阶段实现

表格/公式/代码块的专项解析
音频/视频文件解析
扫描件 PDF 的完整 OCR 管道
多语言文档的语种检测和分语言处理策略

## 目标设计知习文档导入与索引模块，负责将用户上传的资料解析、清洗、切片、生成 embedding 并写入 Qdrant 索引。本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明用户上传的 PDF/DOCX/TXT/MD 等文件需要经过解析才能变成可检索的数据。Ingestion 模块是资料从"文件"到"知识"的加工流水线：DocumentImport 管理导入任务的状态机，解析生成 parsed.md，切片生成 chunk，调用 AI Gateway 生成 embedding，写入 Qdrant 索引。注意：Vision 在本阶段只做 fallback 预留——仅用于 OCR 失败或复杂图片页，不做完整多模态文档理解。 ## 模块职责 1. 本模块负责： - DocumentImport 任务管理（创建、状态机、重试、取消） - PDF/DOCX/TXT/MD 解析 - 图片 OCR（百度 OCR 通过 AI Gateway） - Vision fallback（仅 OCR 失败或复杂图片页时使用，预留） - 文本清洗（去噪、格式化） - 切片策略（按段落/按语义/固定长度，请判断） - Embedding 生成（通过 AI Gateway 调用） - Qdrant upsert（通过 Vector & Retrieval Module） - 导入步骤日志（ImportStepLog） - 失败重试和 heartbeat 2. 本模块不负责： - 文件上传和 COS 操作（走 File Storage） - Material 元数据管理（走 Material & Source） - 知识点生成（走 Artifact Module） - Qdrant 的运维管理（走 Vector & Retrieval 和 Knowledge Ops） ## 候选数据对象 - DocumentImport（导入任务） - ImportStepLog（步骤日志） - ParseResult（解析结果） - ChunkingJob（切片任务） - EmbeddingJob（Embedding 生成任务） - IndexingJob（索引任务） ## 解析流程设计请设计完整的导入流水线：从 COS 拉取文件 → 文件类型判断 → 选择解析器 → PDF：提取文本 + 图片 OCR（如有图片） → DOCX：提取文本 + 内嵌图片 OCR → TXT/MD：直接读取 → 文本清洗 → 切片 → 每个 chunk 调用 AI Gateway 生成 embedding → 批量写入 Qdrant（通过 Vector & Retrieval Module） → 更新 DocumentImport 状态为完成 → 回写 parsed.md 到 COS（通过 File Storage） ## 基础设施依赖判断 - MySQL：是（导入任务和步骤日志） - Redis：否 - BullMQ：是（导入任务异步执行） - Qdrant：是（通过 Vector Module 写入） - AI Gateway：是（OCR、Vision、Embedding） - COS：是（通过 File Storage 拉取和回写） - File Storage：是 - Vector & Retrieval：是 - Content Safety：是（解析后文本需要审核） ## API 设计 1. CAPI： - 创建导入任务 - 查询导入任务状态 - 导入任务列表 2. IAPI（Worker 消费）： - 拉取待处理导入任务 - 更新任务步骤状态 - 上报 heartbeat 3. AAPI： - 导入任务监控列表 - 失败任务详情和重试 ## Domain Event 设计 - DocumentImportCreated - DocumentImportStepCompleted - DocumentImportCompleted - DocumentImportFailed - ChunksGenerated - EmbeddingsGenerated ## 交付检查 - [x] 路由归属：CAPI + IAPI + AAPI - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：否 - [x] 是否需要 BullMQ：是 - [x] 是否需要 Qdrant：是（通过 Vector Module） - [x] 是否需要 AI Gateway：是 - [x] 是否需要 File Storage：是 - [x] 是否需要 Vector & Retrieval：是 - [x] 是否需要 Content Safety：是 - [x] 是否需要 Cost 记录：是（OCR/Vision/Embedding 消耗） - [x] 是否需要 Admin 视图：是 ## 验收标准 1. DocumentImport 状态机设计 2. 多格式解析器方案（PDF/DOCX/TXT/MD） 3. 切片策略设计（含策略选择理由） 4. 完整流水线设计（从 COS 拉取到 Qdrant 写入） 5. ImportStepLog 方案（可追踪每一步） 6. 失败重试和 heartbeat 方案 7. Admin 导入监控视图设计 8. 集成测试覆盖完整导入流程 ## 禁止事项 - 禁止 Vision 做全量多模态文档理解（仅 fallback 预留） - 禁止解析器在主线程同步执行大量文档（必须异步通过 BullMQ） - 禁止 chunk 不关联 KnowledgeSource 和 CitationAnchor - 禁止导入失败不留详细步骤日志 - 禁止 embedding 调用绕过 AI Gateway ## 不建议当前阶段实现 - 表格/公式/代码块的专项解析 - 音频/视频文件解析 - 扫描件 PDF 的完整 OCR 管道 - 多语言文档的语种检测和分语言处理策略

wangdl added this to the M2：知识库主链路闭环（P1） milestone 2026-05-22 21:09:49 +08:00

wangdl self-assigned this 2026-05-22 21:09:49 +08:00

wangdl commented

2026-05-24 13:13:38 +08:00

✅ M2-04 实施完成

关键发现

现有基础设施非常完善：

DocumentImport 状态机（QUEUED→PROCESSING→COMPLETED/FAILED）+ progress/heartbeat/retry
RAG Worker (Python) 已实现 parser/chunker/embedder/indexer/candidate_generator
internal/rag/* IAPI 已实现 job claim/heartbeat/status update

交付内容

模块	说明
`ImportStepLog`	新表，记录导入流水线每步状态（parse/chunk/embed/index/candidate）
Admin AAPI	`GET /admin-api/imports` 列表、`GET /admin-api/imports/:id` 详情含步骤日志、`POST /admin-api/imports/:id/retry` 重试
Admin 页面	ImportMonitor：导入列表 + 抽屉详情（步骤日志时间线）

E2E (test/m2.e2e-spec.ts)

5 tests: import create, admin list + 401, detail, retry.

运行

npx jest --config ./test/jest-e2e.json  # all passing

## ✅ M2-04 实施完成 ### 关键发现现有基础设施非常完善： - `DocumentImport` 状态机（QUEUED→PROCESSING→COMPLETED/FAILED）+ progress/heartbeat/retry - RAG Worker (Python) 已实现 parser/chunker/embedder/indexer/candidate_generator - `internal/rag/*` IAPI 已实现 job claim/heartbeat/status update ### 交付内容 | 模块 | 说明 | |------|------| | `ImportStepLog` | 新表，记录导入流水线每步状态（parse/chunk/embed/index/candidate）| | Admin AAPI | `GET /admin-api/imports` 列表、`GET /admin-api/imports/:id` 详情含步骤日志、`POST /admin-api/imports/:id/retry` 重试 | | Admin 页面 | ImportMonitor：导入列表 + 抽屉详情（步骤日志时间线）| ### E2E (test/m2.e2e-spec.ts) 5 tests: import create, admin list + 401, detail, retry. ### 运行 ```bash npx jest --config ./test/jest-e2e.json # all passing ```

wangdl closed this issue

2026-06-06 14:43:14 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#24