AI开放训练如何实现可复现？从代码公开到完整实验记录

Marin 项目最近被不少 AI 开发者当作“开放训练”的标杆来讨论。原因不是它用了多么前沿的模型结构，也不是它刷了多么惊人的榜单分数，而是它把一件在 AI 领域里最难、最容易被忽略的事做到了位：让训练过程可以被完整复现。

很多 AI 项目的 GitHub 仓库看起来很有吸引力，star 数很高，README 写得很漂亮，但真正 clone 下来准备跑的时候，问题一层接一层：训练代码里写死了绝对路径，数据集不公开，环境依赖版本不锁定，实验记录只有一张不完整的表格。你还不能说它有问题，因为代码确实“能跑”，只是别人跑不出作者声称的效果。

Marin 的典型意义在于，它把“代码公开”升级成了“训练上下文公开”。训练需要的数据、代码、环境配置、数据预处理逻辑、实验评测方式和结果记录，全部以可复现的方式放在一起。这篇文章不打算把 Marin 的每一行代码拆开讲，而是从工程视角分析：为什么这样的开放训练值得成为范例，以及我们自己做一个 AI 训练项目时，应该借鉴哪些具体做法。

如果你正在做 AI 相关的开源项目、课程作业、企业内部分享，或者只是想把一次完整实验整理得让未来的自己和同事都能看懂，这篇文章会帮你建立一套可落地的组织方法。

1. 为什么“代码开放”不等于“训练开放”

先看一个常见的项目现状：作者在 GitHub 上放了完整的训练代码，模型结构、损失函数、优化器都写得清清楚楚。理论上，任何人 clone 下来之后，把数据路径改成自己的目录，就可以开始训练。但是实际操作时，问题几乎必然出现：

训练脚本里写的是/home/user/data/，别人的机器上没有这个路径；requirements.txt 用的是numpy>=1.20，安装时自动装上了 2.x 版本，而代码依赖 numpy 1.x 的 API；数据集有清洗逻辑，但清洗脚本没有提交，别人拿到原始数据后不知道该先做什么；实验记录里写了“本模型在测试集上准确率 92.5%”，却没有说明这个测试集是哪个版本、数据划分的随机种子是多少、是否做了数据增强。

这些细节单独看都不算大问题，但累积起来，就让“开放源码”变成一个无法验证的声明。

所以，真正值得关注的判断是：开放训练的层次有高低之分，代码只是最基础的一层。

Marin 被当作典范，是因为它落在了第四层。它的项目仓库里，训练代码、数据处理流程、环境配置文件、评测脚本、实验结果记录是一个整体。你在本地跑通之后，得到的结果和项目方公布的结果在合理误差范围内一致。这件事说起来容易，真正做过的团队都知道，需要非常严格的工程约束。

从开发者视角看，复现一篇论文的失败率一直居高不下。很多团队一开始也会写 README 说明运行步骤，但等项目迭代几轮之后，文档、脚本、实验记录就慢慢脱节了。Marin 的做法之所以值得写，是因为它给 AI 训练项目提供了一套“结构性解法”，而不是靠个人自觉去维护。

2. 开放训练项目的目录结构应该怎么设计

站在工程角度，Marin 这样的项目首先赢在目录结构上。它让一个陌生人不需要看完整篇 README，就能大致推断出项目的组成部分。

如果你要构建一个可复现的 AI 训练项目，比较合理的目录组织方式如下：

marin-style-project/ ├── README.md ├── LICENSE ├── requirements.txt ├── requirements-lock.txt ├── setup.cfg ├── .gitignore ├── .pre-commit-config.yaml ├── config/ │ ├── train.yaml │ ├── data.yaml │ └── eval.yaml ├── data/ │ ├── raw/ # 原始数据，通常用 DVC 管理 │ ├── processed/ # 清洗后的数据 │ └── README.md # 数据来源与处理说明 ├── scripts/ │ ├── download_data.py │ ├── preprocess.py │ └── run_experiment.sh ├── src/ │ ├── __init__.py │ ├── model.py │ ├── dataset.py │ ├── train.py │ └── evaluate.py ├── experiments/ │ ├── baseline/ │ ├── exp01_augmentation/ │ └── exp02_model_size/ ├── outputs/ │ ├── checkpoints/ │ ├── logs/ │ └── metrics/ └── notebooks/ └── exploratory_analysis.ipynb

这套结构的设计原则是关注点分离：

• config/存放所有可调参数，训练代码里不硬编码超参数。
• data/readme.md记录数据来源、许可协议、下载方式。
• scripts/存放数据处理和实验入口脚本。
• experiments/按实验维度组织，每个实验有自己独立的目录。
• outputs/保存模型权重、训练日志和评测指标。

许多 AI 项目最常见的错误，是把所有脚本都堆在根目录下，今天叫train_v2.py，明天叫train_v3_final.py，后天叫train_v3_final_really.py。表面上看是命名问题，实际上是版本管理粒度不对——文件的命名不应该承担版本管理职责，Git 和目录结构才承担这个职责。

对 Marin 这种级别的开放项目来说，目录结构的意义不仅是整洁，更是一种“协议”：数据在哪、代码在哪、结果在哪，都有固定位置。这也让评审者、协作者和下游研究者能快速进入状态。

3. 数据开放是“开放训练”最容易被低估的一环

训练数据的处理细节，是复现论文时最容易导致偏差的地方。很多项目公开了代码，也发布了最终数据集，但中间清洗、采样、划分的过程只有寥寥几句描述。当别人用同一份数据训练，得到的指标和论文对不上时，问题往往出在这个灰色地带。

Marin 这类项目在数据上的做法可以总结为三点：可下载、可验证、可追溯。

“可下载”指的是数据文件有稳定的存储地址，而不是依赖某个聊天群或某块移动硬盘。“可验证”指的是数据文件有校验值（如 SHA256），别人下载完成后可以确认自己拿到的数据和发布者一致。“可追溯”指的是数据从原始来源到最终训练格式之间经过的处理步骤，每一步都有据可查。

在工程实现上，DVC（Data Version Control）是管理数据集版本的常见工具。它可以把大型数据文件从 Git 仓库中剥离，同时记录每个文件或目录的版本关系。看一个最小示例：

# 安装 dvc pip install dvc # 初始化 dvc dvc init # 将数据目录纳入 dvc 管理 dvc add data/raw # 生成 data/raw.dvc 文件，记录文件哈希和存储规则 cat data/raw.dvc

一个典型的 DVC 文件内容如下：

outs: - md5: 7d9e1c12c8ea9d29f25d8d1a7d4f5e63 size: 20481920 path: data/raw

上面的.dvc文件是文本格式，可以正常提交到 Git。协作者拉取项目之后，使用dvc pull就可以把对应的数据文件同步到本地。

除了版本管理，数据层面的“README”也值得做。像 Marin 这种开放程度较高的项目，通常会在数据目录里放一份说明，介绍：

• 数据来源和原始协议。
• 数据字段含义。
• 已经做的清洗操作。
• 训练集、验证集、测试集的划分比例和划分方法。
• 是否有重复样本、是否有类别不平衡问题。

这段描述的价值在于让下游研究者知道，发布者在数据预处理阶段做了哪些判断。模型结果差异的来源，很多时候根本不在模型结构，而在数据预处理。

4. 实验记录公开的关键：不只是表格，而是“可复现路径”

Marin 项目公开实验结果时，不仅仅是把准确率数字列出来。它会把每一个实验对应到具体的配置、代码提交号、数据集版本和随机种子，让“结果”可以回溯到“过程”。

在做自己的开放训练项目时，可以尝试为每个实验建立这样的记录：

这里要特别说明一点：实验记录里的“配置路径”不要写成文件名，而是写提交号。因为同一个exp01.yaml文件在不同时间点是不同内容。只有“配置 + 提交号 + 数据版本 + 随机种子”四项同时确定，一个实验才真正可复现。

实验记录中的指标定义也需要先统一。例如：

• 准确率是 top-1 还是 top-5。
• 计算准确率时在哪个数据集上评测。
• 是否使用了测试时增强（TTA）。
• 指标的平均值和标准差是否有多次重复实验支撑。

训练代码里，随机种子的设置也有讲究。一个常见的坑是只设置了torch.manual_seed，没有设置 CUDA 和 NumPy 的种子，导致实验仍有一定随机性。更稳妥的做法是在主程序入口统一设置：

import numpy as np import random import torch def set_seed(seed: int = 42): random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) # 关闭 cuDNN 自动选择算法，保证可复现 torch.backends.cudnn.deterministic = True torch.backends.cudnn.benchmark = False

把一个训练任务的随机性控制住，是开放训练的基本功。否则，即使用同一个配置文件，别人的运行结果也可能有波动，读者分不清这种波动是模型问题还是随机种子的问题。

5. 环境依赖锁定：Marin 这类项目都做了哪些事

如果说数据是复现的“燃料”，环境就是复现的“炉子”。同样的训练代码，放在不同的 Python 版本、不同版本的 PyTorch 下，结果可能不同。更麻烦的是，一些底层库的细微差异会影响到数值计算，导致结果无法对齐。

Marin 这类项目在环境管理上的典型做法，是提供两套依赖文件：

第一套是面向日常开发的宽松版本，比如requirements.txt：

torch>=2.0 numpy>=1.24 pandas>=2.0 timm>=0.9 hydra-core>=1.3

第二套是锁定版本，比如requirements-lock.txt：

torch==2.1.2 numpy==1.26.3 pandas==2.1.4 timm==0.9.12 hydra-core==1.3.2

锁定版本依赖的另一个作用是方便环境恢复。如果项目运行半年后需要重新复现，你不可能记得当时到底用了哪个版本的依赖，只有锁文件能告诉你。

对于更严格的场景，还可以提供Dockerfile，把整个训练环境打包成镜像：

FROM pytorch/pytorch:2.1.2-cuda12.1-cudnn8-runtime WORKDIR /workspace COPY requirements-lock.txt . RUN pip install --no-cache-dir -r requirements-lock.txt COPY . . ENV PYTHONUNBUFFERED=1

这样做的好处是，镜像本身对应一个确定的环境快照。只要镜像能构建成功，训练代码就能在一致的依赖层上运行。值得提醒的是，Docker 镜像只解决了软件依赖问题，没有解决 GPU 驱动和 CUDA 版本兼容问题。如果本机 GPU 驱动过旧，镜像里的 CUDA 运行时可能会无法调用显卡。

在环境层面，还可以做一步：把关键依赖的pip freeze结果保存在environment/目录下。当项目运行完成一个实验时，执行：

pip freeze > environment/exp01-requirements-lock.txt

这种做法成本很低，但能让未来的自己知道“当时实际安装的完整包列表”。它比手动维护锁文件更准确，也更贴近真实运行状态。

6. 一个可参考的开放训练实践：从配置到训练再到评估

这一节用一个最小化图像分类为例，展示开放训练项目里，代码和配置是怎么组织的。这里的代码结构和 Marlin 的工程思想一致：参数进配置，实验进目录，结果可追溯。

6.1 配置文件 config/train.yaml

data: train_path: data/processed/train val_path: data/processed/val input_size: 224 batch_size: 32 num_workers: 4 model: name: resnet18 num_classes: 10 pretrained: true train: epochs: 20 lr: 0.001 weight_decay: 0.0001 seed: 42 save_dir: outputs/checkpoints eval: topk: 1

配置文件的优势是把超参数从代码中抽离。做对比实验时，只需要复制一份 YAML 文件并修改其中某个值，而不需要改动代码逻辑。

6.2 训练入口 src/train.py

import os import yaml import torch import torch.nn as nn from torch.utils.data import DataLoader from torchvision import datasets, transforms, models from src.utils import set_seed def load_config(config_path: str) -> dict: with open(config_path, "r", encoding="utf-8") as f: return yaml.safe_load(f) def build_model(cfg: dict): model = models.__dict__[cfg["model"]["name"]]( num_classes=cfg["model"]["num_classes"], pretrained=cfg["model"]["pretrained"], ) return model def build_dataloader(cfg: dict): transform = transforms.Compose([ transforms.Resize((cfg["data"]["input_size"], cfg["data"]["input_size"])), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), ]) train_dataset = datasets.ImageFolder(cfg["data"]["train_path"], transform=transform) val_dataset = datasets.ImageFolder(cfg["data"]["val_path"], transform=transform) train_loader = DataLoader( train_dataset, batch_size=cfg["data"]["batch_size"], shuffle=True, num_workers=cfg["data"]["num_workers"], ) val_loader = DataLoader( val_dataset, batch_size=cfg["data"]["batch_size"], shuffle=False, num_workers=cfg["data"]["num_workers"], ) return train_loader, val_loader def train_one_epoch(model, loader, criterion, optimizer, device): model.train() total_loss = 0 correct = 0 total = 0 for images, labels in loader: images, labels = images.to(device), labels.to(device) optimizer.zero_grad() outputs = model(images) loss = criterion(outputs, labels) loss.backward() optimizer.step() total_loss += loss.item() _, preds = torch.max(outputs, 1) correct += (preds == labels).sum().item() total += labels.size(0) return total_loss / len(loader), correct / total @torch.no_grad() def validate(model, loader, criterion, device): model.eval() total_loss = 0 correct = 0 total = 0 for images, labels in loader: images, labels = images.to(device), labels.to(device) outputs = model(images) loss = criterion(outputs, labels) total_loss += loss.item() _, preds = torch.max(outputs, 1) correct += (preds == labels).sum().item() total += labels.size(0) return total_loss / len(loader), correct / total def main(): config_path = "config/train.yaml" cfg = load_config(config_path) set_seed(cfg["train"]["seed"]) device = torch.device("cuda" if torch.cuda.is_available() else "cpu") print("Using device:", device) train_loader, val_loader = build_dataloader(cfg) model = build_model(cfg).to(device) criterion = nn.CrossEntropyLoss() optimizer = torch.optim.AdamW( model.parameters(), lr=cfg["train"]["lr"], weight_decay=cfg["train"]["weight_decay"], ) os.makedirs(cfg["train"]["save_dir"], exist_ok=True) for epoch in range(1, cfg["train"]["epochs"] + 1): train_loss, train_acc = train_one_epoch( model, train_loader, criterion, optimizer, device ) val_loss, val_acc = validate(model, val_loader, criterion, device) print( f"Epoch {epoch:02d} | " f"Train Loss: {train_loss:.4f} | Train Acc: {train_acc:.4f} | " f"Val Loss: {val_loss:.4f} | Val Acc: {val_acc:.4f}" ) ckpt_path = os.path.join( cfg["train"]["save_dir"], f"epoch_{epoch}_acc_{val_acc:.4f}.pt" ) torch.save(model.state_dict(), ckpt_path) if __name__ == "__main__": main()

6.3 评测脚本 src/evaluate.py

import torch from src.train import load_config, build_model, build_dataloader def main(): config_path = "config/train.yaml" cfg = load_config(config_path) device = torch.device("cuda" if torch.cuda.is_available() else "cpu") # 加载训练好的权重 model = build_model(cfg).to(device) checkpoint_path = "outputs/checkpoints/epoch_20_acc_0.9234.pt" model.load_state_dict(torch.load(checkpoint_path, map_location=device)) # 构建验证集 DataLoader _, val_loader = build_dataloader(cfg) model.eval() correct = 0 total = 0 with torch.no_grad(): for images, labels in val_loader: images, labels = images.to(device), labels.to(device) outputs = model(images) _, preds = torch.max(outputs, 1) correct += (preds == labels).sum().item() total += labels.size(0) print(f"Final Val Acc: {correct / total:.4f}") if __name__ == "__main__": main()

运行方式也比较直接：

# 安装依赖 pip install -r requirements-lock.txt # 执行训练 python src/train.py # 执行评估 python src/evaluate.py

这个最小示例没有包含复杂的数据增强和分布式训练，但它已经体现了“参数可配置”“结果有保存”“入口清晰”三个开放训练的基本要求。如果你想在自己项目里借鉴 Marin 的经验，可以先从整理配置和训练入口开始，不必一步到位。

7. 常见问题与排查思路

开放训练项目的复现，遇到问题时通常可以从下面这个表中找到方向：

这里最容易被忽视的是数据增强的随机性。比如随机裁剪、随机翻转操作，在 GPU 上运行时的随机数序列可能和 CPU 上不同，导致同一份代码在两种环境下训练结果有细微差异。要精确复现，比较可行的做法是固定整体 seed，并在评测阶段关闭随机增强。

8. 做开放训练项目的工程建议

8.1 从项目第一天就开始维护 README

很多开发者习惯写完代码之后才补 README，但那时很多细节已经记不清了。更好的做法是，项目进入开发阶段时就把 README 当作工程的组成部分，每完成一个模块，就补充一段说明。

8.2 把配置和代码分离

训练代码不应该出现lr = 0.001这样的硬编码。超参数应该放到 YAML、JSON 或命令行参数里。这样的好处不仅是灵活，更重要的是，你的实验记录可以明确写出“这个实验用的是哪个配置文件”。

8.3 所有数据都有明确版本

无论是公开数据集还是自采数据，都要有版本概念。可以是 Git 提交号、DVC 文件哈希，也可以是数据文件自身的命名。至少做到“如果数据变了，别人可以感知到这个变化”。

8.4 中间结果也值得保存

很多项目只保存最后模型权重，中间检查点、训练日志、指标曲线都不保存。但实验分析时，最常用的反而是这些中间状态。建议按实验名组织输出目录，让每个实验的产物放在同一个文件夹里。

8.5 别忽视代码审查和自动化检查

开放训练项目面对的是陌生人，质量把关很重要。可以在仓库里配置.pre-commit钩子，自动做代码格式检查、类型检查和基础单元测试。虽然这些不会直接提升模型效果，但能显著提高项目的可信度。

8.6 保持最小可复现粒度

如果你在做一个开源 AI 项目，至少提供一个小规模子集。这意味着数据集是 mini 版本、模型可以小尺寸运行、训练时间控制在分钟级别。这样别人能快速验证你的流程是否通畅，而不必一开始就投入大量算力。

9. 总结与后续方向

Marin 成为 AI 开放训练的典范，不是因为它开创了什么新的算法，而是它展示了一套更成熟的工程态度：训练项目不只是一堆脚本，而是代码、数据、环境、实验记录的组合体。它真正向开发者传递的判断是——在 AI 领域，可复现性是一笔需要主动投入的成本，而不是可有可无的附加项。

如果你想借鉴这套思路，可以先从三件事入手：把训练代码里的硬编码参数抽出来放进配置文件；为项目补一份明确的运行环境说明；建立一个实验记录模板，把每个实验对应的数据版本、配置、代码提交号和评测结果记录下来。这三件事不需要很高深的技术能力，却能立刻提升项目被别人理解和复现的概率。

下一步可以继续关注几个方向：基于容器和自动流水线的全链路复现、数据版本管理的进阶用法、以及面向大模型场景的评测与可复现实践。这些都是在“开放训练”这个大主题下值得深挖的技术点。

建议收藏备用。看完文章之后，对照自己的开源项目或课程作业，先动手补一份配置文件和运行说明。只有真正开始整理，才会理解为什么可复现性对 AI 项目如此重要。