# 企业内部智能知识库 V1 技术方案(简版) > 版本:v0.1 > 目标:完成企业内部知识库第一版本,支持多类型文件上传、自动解析清洗、混合检索、Reranker、权限控制、Knowledge Compilation、REST API、MCP 接入及 Admin Console。 --- ## 1. V1 建设目标 V1 聚焦形成完整可用闭环: ```text 创建知识库 ↓ 上传文件 ↓ 解析 / OCR / 清洗 ↓ 结构化 Chunk ↓ Embedding + BM25 索引 ↓ Hybrid Retrieval ↓ Reranker ↓ ACL 权限过滤 ↓ REST API / MCP ↓ WorkBuddy 等客户端调用 ``` 同时支持第二条知识沉淀链路: ```text 原始知识 Source ↓ 结构化知识 Structured Knowledge ↓ Knowledge Compilation ↓ Wiki / FAQ / SOP / Summary 等派生知识 ↓ 审核、发布、持续更新 ``` --- ## 2. V1 总体架构 ```text ┌─────────────────────┐ │ Admin Console │ └──────────┬──────────┘ │ REST ▼ ┌────────────┐ ┌─────────────────────┐ │ WorkBuddy │──── MCP ────▶│ Knowledge API │◀──── REST ─── Other Systems └────────────┘ │ FastAPI / Python │ └──────────┬──────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────────────────┐ ┌──────────────┐ │ OceanBase MySQL │ │ Object Store │ │ Canonical + Vector │ │ BOS │ │ (logical separation) │ └──────────────┘ └────────────────────────┘ ▲ ▲ │ │ ┌───────┴────────────────────────┘ │ ┌──────────────┐ │ Async Worker │ │ Celery │ └──────┬───────┘ │ ┌──────▼───────┐ │ GPU Worker │ │ Parser/OCR │ │ Embedding │ │ Reranker │ └──────────────┘ ``` ### 架构原则 1. **API First**:后台、MCP、其他业务系统均调用统一 API/Service。 2. **模块化单体优先**:V1 不拆大量微服务,API 服务 + 异步 Worker + MCP Gateway 足够。 3. **Canonical Data 逻辑独立**:OceanBase 关系表 + BOS 保存事实数据,同库向量表仅保存可重建索引。 4. **Provider 可替换**:Embedding、Reranker、Vector DB、Parser、LLM 均通过 Adapter 抽象。 5. **MCP 不暴露底层实现**:客户端只看到 `search_knowledge` 等业务工具。 --- ## 3. 当前技术选型 | 模块 | V1 当前选型 | 说明 | |---|---|---| | Backend | Python + FastAPI | AI / 数据处理生态成熟,适合 MCP、异步任务和模型调用 | | Metadata DB | OceanBase MySQL | 保存用户、权限、文档、版本、任务、Compiled Knowledge 等 Canonical Data | | Object Storage | Baidu BOS | 保存不可变原始文件、解析产物和中间文件;Local Adapter 仅用于测试/本地开发 | | Task Queue | Celery + RabbitMQ | 文件解析、Embedding、索引、Compilation 等异步任务 | | PDF / OCR Parser | MinerU 优先 | 中文复杂 PDF、扫描件、表格、版面解析能力较强 | | Office Parser | Docling 补充 | DOCX/PPTX/XLSX/HTML 等格式统一解析 | | Vector/Search DB | OceanBase Vector | 与关系表同库部署但逻辑隔离,必须通过 `VectorStore` 并可从 canonical Chunk 重建 | | Embedding | Qianfan bge-large-zh | 当前 1024 维基线,后续模型变更使用版本化 Shadow Index | | Reranker | Qianfan bce-reranker-base | 当前 Dense Top20 → Reranker Top5 基线 | | LLM | Provider 抽象,云端优先 | 用于 Knowledge Compilation、分类、摘要等 | | MCP | 独立 MCP Gateway | 面向 WorkBuddy 等客户端,隐藏内部技术栈 | | Frontend | Admin Console | 知识库、文档、权限、检索调试、Benchmark、任务管理 | --- ## 4. 核心模块 ### 4.1 Knowledge Base 管理 支持: - 创建 / 编辑 / 归档知识库; - Folder 分类; - Owner / Member; - 知识库级和文档级权限; - Retrieval Profile; - Embedding / Reranker 配置; - Knowledge Compilation 配置。 --- ### 4.2 文件上传与自动入库 V1 支持: - PDF - DOCX - PPTX - XLSX - CSV - Markdown - TXT - HTML - JPG / PNG 处理流程: ```text Upload → Hash 去重 → Parser Router → OCR(必要时) → Cleaning → Structure Normalize → Chunk → Embedding → BM25 / Vector Index → Completed ``` 任务状态: ```text Queued / Parsing / Cleaning / Chunking / Embedding / Indexing / Completed / Failed ``` 文件必须支持: - Hash 去重; - Document Version; - 失败重试; - Re-parse / Re-embed / Re-index; - 软删除; - 来源页码和章节追踪。 ### 4.2.1 批量异步提交与失败恢复 API 只负责校验并持久化不可变源文件、Document 和 Ingestion Job,然后返回 `202`。批次是 提交与聚合查询边界,不是跨文件数据库事务;每个文件独立排队、执行和失败。 DEMO-016 以 canonical `ingestion_batches` / `ingestion_batch_items` 保存输入顺序和接收引用; 处理阶段、Attempt 与最终结果继续以 `ingestion_jobs` / `ingestion_attempts` 为事实源,批次表 不复制 Worker 状态。 ```text Batch Request ├─ Source A + Document A + Job A ─→ Worker ├─ Source B + Document B + Job B ─→ Worker └─ Source C + Document C + Job C ─→ Worker ``` Worker 对可重试错误执行有界退避。重新执行前必须通过独立的派生数据清理服务按以下顺序 恢复干净状态: ```text Vector/Sparse rows → ChunkIndexState → Chunks → Parsed artifact + parsed_storage_key → reset processing state → next attempt from immutable source ``` 清理服务与 Document 删除语义分离:重试清理保留原始 BOS 对象、Document 和 Job/Attempt 历史。清理失败时 Job 终止,不能在未知状态继续执行。Job 通过数据库状态、唯一有效 Attempt 和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。 公共知识库集群交付阶段由 Celery/RabbitMQ 作为首个生产执行器。API 只调用队列执行器抽象, Celery task 只负责恢复应用上下文并调用 Ingestion Application Service;重试分类、Attempt 状态、 清理顺序和业务幂等仍由应用层持有。Broker 消息不是 Job 的 source of truth,Worker 重启或消息 重复投递必须以 OceanBase 中的持久化 Job/Attempt 状态收敛。 DEPLOY-001 将 API/Admin、MCP Gateway 与 Async Worker 构建为三个共享锁定 Python 运行时的 非 root 镜像 target;进程边界与上述模块边界一致,不新增服务或把 Provider 配置烘焙进镜像。 --- ### 4.3 文档结构与 Chunk 解析后形成统一结构: ```text Document ├─ Heading ├─ Paragraph ├─ List ├─ Table └─ Page ``` Chunk 采用 **Structure-aware + Token-aware** 策略,禁止仅按固定字符数粗暴截断。 Chunk 至少保存: ```text chunk_id knowledge_base_id document_id document_version content title section_path page_start page_end content_type metadata acl index_profile_id ``` --- ## 5. 检索方案 V1 正式检索链: ```text Query ↓ Query Normalize ↓ ACL Resolve ↓ Dense Search + BM25 ↓ Fusion ↓ Candidate Top N ↓ Reranker ↓ Top K ↓ Source Enrichment ``` ### 必须支持 - Dense Semantic Search; - BM25 / Keyword Search; - Hybrid Search; - Metadata Filter; - ACL Filter; - Reranker; - Knowledge Base / Folder / Document Scope; - 来源追踪。 禁止使用“全局检索后再删除无权限结果”的方式,权限过滤必须在召回阶段生效。 --- ## 6. Embedding Benchmark V1 不锁死单一 Embedding 模型。 ### 首批候选 - bge-large-zh(现有基线); - Qwen3-Embedding-0.6B; - Qwen3-Embedding-4B; - 视 GPU 与效果补充 8B 或其他中文模型。 ### Benchmark 指标 ```text Recall@1 / 3 / 5 / 10 MRR NDCG@10 P50 / P95 Latency Index Throughput GPU Memory API Cost Storage Cost ``` ### 测试集 建立企业内部 Golden Dataset,V1 建议 200~500 条真实查询,覆盖: - 中文自然语言; - 精确术语 / 编号; - 产品型号; - 同义表达; - 中英文混写; - 长问题; - 多条件问题; - 跨文档问题。 最终比较的是完整 Pipeline: ```text Embedding × Hybrid Retrieval × Reranker ``` 而不是只比较 Embedding 排行榜。 --- ## 7. Index Profile 与模型切换 Embedding、Chunk、Sparse、Reranker 配置统一形成 `IndexProfile`。 示例: ```text profile_v1 - chunk_strategy: structure_v1 - embedding: bge-large-zh - sparse: bm25 profile_v2 - chunk_strategy: structure_v2 - embedding: qwen3-embedding-4b - sparse: bm25 ``` 新模型上线时: ```text 创建新 Profile → 构建 Shadow Index → Benchmark → 切换 Active Index → 保留旧索引回滚窗口 ``` 避免直接原地覆盖现有生产索引。 ARCH-005/006 将 Profile 生命周期以 `shadow / active / retired` 记录在 OceanBase 关系表;任一时刻至多 一个 Active Profile。重建从 canonical Chunk 生成确定性 `chunk_id + profile_id` 索引行, 重复执行跳过已完整文档,激活前重新核对全部 ChunkIndexState,并在同一事务内锁定 Chunk 写入、退役旧 Profile、激活新 Profile。OceanBase 表本身仍不是 canonical source。 --- ## 8. Vector Store 设计 ### 当前默认:OceanBase Vector 选择理由: - 公司现有知识平台主链已有使用经验; - 可复用现有 OceanBase 运维体系; - 支持 Dense Vector; - 支持 Metadata / Scalar Filter; - 满足当前 Demo 的 Profile 过滤和后续 ACL 下推边界; - `pyobvector` 仅允许出现在 Provider Adapter 内。 BM25/Hybrid 仍是 V1 产品能力,但不在本轮 Provider 迁移中提前扩展;相关实现必须经 独立 Task、契约测试和 RAG 回归后启用。 ### 保留替换能力 统一: ```text VectorStoreProvider ├─ OceanBase Vector (Primary) ├─ Mochow ├─ Qdrant ├─ Milvus └─ pgvector ``` 业务 Domain Model 不依赖 OceanBase/`pyobvector` SDK 数据结构。 OceanBase Vector 表中的数据全部视为 **可重建索引**。同一数据库的关系表保存文档、Chunk、 Profile 和索引状态等 canonical 数据,BOS 保存不可变原始文件和派生产物。物理共库不允许 向量表反向成为业务事实来源。 --- ## 9. Knowledge Compilation V1 支持 **RAG + Knowledge Compilation**。 三层知识模型: ```text L0 Source 原始文件,不允许 AI 修改 L1 Structured Parsed / Chunk / Index L2 Compiled Wiki / FAQ / SOP / Summary / Comparison ``` ### Compilation Pipeline ```text Source 新增或更新 → Impact Analysis → 查找相关 Knowledge Page → LLM 生成 Draft → Source Verification → Conflict Detection → Review Required → Publish ``` ### Compiled Knowledge 类型 - Wiki Page; - FAQ; - SOP; - Summary; - Concept; - Entity; - Comparison。 所有 L2 Knowledge 必须保存 underlying source,并可追溯至 L0。 Source 删除、更新或权限变化时,相关 Compiled Knowledge 自动标记 `Stale`。 V1 默认 AI 只生成 Draft,重要知识需人工审核后发布。 --- ## 10. 权限模型 权限主体: ```text User Group Role ``` 资源层级: ```text Organization Knowledge Base Folder Document ``` 权限类型: ```text Read Write Manage ``` 检索流程: ```text User Identity → Permission Resolver → Allowed Scope / ACL Filter → Provider-neutral Retrieval(OceanBase Vector 当前实现) ``` MCP / REST / Admin Console 必须复用同一权限服务。 --- ## 11. MCP 对外提供统一: ```text Enterprise Knowledge MCP Server ``` V1 建议工具: ### `search_knowledge` 搜索当前用户有权限访问的企业知识。 ### `get_document` 读取文档 metadata。 ### `get_document_section` 获取指定页 / Section / Chunk 的连续上下文。 ### `get_source` 获取检索结果的来源信息。 ### `list_knowledge_bases` 列出当前身份可访问的知识库。 MCP Response 不出现: ```text OceanBase Vector BOS Qdrant bge-large-zh Qwen3 MinerU ``` 等底层实现信息。 首要验证客户端:**WorkBuddy Enterprise**。 ### 11.1 DEMO-012 实现边界 当前已落地独立 Streamable HTTP Gateway,默认只绑定 `127.0.0.1:8766/mcp`,只注册 `search_knowledge`。Gateway 与 REST 共享 `SearchService`,同步检索通过工作线程执行,避免 阻塞 MCP ASGI 事件循环。 Demo 使用运行时专用 Bearer Token 映射到 client/service identity 和最小 `knowledge:search` scope,并启用 Host/Origin allowlist。该边界用于 WorkBuddy 接入验证, 后续 `EKP-070` 仍需用正式 OAuth/企业身份系统和 Permission Resolver 替换静态 Token; `DEMO-012` 不改变 ADR-007 的 ACL 要求。 --- ## 12. REST API 统一前缀: ```text /api/v1/ ``` 主要 Domain: ```text /auth /users /groups /knowledge-bases /documents /compiled-knowledge /search /evaluations /jobs /audit-logs /providers /mcp ``` 核心搜索接口: ```http POST /api/v1/search ``` 返回至少包含: ```text request_id results source score rerank_score document page section chunk_id source_type ``` --- ## 13. Admin Console V1 一级功能建议: ```text Overview Knowledge Bases Documents Compiled Knowledge Search Lab Evaluation Models MCP & API Users & Permissions Jobs Audit Logs System Settings ``` ### Search Lab Search Lab 是 V1 P0 工具,用于查看: ```text Dense Recall Sparse Recall Fusion Reranker Final Result ``` 帮助定位 Parser、Chunk、Embedding、BM25、Reranker 哪一层出现问题。 --- ## 14. 异步任务与 GPU 异步 Job: ```text ParseJob OCRJob ChunkJob EmbeddingJob IndexJob CompilationJob ReindexJob EvaluationJob ``` 当前增量实现先提供单个 `IngestionJob` 编排既有 Parse/Clean/Chunk/Embedding/Indexing 阶段, 保留阶段级状态和 Attempt 历史;以后拆分为独立阶段 Job 时不得改变公开批次/Job 查询契约。 Demo 默认最多 3 次总尝试,只有瞬时 Provider、网络、存储或数据库错误进入自动重试;输入 校验和确定性内容错误直接终止。 GPU 节点优先承担: - MinerU / OCR; - Local Embedding; - Local Reranker。 LLM V1 可继续使用云端 Provider,不要求部署本地大模型。 --- ## 15. 数据存储原则 ### OceanBase MySQL 关系表 保存: - User / Group / Role; - Knowledge Base; - Document / Version; - Chunk metadata; - ACL; - Job; - Index Profile; - Compiled Knowledge; - Audit Log; - Provider Config。 ### Object Storage 保存: - 原始文件; - Parser 输出; - OCR 结果; - Markdown / JSON 中间产物; - 需要持久化的大对象。 ### OceanBase Vector 仅保存: - Dense Vector; - Retrieval metadata; - Profile/ACL 所需过滤字段; - 经独立能力验证后启用的 Sparse/BM25 索引。 数据库损坏或更换时,可由 Canonical Data 全量重建。 --- ## 16. 部署建议 V1 推荐按以下逻辑角色部署: ```text Reverse Proxy / Ingress │ ├─ Admin Console ├─ Knowledge API └─ MCP Gateway OceanBase MySQL(Canonical + Vector,逻辑隔离) RabbitMQ Baidu BOS CPU Worker GPU Worker Observability ``` 当前几十~百人内部用户规模,不建议一开始拆大量微服务。 优先采用: ```text 模块化单体 API + 独立 Async Worker + 独立 GPU Worker + 独立 MCP Gateway ``` 未来根据负载再拆服务。 ### 16.1 当前公共知识库集群交付基线 PLAN-002 将当前交付范围收敛为企业受控网络内的单一公共知识可见域。该范围不重开 ADR-007: 所有现有文档共享同一可见性,因而当前检索不执行事后 ACL 过滤;接收任何非公共知识前,必须 先实现 Permission Resolver 和数据库/向量检索前置过滤。Admin 写接口不得直接暴露到匿名公网, MCP 使用运行时 Secret 注入的最小 `knowledge:search` 服务身份。 集群中 API/Admin、MCP Gateway 和 Async Worker 分别部署并独立扩缩容,业务核心继续保持模块化 单体。当前 Parser 及云端 Embedding/Reranker 不需要 GPU Worker,因此它不进入最小交付,但角色 边界保留。OceanBase、BOS 和 AI Provider 使用外部服务;RabbitMQ 默认使用外部地址,可为开发/ 演示显式启用 Chart 依赖。 Kubernetes/Helm 必须提供:生产镜像、`existingSecret`、串行 Migration Job、Ingress/TLS、 readiness/liveness、资源限制、非 root 与只读根文件系统、多副本和滚动更新。仓库的一键入口只 编排已有集群和外部服务,不创建云账号或把凭据写入 Values、镜像、命令行及日志。现有 `docker-compose.dev.yml` 包含已被 ADR-012 取代的 PostgreSQL/MinIO 假设,只能视为待清理的 本地开发资产,不能作为集群模板。详细依赖和验收见 [`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。 DEPLOY-002 的运行拓扑将 Celery Worker 与 Celery Beat 恢复调度器拆成独立 Pod:Worker 可横向 扩缩,Beat 固定单副本并使用 `Recreate`,避免每个 Worker 都发布周期恢复消息。二者仍调用同一 应用服务与持久化 Job/Attempt 状态,不形成新业务服务,也不改变 ADR-002。Migration 使用 Helm `pre-install,pre-upgrade` Hook;失败会在业务 Deployment 更新前终止原子升级。 --- ## 17. V1 验收重点 ### 文件入库 P0 文件能够完成: ```text Upload → Parse → Clean → Chunk → Embed → Index ``` ### 检索 正式链路支持: ```text Dense + BM25 + Hybrid + Reranker + ACL ``` ### 来源 每条结果能够追踪: ```text Source File → Version → Page → Section → Chunk ``` ### 权限 Admin Console、REST、MCP 均不能访问无权限知识。 ### Benchmark 能够使用同一个 Golden Dataset 对多套 Retrieval Pipeline 进行对比。 ### Knowledge Compilation 能够完成: ```text Source → Draft → Source Linking → Review → Publish → Stale Detection ``` ### MCP WorkBuddy 可以通过 MCP 完成知识搜索和 Source 获取。 --- ## 18. V1 当前最终选型结论 ```text Backend Python + FastAPI Metadata OceanBase MySQL relational tables Object Storage Baidu BOS(Local Adapter 仅测试/本地开发) Queue RabbitMQ + Celery Parser MinerU 主力 + Docling 补充 Vector Store OceanBase Vector Primary,Adapter 可替换,索引可重建 Embedding Qianfan bge-large-zh(1024 维) Reranker Qianfan bce-reranker-base,Dense Top20 → Top5 LLM Provider 抽象,允许云端 Frontend Admin Console Protocol REST API + MCP Architecture Modular Monolith + Workers + MCP Gateway Knowledge RAG + Knowledge Compilation ``` 核心原则:**先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。**