1. 课程导入
在数据驱动的研究工作中，一个令人尴尬却极为常见的场景是：论文或报告已经发表，审稿人或合作者要求你重新生成一遍数据集，你却发现自己无法复现当初的结果。原始数据被覆盖、清洗脚本改过多次、依赖库版本升级、随机种子没有记录——任何一个环节的缺失，都可能让“可重复”变成一句空话。本课程要解决的，正是这个从“结果可信”到“过程可信”的关键跨越。
一、学习目标：从“能跑通”到“可复现、可锁定、可审计”
本课程不是泛泛而谈的科研规范，而是围绕工程化落地展开。完成学习后，你应当能够达成以下四个层次的目标：
- 认知层：准确区分“可重复（reproducible）”“可复现（replicable）”“可重现（repeatable）”三个常被混用的概念，理解版本锁定在其中的位置。
- 方法层：掌握以“数据快照 + 代码版本 + 环境锁定 + 随机性控制”为核心的可重复生成方法论。
- 工具层：能够使用 Git、DVC、Conda/Poetry、容器镜像、校验和（checksum）等工具组合，搭建一条可追溯的数据生成流水线。
- 实战层：独立完成一个研究数据集从原始输入到最终产物的全流程版本锁定，并输出可被第三方验证的复现报告。
学习本课程的最佳姿势是“边学边做”：每章都对应一个可操作的动作，建议你准备一个真实的小型研究数据集，跟随课程逐步改造它，而不是只看不练。
二、核心概念：四个必须厘清的术语
在进入实战之前，先建立一套精确的词汇体系。很多复现失败，根源在于团队对“版本”和“可重复”的理解根本不一致。
| 概念 | 含义 | 关键控制点 |
|---|---|---|
| 可重复生成 | 同一份代码、同一份输入、同一环境下，任何人任何时间都能得到相同输出 | 环境锁定、随机种子、确定性算法 |
| 版本锁定 | 将数据、代码、依赖、配置固定到不可变的标识上 | 提交哈希、数据校验和、依赖锁文件 |
| 数据快照 | 对某一时刻的数据状态做不可变留存 | 内容寻址存储、只读副本 |
| 血缘追踪 | 记录每个产物由哪些输入和步骤产生 | DAG 记录、元数据日志 |
其中，版本锁定是可重复生成的前提。没有锁定，所谓“可重复”只是碰运气。而版本锁定又分为三个层面：代码版本（Git commit）、数据版本（DVC 或校验和）、环境版本（依赖锁文件与容器镜像）。三者缺一不可。
三、整体框架：一条可追溯的数据生成流水线
本课程的整体框架可以用一条“输入—处理—产物—验证”的链路来概括。它的核心思想是：任何产物都必须能反向追溯到确定的输入和确定的执行环境。下图展示了这条流水线的结构与各环节的锁定对象。
这条流水线有三个关键特征：其一，每一步都有明确的输入和输出，便于定位问题；其二，三层锁定相互独立又彼此关联，任何一层缺失都会导致复现失败；其三，产物带校验和，使得“是否一致”可以被机器自动判定，而不是靠人眼比对。
四、实战路线图：从零到可验证复现
本课程后续章节将沿着以下路线逐步展开，每一站都对应一个可交付的工程动作：
- 环境准备：建立项目目录规范，初始化 Git 仓库，配置 .gitignore 与 .dvcignore，明确“什么进版本控制、什么进数据存储”。
- 数据快照：用 DVC 或校验和清单对原始数据做不可变留存，生成 data.dvc 或 checksums.sha256。
- 代码版本化：将清洗、转换、特征工程脚本纳入 Git，每个可复现节点打 tag，禁止在已发布提交上直接修改。
- 环境锁定：用 conda env export --no-builds 或 poetry lock 生成锁文件，进一步用 Dockerfile 固化系统级依赖。
- 随机性控制：统一设置随机种子，记录 numpy、random、框架级种子，并在日志中输出。
- 流水线编排：用 DVC stage 或 Makefile 定义 DAG，实现“一条命令重跑全流程”。
- 验证与报告：生成复现报告，包含提交哈希、数据哈希、环境哈希、产物校验和，供第三方独立验证。
实战路线图的核心口诀：数据进 DVC，代码进 Git，环境进锁文件，随机进日志，产物进校验和。记住这五句话，你就抓住了本课程的骨架。
五、常见误区与复盘提醒
在正式动手前，先看看初学者最容易踩的坑，可以帮你少走弯路：
- 误区一：只锁代码不锁数据。代码没变，但原始数据被悄悄更新，结果自然对不上。数据必须与代码同等对待。
- 误区二：依赖“最新版”库。不写版本号，今天能跑明天就报错。锁文件不是可选项，是必需品。
- 误区三：忽略随机种子。机器学习与抽样过程默认随机，不固定种子，每次结果都不同。
- 误区四：用文件名当版本。“data_final_v2_真的最终版.csv”是版本管理的反面教材，应使用哈希或提交标识。
- 误区五：复现靠记忆。没有自动化脚本，复现步骤只存在于某个人脑子里，人一走就断档。
复盘时请自问三个问题：如果明天换一台机器，我能否在半小时内重建这份数据集？如果合作者只拿到我的仓库，他能否独立验证结果？如果半年后审稿人要求补充实验，我能否精确回到当时的版本？任何一个答“不能”，都说明版本锁定还有缺口。
带着这些目标和框架，你已经具备了进入后续实操章节的基础。接下来，我们将从项目目录规范与 Git 初始化开始，一步步把这条流水线真正搭建起来。