1. 项目概述：从“追踪”到“版本化”的范式转变

在机器学习项目的日常推进中，我们常常陷入一个熟悉的困境：模型训练了上百次，每次调整了学习率、换了数据增强策略、尝试了新的网络结构，然后我们打开TensorBoard或者MLflow的界面，看着密密麻麻的曲线和参数记录，试图回忆“上周三下午跑的那个效果还不错的实验，到底用了哪份数据预处理脚本？”。这就是典型的“实验追踪”（Experiment Tracking）场景——我们记录了大量实验的“快照”和“结果”，但实验本身（代码、数据、环境）的完整可复现状态，却像沙滩上的脚印，被后续的浪潮（新的实验）轻易覆盖。

“How to Version Machine Learning Experiments Instead of Tracking Them”这个标题，指向的正是解决这一痛点的根本性思路转变：从被动的、结果导向的“追踪”，转向主动的、状态完整的“版本化”。这不仅仅是换个工具那么简单，而是一种工程范式的升级。追踪告诉你“发生了什么”，而版本化确保你“随时能完整地重建当时发生的一切”。对于任何需要长期迭代、团队协作或面临严格审计（比如金融、医疗领域）的ML项目，后者不是可选项，而是必需品。

本文将深入拆解“实验版本化”的核心内涵，对比其与传统追踪的差异，并提供一个从思想到落地的完整实操框架。无论你是独立研究者还是团队中的算法工程师，理解并实践这套方法，都将显著提升你的研究效率和工程可靠性。

2. 核心思路拆解：版本化与追踪的本质区别

要实践版本化，首先必须从思想上厘清它与追踪的界限。很多人会把MLflow、Weights & Biases这类工具做的记录工作称为“版本管理”，但这更多是结果的版本化，而非实验本身的版本化。

2.1 传统实验追踪的局限性

传统的实验追踪工具主要关注以下几个方面：

1. 超参数记录 ：记录下本次实验使用的 learning_rate=0.001 , batch_size=32 等参数。
2. 指标记录 ：在训练和验证过程中，记录损失、准确率等指标，并可视化。
3. 产出物快照 ：保存训练好的模型权重文件（ .pth , .h5 等）。
4. 环境信息 ：可能记录Python版本、主要库的版本号。

它的核心问题在于“关联断裂” ：

• 代码与结果的断裂 ：你记录了 acc=0.92 ，但你能立刻找到生成这个准确率的确切代码版本吗？是 main 分支的 HEAD ，还是某个已经删除的特性分支上的某次提交？
• 数据与结果的断裂 ：这个结果是基于原始数据集，还是经过你昨晚临时修改的某个数据清洗函数处理后的数据？数据集的版本是什么？
• 环境与结果的断裂 ：记录 torch==1.9.0 ，但CUDA驱动版本呢？其他间接依赖的包呢？一个 numpy 的隐性版本升级可能导致随机种子行为变化，从而影响结果。

追踪工具提供了一个精美的“实验日志簿”，但它没有将日志条目与产生该条目的完整“实验室”（代码、数据、环境）绑定在一起。

2.2 实验版本化的核心要素

实验版本化追求的是捕获并冻结实验的 完整、可复现的状态 。一个被版本化的实验应该像一个打了标签的集装箱，里面包含了运行它所需的一切。其核心要素包括：

1. 代码版本化（基石） ：使用Git等工具，确保每次实验都对应一个明确的代码提交（Commit SHA）。这不仅是 train.py ，还包括所有配置文件、数据加载脚本、工具函数。
2. 数据版本化（关键输入） ：对输入数据进行版本管理。这可以通过DVC（Data Version Control）、LakeFS，或简单的对象存储（S3、OSS）加版本标识来实现。确保你知道实验跑在 dataset/v2/processed/ 这个确切的数据快照上。
3. 环境版本化（运行土壤） ：通过Docker容器镜像或Conda环境文件（ environment.yml ）精确记录所有依赖库及其版本。Docker镜像是更彻底的选择，它封装了从操作系统到Python解释器的整个环境。
4. 配置版本化（实验参数） ：将超参数、模型结构选择等从代码中分离，存入结构化的配置文件（如YAML、JSON）。该配置文件本身也应被纳入代码仓库进行版本控制。
5. 产出物版本化（关联输出） ：将训练出的模型、评估报告、可视化图表等产出物，与触发其生成的代码、数据、环境版本明确关联。通常通过唯一的实验ID或版本标签来建立这种关联。

注意 ：版本化不是要取代追踪，而是为其提供坚实的基础。理想的工作流是：先完成实验状态的版本化冻结，然后将这个“冻结容器”的运行结果（指标、曲线、模型文件路径）记录到追踪系统中，并在记录中明确指向版本化的各个组件（Git Commit, Docker Image Tag, Data Version）。

2.3 思维转变：从“跑实验”到“创建实验制品”

在追踪思维下，我们的动作是“运行脚本 -> 记录结果”。在版本化思维下，动作应变为“定义实验（代码+配置+数据引用） -> 封装环境 -> 执行并生成版本化制品”。

这个“实验制品”就是一个不可变的、自包含的实体。你可以把它归档，可以在半年后重新打开它并得到完全一致的结果，也可以将它交给同事，他无需询问任何细节就能复现你的工作。这极大地增强了研究的可信度和项目的可维护性。

3. 构建版本化实验系统的技术栈与实操

理解了“为什么”和“是什么”，接下来我们看“怎么做”。我将以一个基于开源工具的典型技术栈为例，展示如何搭建一个轻量但完整的实验版本化系统。

3.1 核心工具选型与职责划分

一个常见的组合是： Git + DVC + Docker + MLflow 。它们各司其职，形成闭环。

• Git ：版本化所有代码和文本配置文件。这是源头。
• DVC (Data Version Control) ：版本化大型数据文件、模型文件。它通过将文件存储在远程存储（S3、GCS、OSS等），而在本地仓库中只保留轻量的元文件（ .dvc 文件）来实现。 git commit 同时提交代码和数据的元信息。
• Docker ：版本化运行环境。通过 Dockerfile 定义环境，每次构建生成一个带标签的镜像（如 exp-env:v1.0 ），确保运行环境的一致性。
• MLflow ：作为实验追踪和模型注册的中心。它记录指标、参数，并 关键地 ，记录本次实验运行所关联的Git Commit、Docker Image和输入数据路径。

3.2 项目结构设计

一个支持版本化的ML项目，其目录结构应有清晰的约定。以下是一个推荐结构：

your-ml-project/
├── .dvc/                  # DVC内部目录
├── .dvcignore             # 类似.gitignore，用于DVC
├── .gitignore
├── Dockerfile             # 环境定义
├── docker-compose.yml     # （可选）服务编排
├── requirements.txt       # Python依赖（Dockerfile中使用）
│
├── configs/               # 配置文件目录
│   ├── experiment/        # 实验特定配置
│   │   ├── exp_001.yaml
│   │   └── exp_002.yaml
│   └── default.yaml       # 基础配置
│
├── data/                  # 数据目录（通过DVC管理）
│   ├── raw/               # 原始数据（.dvc文件跟踪）
│   ├── processed/         # 处理后数据（.dvc文件跟踪）
│   └── external/          # 外部数据（.dvc文件跟踪）
│
├── models/                # 模型输出目录（通过DVC管理）
│   └── .gitkeep
│
├── notebooks/             # 探索性笔记本
├── scripts/               # 工具脚本（如数据预处理）
├── src/                   # 主要源代码
│   ├── data/
│   ├── models/
│   ├── training/
│   └── utils/
│
├── tests/                 # 单元测试
└── run_experiment.py      # 统一的实验启动入口

设计要点 ：

• data/ 和 models/ 下的实际大文件都被 .dvc 文件管理，不应提交到Git。它们的实际内容存储在远程对象存储中。
• 所有核心逻辑在 src/ 下， run_experiment.py 作为一个薄薄的入口，负责读取配置、设置环境、调用训练逻辑。
• 配置文件与代码分离，方便单独版本化管理实验参数。

3.3 实操流程：一次完整的版本化实验

假设我们要进行一个图像分类实验（ exp_001 ）。

步骤1：定义实验配置 在 configs/experiment/exp_001.yaml 中定义本次实验的所有可变部分：

data:
  version: "raw/v1"  # 对应DVC跟踪的数据版本
  split_ratio: 0.8

model:
  name: "resnet50"
  pretrained: true

training:
  lr: 0.001
  batch_size: 32
  epochs: 50
  optimizer: "adam"

experiment:
  id: "exp_001"  # 实验ID，将用于标记产出物
  tags: ["baseline", "resnet50"]

将这个配置文件提交到Git： git add configs/experiment/exp_001.yaml && git commit -m "add config for exp_001 baseline" 。

步骤2：准备版本化数据 确保你的训练数据已被DVC管理。如果数据在 data/raw/ 下，通常你已经运行过 dvc add data/raw/ ，并生成了 data/raw.dvc 文件。这个 *.dvc 文件是应该被Git管理的。当你更新数据时，重新 dvc add ，DVC会计算哈希，如果文件变化，会生成新的元数据，你再提交Git。

步骤3：构建版本化环境 编写 Dockerfile ，基于一个基础镜像，安装所有依赖。构建镜像并打上标签，标签名可以包含Git提交哈希的一部分以确保唯一性。

FROM python:3.9-slim
WORKDIR /workspace
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

构建命令： docker build -t your-registry/ml-project:exp-001-git-$(git rev-parse --short HEAD) . 。之后将镜像推送到镜像仓库。

步骤4：编写可复现的实验入口脚本 run_experiment.py 的核心任务是：

1. 解析命令行参数（获取配置文件名 exp_001.yaml ）。
2. 加载配置。
3. 根据配置中的 data.version ，通过DVC API或命令确保对应版本的数据可用（ dvc pull 特定文件）。
4. 设置随机种子（在配置中定义）。
5. 初始化模型、数据加载器。
6. 开始训练，并在过程中将指标记录到MLflow。
7. 训练结束后，将最佳模型保存到 models/exp_001/ 目录，并使用DVC跟踪（ dvc add models/exp_001 ）。

关键点在于，这个脚本从配置文件中获取数据版本，而不是硬编码路径。

步骤5：运行实验并记录关联 在Docker容器内运行实验，并启动MLflow记录。这里的关键是向MLflow记录 版本元数据 。

# 在容器内运行类似如下命令（MLflow已安装）
export MLFLOW_TRACKING_URI=http://mlflow-server:5000

python run_experiment.py \
  --config configs/experiment/exp_001.yaml \
  --experiment-name "image-classification" \
  --run-name "exp_001_baseline"

在 run_experiment.py 的代码中，在开始记录前，主动设置MLflow的标签（Tags）：

import mlflow
import subprocess

# 设置实验
mlflow.set_experiment(experiment_name)

with mlflow.start_run(run_name=run_name) as run:
    # 记录Git Commit ID
    git_commit = subprocess.check_output(['git', 'rev-parse', 'HEAD']).decode('ascii').strip()
    mlflow.set_tag("git_commit", git_commit)

    # 记录Docker镜像标签（可通过环境变量传入）
    docker_image = os.environ.get('DOCKER_IMAGE_TAG', 'unknown')
    mlflow.set_tag("docker_image", docker_image)

    # 记录数据版本（来自配置文件）
    mlflow.set_tag("data_version", config['data']['version'])

    # 记录所有配置参数
    mlflow.log_params(flatten_dict(config))  # 将嵌套字典展平

    # ... 训练循环，期间用 mlflow.log_metric 记录指标 ...

    # 训练结束后，记录模型文件（模型本身已被DVC管理，这里记录路径或注册模型）
    mlflow.log_artifact("models/exp_001/best_model.pth")

现在，在MLflow的UI中，你不仅能看到指标曲线和参数，还能直接看到生成这次运行的 git_commit 、 docker_image 和 data_version 。

步骤6：版本化产出物 训练完成后，模型文件保存在 models/exp_001/ 。使用DVC对其进行版本化： dvc add models/exp_001 。这会生成 models/exp_001.dvc 文件。将这个 .dvc 文件提交到Git仓库。

dvc add models/exp_001
git add models/exp_001.dvc
git commit -m "dvc: add model artifacts for exp_001"
dvc push  # 将模型文件推送到远程存储

至此，你完成了一次完整的版本化实验。Git仓库的这次提交，通过 .dvc 文件指向了特定版本的数据和模型，通过代码和配置文件定义了逻辑，通过MLflow中的标签指向了特定的Docker镜像环境。四位一体，构成了一个可复现的实验制品。

4. 高级模式与自动化管理

对于实验频率很高的团队，手动执行上述所有步骤会带来负担。此时，引入自动化流水线和工作流引擎是自然的选择。

4.1 使用DVC Pipelines进行编排

DVC不仅管理数据，还内置了一个轻量级的流水线系统。你可以定义一个 dvc.yaml 文件，将数据准备、训练、评估等步骤串联起来。

stages:
  prepare:
    cmd: python scripts/prepare_data.py --config ${config_file}
    deps:
      - scripts/prepare_data.py
      - ${config_file}
      - data/raw
    outs:
      - data/processed
    params:
      - data.split_ratio  # 从config_file中读取参数

  train:
    cmd: python src/training/train.py --config ${config_file}
    deps:
      - src/training/train.py
      - ${config_file}
      - data/processed
    outs:
      - models/${experiment.id}
    metrics:
      - metrics.json:
          cache: false  # 不缓存指标文件，每次运行都更新
    params:
      - model
      - training
      - experiment.id

  evaluate:
    cmd: python src/training/evaluate.py --config ${config_file}
    deps:
      - src/training/evaluate.py
      - ${config_file}
      - models/${experiment.id}
    metrics:
      - final_metrics.json

运行 dvc exp run --set-param config_file=configs/experiment/exp_001.yaml ，DVC会根据依赖关系自动执行各个阶段，并且 自动缓存每一阶段的输出 。如果代码、数据或参数未变，该阶段会直接使用缓存结果，极大加速实验迭代。每一次 dvc exp run 都可以视为创建了一个可复现的流水线快照。

4.2 与CI/CD集成

你可以将实验流水线集成到GitLab CI/CD或GitHub Actions中。例如，每当有新的Git标签（如 v-exp-001 ）被创建时，自动触发CI流程：

1. 根据代码仓库该标签版本的内容，构建Docker镜像并打上对应标签。
2. 在CI Runner中，拉取对应版本的数据（ dvc pull ）。
3. 运行DVC流水线（ dvc repro ）或直接运行实验脚本。
4. 将实验结果（指标、模型）推送到MLflow和模型仓库，并自动生成实验报告。

这样，实验的版本化、执行和记录完全实现了自动化，并与代码开发流程无缝衔接。

4.3 模型注册与部署联动

MLflow提供了模型注册表（Model Registry）功能。当实验产生了一个满足上线条件的模型后，你可以在MLflow UI中将其从“实验阶段”过渡到“准生产阶段”乃至“生产阶段”。这个注册的模型同样与特定的运行ID（关联着Git Commit, Docker Image）绑定。当部署系统（如Kubernetes）拉取这个注册的模型进行服务时，它能够追溯到模型诞生的完整谱系，实现了从研究到生产的可追溯性。

5. 常见问题与实战避坑指南

在实践中，从追踪切换到版本化会遇到不少挑战。以下是一些常见问题及解决方案。

5.1 存储成本与效率问题

问题 ：DVC将数据和模型存储在远程对象存储（如S3），Docker镜像存储在镜像仓库。大量实验会占用巨大存储空间，成本激增。

解决方案 ：

• 制定数据生命周期策略 ：对于中间数据和失败实验的产出物，设置自动清理规则（如S3生命周期策略），只保留最终模型和关键中间结果。
• 使用缓存和重用 ：充分利用DVC的缓存机制。对于数据处理阶段，如果输入数据和代码未变，DVC会直接使用缓存输出，避免重复计算和存储。
• 选择经济存储层 ：将不常访问的旧实验数据移至对象存储的低频访问层或归档层。
• 模型剪枝与量化 ：在保存模型前，考虑进行剪枝、量化，减小模型文件体积。

5.2 团队协作冲突

问题 ：多人同时修改数据（ .dvc 文件）或配置文件时，容易产生Git合并冲突。

解决方案 ：

• 细分数据目录 ：不要将整个 data/ 目录用一个 .dvc 文件管理。按数据集、版本进行细分，例如 data/raw/dataset_a.dvc , data/processed/dataset_a_v1.dvc 。这样不同成员修改不同数据集时不会冲突。
• 配置文件模板化 ：使用基础配置（ default.yaml ）加实验覆盖（ exp_xxx.yaml ）的方式。团队成员各自创建自己的实验配置文件，互不干扰。
• 清晰的命名规范 ：建立实验ID、分支名、镜像标签的命名规范（如 feat-xxx-{user} ， exp-{date}-{seq} ），避免混淆。

5.3 复现时的环境差异

问题 ：即使有Dockerfile，半年后可能因为基础镜像更新、源失效等原因无法构建出完全一致的环境。

解决方案 ：

• 锁定基础镜像版本 ：不要使用 python:3.9-slim 这样的浮动标签，使用 python:3.9.16-slim 这样的精确版本。
• 使用私有镜像仓库 ：将构建好的、用于关键实验的Docker镜像推送到公司私有仓库长期保存，而不是每次都重新构建。镜像本身就是最终的版本化环境制品。
• 记录非Python依赖 ：在Dockerfile中，除了 pip install ，如果涉及系统库（如 libgl1-mesa-glx ），也必须明确写出。考虑使用 apt-get install 时也固定版本（如果可能）。

5.4 实验元数据管理复杂度

问题 ：信息分散在Git、DVC、MLflow、Docker Registry等多个地方，查询和管理复杂。

解决方案 ：

• 以Git为唯一事实源 ：将所有 .dvc 文件、 Dockerfile 、配置文件都放在Git中。Git提交哈希是连接一切的“主键”。
• 利用MLflow作为查询入口 ：在MLflow中记录完整的版本标签（git_commit, docker_image, data_version）。当在MLflow中发现一个优秀实验时，可以通过这些标签一键定位到所有相关组件。
• 考虑一体化平台 ：对于大型团队，可以考虑采用Weights & Biases、Domino Data Lab、Kubeflow等更集成的平台，它们在一定程度上原生提供了代码、数据、环境、模型的版本化与关联管理。

5.5 对快速探索的阻碍感

问题 ：版本化流程似乎增加了实验的“启动成本”，不利于快速试错。

解决方案 ：

• 区分探索与正式实验 ：在Jupyter Notebook中进行快速原型探索是完全可以的。但一旦得到一个有希望的方向，就必须将其“工程化”为版本化实验。可以建立模板，将Notebook中的代码快速转换为 src/ 下的模块和配置文件。
• 自动化工具脚本 ：编写脚本来自动化“创建实验配置 -> 提交Git -> 触发CI运行”的流程。例如，一个 create_exp.py 脚本，交互式询问几个参数，然后生成配置文件、创建Git分支并提交初始代码。
• 本地轻量模式 ：对于本地开发，可以配置一个“轻量模式”，直接使用本地Conda环境（需用 conda env export > environment.yml 版本化），数据使用本地缓存，快速运行调试。但确认有效的实验，仍需走完整的Docker+远程存储流程以确保复现性。

实操心得 ：版本化带来的前期开销，会在项目进行到中后期时以巨大的复利形式回报你。它避免了“鬼知道当时怎么跑的”这种绝望时刻，让回顾、比较、报告和交付变得异常坚实。我的经验是，哪怕个人项目，也至少要做到Git提交关联和明确的配置文件管理，这是迈向可复现科研的第一步。