750 lines
14 KiB
Markdown
Raw Permalink 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 │
└──────────┬──────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 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
```
核心原则:**先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。**