# 企业内部智能知识库 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 │ └──────────┬──────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ PostgreSQL │ │ Object Store │ │ Mochow │ │ Canonical DB │ │ S3/MinIO │ │ Search Index │ └──────────────┘ └──────────────┘ └──────────────┘ ▲ ▲ │ │ ┌───────┴────────────────────────┘ │ ┌──────────────┐ │ Async Worker │ │ Celery │ └──────┬───────┘ │ ┌──────▼───────┐ │ GPU Worker │ │ Parser/OCR │ │ Embedding │ │ Reranker │ └──────────────┘ ``` ### 架构原则 1. **API First**:后台、MCP、其他业务系统均调用统一 API/Service。 2. **模块化单体优先**:V1 不拆大量微服务,API 服务 + 异步 Worker + MCP Gateway 足够。 3. **Canonical Data 独立**:PostgreSQL + 对象存储保存事实数据,Vector DB 仅保存可重建索引。 4. **Provider 可替换**:Embedding、Reranker、Vector DB、Parser、LLM 均通过 Adapter 抽象。 5. **MCP 不暴露底层实现**:客户端只看到 `search_knowledge` 等业务工具。 --- ## 3. 当前技术选型 | 模块 | V1 当前选型 | 说明 | |---|---|---| | Backend | Python + FastAPI | AI / 数据处理生态成熟,适合 MCP、异步任务和模型调用 | | Metadata DB | PostgreSQL | 保存用户、权限、文档、版本、任务、Compiled Knowledge 等 Canonical Data | | Object Storage | S3 Compatible / MinIO | 保存原始文件、解析产物、中间文件 | | Task Queue | Celery + RabbitMQ | 文件解析、Embedding、索引、Compilation 等异步任务 | | PDF / OCR Parser | MinerU 优先 | 中文复杂 PDF、扫描件、表格、版面解析能力较强 | | Office Parser | Docling 补充 | DOCX/PPTX/XLSX/HTML 等格式统一解析 | | Vector/Search DB | Mochow | 延续公司现有经验,支持向量、BM25、Hybrid、Filter | | Embedding | 多模型 Benchmark 决定 | 基线 bge-large-zh,对比 Qwen3 Embedding 等 | | Reranker | Qwen3 Reranker 等候选 | V1 正式检索链必选能力 | | 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.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 → 保留旧索引回滚窗口 ``` 避免直接原地覆盖现有生产索引。 --- ## 8. Vector Store 设计 ### 当前默认:Mochow 选择理由: - 公司已有使用经验; - 已有百度云体系; - 支持 Dense Vector; - 支持 BM25 / Full Text; - 支持 Hybrid Search; - 支持 Metadata / Scalar Filter; - 满足 V1 ACL 下推需求。 ### 保留替换能力 统一: ```text VectorStoreProvider ├─ Mochow ├─ Qdrant ├─ Milvus └─ pgvector ``` 业务 Domain Model 不依赖 Mochow SDK 数据结构。 Mochow 中的数据全部视为 **可重建索引**,真实 Canonical Data 保存在 PostgreSQL / Object Storage。 --- ## 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 → Mochow Hybrid Retrieval ``` 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 Mochow Qdrant bge-large-zh Qwen3 MinerU ``` 等底层实现信息。 首要验证客户端:**WorkBuddy Enterprise**。 --- ## 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 ``` GPU 节点优先承担: - MinerU / OCR; - Local Embedding; - Local Reranker。 LLM V1 可继续使用云端 Provider,不要求部署本地大模型。 --- ## 15. 数据存储原则 ### PostgreSQL 保存: - 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 中间产物; - 需要持久化的大对象。 ### Mochow 仅保存: - Dense Vector; - Sparse/BM25 Index; - Retrieval metadata; - ACL 所需过滤字段。 数据库损坏或更换时,可由 Canonical Data 全量重建。 --- ## 16. 部署建议 V1 推荐按以下逻辑角色部署: ```text Reverse Proxy / Ingress │ ├─ Admin Console ├─ Knowledge API └─ MCP Gateway PostgreSQL RabbitMQ Object Storage CPU Worker GPU Worker Mochow Observability ``` 当前几十~百人内部用户规模,不建议一开始拆大量微服务。 优先采用: ```text 模块化单体 API + 独立 Async Worker + 独立 GPU Worker + 独立 MCP Gateway ``` 未来根据负载再拆服务。 --- ## 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 PostgreSQL Object Storage S3 Compatible / MinIO Queue RabbitMQ + Celery Parser MinerU 主力 + Docling 补充 Vector Store Mochow Primary,Adapter 可替换 Embedding bge-large-zh 基线,多模型 Benchmark 后决定生产模型 Reranker Qwen3 Reranker 等候选,V1 必选 LLM Provider 抽象,允许云端 Frontend Admin Console Protocol REST API + MCP Architecture Modular Monolith + Workers + MCP Gateway Knowledge RAG + Knowledge Compilation ``` 核心原则:**先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。**