MBE 文档中心

统一知识图谱 Feature Flags 使用指南

概述

统一知识图谱支持全局和组件级别的 feature flag 控制，允许渐进式迁移和细粒度控制。

Feature Flags 列表

全局开关

  • MBE_UNIFIED_GRAPH_ENABLED (默认: true)
    • 控制所有图谱功能的全局开关
    • 如果设置为 false，所有组件都不会启用图谱功能
    • 优先级最高，必须先启用才能使用组件级别开关

组件级别开关

以下开关只有在 MBE_UNIFIED_GRAPH_ENABLED=true 时才会生效：

  1. MBE_GRAPH_EXPERT_ROUTING (默认: true)

    • 控制 ExpertRouter 的图谱路由功能
    • 影响：专家匹配、互补专家查找、用户偏好更新

  2. MBE_GRAPH_MIRAS_CONTEXT (默认: true)

    • 控制 MIRASMatcher 的图谱上下文增强
    • 影响：用户偏好加权、领域偏好加权

  3. MBE_GRAPH_CONVERSATION (默认: true)

    • 控制 ConversationContext 的图谱同步
    • 影响：实体追踪、用户偏好更新、对话事件同步

  4. MBE_GRAPH_EDUCATION (默认: true)

    • 控制 CourseManager 的图谱集成
    • 影响：学习路径生成、环检测、知识点依赖管理

  5. MBE_GRAPH_RETRIEVAL_KG (默认: true)

    • 控制 RetrievalMoE 的图谱检索适配器
    • 影响：结构化查询专家的图谱适配器注入

使用场景

场景 1: 完全禁用图谱功能

export MBE_UNIFIED_GRAPH_ENABLED=false

所有组件都会使用原有逻辑，不启用任何图谱功能。

场景 2: 启用全局图谱，但禁用特定组件

# 启用全局图谱
export MBE_UNIFIED_GRAPH_ENABLED=true

# 禁用专家路由的图谱功能（仍使用原有路由逻辑）
export MBE_GRAPH_EXPERT_ROUTING=false

# 禁用教育模块的图谱功能（仍使用原有学习路径算法）
export MBE_GRAPH_EDUCATION=false

场景 3: 渐进式迁移 - 逐个启用组件

# 第一步：只启用对话上下文同步
export MBE_UNIFIED_GRAPH_ENABLED=true
export MBE_GRAPH_CONVERSATION=true
export MBE_GRAPH_EXPERT_ROUTING=false
export MBE_GRAPH_MIRAS_CONTEXT=false
export MBE_GRAPH_EDUCATION=false
export MBE_GRAPH_RETRIEVAL_KG=false

# 第二步：启用专家路由
export MBE_GRAPH_EXPERT_ROUTING=true

# 第三步：启用所有组件
export MBE_GRAPH_MIRAS_CONTEXT=true
export MBE_GRAPH_EDUCATION=true
export MBE_GRAPH_RETRIEVAL_KG=true

场景 4: 测试环境配置

# 测试环境：只启用核心功能
export MBE_UNIFIED_GRAPH_ENABLED=true
export MBE_GRAPH_EXPERT_ROUTING=true
export MBE_GRAPH_CONVERSATION=true
export MBE_GRAPH_MIRAS_CONTEXT=false  # 暂时禁用
export MBE_GRAPH_EDUCATION=false      # 暂时禁用
export MBE_GRAPH_RETRIEVAL_KG=false   # 暂时禁用

实现细节

检查逻辑

所有组件的初始化代码都遵循以下逻辑：

# 1. 检查全局开关
if os.getenv("MBE_UNIFIED_GRAPH_ENABLED", "true").lower() != "true":
    return  # 不启用图谱功能

# 2. 检查组件级别开关（默认跟随全局开关）
component_flag = os.getenv("MBE_GRAPH_<COMPONENT>", "true").lower()
if component_flag != "true":
    logger.debug(f"图谱功能已禁用 (MBE_GRAPH_<COMPONENT>=false)")
    return  # 不启用该组件的图谱功能

# 3. 初始化图谱查询引擎
try:
    from src.knowledge.graph import get_graph_query_engine
    self._graph_query = get_graph_query_engine()
    logger.info("🔗 图谱查询引擎已连接")
except Exception as e:
    logger.debug(f"Graph query engine not available: {e}")

Fallback 机制

所有集成点都有 try/except fallback 机制：

  • 如果图谱功能初始化失败，自动回退到原有逻辑
  • 如果图谱查询失败，自动回退到原有逻辑
  • 不会因为图谱功能问题导致系统崩溃

验证方法

检查日志

启用图谱功能时，会看到以下日志：

🔗 Expert router: 统一图谱查询引擎已连接
🔗 MIRAS: 统一图谱查询引擎已连接
🔗 ConversationContext: 图谱同步已启用
🔗 CourseManager: 统一图谱集成已启用
🔗 RetrievalMoE: 统一图谱适配器已注入 StructuredQueryExpert

禁用图谱功能时，会看到：

🔗 Expert router: 图谱路由已禁用 (MBE_GRAPH_EXPERT_ROUTING=false)
🔗 MIRAS: 图谱上下文已禁用 (MBE_GRAPH_MIRAS_CONTEXT=false)
🔗 ConversationContext: 图谱同步已禁用 (MBE_GRAPH_CONVERSATION=false)
🔗 CourseManager: 图谱集成已禁用 (MBE_GRAPH_EDUCATION=false)
🔗 RetrievalMoE: 图谱检索已禁用 (MBE_GRAPH_RETRIEVAL_KG=false)

功能验证

  1. ExpertRouter: 检查专家路由是否使用图谱查询
  2. MIRASMatcher: 检查是否使用用户偏好加权
  3. ConversationContext: 检查是否追踪实体和更新偏好
  4. CourseManager: 检查学习路径是否使用拓扑排序
  5. RetrievalMoE: 检查是否注入图谱适配器

注意事项

  1. 默认行为: 所有组件级别开关默认为 true，即默认启用图谱功能
  2. 优先级: 全局开关优先级最高，必须先启用
  3. 向后兼容: 如果未设置任何环境变量，默认行为是启用所有图谱功能
  4. 性能影响: 禁用图谱功能会回退到原有逻辑，性能特征可能不同
  5. 数据一致性: 在迁移过程中，建议保持数据同步，避免不一致

迁移建议

  1. 阶段 1: 启用全局开关，但禁用所有组件级别开关，验证系统稳定性
  2. 阶段 2: 逐个启用组件级别开关，监控性能和错误率
  3. 阶段 3: 全部启用，持续监控
  4. 回退: 如果出现问题，可以快速禁用全局开关或特定组件开关