MBE系统处理知识库全流程

📋 流程概览

MBE系统处理知识库的完整流程包括以下阶段：

创建知识库 → 上传文档 → 文档处理 → 文本提取 → 质量评估 → 分块处理 → 向量化 → AI分析 → 索引构建 → 知识库就绪 → [必须：专家模型训练]

关键顺序（CRITICAL SEQUENCE）：以上步骤构成必须按顺序执行的链条，不可跳过或颠倒。例如：未创建知识库不能上传；未就绪不能训练；生产环境必须完成专家模型训练。扩展应用（API 校验、UI 引导、对话逻辑）见 → MBE_CRITICAL_SEQUENCE_AND_USER_GUIDANCE.md。

🔄 详细流程

阶段1: 创建知识库

状态: pending（等待上传文件）

流程:

1. 用户填写知识库信息（名称、描述、分块大小、重叠大小等）
2. 前端调用 POST /admin/knowledge/create API
3. 后端创建知识库对象，保存到 index.json
4. 返回知识库ID和基本信息

关键配置:

• chunk_size: 分块大小（默认1000 tokens）
• chunk_overlap: 重叠大小（默认200 tokens）
• chunk_strategy: 分块策略（smart/fixed/sentence）
• enable_embedding: 是否启用向量化
• embedding_model: 向量模型名称

阶段2: 文档上传

上传方式:

1. 单文件上传: 拖放或选择文件
2. 批量上传: 选择多个文件或整个文件夹
3. 分块上传: 大文件（>50MB）使用断点续传

API端点:

• POST /admin/knowledge/upload/{kb_id} - 单文件上传
• POST /admin/knowledge/upload-batch/{kb_id} - 批量上传
• POST /admin/knowledge/upload-chunk/init/{kb_id} - 初始化分块上传

处理策略:

• 小文件（≤5MB）: 同步处理，立即返回结果
• 大文件（>5MB）: 异步处理，使用消息队列（Celery）或后台任务

状态变化: pending → processing

阶段3: 文档处理（核心流程）

3.1 文件保存

# 保存上传的文件到磁盘
save_path = UPLOAD_DIR / f"{kb_id}_{filename}"
with open(save_path, "wb") as f:
    f.write(file_content)

3.2 文本提取

PDF文件:

• 使用PDF处理器提取文本
• 支持OCR（可选，用于扫描件）
• 提取元数据（页数、语言、标题、作者等）

TXT/MD文件:

• 直接读取文本内容
• 自动检测语言

代码位置: knowledge_manager.py:upload_file()

if file_type == "pdf":
    text, metadata = self.pdf_processor.extract_text(
        str(file_path), use_ocr=use_ocr, ocr_lang=ocr_lang
    )
elif file_type in ["txt", "md"]:
    with open(file_path, "r", encoding="utf-8") as f:
        text = f.read()

阶段4: 质量评估

4.1 文档质量评估

评估维度:

• 文本清晰度 (text_clarity_score): 乱码率、字符质量
• 内容密度 (content_density_score): 每页字符数、段落数
• 结构完整性 (structure_score): 段落结构、标题层次
• 内容完整性 (completeness_score): 内容是否完整

质量等级:

• A: 90-100分 - 优秀
• B: 70-89分 - 良好
• C: 50-69分 - 一般
• D: <50分 - 较差

代码位置: knowledge_manager.py:upload_file() → pdf_processor.evaluate_quality()

4.2 权威性评估

评估维度:

• 元数据评分 (metadata_score): 标题、作者、出版社信息
• 内容评分 (content_score): 内容质量、专业性
• 来源类型评分 (source_type_score): 学术论文、专业书籍、官方文档等

权威等级:

• A级: 90-100分 - 权威来源（学术论文、官方文档）
• B级: 70-89分 - 可靠来源（专业书籍、知名作者）
• C级: 50-69分 - 一般来源（博客、论坛）
• D级: <50分 - 低质量来源

代码位置: knowledge_manager.py:upload_file() → authority_evaluator.evaluate()

阶段5: 文本分块

分块策略:

1. 智能分块 (smart): 根据段落和主题自动调整（推荐）
2. 固定大小分块 (fixed): 按固定token数分块
3. 按句子分块 (sentence): 按句子边界分块

分块参数:

• chunk_size: 每个块的token数（默认1000）
• chunk_overlap: 相邻块的重叠token数（默认200）

分块结果:

chunks = [
    {
        "id": "{kb_id}_chunk_{index}",
        "text": "块内容",
        "chunk_index": 0,
        "page": 1,
        "source": "知识库名称"
    },
    ...
]

代码位置: knowledge_manager.py:upload_file() → pdf_processor.chunk_text()

阶段6: 向量化（Embedding）

向量模型:

• TITANS嵌入: 使用TITANS+MIRAS核心模型的嵌入（统一语义空间）
• TITANS增强: 使用TITANS记忆增强编码（更精准但更慢）
• 独立嵌入: 使用独立的嵌入模型

处理流程:

1. 批量编码文本块（GPU可用时批次256，CPU批次64）
2. 向量归一化（确保余弦相似度计算准确）
3. 向量质量检查（验证归一化是否正确）

向量存储:

• 向量存储在知识块对象中（chunk["embedding"]）
• 可选：保存到FAISS索引（提升检索性能）

代码位置: knowledge_manager.py:_generate_embeddings()

# 批量处理
for i in range(0, total, batch_size):
    batch_texts = texts[i : i + batch_size]
    batch_embeddings = model.encode(batch_texts)
    # 归一化
    norms = np.linalg.norm(batch_embeddings, axis=1, keepdims=True)
    batch_embeddings = batch_embeddings / norms

阶段7: AI内容分析

分析内容:

• 专家名称建议
• 专家描述建议
• 关键词提取（用于检索）
• 领域分类

处理流程:

1. 提取文档开头5000字符作为样本
2. 调用LLM分析文档内容
3. 生成JSON格式的专家配置建议

代码位置: knowledge_manager.py:_analyze_content_for_expert()

阶段8: 知识库质量评估

评估维度:

• 分块数量评分 (chunk_count_score): 分块数量是否合理
• 分块长度评分 (chunk_length_score): 分块长度是否均匀
• 分块多样性评分 (chunk_diversity_score): 内容多样性
• 向量覆盖率评分 (vector_coverage_score): 向量化覆盖率

代码位置: knowledge_manager.py:upload_file() → pdf_processor.evaluate_kb_quality()

阶段9: 数据持久化

9.1 保存知识块

文件位置: {KB_DIR}/{kb_id}/chunks.json

保存内容:

• 知识块文本
• 元数据（索引、页码、来源）
• 不包含向量（向量太大，单独存储）

代码位置: knowledge_manager.py:_save_chunks()

9.2 保存索引

文件位置: {KB_DIR}/index.json

保存内容:

• 知识库基本信息
• 统计信息（块数、字符数、页数）
• 质量评估结果
• 权威性评估结果
• 专家建议

持久化保证: 使用 fsync() 确保数据可靠写入磁盘

代码位置: knowledge_manager.py:_save_index()

9.3 保存向量索引（可选）

FAISS索引:

• 用于快速向量检索
• 支持GPU加速
• 自动预加载（提升首次查询性能）

代码位置: knowledge_manager.py:_save_embeddings_only() → faiss_index

阶段10: 状态更新

状态变化: processing → ready

更新内容:

• status: "ready"
• updated_at: 当前时间戳
• chunk_count: 分块数量
• char_count: 字符总数
• page_count: 页数（PDF）

代码位置: knowledge_manager.py:upload_file()

阶段11: 专家模型训练（必须）

前提条件: 知识库状态为 ready

重要性: ⚠️ 专家模型训练不是可选的，而是必须的。 MBE引擎中，上下文管理和回答问题的质量非常关键，因此所有生产环境的知识库都应该经过模型训练。

目的: 将知识库升级为完整训练的专家模型，获得更强的推理能力和更高的答案质量

训练类型:

1. 专家模型训练 (expert): 基于知识库微调专家模型（推荐）
2. TITANS模型训练 (titans): 训练核心TITANS模型
3. MoE模型训练 (moe): 训练专家混合模型

训练流程:

11.1 准备训练数据

从知识库chunks生成训练样本：

def _prepare_expert_training_data(chunks: list) -> list:
    """准备专家训练数据"""
    train_data = []
    for chunk in chunks:
        content = chunk.get("content", "")
        if len(content) > 50:  # 过滤太短的
            train_data.append({
                "text": content,
                "label": 1,
            })
    return train_data

代码位置: mbe-monorepo/shared/src/tasks/training_tasks.py:_prepare_expert_training_data()

11.2 初始化模型

基于核心TITANS+MIRAS模型创建专家模型：

# 获取或创建专家模型
from core.memory import get_titans_memory
memory = get_titans_memory()
model = _create_expert_model(kb_id, memory)

# 从核心模型继承权重
model.load_state_dict(core_model_weights)

代码位置: mbe-monorepo/shared/src/tasks/training_tasks.py:_create_expert_model()

11.3 训练循环

多轮训练，优化模型参数：

optimizer = torch.optim.AdamW(model.parameters(), lr=config["learning_rate"])

for epoch in range(num_epochs):
    for batch in dataloader:
        loss = compute_loss(model, batch)
        loss.backward()
        optimizer.step()
    
    # 保存检查点
    save_checkpoint(model, epoch, loss)

训练参数:

• num_epochs: 训练轮数（默认100）
• batch_size: 批次大小（默认16）
• learning_rate: 学习率（默认1e-4）
• use_gpu: 是否使用GPU（默认True）

代码位置: mbe-monorepo/shared/src/tasks/training_tasks.py:_train_expert_model()

11.4 检查点管理

定期保存训练检查点，支持断点续传：

• 检查点间隔: 每个epoch或每500步
• 最佳模型保存: 自动保存损失最低的模型
• 断点续传: 支持暂停和恢复训练

代码位置: mbe-monorepo/shared/src/training/checkpoint_manager.py

11.5 模型评估

评估训练质量：

• 损失曲线: 监控训练损失和验证损失
• 资源使用: GPU/CPU使用率
• 训练进度: Epoch、Step、ETA

代码位置: mbe-monorepo/shared/src/training/monitor.py

11.6 导出模型

保存训练好的模型：

save_path = f"training/checkpoints/expert_{kb_id}_best.pt"
torch.save({
    "model_state_dict": model.state_dict(),
    "config": config,
    "kb_id": kb_id,
    "best_loss": best_loss,
}, save_path)

API端点:

# 启动训练
POST /admin/training/start
{
    "kb_id": "知识库ID",
    "user_id": "用户ID",
    "model_type": "expert",  # expert/titans/moe
    "preset": "standard",  # fast/standard/thorough
    "config": {
        "num_epochs": 100,
        "batch_size": 16,
        "learning_rate": 1e-4,
        "use_gpu": true
    }
}

# 查询训练状态
GET /admin/training/status/{job_id}

# 暂停/恢复/取消训练
POST /admin/training/{job_id}/pause
POST /admin/training/{job_id}/resume
POST /admin/training/{job_id}/cancel

# 列出检查点
GET /admin/training/{job_id}/checkpoints

# 导出模型
POST /admin/training/{job_id}/export

训练配置预设:

• fast: 快速训练（10 epochs，适合测试）
• standard: 标准训练（50 epochs，平衡质量和时间）
• thorough: 完整训练（100 epochs，最佳质量）

训练时间参考:

训练后的优势:

• ✅ 更强的推理能力
• ✅ 更好的领域适配
• ✅ 更准确的答案生成
• ✅ 支持复杂问题理解

代码位置:

• mbe-monorepo/shared/src/api/training_v2.py - 训练API
• mbe-monorepo/shared/src/tasks/training_tasks.py - 训练任务
• mises-behavior-engine/training/titans_expert_trainer.py - 专家训练器

重要说明:

• ⚠️ 训练是必须的: 生产环境必须使用训练专家，动态专家仅用于快速原型和测试
• 套餐要求: 需要BASIC及以上套餐才能进行训练（FREE套餐不允许训练）
• 自动触发: 系统会根据查询复杂度自动触发训练（如果配额允许）
• 资源需求: 训练需要GPU资源，建议在GPU环境下进行
• 训练时间: 取决于数据量和硬件配置（GPU: 10-30分钟，CPU: 2-6小时）

详细策略: 请参考 MBE_EXPERT_MODEL_TRAINING_STRATEGY.md 了解完整的训练策略、套餐体系、智能选择机制和付费模式。

📊 状态流转图

pending (创建后)
    ↓
processing (上传文件后)
    ↓
ready (处理完成后)
    ↓
[可选] training (专家模型训练中)
    ↓
trained (训练完成，可选)
    ↓
error (处理失败)

状态说明:

• pending: 等待上传文件
• processing: 正在处理文件（提取文本、分块、生成向量）
• ready: 处理完成，可以使用（动态专家模式）
• training: 专家模型训练中（可选）
• trained: 训练完成，可以使用完整模型（可选）
• error: 处理失败

🔍 关键组件

1. KnowledgeManager（知识库管理器）

职责:

• 管理知识库生命周期
• 处理文档上传和处理
• 管理向量索引
• 提供检索接口

代码位置: mbe-monorepo/private/core/src/knowledge/knowledge_manager.py

2. PDFProcessor（PDF处理器）

职责:

• PDF文本提取
• OCR支持
• 文本分块
• 质量评估

代码位置: mbe-monorepo/private/core/src/knowledge/pdf_processor.py

3. AuthorityEvaluator（权威性评估器）

职责:

• 评估文档权威性
• 识别来源类型
• 生成评估报告

代码位置: mbe-monorepo/private/core/src/knowledge/authority_evaluator.py

4. FAISS索引管理器

职责:

• 构建向量索引
• 快速向量检索
• GPU加速支持

代码位置: mbe-monorepo/private/core/src/knowledge/faiss_index.py

5. 训练任务管理器（可选）

职责:

• 管理训练任务生命周期
• 准备训练数据
• 执行模型训练
• 管理检查点

代码位置: mbe-monorepo/shared/src/tasks/training_tasks.py

6. 训练监控器（可选）

职责:

• 监控训练进度
• 记录损失曲线
• 跟踪资源使用
• 生成训练报告

代码位置: mbe-monorepo/shared/src/training/monitor.py

7. 检查点管理器（可选）

职责:

• 保存训练检查点
• 支持断点续传
• 管理最佳模型
• 导出训练模型

代码位置: mbe-monorepo/shared/src/training/checkpoint_manager.py

🚀 性能优化

1. 异步处理

• 小文件（≤5MB）: 同步处理，立即返回
• 大文件（>5MB）: 异步处理，使用消息队列

2. 批量处理

• 向量化: 批量编码（GPU: 256/批次，CPU: 64/批次）
• 批量上传: 支持一次上传多个文件

3. 索引预加载

• FAISS索引后台预加载
• 提升首次查询性能

4. 向量归一化

• 确保余弦相似度计算准确
• 提升检索质量

📝 数据存储结构

knowledge_bases/
├── index.json                    # 知识库索引（元数据）
├── uploads/                      # 上传文件存储
│   └── {kb_id}_{filename}
└── {kb_id}/                      # 知识库目录
    ├── chunks.json              # 知识块（不含向量）
    └── embeddings.faiss         # FAISS向量索引（可选）

🔗 相关API端点

创建和管理

• POST /admin/knowledge/create - 创建知识库
• GET /admin/knowledge/ - 列出所有知识库
• GET /admin/knowledge/{kb_id} - 获取知识库详情
• DELETE /admin/knowledge/{kb_id} - 删除知识库

上传

• POST /admin/knowledge/upload/{kb_id} - 单文件上传
• POST /admin/knowledge/upload-batch/{kb_id} - 批量上传
• POST /admin/knowledge/upload-chunk/init/{kb_id} - 初始化分块上传
• POST /admin/knowledge/upload-chunk/{upload_id}/{chunk_index} - 上传分块
• POST /admin/knowledge/upload-chunk/complete/{upload_id} - 完成分块上传

检索

• POST /admin/knowledge/search - 搜索知识库
• GET /admin/knowledge/search/context - 获取专家上下文

训练（可选）

• POST /admin/training/start - 启动训练任务
• GET /admin/training/status/{job_id} - 查询训练状态
• POST /admin/training/{job_id}/pause - 暂停训练
• POST /admin/training/{job_id}/resume - 恢复训练
• POST /admin/training/{job_id}/cancel - 取消训练
• GET /admin/training/{job_id}/checkpoints - 列出检查点
• POST /admin/training/{job_id}/export - 导出模型

✅ 质量保证

1. 数据持久化

• 使用 fsync() 确保数据可靠写入磁盘
• 定期保存索引和知识块

2. 错误处理

• 处理失败时自动清理无内容的知识库
• 详细的错误日志记录

3. 质量评估

• 文档质量评估（A/B/C/D级）
• 权威性评估（A/B/C/D级）
• 知识库质量评估

📚 总结

MBE系统处理知识库的全流程是一个自动化、智能化的RAG（检索增强生成）知识库构建流程，包括：

1. ✅ 创建知识库 - 配置分块策略和向量化参数
2. ✅ 文档上传 - 支持单文件、批量、分块上传
3. ✅ 文本提取 - 支持PDF、TXT、MD格式，可选OCR
4. ✅ 质量评估 - 文档质量和权威性双重评估
5. ✅ 智能分块 - 根据策略自动分块，保持上下文
6. ✅ 向量化 - 使用TITANS模型生成高质量向量
7. ✅ AI分析 - 自动生成专家配置建议
8. ✅ 索引构建 - 构建FAISS向量索引，提升检索性能
9. ✅ 数据持久化 - 可靠保存到磁盘
10. ✅ 状态管理 - 完整的状态流转和错误处理
11. ✅ 专家模型训练（必须） - 将知识库升级为完整训练的专家模型，生产环境标准配置

整个流程高度自动化，用户只需上传文档，系统会自动完成所有处理步骤，最终生成一个可用于RAG检索的高质量知识库。

两种使用模式:

1. 动态专家模式（原型/测试）: 知识库处理完成后直接使用，轻量级（5.1MB），响应快，仅用于快速原型和测试
2. 训练专家模式（生产标准）: 经过模型训练后使用，完整模型（161MB），推理能力强，生产环境必须使用

⚠️ 重要: 训练专家是生产环境的标准配置，动态专家仅用于快速原型和测试。详细策略请参考 MBE_EXPERT_MODEL_TRAINING_STRATEGY.md。

🔗 后续流程

知识库处理完成后，还需要经过以下流程才能被用户使用：

1. 发布为专家 - 将知识库发布为可查询的AI专家
2. 专家路由 - 用户提问时，智能匹配最合适的专家
3. RAG检索 - 从知识库中检索相关内容
4. 答案生成 - LLM基于检索结果生成答案
5. 终端集成 - 支持Web、小智、小爱等多种终端
6. 反馈学习 - HOPE持续学习，优化用户体验

详细文档: 请参考 MBE_USER_USAGE_COMPLETE_WORKFLOW.md