5-实验记录格式

概述与定位

一句话定位: 标准化的实验记录格式确保实验过程可追溯、结果可比较、代码可复用。

** prerequisites **

Git版本控制基础
实验追踪工具基础（可选 wandb/mlflow）
机器学习实验设计基础
Markdown书写基础

核心直觉

机器学习研究本质上是实验驱动的，但实验管理的专业化程度往往落后于代码管理。一个好的实验记录系统应该做到：任何时候回看实验日志，都能立即理解实验目的、配置、结果和分析。

为什么需要标准化格式的核心直觉：当实验数量从10个增加到100个时，没有结构化记录会导致”这个配置是做什么的来着”这样的问题。标准化格式使得实验可以被高效检索和比较。

版本控制的核心直觉：代码用Git管理，实验配置和结果也应该用Git管理。这样实验记录和代码变更同步，可以在任意时刻重现任何历史实验状态。

实验记录模板

核心格式（Markdown）

# Experiment: [唯一标识符]
 
## 基本信息
- **实验ID**: exp-[日期]-[序号]
- **日期**: YYYY-MM-DD
- **负责人**: [姓名]
- **目的**: [一句话描述实验目的]
 
## 研究问题
[描述这个实验试图回答的研究问题]
 
## 实验配置
 
### 数据集
- 名称: [数据集名称]
- 版本: [commit hash 或日期]
- 大小: [N_train, N_val, N_test]
- 预处理: [预处理步骤描述]
 
### 模型
- 基础模型: [模型架构]
- 修改点: [相比baseline的改动]
- 关键超参数: [表格记录]
 
### 训练
- 优化器: [optimizer]
- 学习率: [lr]
- Batch size: [bs]
- Epochs: [n_epochs]
- 随机种子: [seed]
 
## 结果
 
### 主要指标
| 指标 | 数值 | 标准差 | 对比baseline |
|------|------|--------|-------------|
| Accuracy | 0.85 | 0.02 | +0.03 |
| F1 | 0.82 | 0.03 | +0.02 |
 
### 次要指标
[记录其他关注指标]
 
### 关键观察
1. [第一个关键发现]
2. [第二个关键发现]
 
## 分析
 
### 为什么这样（/为什么不工作）
[分析结果背后的原因]
 
### 与假设的对比
[实验结果是否支持假设]
 
### 下一步
[基于这个实验，下一步计划是什么]
 
## 复现信息
- **代码commit**: [git commit hash]
- **分支**: [git branch]
- **复现命令**: [运行命令]

Metric日志格式

JSON格式（机器可读）

{
  "experiment_id": "exp-20240115-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "config": {
    "model": "PC algorithm",
    "alpha": 0.05,
    "n_samples": 1000,
    "seed": 42
  },
  "metrics": {
    "train": {
      "shd": 5.0,
      "tpr": 0.8,
      "fpr": 0.1
    },
    "test": {
      "shd": 6.0,
      "tpr": 0.75,
      "fpr": 0.15
    }
  },
  "runtime": {
    "total_seconds": 120.5,
    "memory_mb": 2048
  }
}

CSV格式（表格化）

exp_id,model,alpha,n_samples,shd,tpr,fpr,runtime
exp-001,PC,0.05,1000,5.0,0.80,0.10,120.5
exp-002,PC,0.01,1000,8.0,0.70,0.05,125.3
exp-003,GES,0.10,1000,4.0,0.85,0.12,200.1

版本控制实践

Git仓库结构

project/
├── configs/
│   ├── exp-001.yaml      # 每次实验的配置文件
│   ├── exp-002.yaml
│   └── ...
├── experiments/
│   ├── exp-001/
│   │   ├── metrics.json  # 指标记录
│   │   ├── analysis.md   # 分析笔记
│   │   └── plots/       # 可视化结果
│   └── ...
├── logs/
│   └── training.log      # 训练日志
├── src/                  # 代码
├── README.md
└── .gitignore

Commit规范

# 实验配置的commit
git add configs/exp-001.yaml
git commit -m "exp: add config for PC algorithm alpha=0.05"
 
# 实验结果的commit
git add experiments/exp-001/
git commit -m "exp: record results for exp-001 (SHD=5.0)"
 
# Tag重要实验
git tag exp-baseline-v1
git tag exp-with-noise-v1

实验追踪工具

WandB 集成

import wandb
 
wandb.init(
    project="causal-discovery",
    name="exp-001-pc-alpha005",
    config={
        "model": "PC",
        "alpha": 0.05,
        "n_samples": 1000
    }
)
 
# 记录指标
wandb.log({"shd": 5.0, "tpr": 0.80})

MLflow 集成

import mlflow
 
mlflow.start_run(run_name="exp-001")
mlflow.log_params({"model": "PC", "alpha": 0.05})
mlflow.log_metrics({"shd": 5.0, "tpr": 0.80})
mlflow.end_run()

可视化与比较

标准比较图

import matplotlib.pyplot as plt
import pandas as pd
 
# 读取实验结果
df = pd.read_csv("experiments/results.csv")
 
# 超参数敏感性分析图
fig, axes = plt.subplots(1, 2, figsize=(12, 5))
 
# Alpha敏感性
ax1 = axes[0]
for model in df['model'].unique():
    subset = df[df['model'] == model]
    ax1.plot(subset['alpha'], subset['shd'], marker='o', label=model)
ax1.set_xlabel('Alpha')
ax1.set_ylabel('SHD')
ax1.legend()
ax1.set_title('Alpha Sensitivity')
 
# 样本量敏感性
ax2 = axes[1]
for model in df['model'].unique():
    subset = df[df['model'] == model]
    ax2.plot(subset['n_samples'], subset['shd'], marker='o', label=model)
ax2.set_xlabel('Number of Samples')
ax2.set_ylabel('SHD')
ax2.legend()
ax2.set_title('Sample Size Sensitivity')
 
plt.tight_layout()
plt.savefig("figures/sensitivity_analysis.png")

表格比较

## 方法比较
 
| Method | SHD ↓ | TPR ↑ | FPR ↓ | Runtime |
|--------|-------|-------|-------|---------|
| PC (α=0.05) | 5.0 | 0.80 | 0.10 | 120s |
| GES | 4.0 | 0.85 | 0.12 | 200s |
| NOTEARS | 3.5 | 0.90 | 0.08 | 300s |
| LiNGAM | 4.5 | 0.75 | 0.15 | 180s |

复现注意事项

关键记录点

精确配置: 每个超参数都要记录，包括看似不重要的
随机种子: 记录所有随机种子（PyTorch、NumPy、Python）
环境版本: 记录关键依赖版本（Python、numpy、scipy）
运行时间: 记录训练/推理时间便于资源规划

常见问题

记录缺失: 事后补记不完整且不准确
格式不一致: 不同实验格式不同导致比较困难
结果分散: 结果存在多个文件难以汇总

最佳实践

# 每个实验开始前创建记录文件
touch experiments/exp-$(date +%Y%m%d)-001/metrics.json
 
# 训练完成后立即记录结果
git add experiments/exp-*/metrics.json
git commit -m "exp: record metrics"

本章要点总结

结构化实验记录确保过程可追溯
唯一实验ID连接配置、代码、结果
JSON/CSV格式便于程序化分析
Git管理实验配置与代码同步
WandB/MLflow提供自动化追踪
可视化比较加速方法评估
超参数敏感性分析指导调参
随机种子必须记录确保可复现
事后补记不完整，应实时记录
标准化格式使批量分析成为可能

关键词

实验记录实验追踪 Metric日志版本控制 Git WandB MLflow 超参数敏感性实验比较研究规范

Huajishe Notes

Explorer