568 lines
10 KiB
Markdown
568 lines
10 KiB
Markdown
# 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
|