10 KiB
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 核心目标
验证以下关键问题:
- 中文企业文档是否能够稳定上传和解析;
- 清洗后的内容是否可以形成质量可接受的 Chunk;
- 使用现有 Embedding + Mochow 能否完成稳定召回;
- Reranker 是否能提升最终 TopK 结果质量;
- 检索结果是否能够准确返回文件名、页码、章节和原文;
- 非研发人员是否能够通过简单页面完成上传和检索验证。
Demo 成功标准不是“企业级能力完备”,而是:
核心知识入库和召回链路可用,并具备继续扩展为正式产品的基础。
3. Demo 最小架构
Admin Web
│
↓
FastAPI
│
├── Document Upload
│ ↓
│ Parser
│ ↓
│ Cleaner
│ ↓
│ Chunker
│ ↓
│ Embedding
│ ↓
│ Mochow
│
└── Search
↓
Query Embedding
↓
Mochow TopN
↓
Reranker
↓
TopK
↓
Source Enrichment
辅助存储:
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 文件上传
支持:
- DOCX
- TXT
- Markdown
功能要求:
- 单文件上传;
- 简单批量上传可选;
- 上传后记录文档状态;
- 保存原始文件;
- 上传完成后触发解析流程。
暂不支持:PPTX、XLSX、图片、扫描 PDF、视频、音频。
5.2 文档解析
PDF:第一版仅要求文本型 PDF,提取正文并尽量保留页码。
DOCX:提取标题、段落,并保留基础章节结构。
TXT/Markdown:直接读取;Markdown 尽量保留标题层级。
5.3 基础清洗
至少处理:
- 多余空行;
- 连续空格;
- 异常换行;
- 首尾空白;
- 简单重复空白字符。
Demo 不要求复杂页眉页脚识别、OCR 噪声修复、复杂表格恢复和多栏阅读顺序恢复。
5.4 Chunk
第一版策略:
标题 / 章节优先
↓
段落组合
↓
达到约 400~500 tokens
↓
生成 Chunk
↓
Overlap 50~100 tokens
每个 Chunk 至少包含:
chunk_id
document_id
filename
page
section
chunk_index
content
5.5 Embedding
第一版固定使用 bge-large-zh,通过现有百度千帆能力调用。
Demo 阶段不实现多 Embedding Benchmark 平台和动态模型切换,但代码层建议保留简单接口,避免业务逻辑直接写死调用细节。
5.6 Mochow 入库
将 Chunk 写入 Mochow,至少保存:
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
Query
↓
bge-large-zh Embedding
↓
Mochow Dense Search
↓
Top 20 Candidates
第一阶段先验证纯 Dense Retrieval。
5.8 Reranker
Top20
↓
Reranker
↓
Top5
最终返回原始向量分数、Reranker 分数、Chunk 内容和来源信息。
Reranker 是 Demo P0,不建议删除。
5.9 Source Result
每条检索结果至少返回:
document_id
filename
page
section
chunk_id
content
score
rerank_score
UI 必须能够直观看到来源。
6. P0 REST API
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 示例:
{
"query": "产品A退款周期是多少?",
"top_k": 5
}
Search Response 示例:
{
"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
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 清单
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
可选:
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,例如:
产品A退款周期是多少?
员工出差住宿标准是多少?
产品A支持哪些部署方式?
系统出现XX错误应该怎么处理?
每个 Query 人工标记:
expected_document
expected_section
Demo 阶段不要求完整 Benchmark 平台,只需检查 Top5 是否包含正确来源。
13. Demo Definition of Done
Upload
PDF / DOCX / TXT / MD 可以成功上传。
Ingestion
Upload
→ Parse
→ Clean
→ Chunk
→ Embedding
→ Mochow
完整跑通。
Retrieval
Query
→ Embedding
→ Mochow Dense Top20
→ Reranker
→ Top5
完整跑通。
Source
每个结果至少显示:filename、page、section、content。
Search Quality
使用 30~50 个测试 Query,大部分核心问题在 Top5 中能够找到正确文档或章节。
Demo 阶段不设严格生产指标。
UI
非研发用户可以自行完成:
上传文件
→ 等待 Ready
→ 输入问题
→ 查看 Top5 召回结果
14. Codex 开发约束
Codex 当前只能实现 DEMO-001 ~ DEMO-010。
除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、微服务、Kubernetes 和企业级 Job Queue。
当本文件与完整 PRD 的实现优先级冲突时:
docs/demo/DEMO_SCOPE.md优先。
完整 PRD 和总体技术架构仍作为长期演进方向,不应删除或修改其长期目标。
15. 推荐 Codex 初始提示词
当前目标已经从完整 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 后的演进顺序
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