WB实验管理：构建可追溯、可复用的机器学习实验体系

1. 为什么“看不见的实验”正在悄悄拖垮你的模型交付效率

你有没有过这种经历：上周刚跑通的一个效果还不错的模型，这周想复现时发现——训练脚本里混着三版数据预处理逻辑，超参配置散落在两个 Jupyter Notebook 和一个被遗忘的 config.yaml 里，关键指标只在终端里闪了一下就没了；你想跟同事解释“为什么最终选了 DecisionTree 而不是 Ridge”，翻遍代码却找不到那次对比实验的完整记录；更糟的是，当业务方问“这个 RMSE 是在哪个数据版本上测的？用的是清洗前还是清洗后的测试集？”，你只能沉默两秒，然后说：“我……再跑一遍试试？”

这不是个别现象，而是绝大多数 ML 工程师每天都在面对的“实验债务”。它不像代码 bug 那样立刻报错，却像慢性病一样持续侵蚀项目可信度、协作效率和迭代速度。我带过 7 个从零搭建 MLOps 流程的团队，其中 5 个在项目中期都卡在同一个瓶颈：不是模型不够好，而是实验过程无法追溯、无法对齐、无法复用。有人把模型训练比作炼丹，那传统做法就是烧完一炉丹，连炉子、药材批次、火候记录都扔了——下次想炼同款，只能靠玄学重试。

Weights & Biases（下文简称 W&B）不是又一个“炫技型”可视化工具，它是专为解决这个根本矛盾而生的实验操作系统。它的核心价值，不在于画出多漂亮的曲线图，而在于把原本隐性、碎片化、易丢失的实验行为，强制转化为显性、结构化、可版本化的数字资产。比如，当你调用wandb.init(project="predicting_london_temperature")，你不是在启动一个日志进程，而是在为这次实验铸造一枚不可篡改的“数字身份证”——它自动绑定代码快照、数据版本、超参组合、硬件环境、所有指标和图表，甚至包括你训练时顺手画的那张相关性热力图。后续任何人（包括三个月后的你自己）点开这个链接，就能瞬间回到实验发生的“现场”。

这背后是三个底层设计哲学：第一，实验即实体（Experiment as First-Class Object）——W&B 把每一次init()调用视为一个独立、可命名、可搜索、可关联的实体，而非临时日志流；第二，一切皆可溯源（Everything is Traceable）——从pip install的包版本到pd.read_csv()读入的文件路径，系统会尽可能捕获上下文；第三，协作即共享上下文（Collaboration = Shared Context）——当同事看到你的rmse: 3.86，他同时能看到这个数字背后对应的数据 artifact 版本、模型代码 commit、甚至你当时写的那句# 这里跳过了 snow_depth 因为缺失率超 9%的注释。这种能力，直接把“我说我试过了”升级为“你点开链接自己看”。

所以，如果你正被以下问题困扰：模型效果波动大却找不到原因；新成员上手要花三天搞懂历史实验；A/B 测试结果无法归因到具体改动；或者每次上线前都要手动整理一份“本次更新说明”PPT——那么，这不是你技术不行，而是你缺了一套让实验过程“长出骨骼”的基础设施。接下来，我会以伦敦气温预测这个真实项目为切口，带你亲手搭建一条从数据加载到超参调优的完整实验流水线，不讲虚概念，只拆解每一步“为什么这么写”、“不这么写会踩什么坑”、“实操中哪些细节决定成败”。

2. 实验架构设计：为什么 W&B 不是日志库，而是实验操作系统

2.1 理解 W&B 的四大核心组件及其协同逻辑

很多初学者把 W&B 当成print()的高级替代品，这是最大的认知偏差。W&B 的设计本质是构建一个实验生命周期管理平台，其四大核心组件（Experiments, Artifacts, Sweeps, Models）不是并列功能，而是分层协作的有机体。理解它们的定位和交互关系，是避免后续使用中“功能堆砌却收效甚微”的前提。

• Experiments（实验）：这是整个系统的“细胞核”。每一次wandb.init()调用，无论你传入project、job_type还是group，本质上都是在创建一个具有唯一身份标识（run ID）的实验实例。它不是简单的日志容器，而是承载实验元信息的载体——包括启动时间、运行环境（GPU 型号、CUDA 版本）、代码快照（save_code=True时自动打包当前目录）、以及所有后续log()操作的归属空间。关键洞察：一个 Experiment 应该对应一个明确、单一的实验目标。比如，“Baseline modeling” 和 “Hyperparameter tuning” 必须拆成两个独立 run，而不是在一个 run 里 log 两套超参。我见过太多团队把所有调试过程塞进一个 run，结果 dashboard 里指标曲线乱成毛线团，根本无法归因。

• Artifacts（制品）：这是系统的“记忆器官”。Artifact 的设计哲学是数据/模型/代码的版本化封装。它不是一个文件上传功能，而是一个带元数据、可依赖、可追溯的实体。当你执行data_artifact.add_file("london_weather.csv")，W&B 并非简单复制文件，而是计算其 SHA256 哈希值作为该数据版本的“指纹”，并记录添加时间、操作者、关联的 run ID。后续任何实验若需使用此数据，只需声明artifact = run.use_artifact("original_dataset:v0")，系统自动解析依赖并挂载。实操心得：Artifact 的type字段（如"data"、"model"、"code"）绝非可有可无的标签。它决定了 W&B 后台如何索引和展示——type="data"的制品会出现在 Data Browser 中，支持 CSV 预览和行数统计；type="model"则能触发模型卡片生成，显示框架、输入输出签名。我建议严格遵循官方推荐类型，避免自定义type="my_custom_thing"，否则后续协作时同事根本找不到你的制品。

• Sweeps（超参搜索）：这是系统的“自动化引擎”。Sweep 不是GridSearchCV的包装器，而是将超参搜索本身定义为一个可配置、可复现、可监控的实验范式。它通过 YAML 配置文件定义搜索空间、优化目标（如最小化val_loss）、调度策略（如 Bayesian Optimization），然后由 W&B Agent 在指定机器上拉起多个并发 Experiment 自动执行。为什么必须用 Sweep 而非手写循环？因为手写循环的每个fit()调用都是孤立的 Experiment，缺乏统一的目标对齐和失败重试机制。而 Sweep 将整个搜索过程视为一个父实验（parent sweep），每个子实验（child run）自动继承父级配置，并实时聚合最优结果。我在金融风控项目中用 Sweep 替代手写 for 循环后，超参搜索耗时降低 40%，且所有失败实验的错误日志自动归集到 Sweep Dashboard，排查效率提升数倍。

• Models（模型注册）：这是系统的“交付枢纽”。Model 是 Artifact 的特化子集，专为生产部署设计。当你log_artifact()一个type="model"的制品，并打上aliases=["production", "v2.1"]标签，它就进入了 Model Registry。这里支持模型版本语义化（v1.0,staging,latest）、A/B 测试流量分配、以及与 CI/CD 系统集成（如 GitHub Action 推送新模型时自动触发测试）。避坑提示：不要把训练好的.pkl文件直接log_artifact()就完事。W&B Model Registry 要求模型必须包含可执行的inference.py和requirements.txt，否则无法在生产环境一键部署。我曾因漏传inference.py导致线上服务启动失败，回滚耗时 2 小时——现在所有模型制品都强制通过wandb model validate检查才允许注册。

这四大组件的协同，构成了一个闭环：Experiment 定义单次探索 → Artifact 固化输入输出 → Sweep 编排批量探索 → Model 封装可交付成果。它们共同作用，把原本线性的、易丢失的实验流程，重构为网状的、可追溯的知识网络。

2.2 项目结构设计：如何规划一个可持续演进的 W&B 项目

一个混乱的 W&B 项目，其危害不亚于一个没有 Git 分支管理的代码库。我见过最典型的反模式是：所有实验都丢进一个叫ml_project的 project 下，run 名称全是默认的run-20231015_142321-8xkz9q3m，Artifact 名称五花八门（data_v1,clean_data_final,final_clean_data_really）。半年后，没人能说清哪个 run 对应哪个业务需求。

基于 12 个落地项目的沉淀，我总结出一套经过验证的项目结构规范：

Project 层级：按业务域或模型类型划分

• predicting_london_temperature（气候预测）
• customer_churn_prediction（用户流失）
• fraud_detection_v2（风控，带版本号）
  原则：Project 名称必须清晰表达业务目标，禁止使用ml_experiments、all_models等模糊名称。一个 Project 内只放同一类问题的实验，避免跨领域混杂。

Run 层级：用job_type+group构建语义化分组

• job_type="data_ingestion"：数据接入与校验
• job_type="eda"：探索性分析（必须 log 所有分布图、缺失值报告）
• job_type="feature_engineering"：特征构造与选择（log 特征重要性图、相关性矩阵）
• job_type="baseline_training"：基线模型训练（log 训练/验证曲线、残差图）
• job_type="hyperparameter_tuning"：超参搜索（必须关联 Sweep ID）
• job_type="ab_test"：线上 A/B 测试（log 流量分配比例、业务指标）
  原则：job_type是实验类型的“宪法”，必须全局统一。我在团队推行时，会维护一份JOB_TYPE_REGISTRY.md文档，明确定义每个 type 的输入输出规范。group参数则用于逻辑分组，例如group="Q3_2023_finetune"可将季度内所有调优实验聚类。

Artifact 命名：采用<domain>_<stage>_<version>语义化格式

• london_weather_raw_v1（原始数据 v1）
• london_weather_cleaned_v2（清洗后数据 v2）
• temperature_baseline_model_v3（基线模型 v3）
• temperature_tuned_model_production（生产就绪模型）
  原则：版本号vX仅在数据/模型发生实质性变更时递增（如新增特征、修改清洗逻辑、更换算法），而非每次实验都加 1。production等别名（alias）只用于 Model Registry，不用于普通 Artifact。

这套结构的价值，在于它把“人脑记忆”转化为“系统可查询”。当产品经理问“上个月上线的温度预测模型，用的是哪版数据？”，你只需在 W&B Dashboard 的predicting_london_temperature项目中，筛选job_type="baseline_training"且alias="production"的 run，点击进入，就能看到它明确依赖的london_weather_cleaned_v2Artifact——点击该 Artifact，立即显示其创建时间、SHA256 哈希、以及所有引用它的实验列表。整个过程无需翻代码、无需问同事、无需猜。

3. 核心实操解析：从数据加载到超参调优的完整链路

3.1 数据加载与 Artifact 创建：为什么add_file()不是简单的文件上传

数据是实验的基石，但数据管理恰恰是最容易被轻视的环节。原始教程中data_artifact.add_file("london_weather.csv")这行代码看似简单，实则暗藏关键决策点。我来拆解其背后的工程逻辑和常见陷阱。

第一步：理解add_file()的原子性与不可变性
add_file()操作并非将文件内容实时写入 W&B 服务器，而是将文件路径注册到当前 Artifact 的“待提交清单”中。真正的上传发生在run.log_artifact(data_artifact)被调用时，此时 W&B SDK 会：

1. 计算文件的 SHA256 哈希值（作为该数据版本的唯一指纹）
2. 将哈希值、文件名、大小、MIME 类型等元数据打包为 Artifact Manifest
3. 将文件内容分块上传至 W&B 对象存储（默认 AWS S3 兼容）
4. 返回一个包含id、version、digest的 Artifact 引用

这意味着：Artifact 一旦log_artifact()，其内容即不可更改。如果你发现london_weather.csv有脏数据，不能直接编辑原文件再add_file()，而必须创建新 Artifact（如london_weather_cleaned_v1）并重新关联。这是保证实验可复现的基石——任何 run 关联的 Artifact，永远指向它创建时的确切数据状态。

第二步：处理大型数据集的实践方案
london_weather.csv仅 1.2MB，适合直接add_file()。但若数据集达 GB 级（如图像数据集），直接上传会阻塞训练流程。此时应采用add_reference()：

# 不上传文件本身，而是注册一个可访问的 URL 引用 data_artifact.add_reference( uri="s3://my-bucket/datasets/london_weather_full.parquet", name="london_weather_full" )

W&B 会存储该 URI，并在下游实验中通过artifact.get_path("london_weather_full").download()按需拉取。这要求你的存储桶（S3/GCS/Azure Blob）配置好权限，且网络可达。我在医疗影像项目中，用此方案将 200GB 数据集的上传时间从 45 分钟降至 2 秒。

第三步：数据版本控制的黄金法则
Artifact 版本（v0,v1）不是随意递增的。我严格执行三条规则：

• 规则1：数据 Schema 变更必升版（如新增humidity列、修改date格式）
• 规则2：数据清洗逻辑变更必升版（如将缺失值填充从均值改为中位数）
• 规则3：数据采样范围变更必升版（如从 2010-2020 年扩展到 2005-2020 年）
  反例警示：曾有团队为“快速修复”在v1数据上直接覆盖文件，导致所有依赖v1的历史实验结果失效。W&B 虽然保留旧版本，但 dashboard 默认显示最新版，极易引发误判。

实操代码增强版（含错误处理与日志）：

import os import wandb from pathlib import Path def create_data_artifact(file_path: str, name: str, type_: str, description: str, verify_checksum: bool = True) -> wandb.Artifact: """ 创建带完整性校验的数据 Artifact Args: file_path: 本地文件路径 name: Artifact 名称（建议含 domain_stage） type_: Artifact 类型（"data", "dataset"） description: 描述（含数据来源、时间范围、关键字段） verify_checksum: 是否校验文件完整性（防止传输损坏） """ # 1. 路径存在性检查 if not Path(file_path).exists(): raise FileNotFoundError(f"Data file not found: {file_path}") # 2. 文件大小预警（>100MB 提示） file_size = os.path.getsize(file_path) if file_size > 100 * 1024 * 1024: # 100MB print(f"⚠️ Warning: Large file ({file_size/1024/1024:.1f} MB). Consider add_reference().") # 3. 创建 Artifact artifact = wandb.Artifact( name=name, type=type_, description=description ) # 4. 添加文件（带校验） try: artifact.add_file(file_path, name=Path(file_path).name) print(f"✅ Added file '{file_path}' to artifact '{name}'") except Exception as e: raise RuntimeError(f"Failed to add file: {e}") return artifact # 使用示例 if __name__ == "__main__": # 初始化 run（确保在 init 后调用） run = wandb.init(project="predicting_london_temperature", job_type="data_ingestion") # 创建原始数据 Artifact raw_artifact = create_data_artifact( file_path="london_weather.csv", name="london_weather_raw", type_="data", description="Raw London weather data from Met Office (2000-2023), daily frequency. Columns: date, cloud_cover, sunshine, global_radiation, max_temp, mean_temp, min_temp, precipitation, pressure, snow_depth." ) # 记录 Artifact run.log_artifact(raw_artifact) run.finish()

这段代码将原始教程中脆弱的单行操作，升级为具备路径检查、大小预警、异常捕获的健壮流程。它体现了一个资深工程师的核心思维：把可能出错的环节，变成显式的、可监控的步骤。

3.2 EDA 与可视化日志：如何让图表真正成为可分析的“数据”

EDA 阶段产生的图表，常被当作“一次性产物”随手保存。但在 W&B 中，wandb.Image()的意义远不止于截图存档——它是将视觉洞察转化为可查询、可比较、可关联的结构化数据。

为什么wandb.Image()比plt.savefig()强大？

• 元数据绑定：wandb.Image()会自动捕获图像的尺寸、色彩模式、生成时间，并将其与当前 run 绑定。当你在 Dashboard 查看correlation_heatmap时，不仅能看见图片，还能看到它生成于job_type="eda"的 run，且该 run 的config中记录了pandas_version="1.5.3"。
• 交互式分析：W&B 对wandb.Image()支持缩放、下载、对比（Compare Images）。你可以将不同 run 的feature_importance_plot并排查看，直观对比特征权重变化。
• 自动 OCR 与标签：W&B 后台会对图像进行光学字符识别（OCR），提取图中文字（如坐标轴标签、标题），使其可被全文搜索。搜索max_temp，所有含该词的热力图都会被召回。

实操要点：避免“死图”，打造“活图”
原始教程中wandb.log({"correlation_heatmap": wandb.Image(plt)})存在两个隐患：

1. plt对象未关闭：matplotlib 的 figure 对象若不显式关闭，会持续占用内存，尤其在循环日志时易导致 OOM。
2. 缺少上下文描述：一张热力图本身不说明问题，需要关联其生成逻辑。

增强版 EDA 日志实践：

import matplotlib.pyplot as plt import seaborn as sns import numpy as np import pandas as pd import wandb def log_eda_visualization( fig: plt.Figure, title: str, description: str, tags: list = None, close_fig: bool = True ) -> None: """ 日志化 EDA 图表，附带丰富元数据 Args: fig: matplotlib Figure 对象 title: 图表标题（将作为 key 用于 wandb.log） description: 详细描述（含数据状态、分析目的） tags: 标签列表（用于 Dashboard 过滤，如 ["correlation", "outlier"]） close_fig: 是否关闭 figure 释放内存 """ # 1. 添加描述性 metadata 到 figure fig.suptitle(f"{title}\n{description}", fontsize=10, y=1.02) # 2. 日志化图像 wandb.log({ title: wandb.Image(fig, caption=description) }) # 3. 可选：记录图像统计信息（如像素尺寸、DPI） wandb.log({ f"{title}_stats": { "width_pixels": fig.get_figwidth() * fig.dpi, "height_pixels": fig.get_figheight() * fig.dpi, "dpi": fig.dpi } }) # 4. 关闭 figure if close_fig: plt.close(fig) # 使用示例：相关性热力图 if __name__ == "__main__": run = wandb.init(project="predicting_london_temperature", job_type="eda") # 加载数据（假设已预处理） london = pd.read_csv("london_weather_preprocessed.csv") # 生成热力图 plt.figure(figsize=(12, 8)) corr_matrix = london.corr() sns.heatmap(corr_matrix, annot=True, center=0, cmap="coolwarm", square=True, cbar_kws={"shrink": .5}) plt.title("Feature Correlation Matrix (Preprocessed Data)") # 日志化（带描述和标签） log_eda_visualization( fig=plt.gcf(), title="correlation_heatmap", description="Pearson correlation coefficients between all numeric features after preprocessing. High positive/negative values indicate strong linear relationships.", tags=["correlation", "preprocessed_data"] ) # 生成缺失值报告图 plt.figure(figsize=(10, 6)) missing_pct = london.isnull().mean() * 100 missing_pct.plot(kind='barh', color='skyblue') plt.xlabel('Missing Values (%)') plt.title('Missing Value Percentage by Column') log_eda_visualization( fig=plt.gcf(), title="missing_value_report", description="Percentage of missing values in each column of the preprocessed dataset. Columns with >5% missingness may require imputation or removal.", tags=["missing_values", "data_quality"] ) run.finish()

这段代码的关键升级在于：

• caption参数：为每张图添加可搜索的文本描述，Dashboard 中鼠标悬停即可查看。
• tags参数：在 Dashboard 的 Filter 面板中，可一键筛选所有tag="correlation"的图表，极大提升分析效率。
• stats日志：记录图像 DPI 和尺寸，为后续自动化质量检查（如检测低分辨率图）提供依据。

提示：W&B 还支持wandb.Table()记录结构化表格数据。对于 EDA，我强烈建议将london.info()的输出解析为 Table：

# 将数据信息转为 wandb.Table info_table = wandb.Table(columns=["Column", "Non-Null Count", "Dtype", "Memory Usage"]) for col in london.columns: non_null = london[col].count() dtype = str(london[col].dtype) mem_usage = london[col].memory_usage(deep=True).sum() info_table.add_data(col, non_null, dtype, mem_usage) wandb.log({"data_info_table": info_table})

这样，data_info_table在 Dashboard 中可排序、可筛选、可导出，比终端输出强大百倍。

3.3 特征工程与模型日志：如何让“黑箱”变得透明可审计

特征工程是模型效果的隐形天花板，但其过程往往充满主观判断。W&B 的Artifact和log()机制，能将这些判断显性化、可审计化。

原始教程的局限性：
教程中ridge.fit(X_train, y_train)后直接sns.barplot(x=X_train.columns, y=ridge.coef_)，这存在两个问题：

1. 特征重要性图未关联原始数据：图中显示cloud_cover权重最高，但没说明这个X_train是从哪个数据版本（london_weather_cleaned_v2？v3？）生成的。
2. 模型未持久化为 Artifact：pickle.dump(ridge, ...)保存了模型，但未将其与训练数据、超参、评估指标形成强关联。

增强版特征工程与模型日志方案：

import pickle import pandas as pd import numpy as np from sklearn.linear_model import Ridge from sklearn.model_selection import train_test_split import wandb def log_feature_selection_and_model( X: pd.DataFrame, y: pd.Series, model: object, model_name: str, feature_importance_method: str = "coefficient", description: str = "" ) -> None: """ 一体化日志化特征选择过程与模型 Args: X: 特征矩阵（DataFrame） y: 目标变量（Series） model: 已训练的模型对象 model_name: 模型名称（用于 Artifact 命名） feature_importance_method: 重要性计算方法（"coefficient", "permutation"） description: 模型描述（含特征选择逻辑、超参） """ # 1. 创建模型 Artifact model_artifact = wandb.Artifact( name=f"{model_name}_model", type="model", description=description ) # 2. 保存模型（带元数据） model_path = f"{model_name}_model.pkl" with open(model_path, "wb") as f: pickle.dump({ "model": model, "feature_names": X.columns.tolist(), # 显式保存特征名 "target_name": y.name, "training_date": pd.Timestamp.now().isoformat(), "feature_importance_method": feature_importance_method }, f) model_artifact.add_file(model_path, name=f"{model_name}_model.pkl") # 3. 生成并日志化特征重要性图 if feature_importance_method == "coefficient": importance = np.abs(model.coef_) feature_names = X.columns else: # permutation importance（需额外计算） from sklearn.inspection import permutation_importance perm_imp = permutation_importance(model, X, y, n_repeats=10, random_state=42) importance = perm_imp.importances_mean feature_names = X.columns # 绘制重要性图 plt.figure(figsize=(10, 6)) indices = np.argsort(importance)[::-1] plt.bar(range(len(importance)), importance[indices]) plt.xticks(range(len(importance)), [feature_names[i] for i in indices], rotation=45) plt.title(f"Feature Importance ({feature_importance_method})") plt.ylabel("Importance Score") # 日志化图表 wandb.log({ f"{model_name}_feature_importance": wandb.Image(plt.gcf()) }) plt.close() # 4. 记录重要性数值（结构化数据） importance_table = wandb.Table( columns=["Feature", "Importance_Score", "Rank"], data=[[feature_names[i], importance[i], rank+1] for rank, i in enumerate(indices)] ) wandb.log({f"{model_name}_importance_table": importance_table}) # 5. 记录特征选择逻辑（文本日志） wandb.log({ f"{model_name}_selection_logic": wandb.Html(f""" <h3>Feature Selection Logic</h3> <ul> <li><strong>Method:</strong> {feature_importance_method}</li> <li><strong>Threshold:</strong> Top 5 features selected</li> <li><strong>Rationale:</strong> {description}</li> </ul> """) }) # 6. 记录模型超参（自动从 model.__dict__ 提取） wandb.config.update({ f"{model_name}_params": {k: v for k, v in model.__dict__.items() if not k.startswith('_') and isinstance(v, (int, float, str, bool))} }) # 7. 记录模型 Artifact wandb.log_artifact(model_artifact) # 使用示例 if __name__ == "__main__": run = wandb.init(project="predicting_london_temperature", job_type="feature_engineering") # 加载预处理数据 london = pd.read_csv("london_weather_preprocessed.csv") X = london.drop(columns=["mean_temp", "min_temp", "max_temp", "date"]) y = london["mean_temp"] # 训练 Ridge 模型 ridge = Ridge(alpha=0.1) ridge.fit(X, y) # 日志化整个流程 log_feature_selection_and_model( X=X, y=y, model=ridge, model_name="ridge_feature_selector", feature_importance_method="coefficient", description="Ridge regression with alpha=0.1 used to identify top features for temperature prediction. Coefficients' absolute values indicate relative importance." ) run.finish()

这个函数将原本分散的 5-6 个操作（训练、绘图、保存、日志）整合为一个原子化动作，其价值在于：

• 特征名显式保存：模型.pkl文件中嵌入feature_names，避免部署时因列顺序错乱导致预测错误。
• 重要性数值结构化：importance_table可在 Dashboard 中排序、筛选、导出，支持后续自动化分析（如“找出所有重要性 > 0.5 的特征”）。
• 逻辑文本化：selection_logic以 HTML 形式呈现，清晰记录决策依据，新人接手时无需猜测。
• 超参自动提取：wandb.config.update()将模型内部参数（如Ridge.alpha）同步到 run config，实现“模型即配置”。

注意：wandb.Html()是一个被低估的强大功能。它允许你将任意 HTML 片段（含 CSS/JS）注入 Dashboard，用于展示复杂逻辑、流程图、甚至小型交互式组件。我常用它来嵌入pandas-profiling生成的 HTML 报告，或plotly的交互式图表。

3.4 基线训练与评估：如何构建防错的评估流水线

基线模型训练是实验的“锚点”，其评估结果的可靠性直接决定后续所有优化的方向。原始教程中mean_squared_error(y_test, y_pred, squared=False)的计算虽正确，但缺少关键的防错机制和上下文关联。

为什么RMSE单一指标不够？
RMSE 对异常值敏感，可能掩盖模型在特定子群体上的失效。例如，伦敦冬季低温预测误差大，但夏季误差小，平均 RMSE 看似合理，实则模型在关键季节不可靠。因此，评估必须是多维度的。

增强版评估流水线设计：

import numpy as np import pandas as pd from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error from sklearn.tree import DecisionTreeRegressor from sklearn.model_selection import train_test_split import matplotlib.pyplot as plt import seaborn as sns import wandb def comprehensive_model_evaluation( model: object, X_train: pd.DataFrame, y_train: pd.Series, X_test: pd.DataFrame, y_test: pd.Series, model_name: str, evaluation_metrics: list = None ) -> dict: """ 执行全面的模型评估，生成可审计的报告 Args: model: 已训练模型 X_train/y_train: 训练数据 X_test/y_test: 测试数据 model_name: 模型名称 evaluation_metrics: 自定义指标列表（默认包含 RMSE, MAE, R2, MAPE） Returns: dict: 包含所有指标、图表、分析结论的字典 """ if evaluation_metrics is None: evaluation_metrics = ["rmse", "mae", "r2", "mape"] # 1. 生成预测 y_train_pred = model.predict(X_train) y_test_pred = model.predict(X_test) # 2. 计算核心指标 metrics = {} metrics["rmse"] = mean_squared_error(y_test, y_test_pred, squared=False) metrics["mae"] = mean_absolute_error(y_test, y_test_pred) metrics["r2"] = r2_score(y_test, y_test_pred) metrics["mape"] = np.mean(np.abs((y_test - y_test_pred) / y_test)) * 100 # 3. 子群体分析（按月份分组） # 假设 X_test 包含 'month' 列 if "month" in X_test.columns: monthly_metrics = {} for month in sorted(X_test["month"].unique()): mask = X_test["month"] == month if mask.sum() > 0: rmse_month = mean_squared_error( y_test[mask], y_test_pred[mask], squared=False ) monthly_metrics[f"rmse_month_{month}"] = rmse_month metrics.update(monthly_metrics) # 4. 生成评估图表 fig, axes = plt.subplots(2, 2, figsize=(15, 12)) # 图1：预测 vs 真实值（训练集） axes[0, 0].scatter(y_train, y_train_pred, alpha=0.6, label="Train") axes[0, 0].plot([y_train.min(), y_train.max()], [y_train.min(), y_train.max()], 'r--', lw=2) axes[0, 0].set_xlabel("True Values") axes[0, 0].set_ylabel("Predictions") axes[0, 0].set_title(f"Train: Predictions vs True ({model_name})") axes[0, 0].legend() # 图2：预测 vs 真实值（测试集） axes[0, 1].scatter(y_test, y_test_pred, alpha=0.6