knowledge-platform/docs/demo/DEMO_SCOPE.md

11 KiB
Raw Blame History

EKP Knowledge Retrieval Demo v0.1

1. 文档目的

本文档定义 Enterprise Knowledge Platform(EKP)第一阶段 Demo 的最小实现范围。

该 Demo 的目标不是完成完整企业级知识平台,而是优先验证最核心的技术闭环:

文件上传 → 文档解析/清洗 → Chunk → Embedding → OceanBase Vector 入库 → 检索召回 → Reranker → 来源返回 → 简单管理页面

当前 Demo Scope 的优先级高于完整 V1 PRD。

在 Demo 阶段,除非本文件明确要求,否则不得因为完整 PRD 中存在某项能力而提前实现。


2. Demo 核心目标

验证以下关键问题:

  1. 中文企业文档是否能够稳定上传和解析;
  2. 清洗后的内容是否可以形成质量可接受的 Chunk;
  3. 使用现有 Embedding + OceanBase Vector 能否完成稳定召回;
  4. Reranker 是否能提升最终 TopK 结果质量;
  5. 检索结果是否能够准确返回文件名、页码、章节和原文;
  6. 非研发人员是否能够通过简单页面完成上传和检索验证。

Demo 成功标准不是“企业级能力完备”,而是:

核心知识入库和召回链路可用,并具备继续扩展为正式产品的基础。


3. Demo 最小架构

Admin Web
   │
   ↓
FastAPI
   │
   ├── Document Upload
   │      ↓
   │    Parser
   │      ↓
   │    Cleaner
   │      ↓
   │    Chunker
   │      ↓
   │    Embedding
   │      ↓
   │    OceanBase Vector
   │
   └── Search
          ↓
       Query Embedding
          ↓
       OceanBase Vector TopN
          ↓
       Reranker
          ↓
        TopK
          ↓
     Source Enrichment

辅助存储:

SQLite / PostgreSQL
    └── document / chunk metadata

Local Storage / BOS
    └── original files

Demo 阶段优先简单实现,不引入不必要的基础设施。


4. 当前推荐技术选型

模块 Demo 推荐选型 说明
Backend FastAPI 简单、开发效率高
Metadata DB SQLite 或 PostgreSQL 单机 Demo 可 SQLite;已有环境可直接 PostgreSQL
File Storage 百度 BOS Local Adapter 仅用于测试和本地开发,目标环境使用 BOS
Parser PyMuPDF + python-docx 或 MinerU 优先快速跑通;复杂 PDF 后续增强
Cleaner 自定义基础清洗 处理空行、空白、异常换行等
Chunker 标题/段落优先 + Token 限制 暂不设计复杂 Chunk 策略
Embedding bge-large-zh 延续公司现有百度千帆方案
Vector DB OceanBase Vector 当前默认,通过 VectorStore 隔离 SDK,不做多数据库运行时切换
Reranker bce-reranker-base 延续当前可调用的千帆 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

第一版策略:

标题 / 章节优先
      ↓
段落组合
      ↓
达到约 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 OceanBase Vector 入库

将 Chunk 写入 OceanBase Vector 专用索引表,至少保存:

chunk_id
document_id
filename
page
section
content
embedding

支持:Upsert、按 document_id 删除相关 Chunk、Dense Search。

Demo 阶段不实现 Qdrant/Milvus/pgvector,也不实现多 Vector Store 动态切换,但避免 OceanBase/pyobvector 调用散落在整个项目中。OceanBase Vector 行仍是可重建索引,不能替代 PostgreSQL canonical Chunk。

5.7 Dense Retrieval

Query
  ↓
bge-large-zh Embedding
  ↓
OceanBase Vector 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 阶段删除可以直接执行:删除 BOS/本地原始文件 + 删除 Metadata + 删除 OceanBase Vector 对应 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 可选增强

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 入库(将由 ARCH-003 迁移)
DEMO-007 Dense Retrieval
DEMO-008 Reranker + Source Result
DEMO-009 Document/Search REST API
DEMO-010 简单 Admin Console
ARCH-001~006 Provider 架构迁移与真实验收

可选:

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
→ OceanBase Vector

完整跑通。

Retrieval

Query
→ Embedding
→ OceanBase Vector 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 和已批准的 ARCH-001 ~ ARCH-006。 ARCH 迁移任务不授权实现下列被排除的完整 V1 能力。

除非明确要求,否则禁止提前实现权限、审计、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 以及本文件明确列出的 ARCH-001 ~ ARCH-006。
Provider 架构迁移任务按顺序完成后,再继续 DEMO-010。

当前 Demo 的目标只有:

Upload
→ Parse/Clean
→ Chunk
→ bge-large-zh
→ OceanBase Vector
→ 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 与 ARCH-001 ~ ARCH-006 的建议执行顺序;
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