2026-09-02 20:42:52 +08:00

20 KiB
Raw Permalink Blame History

企业内部智能知识库 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     │
                        └──────────────┘

架构原则

  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

处理流程:

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。批次是 提交与聚合查询边界,不是跨文件数据库事务;每个文件独立排队、执行和失败。

DEMO-016 以 canonical ingestion_batches / ingestion_batch_items 保存输入顺序和接收引用; 处理阶段、Attempt 与最终结果继续以 ingestion_jobs / ingestion_attempts 为事实源,批次表 不复制 Worker 状态。

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 和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。

公共知识库集群交付阶段由 Celery/RabbitMQ 作为首个生产执行器。API 只调用队列执行器抽象, Celery task 只负责恢复应用上下文并调用 Ingestion Application Service;重试分类、Attempt 状态、 清理顺序和业务幂等仍由应用层持有。Broker 消息不是 Job 的 source of truth,Worker 重启或消息 重复投递必须以 OceanBase 中的持久化 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

未来根据负载再拆服务。

16.1 当前公共知识库集群交付基线

PLAN-002 将当前交付范围收敛为企业受控网络内的单一公共知识可见域。该范围不重开 ADR-007: 所有现有文档共享同一可见性,因而当前检索不执行事后 ACL 过滤;接收任何非公共知识前,必须 先实现 Permission Resolver 和数据库/向量检索前置过滤。Admin 写接口不得直接暴露到匿名公网, MCP 使用运行时 Secret 注入的最小 knowledge:search 服务身份。

集群中 API/Admin、MCP Gateway 和 Async Worker 分别部署并独立扩缩容,业务核心继续保持模块化 单体。当前 Parser 及云端 Embedding/Reranker 不需要 GPU Worker,因此它不进入最小交付,但角色 边界保留。OceanBase、BOS 和 AI Provider 使用外部服务;RabbitMQ 默认使用外部地址,可为开发/ 演示显式启用 Chart 依赖。

Kubernetes/Helm 必须提供:生产镜像、existingSecret、串行 Migration Job、Ingress/TLS、 readiness/liveness、资源限制、非 root 与只读根文件系统、多副本和滚动更新。仓库的一键入口只 编排已有集群和外部服务,不创建云账号或把凭据写入 Values、镜像、命令行及日志。现有 docker-compose.dev.yml 包含已被 ADR-012 取代的 PostgreSQL/MinIO 假设,只能视为待清理的 本地开发资产,不能作为集群模板。详细依赖和验收见 PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md。


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

核心原则:先保证知识可正确解析、可靠检索、严格授权、完整追溯,再逐步增加更高级的知识编译和智能化能力。