MBE 文档中心

课程同步功能使用指南

📋 概述

课程同步功能实现了知识库更新时自动同步课程映射的机制，解决了知识库更新后课程内容不一致的问题。

🚀 快速开始

1. 自动同步（推荐）

知识库更新时会自动触发课程同步，无需手动操作。

触发场景：

  • 上传新文件到知识库
  • 更新知识库 chunks
  • 重新处理知识库

工作流程：

知识库更新 → 发布事件 → 课程同步服务 → 更新 course_mappings.json

2. 手动同步

如果需要手动触发同步（例如测试或修复）：

# 使用 API
curl -X POST "http://localhost:8000/api/course-sync/manual/{kb_id}" \
  -H "Content-Type: application/json" \
  -d '{"expert_id": "optional_expert_id"}'

Python 示例：

from src.services.course_sync_service import get_course_sync_service

sync_service = get_course_sync_service()
await sync_service.sync_course_for_kb(
    kb_id="your_kb_id",
    expert_id="optional_expert_id"
)

3. 检查同步状态

curl "http://localhost:8000/api/course-sync/status/{kb_id}"

响应示例：

{
  "kb_id": "e22dff89-51f",
  "synced": true,
  "course_name": "考公专家",
  "knowledge_points_count": 12,
  "last_updated": "2026-02-05T10:30:00",
  "analysis_method": "titans"
}

🔧 配置

启用/禁用同步

在 src/services/course_sync_service.py 中：

sync_service = get_course_sync_service()
sync_service.enabled = True  # 启用
sync_service.enabled = False  # 禁用

同步模式

支持三种同步模式（见架构文档）：

  1. Webhook 事件（默认，实时）
  2. 消息队列（高可靠性）
  3. 数据库事件表（简单可靠）

📡 Webhook 集成

订阅知识库更新事件

教育应用可以订阅知识库更新事件：

# 在 webhooks.py 中注册端点
endpoint = {
    "url": "http://your-app/api/course-sync/webhook/knowledge-base-updated",
    "events": [
        WebhookEvent.KNOWLEDGE_BASE_CHUNKS_UPDATED,
        WebhookEvent.KNOWLEDGE_BASE_UPDATED
    ]
}

接收事件

# opensource/mbe-education/backend/api/course_sync_api.py
@router.post("/webhook/knowledge-base-updated")
async def handle_kb_update(event: KnowledgeBaseUpdateEvent):
    # 自动处理课程同步
    ...

🔍 监控和日志

查看日志

课程同步服务会记录详细日志：

# 成功同步
logger.info("✅ 课程已更新: {course_name} ({count} 个知识点)")

# 同步失败
logger.error("同步课程失败: {error}", exc_info=True)

# 事件发布
logger.info("📚 知识库更新事件: {kb_id}, 类型: {update_type}")

监控指标

建议监控：

  • 同步成功率
  • 同步延迟
  • 失败重试次数
  • 事件队列长度

⚠️ 注意事项

1. 性能考虑

  • TITANS 分析耗时较长，同步是异步执行的
  • 避免短时间内频繁更新同一知识库
  • 大批量更新建议使用批量接口

2. 数据一致性

  • 同步过程中，课程映射文件可能短暂不一致
  • 建议在同步完成后再读取课程数据
  • 使用 get_sync_status API 检查同步状态

3. 错误处理

  • 同步失败不会影响知识库更新
  • 失败事件会记录日志，支持手动重试
  • 建议设置告警监控同步失败

4. 专家ID查找

系统会按以下顺序查找专家ID：

  1. 事件中提供的 expert_id
  2. 从专家管理器查找（通过 kb_id）
  3. 从课程映射中查找
  4. 使用默认值 dynamic_{kb_id}

🐛 故障排查

问题1：同步未触发

检查：

  1. 确认 course_sync_service.enabled = True
  2. 检查知识库更新是否成功
  3. 查看日志是否有错误

解决：

# 手动触发同步
await sync_service.sync_course_for_kb(kb_id="your_kb_id")

问题2：同步失败

检查：

  1. 知识库 chunks 文件是否存在
  2. TITANS 分析是否正常
  3. 课程映射文件是否可写

解决：

# 查看详细错误日志
logger.error("同步失败", exc_info=True)

# 手动重试
await sync_service.sync_course_for_kb(kb_id="your_kb_id")

问题3：课程内容未更新

检查：

  1. 确认同步任务已执行
  2. 检查 course_mappings.json 的更新时间
  3. 确认前端是否重新加载课程数据

解决：

# 检查同步状态
curl "http://localhost:8000/api/course-sync/status/{kb_id}"

# 手动触发同步
curl -X POST "http://localhost:8000/api/course-sync/manual/{kb_id}"

📚 相关文档

🔄 更新历史

  • 2026-02-05: 初始版本，支持基于 Webhook 的自动同步
  • 计划：添加消息队列支持、批量同步、监控面板