# 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