machine-learning

Machine Learning 是 Agent Skills™ by googleadsagent.ai™ 中的一个技能，用于端到端构建机器学习流水线，基于 PyTorch 与 scikit-learn，覆盖模型选择、训练、评估、可解释性、超参数调优与实验追踪。该技能帮助智能体构建可复现的 ML 工作流，并遵循软件工程最佳实践：版本控制的实验、确定性训练与可解释的结果。

用途

该技能的核心目标是弥合“可运行的 notebook”与“生产级 ML 流水线”之间的巨大差距。它通过强制实施结构化的实验管理、正确的训练/验证/测试划分、分层交叉验证、学习曲线分析与系统化超参数优化来实现这一点。智能体会记录每个实验的配置、指标与产物，使得数月之后仍可复现任意结果。

模型可解释性被当作一等要求，而非可选的事后分析。每个模型都附带 SHAP 值、特征重要性排名与部分依赖图，用以解释模型学到了什么以及为何做出特定预测。对于科学与业务关键型应用而言，缺乏解释的黑盒预测是不够的。

主要能力

端到端 ML 流水线构建：从数据集到模型注册表，包含训练/验证/测试划分、特征工程、模型选择、超参数调优、交叉验证、最佳模型训练、测试集评估、可解释性分析与实验日志记录。
超参数调优：使用 Optuna 进行系统化搜索，示例中支持 hidden_dim、lr、dropout 等参数的搜索空间定义。
交叉验证：使用 StratifiedKFold 进行分层交叉验证，保留类别分布。
可解释性：使用 SHAP（如 DeepExplainer）生成 SHAP 值、特征重要性排名与部分依赖图。
实验追踪：记录所有实验参数、指标与产物，支持复现。
PyTorch 模型训练：提供结构化训练循环示例，包括自定义 Classifier 模块、训练 epoch 函数等。
评估：使用 classification_report、roc_auc_score 等指标，并报告交叉验证的置信区间而非单次运行指标。

使用方式

该技能在以下情况使用：构建分类或回归模型；系统化调优超参数；用 SHAP 或特征重要性解释模型预测；为 ML 项目搭建实验追踪；用正确的交叉验证评估模型性能；训练带结构化训练循环的 PyTorch 模型。

流水线流程为：数据集 → 训练/验证/测试划分 → 特征工程 → 模型选择 → 超参数调优（Optuna）→ 交叉验证 → 最佳模型训练 → 测试集评估 → 可解释性（SHAP）→ 实验日志记录 → 模型注册表。该流水线强制严格区分调优（使用验证数据）与最终评估（使用留出的测试数据）。测试集只被触碰一次，防止重复评估导致的信息泄漏。

实现示例（代码内容保持不变）：

import torch import torch.nn as nn from torch.utils.data import DataLoader, TensorDataset from sklearn.model_selection import StratifiedKFold from sklearn.metrics import classification_report, roc_auc_score import optuna import shap import numpy as np

class Classifier(nn.Module): def init(self, input_dim: int, hidden_dim: int, dropout: float): super().init() self.net = nn.Sequential( nn.Linear(input_dim, hidden_dim), nn.ReLU(), nn.Dropout(dropout), nn.Linear(hidden_dim, hidden_dim // 2), nn.ReLU(), nn.Dropout(dropout), nn.Linear(hidden_dim // 2, 1), )

def forward(self, x: torch.Tensor) -> torch.Tensor:
    return self.net(x)

def train_epoch(model, loader, optimizer, criterion, device): model.train() total_loss = 0 for X_batch, y_batch in loader: X_batch, y_batch = X_batch.to(device), y_batch.to(device) optimizer.zero_grad() pred = model(X_batch).squeeze() loss = criterion(pred, y_batch.float()) loss.backward() optimizer.step() total_loss += loss.item() * len(X_batch) return total_loss / len(loader.dataset)

def hyperparameter_search(X: np.ndarray, y: np.ndarray, n_trials: int = 50) -> dict: def objective(trial): hidden = trial.suggest_int("hidden_dim", 32, 256) lr = trial.suggest_float("lr", 1e-4, 1e-2, log=True) dropout = trial.suggest_float("dropout", 0.1, 0.5)

    skf = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
    scores = []
    for train_idx, val_idx in skf.split(X, y):
        model = Classifier(X.shape[1], hidden, dropout)
        optimizer = torch.optim.Adam(model.parameters(), lr=lr)
        criterion = nn.BCEWithLogitsLoss()

        train_ds = TensorDataset(torch.tensor(X[train_idx], dtype=torch.float32),
                                 torch.tensor(y[train_idx], dtype=torch.float32))
        loader = DataLoader(train_ds, batch_size=64, shuffle=True)

        for _ in range(20):
            train_epoch(model, loader, optimizer, criterion, "cpu")

        model.eval()
        with torch.no_grad():
            val_pred = model(torch.tensor(X[val_idx], dtype=torch.float32)).squeeze()
        scores.append(roc_auc_score(y[val_idx], val_pred.numpy()))

    return np.mean(scores)

study = optuna.create_study(direction="maximize")
study.optimize(objective, n_trials=n_trials)
return study.best_params

def explain_model(model, X_sample: np.ndarray, feature_names: list[str]): model.eval() explainer = shap.DeepExplainer(model, torch.tensor(X_sample[:100], dtype=torch.float32)) shap_values = explainer.shap_values(torch.tensor(X_sample, dtype=torch.float32)) shap.summary_plot(shap_values, X_sample, feature_names=feature_names, show=False)

最佳实践

为 numpy、torch 与 Python 的 random 模块设置随机种子以保证可复现性。
分类任务使用分层划分以保留类别分布。
测试集只触碰一次——绝不在测试数据上调优超参数。
报告交叉验证得到的置信区间，而非单次运行的指标。
对基线之外的每个模型都包含 SHAP 或排列重要性。
记录所有实验参数、指标与产物以便复现。

适用场景

适用于构建分类或回归模型、系统化调优超参数、用 SHAP 或特征重要性解释模型预测、为 ML 项目搭建实验追踪、用正确的交叉验证评估模型性能、训练带结构化训练循环的 PyTorch 模型等场景。

平台兼容性

Cursor：完全支持，Python + PyTorch + Jupyter。
VS Code：完全支持，ML 扩展生态。
Windsurf：完全支持，ML 工作流支持。
Claude Code：完全支持，训练脚本生成。
Cline：完全支持，ML 流水线构建。
aider：部分支持，仅代码生成。

技能介绍