17 KiB
企业内部智能知识库 V1 技术方案(简版)
版本:v0.1
目标:完成企业内部知识库第一版本,支持多类型文件上传、自动解析清洗、混合检索、Reranker、权限控制、Knowledge Compilation、REST API、MCP 接入及 Admin Console。
1. V1 建设目标
V1 聚焦形成完整可用闭环:
创建知识库
↓
上传文件
↓
解析 / OCR / 清洗
↓
结构化 Chunk
↓
Embedding + BM25 索引
↓
Hybrid Retrieval
↓
Reranker
↓
ACL 权限过滤
↓
REST API / MCP
↓
WorkBuddy 等客户端调用
同时支持第二条知识沉淀链路:
原始知识 Source
↓
结构化知识 Structured Knowledge
↓
Knowledge Compilation
↓
Wiki / FAQ / SOP / Summary 等派生知识
↓
审核、发布、持续更新
2. V1 总体架构
┌─────────────────────┐
│ 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 │
└──────────────┘
架构原则
- API First:后台、MCP、其他业务系统均调用统一 API/Service。
- 模块化单体优先:V1 不拆大量微服务,API 服务 + 异步 Worker + MCP Gateway 足够。
- Canonical Data 逻辑独立:OceanBase 关系表 + BOS 保存事实数据,同库向量表仅保存可重建索引。
- Provider 可替换:Embedding、Reranker、Vector DB、Parser、LLM 均通过 Adapter 抽象。
- 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 支持:
- DOCX
- PPTX
- XLSX
- CSV
- Markdown
- TXT
- HTML
- JPG / PNG
处理流程:
Upload
→ Hash 去重
→ Parser Router
→ OCR(必要时)
→ Cleaning
→ Structure Normalize
→ Chunk
→ Embedding
→ BM25 / Vector Index
→ Completed
任务状态:
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。批次是
提交与聚合查询边界,不是跨文件数据库事务;每个文件独立排队、执行和失败。
Batch Request
├─ Source A + Document A + Job A ─→ Worker
├─ Source B + Document B + Job B ─→ Worker
└─ Source C + Document C + Job C ─→ Worker
Worker 对可重试错误执行有界退避。重新执行前必须通过独立的派生数据清理服务按以下顺序 恢复干净状态:
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 和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。
4.3 文档结构与 Chunk
解析后形成统一结构:
Document
├─ Heading
├─ Paragraph
├─ List
├─ Table
└─ Page
Chunk 采用 Structure-aware + Token-aware 策略,禁止仅按固定字符数粗暴截断。
Chunk 至少保存:
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 正式检索链:
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 指标
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:
Embedding × Hybrid Retrieval × Reranker
而不是只比较 Embedding 排行榜。
7. Index Profile 与模型切换
Embedding、Chunk、Sparse、Reranker 配置统一形成 IndexProfile。
示例:
profile_v1
- chunk_strategy: structure_v1
- embedding: bge-large-zh
- sparse: bm25
profile_v2
- chunk_strategy: structure_v2
- embedding: qwen3-embedding-4b
- sparse: bm25
新模型上线时:
创建新 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 回归后启用。
保留替换能力
统一:
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。
三层知识模型:
L0 Source
原始文件,不允许 AI 修改
L1 Structured
Parsed / Chunk / Index
L2 Compiled
Wiki / FAQ / SOP / Summary / Comparison
Compilation Pipeline
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. 权限模型
权限主体:
User
Group
Role
资源层级:
Organization
Knowledge Base
Folder
Document
权限类型:
Read
Write
Manage
检索流程:
User Identity
→ Permission Resolver
→ Allowed Scope / ACL Filter
→ Provider-neutral Retrieval(OceanBase Vector 当前实现)
MCP / REST / Admin Console 必须复用同一权限服务。
11. MCP
对外提供统一:
Enterprise Knowledge MCP Server
V1 建议工具:
search_knowledge
搜索当前用户有权限访问的企业知识。
get_document
读取文档 metadata。
get_document_section
获取指定页 / Section / Chunk 的连续上下文。
get_source
获取检索结果的来源信息。
list_knowledge_bases
列出当前身份可访问的知识库。
MCP Response 不出现:
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
统一前缀:
/api/v1/
主要 Domain:
/auth
/users
/groups
/knowledge-bases
/documents
/compiled-knowledge
/search
/evaluations
/jobs
/audit-logs
/providers
/mcp
核心搜索接口:
POST /api/v1/search
返回至少包含:
request_id
results
source
score
rerank_score
document
page
section
chunk_id
source_type
13. Admin Console
V1 一级功能建议:
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 工具,用于查看:
Dense Recall
Sparse Recall
Fusion
Reranker
Final Result
帮助定位 Parser、Chunk、Embedding、BM25、Reranker 哪一层出现问题。
14. 异步任务与 GPU
异步 Job:
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 推荐按以下逻辑角色部署:
Reverse Proxy / Ingress
│
├─ Admin Console
├─ Knowledge API
└─ MCP Gateway
OceanBase MySQL(Canonical + Vector,逻辑隔离)
RabbitMQ
Baidu BOS
CPU Worker
GPU Worker
Observability
当前几十~百人内部用户规模,不建议一开始拆大量微服务。
优先采用:
模块化单体 API
+ 独立 Async Worker
+ 独立 GPU Worker
+ 独立 MCP Gateway
未来根据负载再拆服务。
17. V1 验收重点
文件入库
P0 文件能够完成:
Upload → Parse → Clean → Chunk → Embed → Index
检索
正式链路支持:
Dense + BM25 + Hybrid + Reranker + ACL
来源
每条结果能够追踪:
Source File → Version → Page → Section → Chunk
权限
Admin Console、REST、MCP 均不能访问无权限知识。
Benchmark
能够使用同一个 Golden Dataset 对多套 Retrieval Pipeline 进行对比。
Knowledge Compilation
能够完成:
Source → Draft → Source Linking → Review → Publish → Stale Detection
MCP
WorkBuddy 可以通过 MCP 完成知识搜索和 Source 获取。
18. V1 当前最终选型结论
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
核心原则:先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。