2026-08-31 20:41:11 +08:00

568 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# EKP Knowledge Retrieval Demo v0.1
## 1. 文档目的
本文档定义 Enterprise Knowledge Platform(EKP)第一阶段 Demo 的最小实现范围。
该 Demo 的目标不是完成完整企业级知识平台,而是优先验证最核心的技术闭环:
> 文件上传 → 文档解析/清洗 → Chunk → Embedding → Mochow 入库 → 检索召回 → Reranker → 来源返回 → 简单管理页面
当前 Demo Scope 的优先级高于完整 V1 PRD。
在 Demo 阶段,除非本文件明确要求,否则不得因为完整 PRD 中存在某项能力而提前实现。
---
## 2. Demo 核心目标
验证以下关键问题:
1. 中文企业文档是否能够稳定上传和解析;
2. 清洗后的内容是否可以形成质量可接受的 Chunk;
3. 使用现有 Embedding + Mochow 能否完成稳定召回;
4. Reranker 是否能提升最终 TopK 结果质量;
5. 检索结果是否能够准确返回文件名、页码、章节和原文;
6. 非研发人员是否能够通过简单页面完成上传和检索验证。
Demo 成功标准不是“企业级能力完备”,而是:
> 核心知识入库和召回链路可用,并具备继续扩展为正式产品的基础。
---
## 3. Demo 最小架构
```text
Admin Web
│
↓
FastAPI
│
├── Document Upload
│ ↓
│ Parser
│ ↓
│ Cleaner
│ ↓
│ Chunker
│ ↓
│ Embedding
│ ↓
│ Mochow
│
└── Search
↓
Query Embedding
↓
Mochow TopN
↓
Reranker
↓
TopK
↓
Source Enrichment
```
辅助存储:
```text
SQLite / PostgreSQL
└── document / chunk metadata
Local Storage / MinIO
└── original files
```
Demo 阶段优先简单实现,不引入不必要的基础设施。
---
## 4. 当前推荐技术选型
| 模块 | Demo 推荐选型 | 说明 |
|---|---|---|
| Backend | FastAPI | 简单、开发效率高 |
| Metadata DB | SQLite 或 PostgreSQL | 单机 Demo 可 SQLite;已有环境可直接 PostgreSQL |
| File Storage | 本地目录 | Demo 阶段优先简单;后续可替换 MinIO/S3 |
| Parser | PyMuPDF + python-docx 或 MinerU | 优先快速跑通;复杂 PDF 后续增强 |
| Cleaner | 自定义基础清洗 | 处理空行、空白、异常换行等 |
| Chunker | 标题/段落优先 + Token 限制 | 暂不设计复杂 Chunk 策略 |
| Embedding | bge-large-zh | 延续公司现有百度千帆方案 |
| Vector DB | Mochow | 当前默认,不做多数据库实现 |
| Reranker | Qwen3 Reranker 或现有可调用 Reranker | Demo 中保留 |
| Frontend | 简单 React/Vue 或 FastAPI HTML | 以最小可用为目标 |
| Deployment | 本地 / 单机 Docker | 暂不考虑 K8s |
---
## 5. P0 功能范围
### 5.1 文件上传
支持:
- PDF
- DOCX
- TXT
- Markdown
功能要求:
- 单文件上传;
- 简单批量上传可选;
- 上传后记录文档状态;
- 保存原始文件;
- 上传完成后触发解析流程。
暂不支持:PPTX、XLSX、图片、扫描 PDF、视频、音频。
### 5.2 文档解析
PDF:第一版仅要求文本型 PDF,提取正文并尽量保留页码。
DOCX:提取标题、段落,并保留基础章节结构。
TXT/Markdown:直接读取;Markdown 尽量保留标题层级。
### 5.3 基础清洗
至少处理:
- 多余空行;
- 连续空格;
- 异常换行;
- 首尾空白;
- 简单重复空白字符。
Demo 不要求复杂页眉页脚识别、OCR 噪声修复、复杂表格恢复和多栏阅读顺序恢复。
### 5.4 Chunk
第一版策略:
```text
标题 / 章节优先
↓
段落组合
↓
达到约 400~500 tokens
↓
生成 Chunk
↓
Overlap 50~100 tokens
```
每个 Chunk 至少包含:
```text
chunk_id
document_id
filename
page
section
chunk_index
content
```
### 5.5 Embedding
第一版固定使用 `bge-large-zh`,通过现有百度千帆能力调用。
Demo 阶段不实现多 Embedding Benchmark 平台和动态模型切换,但代码层建议保留简单接口,避免业务逻辑直接写死调用细节。
### 5.6 Mochow 入库
将 Chunk 写入 Mochow,至少保存:
```text
chunk_id
document_id
filename
page
section
content
embedding
```
支持:Upsert、按 document_id 删除相关 Chunk、Dense Search。
Demo 阶段不实现 Qdrant/Milvus/pgvector,也不实现完整 VectorStore Adapter 体系,但避免 Mochow SDK 调用散落在整个项目中。
### 5.7 Dense Retrieval
```text
Query
↓
bge-large-zh Embedding
↓
Mochow Dense Search
↓
Top 20 Candidates
```
第一阶段先验证纯 Dense Retrieval。
### 5.8 Reranker
```text
Top20
↓
Reranker
↓
Top5
```
最终返回原始向量分数、Reranker 分数、Chunk 内容和来源信息。
Reranker 是 Demo P0,不建议删除。
### 5.9 Source Result
每条检索结果至少返回:
```text
document_id
filename
page
section
chunk_id
content
score
rerank_score
```
UI 必须能够直观看到来源。
---
## 6. P0 REST API
```http
POST /api/documents
GET /api/documents
GET /api/documents/{id}
DELETE /api/documents/{id}
POST /api/search
```
Demo 阶段删除可以直接执行:删除原始文件 + 删除 Metadata + 删除 Mochow 对应 Chunk,暂不要求 Soft Delete。
Search Request 示例:
```json
{
"query": "产品A退款周期是多少?",
"top_k": 5
}
```
Search Response 示例:
```json
{
"results": [
{
"document_id": "doc-001",
"filename": "产品A说明书.pdf",
"page": 12,
"section": "退款政策",
"chunk_id": "chunk-023",
"content": "……",
"score": 0.82,
"rerank_score": 0.94
}
]
}
```
---
## 7. Demo Admin Console
只实现 3 个核心页面:
### 7.1 文档上传页
- 选择文件;
- 上传;
- 查看状态。
状态简化为:`Uploaded / Processing / Ready / Failed`。
### 7.2 文档列表页
展示:文件名、类型、上传时间、状态。
操作:查看、删除、重新解析(可选)。
### 7.3 Search Lab
展示:Rank、Filename、Page、Section、Chunk Content、Dense Score、Rerank Score。
---
## 8. P1 可选增强
### DEMO-011 Hybrid Search
```text
Dense
+
BM25
↓
Fusion
↓
Reranker
```
用于对比 Dense Only 与 Hybrid 的实际效果。
### DEMO-012 MCP
只实现一个最小 MCP Tool:`search_knowledge`,内部调用 `/api/search`,用于验证 WorkBuddy 接入。
### DEMO-013 OCR / MinerU
增加扫描 PDF、图片、OCR 和复杂中文 PDF 处理能力。
---
## 9. 明确后置能力
当前 Demo 不做:
- 多租户;
- RBAC / Document ACL;
- LDAP / SSO;
- 审计日志;
- Document Version;
- Source Hash 增量更新;
- Soft Delete;
- Shadow Index / Index Profile;
- Knowledge Compilation;
- Compiled Wiki / FAQ / SOP;
- 多 Embedding Benchmark Platform;
- 多 Vector DB;
- 动态 Provider;
- RabbitMQ / Celery;
- Kubernetes;
- 高可用;
- 灾备;
- 完整 Observability。
---
## 10. Demo Task 清单
```text
DEMO-001 项目骨架 + FastAPI + 配置
DEMO-002 Document 数据模型 + 文件存储
DEMO-003 PDF/DOCX/TXT/MD 上传
DEMO-004 Parser + Cleaner
DEMO-005 Chunk Pipeline
DEMO-006 bge-large-zh Embedding + Mochow 入库
DEMO-007 Dense Retrieval
DEMO-008 Reranker + Source Result
DEMO-009 Document/Search REST API
DEMO-010 简单 Admin Console
```
可选:
```text
DEMO-011 Hybrid Search
DEMO-012 MCP search_knowledge
DEMO-013 OCR / MinerU
```
---
## 11. Demo 测试数据
建议准备 10~20 份中文测试文档,覆盖产品说明、FAQ、业务制度、技术文档和 SOP。
必须使用人工构造、已脱敏或明确允许测试的数据。禁止将真实敏感企业资料提交 Git。
---
## 12. Demo 检索测试集
准备 30~50 个 Query,例如:
```text
产品A退款周期是多少?
员工出差住宿标准是多少?
产品A支持哪些部署方式?
系统出现XX错误应该怎么处理?
```
每个 Query 人工标记:
```text
expected_document
expected_section
```
Demo 阶段不要求完整 Benchmark 平台,只需检查 Top5 是否包含正确来源。
---
## 13. Demo Definition of Done
### Upload
PDF / DOCX / TXT / MD 可以成功上传。
### Ingestion
```text
Upload
→ Parse
→ Clean
→ Chunk
→ Embedding
→ Mochow
```
完整跑通。
### Retrieval
```text
Query
→ Embedding
→ Mochow Dense Top20
→ Reranker
→ Top5
```
完整跑通。
### Source
每个结果至少显示:filename、page、section、content。
### Search Quality
使用 30~50 个测试 Query,大部分核心问题在 Top5 中能够找到正确文档或章节。
Demo 阶段不设严格生产指标。
### UI
非研发用户可以自行完成:
```text
上传文件
→ 等待 Ready
→ 输入问题
→ 查看 Top5 召回结果
```
---
## 14. Codex 开发约束
Codex 当前只能实现 `DEMO-001 ~ DEMO-010`。
除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、微服务、Kubernetes 和企业级 Job Queue。
当本文件与完整 PRD 的实现优先级冲突时:
> `docs/demo/DEMO_SCOPE.md` 优先。
完整 PRD 和总体技术架构仍作为长期演进方向,不应删除或修改其长期目标。
---
## 15. 推荐 Codex 初始提示词
```text
当前目标已经从完整 Enterprise Knowledge Platform V1
收缩为 Knowledge Retrieval Demo v0.1。
请首先阅读:
1. AGENTS.md
2. docs/demo/DEMO_SCOPE.md
3. docs/product/PRD.md
4. docs/architecture/ARCHITECTURE.md
当前开发优先级:
docs/demo/DEMO_SCOPE.md
>
完整 V1 PRD
只允许实现 DEMO-001 ~ DEMO-010。
当前 Demo 的目标只有:
Upload
→ Parse/Clean
→ Chunk
→ bge-large-zh
→ Mochow
→ Dense Retrieval
→ Reranker
→ Source Result
→ Search UI
不要提前实现:
- ACL
- RBAC
- Audit
- Document Version
- Knowledge Compilation
- Multi Vector Store
- Embedding Benchmark Platform
- Celery/RabbitMQ
- Kubernetes
- 企业级高可用
先不要修改代码。
请浏览当前仓库后输出:
1. 当前仓库状态;
2. 为完成 Demo 需要保留哪些现有结构;
3. 哪些完整 V1 设计可以暂时不实现;
4. DEMO-001 ~ DEMO-010 的建议执行顺序;
5. 下一步应该实施的第一个 Task。
```
---
## 16. Demo 后的演进顺序
```text
Demo
↓
Hybrid Search
↓
MCP
↓
OCR / Complex Parsing
↓
Document Version
↓
ACL
↓
Audit
↓
Multi Embedding Benchmark
↓
Knowledge Compilation
↓
Enterprise Production Hardening
```
避免在核心召回能力尚未验证前投入大量企业平台工程能力。
---
**Document:** EKP Knowledge Retrieval Demo v0.1
**Status:** Development Scope Baseline