Whitebox项目SDK开发指南：从模型管理到监控告警全解析

前言

Whitebox作为一个专业的机器学习模型管理平台，其SDK提供了完整的模型生命周期管理能力。本文将深入解析Whitebox SDK的核心功能，帮助开发者快速掌握模型创建、训练数据记录、推理日志、监控告警等关键操作。

模型管理

创建模型

create_model方法是模型生命周期的起点，它会在数据库中创建模型元数据记录。该方法支持三种类型的模型：

• 二分类模型(binary)
• 多分类模型(multi_class)
• 回归模型(regression)

关键参数说明：

• granularity定义了报告生成的时间粒度，支持分钟(T)、小时(H)、天(D)、周(W)等单位
• labels参数用于分类模型，定义标签名称与编码的映射关系
• 回归模型不需要指定labels参数

# 创建二分类模型示例
labels = {"正常":0, "异常":1}
model = create_model(
    name="欺诈检测模型",
    type="binary",
    target_column="is_fraud",
    granularity="1D",
    labels=labels,
    description="用于检测信用卡欺诈交易的模型"
)

模型查询与删除

通过get_model和delete_model可以方便地查询和删除模型：

# 查询模型
model_details = get_model(model_id="your_model_id")

# 删除模型
delete_model(model_id="your_model_id")

训练数据管理

log_training_dataset方法用于记录模型的训练数据，特点包括：

1. 同时记录原始数据和预处理后的数据
2. 数据保存后会触发训练流水线
3. 训练完成的模型会自动保存在指定目录

log_training_dataset(
    model_id="your_model_id",
    non_processed=raw_df,  # 原始数据DataFrame
    processed=processed_df  # 处理后的DataFrame
)

注意：两个DataFrame的行数必须严格一致，否则会抛出异常。

推理记录

log_inferences方法用于记录模型的推理结果，支持以下特性：

• 同时记录原始输入和预处理后的输入
• 可选记录实际值(actuals)，用于后续模型评估
• 必须提供每个推理记录的时间戳

log_inferences(
    model_id="your_model_id",
    non_processed=inference_raw_df,
    processed=inference_processed_df,
    timestamps=pd.Series([...]),  # 每个推理记录的时间戳
    actuals=pd.Series([...])     # 可选的实际值
)

可解释性分析

通过get_xai_row可以获取单个推理记录的可解释性报告：

xai_report = get_xai_row(inference_row_id="row_id_123")

模型监控

Whitebox提供了强大的模型监控能力，可以监控多种指标：

监控指标类型

1. 性能指标：

   • 准确率(accuracy)
   • 精确率(precision)
   • 召回率(recall)
   • F1分数(f1)
   • R平方(r_square)
   • 均方误差(mean_squared_error)
   • 平均绝对误差(mean_absolute_error)

2. 数据指标：

   • 数据漂移(data_drift)
   • 概念漂移(concept_drift)

创建监控器

create_model_monitor(
    model_id="your_model_id",
    name="准确率监控",
    status="active",
    metric="accuracy",
    severity="high",
    email="[e-mail]",
    lower_threshold=0.85  # 当准确率低于0.85时触发告警
)

对于数据漂移类监控，需要指定feature参数而不是阈值

监控器管理

# 更新监控器
update_model_monitor(
    model_monitor_id="monitor_123",
    severity="mid",  # 降低告警级别
    lower_threshold=0.80  # 调整阈值
)

# 删除监控器
delete_model_monitor(model_monitor_id="monitor_123")

指标报告

Whitebox SDK提供了多种报告获取方法：

# 获取漂移指标报告
drift_report = get_drifting_metrics(model_id="your_model_id")

# 获取描述性统计报告
stats_report = get_descriptive_statistics(model_id="your_model_id")

# 获取性能指标报告
performance_report = get_performance_metrics(model_id="your_model_id")

最佳实践

1. 模型命名规范：建议使用"业务领域_模型类型_版本"的命名方式，如"fraud_detection_binary_v1"

2. 监控设置建议：

   • 关键业务模型设置高严重级别告警
   • 对于数据漂移，建议监控模型的关键特征
   • 设置合理的阈值，避免告警风暴

3. 推理记录优化：

   • 批量记录推理结果，减少API调用次数
   • 确保时间戳的准确性，这对后续分析至关重要

总结

Whitebox SDK提供了一套完整的模型管理工具链，从模型创建、训练数据记录、推理日志到监控告警，覆盖了模型生命周期的各个阶段。通过合理使用这些功能，团队可以更好地管理和维护生产环境中的机器学习模型，及时发现并解决问题，确保模型的稳定性和可靠性。