mle-workflow

name	mle-workflow
description	生产机器学习工程工作流，用于数据契约、可重现训练、模型评估、部署、监控和回滚。在构建、审查或强化一次性笔记本之外的 ML 系统时使用。
allowed-tools	Read, Write, Edit, Bash, Grep, Glob

机器学习工程工作流

使用此技能将模型工作转化为生产 ML 系统，具有清晰的数据契约、可重复的训练、可测量的质量门槛、可部署的工件和操作监控。

何时激活

• 规划或审查生产 ML 功能、模型刷新、排名系统、推荐器、分类器、嵌入工作流或预测管道
• 将笔记本代码转换为可重用的训练、评估、批量推理或在线推理管道
• 设计模型推广标准、离线/在线评估、实验跟踪或回滚路径
• 调试由数据漂移、标签泄漏、陈旧特征、工件不匹配或不一致的训练和服务逻辑引起的故障
• 添加模型监控、金丝雀推出、影子流量或部署后质量检查

范围校准

仅使用适合面前系统的路径。此技能对排名、搜索、推荐、分类器、预测、嵌入、LLM 工作流、异常检测和批量分析有用，但不应强制将一种架构用于所有这些。

• 不要假设每个模型都有监督标签、在线服务、特征存储、PyTorch、GPU、人工审查、A/B 测试或实时反馈。
• 当数据契约、基线、评估脚本和回滚笔记会使更改可审查时，不要添加重量级 MLOps 机械。
• 当项目缺少标签、延迟结果、切片定义、生产流量或监控所有权时，使假设明确。
• 将示例视为可互换的脚手架。用项目原生等效项替换指标、服务模式、数据存储和推出机制。

相关技能

• python-patterns 和 python-testing：Python 实现和 pytest 覆盖率
• pytorch-patterns：深度学习模型、数据加载器、设备处理和训练循环
• eval-harness 和 ai-regression-testing：推广门槛和代理辅助的回归检查
• database-migrations、postgres-patterns 和 clickhouse-io：数据存储和分析表面
• deployment-patterns、docker-patterns 和 security-review：服务、机密、容器和生产强化

重用 SWE 表面

不要将 MLE 与软件工程分开。大多数 ECC SWE 工作流直接适用于 ML 系统，通常具有更严格的故障模式：

推荐的 minimal --with capability:machine-learning 安装使核心代理表面与此技能一起可用。对于仅技能或代理受限的 harness，在目标支持代理的地方将 skill:mle-workflow 与 agent:mle-reviewer 配对。

SWE 表面	MLE 用途
product-capability / architecture-decision-records	将模型工作转化为明确的产品契约并记录不可逆的数据、模型和推出选择
repo-scan / codebase-onboarding / code-tour	在引入并行 ML 堆栈之前查找现有的训练、特征、服务、评估和监控路径
plan / feature-dev	将模型更改范围化为具有数据、评估、服务和回滚阶段的产品能力
tdd-workflow / python-testing	在实现之前测试特征转换、分割逻辑、指标计算、工件加载和推理 schema
code-reviewer / mle-reviewer	审查代码质量加上 ML 特定的泄漏、可重现性、推广和监控风险
build-fix / pr-test-analyzer	诊断损坏的 CI、不稳定的评估、缺失的 fixture 和环境特定的模型或依赖失败
quality-gate / test-coverage	要求转换、指标、推理契约、推广门槛和回滚行为的自动证据
eval-harness / verification-loop	将离线指标、切片检查、延迟预算和回滚演练转化为可重复门槛
ai-regression-testing	将每个生产错误保留为回归：缺失特征、陈旧标签、坏工件、schema 漂移或服务不匹配
api-design / backend-patterns	设计预测 API、批量作业、幂等重新训练端点和响应包络
database-migrations / postgres-patterns / clickhouse-io	版本标签、特征快照、预测日志、实验指标和漂移分析
deployment-patterns / docker-patterns	使用健康检查、资源限制和回滚打包可重现的训练和服务映像
canary-watch / dashboard-builder	使推出健康可见，具有模型版本、切片、漂移、延迟、成本和延迟标签仪表板
security-review / security-scan	检查模型工件、笔记本、提示、数据集和日志中的机密、PII、不安全反序列化和供应链风险
e2e-testing / browser-qa / accessibility	测试消费预测的关键产品流程，包括可解释性和后备 UI 状态
benchmark / performance-optimizer	测量吞吐量、p95 延迟、内存、GPU 利用率以及每次预测或重新训练的成本

十个 MLE 任务模拟

在规划或审查 MLE 工作时使用这些模拟作为覆盖检查。强大的 MLE 工作流应将每个任务减少到明确契约、可重用的 SWE 表面、自动证据和可审查的工件。

ID	常见 MLE 任务	简化的 ECC 路径	所需输出	覆盖的管道路径
MLE-01	框架模糊的预测、排名、推荐器、分类器、嵌入或预测能力	product-capability、plan、architecture-decision-records、mle-workflow	迭代简报命名谁关心、决策所有者、成功指标、不可接受的错误、假设、约束和第一个实验	产品契约、利益相关者损失、风险、推出
MLE-02	定义指标目标、标签、数据来源和错误预算	repo-scan、database-reviewer、database-migrations、postgres-patterns、clickhouse-io	数据和指标契约，具有实体粒度、标签时间、标签置信度、特征时间、时间点连接、分割策略和数据集快照	数据契约、指标设计、泄漏、可重现性
MLE-03	在添加复杂性之前构建基线模型和评分路径	tdd-workflow、python-testing、python-patterns、code-reviewer	具有混淆矩阵、校准注释、延迟/成本估算、已知弱点和分数形状及确定性测试的基线评分器	基线、评分、测试、服务同等性
MLE-04	根据关于什么分离结果的假设生成特征	python-patterns、pytorch-patterns、docker-patterns、deployment-patterns	特征计划和转换模块，涵盖信号源、缺失值、异常值、相关性、泄漏检查和训练/服务同等性	特征管道、泄漏、训练、工件
MLE-05	在权衡下调整阈值、配置和模型复杂性	eval-harness、ai-regression-testing、quality-gate、test-coverage	阈值/配置报告，比较精确度、召回率、F1、AUC、校准、组切片、延迟、成本、复杂性和可接受的错误类别	评估、阈值、推广、回归
MLE-06	运行错误分析并将错误转化为下一个实验	eval-harness、ai-regression-testing、mle-reviewer、silent-failure-hunter	错误集群报告，用于误报、漏报、模糊标签、陈旧特征、缺失信号和错误跟踪，包含捕获的教训	错误分析、错误跟踪、迭代、回归
MLE-07	为批量或在线推理打包模型工件	api-design、backend-patterns、security-review、security-scan	版本化工件包，具有预处理、配置、依赖约束、schema 验证、安全加载和 PII 安全日志	工件、安全、推理契约
MLE-08	推出在线服务或带反馈捕获的批量评分	api-design、backend-patterns、e2e-testing、、

迭代简报

在接触模型代码之前，将工作压缩为一个可审查的工件。这应该足够短以适合 PR 描述，并足够精确，以便另一个工程师可以挑战权衡。

目标：
谁关心：
决策所有者：
模型改变的用户或系统操作：
成功指标：
护栏指标：
错误预算：
不可接受的错误：
可接受的错误：
假设：
约束：
标签和数据快照：
基线：
候选信号：
阈值或配置计划：
评估切片：
已知风险：
下一个实验：
回滚或后备：

此简报是强 SWE 设计说明的 MLE 等价物。它防止团队优化没人信任的指标、添加不解决真正错误模式的特征，或在没有回滚的情况下发布复杂性。

决策大脑

当任务模糊、高影响或指标繁重时使用此循环：

1. 从决策开始，而不是模型。命名改变下游行为的操作。
2. 命名谁关心以及为什么。不同的利益相关者为误报、漏报、延迟、计算支出、不透明性或错失机会支付不同的成本。
3. 将模糊性转化为假设。询问什么信号会分离结果，什么证据会反驳它，以及什么简单基准应该难以击败。
4. 在发明定制系统之前研究先前的艺术或附近的已知问题。
5. 用 (概率, 置信度) x (成本, 严重性, 重要性, 影响) 对选择进行评分。
6. 考虑对抗行为、激励、选择性披露、分布转移和反馈循环。
7. 优先选择减少最重要错误的最简单更改。简单不是懒惰；它是在保持迭代速度的同时最小化错误的一种方式。
8. 捕获决策、证据、反驳论点和下一个可逆步骤。

指标和错误经济学

从失败成本而不是习惯中选择指标：

• 尽早使用混淆矩阵，以便团队可以讨论具体的误报和漏报，而不是抽象准确性。
• 当不正确积极决策的成本占主导地位时，优先考虑精确度。
• 当错失积极决策的成本占主导地位时，优先考虑召回率。
• 仅当精确度/召回率权衡真正平衡且可解释时才使用 F1。
• 当排序质量比单个阈值更重要时，使用 AUC 或排名指标。
• 将延迟、吞吐量、内存和成本作为一等指标跟踪，因为它们决定了可行的模型复杂性。
• 在庆祝离线收益之前，与基线和当前生产模型进行比较。
• 将现实世界的反馈信号视为具有偏差、滞后和覆盖范围的延迟标签；不经分析不将其视为基本事实。

每个指标选择都应陈述它使哪个错误更便宜，使哪个错误更有可能，以及谁吸收该成本。

数据和特征假设

特征应来自分离理论：

• 文本、分类字段、数字历史、图形关系、最近性、频率和聚合是候选信号族，而不是自动特征。
• 对于每个特征族，陈述为什么它应该分离结果以及它如何可能泄漏未来信息。
• 对于噪声标签，考虑裁决、标签置信度、软目标或置信度加权。
• 对于类别不平衡，比较加权损失、重采样、阈值移动和校准决策规则。
• 对于缺失值，决定缺席是否具有信息性、可插补或是否是弃权的理由。
• 对于异常值，决定是否剪裁、分桶、调查或将其保留为罕见但重要的信号。
• 对于相关特征，检查它们是否冗余、不稳定或不可用未来状态的代理。

在错误分析显示基线因额外信号或容量可以合理修复的原因失败之前，不要增加模型复杂性。

错误分析循环

在每个基线、训练运行、阈值更改或配置更改后：

1. 将错误拆分为误报、漏报、弃权、低置信度案例和系统故障。
2. 通过共享特征对错误进行聚类：语言、实体类型、来源、时间、地理、设备、稀疏性、最近性、特征新鲜度、标签来源或模型版本。
3. 将模型错误与数据错误、标签模糊、产品模糊、检测缺口和服务不匹配分开。
4. 将每个主要集群追溯到四个动作之一：更好的标签、更好的特征、更好的阈值/配置或更好的产品后备。
5. 将每个重要错误保留为回归测试、评估切片、仪表板面板或运行手册条目。
6. 将下一次迭代写成可证伪的实验，而不是模糊的"改进模型"任务。

最强的 MLE 循环不是训练 -> 指标 -> 发布。它是错误 -> 聚类 -> 假设 -> 实验 -> 证据 -> 更简单的系统。

观察账本

在代码、PR、实验报告或运行手册旁边保留紧凑的决策和证据跟踪：

迭代：
更改：
为什么这很重要：
指标移动：
切片移动：
误报：
漏报：
意外错误：
决策：
接受的权衡：
捕获的教训：
添加的回归：
创建的债务：
下一次迭代：

使用账本使模型工作累积。目标是让每次迭代使下一个决策更容易，而不仅仅是产生另一个工件。

核心工作流程

1. 定义预测契约

在编写模型代码之前捕获产品级契约：

• 预测目标和决策所有者
• 输入实体、输出 schema、置信度/校准字段和允许的延迟
• 批处理、在线、流式或混合服务模式
• 当模型、特征存储或依赖项不可用时的后备行为
• 高影响决策的人工审查或覆盖路径
• 输入、预测和标签的隐私、保留和审计要求

不要接受"改进模型"作为要求。将模型与可观察的产品行为和可测量的接受门槛联系起来。

2. 锁定数据契约

每个 ML 任务都需要明确的数据契约：

• 实体粒度和主键
• 标签定义、标签时间戳和标签可用性延迟
• 特征时间戳、新鲜度 SLA 和时间点连接规则
• 训练、验证、测试和回测分割策略
• 所需列、允许空值、范围、类别和单位
• 不得进入训练工件或日志的 PII 或敏感字段
• 可重现性的数据集版本或快照 ID

首先防范泄漏。如果特征在预测时间不可用或使用未来信息连接，删除它或将其移动到仅分析路径。

3. 构建可重现管道

训练代码应可由另一个工程师运行，无需隐藏的笔记本状态：

• 对所有超参数和路径使用类型化配置文件或 dataclass
• 固定包和模型依赖
• 设置随机种子并记录任何非确定性 GPU 行为
• 记录数据集版本、代码 SHA、配置哈希、指标和工件 URI
• 将预处理逻辑与模型工件一起保存，而不是单独保存在笔记本中
• 保持训练、评估和推理转换共享或从一个源生成
• 使每个步骤幂等，以便重试不会损坏工件或指标

优先使用不可变值和纯转换函数。避免在特征生成期间变异共享数据帧或全局配置。

import hashlib
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class TrainingConfig:
    dataset_uri: str
    model_dir: Path
    seed: int
    learning_rate: float
    batch_size: int


def artifact_name(config: TrainingConfig, code_sha: str) -> str:
    config_key = f"{config.dataset_uri}:{config.seed}:{config.learning_rate}:{config.batch_size}"
    config_hash = hashlib.sha256(config_key.encode("utf-8")).hexdigest()[:12]
    return f"{code_sha[:12]}-{config_hash}"

4. 推广前评估

应在训练完成前声明推广标准：

• 基线模型和当前生产模型比较
• 与产品行为一致的主要指标
• 延迟、校准、公平切片、成本和错误集中的护栏指标
• 重要队列、地理、设备、语言或数据源的切片指标
• 指标噪声时的置信区间或重复运行方差
• 高影响模型的人工审查故障示例
• 明确的"不发布"门槛

PROMOTION_GATES = {
    "auc": ("min", 0.82),
    "calibration_error": ("max", 0.04),
    "p95_latency_ms": ("max", 80),
}


def assert_promotion_ready(metrics: dict[str, float]) -> None:
    missing = sorted(name for name in PROMOTION_GATES if name not in metrics)
    if missing:
        raise ValueError(f"模型推广指标缺少所需门槛: {missing}")

    failures = {
        name: value
        for name in (direction, threshold) in PROMOTION_GATES.items()
        for value in [metrics[name]]
        if (direction == "min" and value < threshold)
        or (direction == "max" and value > threshold)
    }
    if failures:
        raise ValueError(f"模型未通过推广门槛: {failures}")

将离线指标用作门槛，而非保证。当模型改变产品行为时，在完全推出之前规划影子评估、金丝雀推出或 A/B 测试。

5. 为服务打包

ML 工件仅在服务契约可测试时才可用于生产：

• 模型工件包括版本、训练数据引用、配置和预处理
• 输入 schema 拒绝无效、陈旧或超出范围的特征
• 输出 schema 在有用时包括模型版本和置信度或解释字段
• 服务路径具有超时、批处理、资源限制和后备行为
• CPU/GPU 要求明确且已测试
• 预测日志避免 PII 并包括足够的标识符用于调试和标签连接
• 集成测试覆盖缺失特征、陈旧特征、坏类型、空批量和后备路径

永远不要让仅训练特征代码与服务特征代码分歧，而没有证明同等性的测试。

6. 运营模型

模型监控需要系统和质量信号：

• 可用性、错误率、超时率、队列深度和 p50/p95/p99 延迟
• 特征空值率、范围漂移、分类漂移和新鲜度漂移
• 预测分布漂移和置信度分布漂移
• 标签到达健康和延迟质量指标
• 业务 KPI 护栏和回滚触发器
• 金丝雀和回滚的每个版本仪表板

每个部署都应有回滚计划，命名先前工件、配置、数据依赖和流量切换机制。

审查清单

• 预测契约明确且可测试
• 数据契约定义实体粒度、标签时间、特征时间和快照/版本
• 根据预测时间可用性检查泄漏风险
• 训练可从代码、配置、数据版本和种子重现
• 指标与基线和当前生产模型比较
• 高风险队列的切片指标和护栏
• 推广门槛自动化且失败关闭
• 训练和服务转换共享或同等性测试
• 模型工件携带版本、配置、数据集引用和预处理
• 服务路径验证输入并具有超时、后备和回滚行为
• 监控覆盖系统健康、特征漂移、预测漂移和延迟标签
• 敏感数据从工件、日志、提示和示例中排除

反模式

• 需要笔记本状态才能重现模型
• 随机分割将未来数据泄漏到验证或测试集
• 特征连接忽略事件时间和标签可用性
• 离线指标改进而重要切片回归
• 阈值在测试集上反复调整
• 训练预处理手动复制到服务代码
• 预测日志中缺少模型版本
• 监控仅检查服务正常运行时间，而非数据或预测质量
• 回滚需要重新训练而不是切换到已知良好的工件

输出期望

使用此技能时，返回具体工件：数据契约、推广门槛、管道步骤、测试计划、部署计划或审查发现。调用阻止生产准备的未知数，而不是用假设填充它们。