2026-09-02 16:39:26 +08:00

804 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 企业内部智能知识库 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`。批次是
提交与聚合查询边界,不是跨文件数据库事务;每个文件独立排队、执行和失败。
```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
和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。
---
### 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
```
未来根据负载再拆服务。
---
## 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
```
核心原则:**先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。**