15 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 │
└──────────┬──────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Object Store │ │ OceanBase │
│ Canonical DB │ │ BOS │ │ Vector Index │
└──────────────┘ └──────────────┘ └──────────────┘
▲ ▲
│ │
┌───────┴────────────────────────┘
│
┌──────────────┐
│ Async Worker │
│ Celery │
└──────┬───────┘
│
┌──────▼───────┐
│ GPU Worker │
│ Parser/OCR │
│ Embedding │
│ Reranker │
└──────────────┘
架构原则
- API First:后台、MCP、其他业务系统均调用统一 API/Service。
- 模块化单体优先:V1 不拆大量微服务,API 服务 + 异步 Worker + MCP Gateway 足够。
- Canonical Data 独立:PostgreSQL + 对象存储保存事实数据,Vector DB 仅保存可重建索引。
- Provider 可替换:Embedding、Reranker、Vector DB、Parser、LLM 均通过 Adapter 抽象。
- MCP 不暴露底层实现:客户端只看到
search_knowledge等业务工具。
3. 当前技术选型
| 模块 | V1 当前选型 | 说明 |
|---|---|---|
| Backend | Python + FastAPI | AI / 数据处理生态成熟,适合 MCP、异步任务和模型调用 |
| Metadata DB | PostgreSQL | 保存用户、权限、文档、版本、任务、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 隔离并可从 PostgreSQL 重建 |
| 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.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 将 Profile 生命周期以 shadow / active / retired 记录在 PostgreSQL;任一时刻至多
一个 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 中的数据全部视为 可重建索引。PostgreSQL 保存文档、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。
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
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 中间产物;
- 需要持久化的大对象。
OceanBase Vector
仅保存:
- Dense Vector;
- Retrieval metadata;
- Profile/ACL 所需过滤字段;
- 经独立能力验证后启用的 Sparse/BM25 索引。
数据库损坏或更换时,可由 Canonical Data 全量重建。
16. 部署建议
V1 推荐按以下逻辑角色部署:
Reverse Proxy / Ingress
│
├─ Admin Console
├─ Knowledge API
└─ MCP Gateway
PostgreSQL
RabbitMQ
Baidu BOS
CPU Worker
GPU Worker
OceanBase Vector
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 PostgreSQL
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
核心原则:先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。