Whitebox SDK 使用教程：从安装到模型管理的完整指南

前言

Whitebox 是一个强大的机器学习模型监控和管理平台，其 SDK 提供了便捷的 Python 接口，帮助开发者轻松集成模型监控功能到现有工作流中。本文将详细介绍如何使用 Whitebox SDK 完成从安装到模型管理的全流程操作。

环境准备与安装

安装 Whitebox SDK

Whitebox SDK 可以通过 pip 包管理器轻松安装，安装过程会自动处理所有依赖项：

pip install whitebox-sdk

安装完成后，您可以通过 Python 导入来验证是否安装成功：

import whitebox
print(whitebox.__version__)

初始化配置

获取 API 密钥

在使用 SDK 前，您需要获取 Whitebox 服务的 API 密钥。这个密钥通常在首次启动 Whitebox 服务时自动生成。启动服务后，您将在日志中看到类似以下输出：

Created username: admin, API key: some_api_key

重要提示：请妥善保管此 API 密钥，如果丢失，您需要重置管理员用户才能获取新密钥。

初始化 Whitebox 客户端

获取 API 密钥后，您可以这样初始化 Whitebox 客户端：

from whitebox import Whitebox

# 替换为您的实际主机地址和API密钥
wb = Whitebox(
    host="http://127.0.0.1:8000",  # Whitebox服务地址
    api_key="some_api_key"         # 您的API密钥
)

模型管理

创建模型

在 Whitebox 中，模型是监控的基本单位。创建模型时需要指定多个关键参数：

model_response = wb.create_model(
    name="信用卡欺诈检测模型",      # 模型名称
    type="binary",                # 模型类型：binary(二分类)/regression(回归)/multi(多分类)
    labels={                      # 标签映射
        '正常交易': 0,
        '欺诈交易': 1
    },
    target_column="is_fraud",     # 目标列名
    granularity="1D"              # 监控粒度：1D(每天)/1H(每小时)等
)

参数说明：

• type：指定模型类型，影响后续的监控指标计算
• labels：将可读标签映射到模型输出的数值
• granularity：决定监控数据的聚合频率

获取模型信息

创建模型后，您可以通过模型ID获取详细信息：

model_info = wb.get_model("your_model_id_here")
print(model_info)

删除模型

删除模型会级联删除所有相关数据（包括数据集、推理记录和监控器）：

wb.delete_model("your_model_id_here")

警告：此操作不可逆，请谨慎执行！

数据管理

加载训练数据集

训练数据集是模型性能基准的基础，Whitebox 需要原始数据和预处理后的数据进行比较：

import pandas as pd

# 加载数据
raw_train = pd.read_csv("raw_train_data.csv")
processed_train = pd.read_csv("processed_train_data.csv")

# 记录训练数据
wb.log_training_dataset(
    model_id="your_model_id_here",
    non_processed=raw_train,  # 原始数据
    processed=processed_train  # 预处理后数据
)

关键要求：

1. 原始数据和预处理数据必须行数相同
2. 数据必须包含多行（不能是单行）
3. 训练数据应一次性完整提交

记录推理数据

记录推理数据时，除了原始和处理后的数据，还需要提供时间戳和实际值（可选）：

# 加载推理数据
raw_infer = pd.read_csv("raw_inference_data.csv")
processed_infer = pd.read_csv("processed_inference_data.csv")

# 准备时间戳和实际值
timestamps = pd.Series(["2023-01-01T12:00:00"] * len(raw_infer))
actuals = pd.Series([0, 1, 0, 0, 1])  # 实际标签

# 记录推理
wb.log_inferences(
    model_id="your_model_id_here",
    non_processed=raw_infer,
    processed=processed_infer,
    timestamps=timestamps,
    actuals=actuals  # 如果已知实际值，强烈建议提供
)

注意事项：

• 时间戳数量必须与数据行数匹配
• 实际值一旦提交无法更新，请确保准确性
• 推理数据可以分批提交

最佳实践建议

1. 密钥管理：将 API 密钥存储在环境变量中而非代码中
2. 错误处理：对 SDK 调用添加 try-except 块捕获异常
3. 数据验证：在提交前检查数据一致性（行数、列名等）
4. 监控策略：根据业务需求选择合适的监控粒度（granularity）

通过本教程，您应该已经掌握了 Whitebox SDK 的核心功能。实际应用中，您还可以结合 Whitebox 的监控功能，设置数据漂移、性能下降等告警，全面保障模型在生产环境中的稳定性。