Superwise 漂移检测技能

当用户希望为其模型配置漂移检测时，请按以下顺序引导其完成各步骤。必须完整执行当前步骤后，再进入下一步。

您需要向用户提供哪些信息

开始前，请用户提前提供以下内容：

1. Superwise 凭据 — SUPERWISE_CLIENT_ID 和 SUPERWISE_SECRET_TOKEN（可在其 Superwise 账户的「设置 → API 密钥」中找到）
2. 训练 CSV 文件 — 其模型所基于训练的 CSV 文件（仅需特征列；系统将自动添加 row_id 列）
3. 模型名称 — 一个不含空格的简短标识符（例如：my_churn_model）；该名称将用于在 Superwise 中命名数据集
4. 推理端点（Inference endpoint） — 以下两种选项之一：
   • 选项 A：用户已部署运行中的模型端点。请其提供 URL。该端点必须返回 JSON 格式响应，结构为 {"records": [{...}, ...]}，其中每个 record 包含与训练 CSV 完全一致的列名。
   • 选项 B：用户尚无可用端点，需自行部署。可参考 examples/dc-bikeshare-drift/app.py 中的 dc-bikeshare 示例作为模板。指导用户适配其自身的 predict.py，然后本地运行 python app.py。本地测试时，请设置 INFERENCE_ENDPOINT_URL=http://localhost:5001/predict。

步骤 1 — 安装依赖项

pip install -r requirements.txt

在技能根目录下创建一个 .env 文件，内容如下，并填入用户提供的对应值：

SUPERWISE_CLIENT_ID=<来自用户>
SUPERWISE_SECRET_TOKEN=<来自用户>
MODEL_NAME=<模型名称>
INFERENCE_ENDPOINT_URL=<来自用户对第 4 项问题的回答>
SUPERWISE_AUTO_TRIGGER=true
SUPERWISE_TRAINING_DATASET_ID=
SUPERWISE_TRAINING_DATASET_NAME=
SUPERWISE_TRAINING_CUBE_NAME=
SUPERWISE_INFERENCE_DATASET_ID=
SUPERWISE_INFERENCE_DATASET_NAME=
SUPERWISE_INFERENCE_CUBE_NAME=
SUPERWISE_DRIFT_POLICY_ID=
# 针对各列的独立策略配置 — 每行对应 setup_drift_policy.py 输出的一列：
# SUPERWISE_DRIFT_POLICY_ID_<列名>=<策略 ID>
SCHEDULE_HOUR_UTC=6
SCHEDULE_MINUTE_UTC=0
PORT=5000

数据集 ID 和策略 ID 字段将在步骤 2 和步骤 3 执行完成后填入。

步骤 2 — 创建 Superwise 数据集并上传训练数据

python setup_dataset.py 
    --training-csv path/to/training.csv 
    --model-name their_model_name

该命令将在 Superwise 中创建一个训练数据集和一个推理数据集，逐行上传训练 CSV 文件，并打印出数据集 ID 和 Cube 名称。

请将打印出的值复制到 .env 文件中：

SUPERWISE_TRAINING_DATASET_ID=<打印值>
SUPERWISE_TRAINING_DATASET_NAME=<打印值>
SUPERWISE_TRAINING_CUBE_NAME=<打印值>
SUPERWISE_INFERENCE_DATASET_ID=<打印值>
SUPERWISE_INFERENCE_DATASET_NAME=<打印值>
SUPERWISE_INFERENCE_CUBE_NAME=<打印值>

注意：训练 CSV 的列名只能包含字母、数字和下划线，且必须以字母开头。若发现任何列名违反此规则，请提醒用户修正。

步骤 3 — 创建漂移策略

python setup_drift_policy.py 
    --training-csv path/to/training.csv 
    --policy-name their_model_drift

该命令将为训练 CSV 中每一个分类型（字符串/布尔型）列，创建一条 Jensen-Shannon 散度（JSD）策略，用于比对训练数据集与推理数据集。数值型列会被跳过并输出警告 —— 这是当前 Superwise 平台的已知限制（暂不支持对数值型列使用 Wasserstein 距离进行漂移检测）。

请将主策略 ID（即首行打印出的策略 ID）复制到 .env 中：

SUPERWISE_DRIFT_POLICY_ID=<主策略 ID>
SUPERWISE_DRIFT_POLICY_ID_=<策略 ID>
SUPERWISE_DRIFT_POLICY_ID_=<策略 ID>
# ... 每条由 setup_drift_policy.py 打印出的额外列策略均需单独添加一行

请复制所有打印出的策略行（不仅限于第一行）—— _check_drift() 函数会自动识别并触发所有以 SUPERWISE_DRIFT_POLICY_ID* 开头的环境变量所对应的策略检查。

若用户仅希望监控特定若干列，可在命令中添加参数：--columns col1 col2 col3。

步骤 4 — 执行端到端漂移检测

python -c "
import os; os.chdir('.')
from dotenv import load_dotenv; load_dotenv()
from skill import run
result = run()
print(result)
"

该操作将执行以下流程：

1. 从 INFERENCE_ENDPOINT_URL 获取推理记录
2. 将这些记录写入 Superwise 推理数据集
3. 触发所有已配置的漂移策略评估任务
4. 轮询等待每项评估任务完成
5. 若检测到漂移，则通过 OpenClaw 已有的 Telegram 连接发送告警
6. 最终打印汇总结果

注意：一次完整检测耗时约 5–10 分钟（含推理请求、数据写入及全量列策略轮询）。为避免 exec 超时，请在后台或 PTY 会话中运行：

nohup python -c "..." &> drift_check.log &

步骤 5 — 设置周期性漂移检测

使用 skill.py 中定义的元数据，在 OpenClaw 中注册该技能：

• 触发命令： /drift_check
• 调度表达式： 0 6 * * *（每日 UTC 时间 06:00 执行 —— 可根据用户的推理频率调整）
• 告警通道： 复用 OpenClaw 当前已配置的 Telegram 连接

如需生产环境部署，请指导用户使用随附的 render.yaml 将 scheduler.py 部署至 Render 平台，并将全部 .env 中的变量配置为 Render 的环境变量。

Telegram 告警

本技能复用 OpenClaw 已建立的 Telegram 连接，无需单独配置 Bot。技能中 skill.py 内的 _send_telegram() 函数将直接读取用户 OpenClaw 环境下的 TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID。若用户尚未在 OpenClaw 中配置 Telegram，请指引其查阅 OpenClaw 官方 Telegram 配置文档。

漂移告警格式如下：

• Unhealthy（异常）：列出漂移程度较高（得分 > 0.2）的特征，并提示预测结果可能不可靠
• Healthy（正常）：确认未检测到显著漂移，并展示各特征的具体漂移得分

参考示例：DC Bikeshare

examples/dc-bikeshare-drift/ 是一个完整的可运行示例，用户可在接入自身模型前，先运行该示例验证整套技能流程是否正常工作：

cd examples/dc-bikeshare-drift
pip install -r requirements.txt
python collect_training_data.py   # 获取真实站点数据，生成模拟历史数据
python train.py                   # 训练 RandomForest 分类器
python app.py                     # 启动本地 Flask 推理服务（端口 5001）

随后，在技能根目录下执行漂移检测，并指定：

INFERENCE_ENDPOINT_URL=http://localhost:5001/predict

该示例仅使用分类型特征（站点规模、是否配备电助力自行车、小时、日期类型、季节）来预测单车可用性 —— 所有特征均适用于 JSD 漂移检测。

模型重训练

当用户对其模型进行重训练时，请执行：

python setup_dataset.py 
    --training-csv path/to/new_training.csv 
    --model-name their_model_name 
    --retrain

该命令将创建一个带版本号的新训练数据集，同时保留原有推理数据历史。请更新 .env 中的训练数据集 ID 和 Cube 名称，然后重新运行 setup_drift_policy.py，以生成指向新基线数据集的漂移策略。

故障排查

• 策略状态长期停留在 pending：请确认推理记录已在触发策略前成功写入推理数据集。若推理数据集为空，策略无法启动评估。
• 首次运行即返回 unhealthy：若推理记录仅为单一时段快照（如全部记录均属同一小时/同一天/同一季节），该现象属预期行为。建议积累更长时间跨度的推理记录，以构建更具代表性的分布。
• 数值型列被跳过：数值维度的 Wasserstein 距离计算是 Superwise 平台当前已知缺陷。临时解决方案包括：对数值列进行分桶（categorical bucketing）转为分类型，或等待 Superwise 平台后续修复。
• 上传后 CubeJS Cube 未找到：新建数据集需数分钟才能在 Superwise 的 CubeJS 层完成注册。请等待 2–3 分钟后重试验证步骤。
• 漂移检测被终止 / 无输出（收到 SIGTERM）：完整检测耗时 5–10 分钟，易因环境 exec 超时而被强制中断。请改用后台会话运行：nohup python -c "from skill import run; run()" &> drift_check.log &，随后通过 tail -f drift_check.log 实时跟踪执行进度。