DVC Pipelines：构建可复现机器学习项目的工业级实践

1. 项目概述：为什么“可复现的ML项目”不是口号，而是生存刚需

我带过十几支从零起步的机器学习团队，也帮二十多家公司做过模型落地咨询。最常听到的一句话是：“这个模型在我们本地跑得好好的，一上生产环境就崩。”接着就是连续三天通宵排查——数据路径错了一级、特征工程版本对不上、训练时用的超参配置文件被覆盖了……最后发现，问题根源不在代码，而在整个项目的组织方式。 DVC Pipelines 不是给“高级玩家”锦上添花的工具，而是把 ML 项目从“能跑通”拉到“敢上线”的基础设施层重构。 它解决的从来不是“怎么写模型”，而是“怎么让三个人、五个环境、八个月时间里的每一次改动都可追溯、可验证、可回滚”。标题里那个“Highly-Organized”（高度结构化），说白了就是：当你把数据、代码、模型、指标全扔进一个目录，别人打开第一眼就能看懂数据从哪来、中间怎么加工、最终怎么评估、哪个环节出了问题——不需要你坐在旁边解释十分钟。而“Anyone Can Reproduce”（任何人可复现）更狠：它不依赖你的开发机环境、不依赖你本地的 conda 虚拟环境名、不依赖你硬盘里某个隐藏文件夹里的缓存，只依赖一份清晰的 dvc.yaml 和几行 dvc repro 命令。这不是理想主义，是我在金融风控模型交付中被客户审计团队连续追问三个月后，亲手踩坑、反复推倒重来、最终沉淀下来的最小可行结构。它适用于所有需要交付、协作、迭代的 ML 场景——无论是 Kaggle 竞赛选手想把 notebook 拆成可维护 pipeline，还是 AI 初创公司要让算法工程师和 MLOps 工程师在同一个 repo 里高效协同，甚至是你自己半年后想重新跑通当年的实验，这套结构都能让你少掉一半头发。

2. 整体设计思路：为什么不用纯 Makefile 或纯 GitHub Actions？DVC Pipelines 的不可替代性

2.1 核心矛盾：ML 项目天然具备“大体积、高依赖、弱线性”的三重反模式

传统软件工程习惯用 Makefile 或 CI/CD 流水线管理构建流程，但直接套用到 ML 项目上会立刻卡死。原因有三：

第一，“大体积”——原始数据动辄几十GB，预处理后的特征矩阵可能上百GB，模型权重文件也常达数GB。Git 无法有效版本化这些二进制大文件，而普通 CI 工具每次触发都要完整拉取全部数据，光下载就耗掉半小时，根本没法做快速迭代。

第二，“高依赖”——ML 流程不是简单的“源码 → 编译 → 可执行文件”，而是“原始数据 → 清洗脚本 → 清洗后数据 → 特征工程脚本 → 特征矩阵 → 训练脚本 → 模型文件 → 评估脚本 → 指标报告”。其中任意一个上游节点（比如清洗脚本）变了，下游所有节点理论上都应该重新运行。但手动判断哪些该重跑、哪些可跳过，靠人脑根本不可靠；而纯脚本化方案又缺乏自动化的依赖图谱和缓存机制。

第三，“弱线性”——真实场景中，流程常分叉：同一份清洗后数据，要同时喂给 XGBoost 和 PyTorch 模型；同一组超参搜索结果，要并行生成多个评估报告。Makefile 的单线性依赖树和 GitHub Actions 的串行 job 模型，很难优雅表达这种 DAG（有向无环图）结构。

提示：我试过用纯 GitHub Actions + S3 存储中间产物，结果是每次调试一个参数，都要等 12 分钟上传下载，团队成员干脆退回本地跑，整个 CI 形同虚设。

2.2 DVC Pipelines 的破局点：将“数据版本控制”与“流水线编排”原生融合

DVC（Data Version Control）不是 Git 插件，也不是独立的存储服务，而是一个 以数据为中心的构建系统 。它的核心设计哲学是： 把数据当作一等公民，让代码围绕数据流动。 具体体现在三个层面：

• 数据即输入/输出（Data as I/O） ：DVC 不要求你把数据塞进 Git，而是用 .dvc 元数据文件记录数据文件的哈希值、远程存储位置（S3/GCS/Azure Blob）、以及它被哪个 stage 消费或生成。 dvc add data/raw.csv 这条命令，本质是创建一个指向真实数据的“符号链接+校验指纹”。

• Stage 即原子单元（Stage as Atomic Unit） ：每个 pipeline stage（如 prepare_data 、 train_model ）必须明确定义 cmd （执行命令）、 deps （依赖项，可以是代码文件、数据文件、配置文件）、 outs （产出项，模型、指标、可视化图）。DVC 会自动计算 deps 的哈希值，只有当任一 dep 内容变更时，才触发该 stage 重跑——这是比 Makefile 更细粒度的增量构建。

• Pipeline 即 DAG 图（Pipeline as DAG） ： dvc.yaml 文件用 YAML 描述整个流程拓扑。DVC 内置 DAG 解析器，能自动识别 train_model 依赖 prepare_data 的产出，也能识别 evaluate_xgb 和 evaluate_pytorch 并行依赖 train_model 的产出。 dvc repro 命令不是顺序执行，而是按拓扑序智能调度，自动跳过未变更的节点。

注意：DVC Pipeline 不是取代 Git，而是补足 Git 的短板。Git 管理代码逻辑（ .py 、 .yaml ），DVC 管理数据状态（ .dvc 文件 + 远程存储），二者分工明确，协同工作。

2.3 与竞品方案的关键对比：为什么选 DVC 而非 Kubeflow 或 Airflow？

实测下来，一个刚学 Python 三个月的实习生，用 DVC 搭建完“数据加载→缺失值填充→XGBoost 训练→AUC 评估”四阶段 pipeline，只花了不到两小时——因为他不需要理解容器、调度器、消息队列，只需要写清楚“这个脚本读什么、写什么、依赖什么”。

3. 核心细节解析：从零搭建一个工业级可复现 ML 项目结构

3.1 项目根目录骨架：为什么这 7 个文件夹是黄金比例？

一个经受过生产检验的 DVC 项目，目录结构绝不是随意堆砌。我推荐以下最小可行骨架（已在 8 个项目中验证）：

my_ml_project/
├── .dvc/                  # DVC 自动创建，存放全局配置、缓存索引
├── .git/                  # Git 仓库元数据
├── data/                  # 所有数据相关（原始、中间、最终）
│   ├── raw/               # 原始数据（.csv, .parquet），由 dvc add 管理
│   ├── interim/           # 清洗/转换中的中间数据（DVC 自动缓存）
│   └── processed/         # 特征工程完成的数据（模型直接读取）
├── models/                # 模型文件（.pkl, .pt），由 dvc add 管理
├── notebooks/             # 探索性分析（EDA）、原型验证（.ipynb），**不参与 pipeline**
├── src/                   # 核心代码（Python 模块）
│   ├── __init__.py
│   ├── data/              # 数据加载、清洗、特征工程函数
│   ├── features/          # 特征构造、缩放、编码类
│   ├── models/            # 模型定义、训练、预测函数
│   └── evaluation/        # 指标计算、可视化函数
├── tests/                 # 单元测试（测试函数逻辑，不测试 pipeline）
├── dvc.yaml               # 主 pipeline 定义（核心！）
├── params.yaml            # 全局可调参数（学习率、batch_size、random_state）
├── metrics.json           # pipeline 运行后自动生成的评估指标（供 CI 读取）
└── requirements.txt     # Python 依赖（精简版，只含 runtime 依赖）

关键设计理由：

• notebooks/ 与 src/ 严格分离：Notebook 用于快速试错、可视化，但 绝不允许在 pipeline 中直接调用 .ipynb 。所有稳定逻辑必须提炼为 src/ 下的 .py 模块。这是避免“Notebook 诅咒”（逻辑散落、难以测试、版本混乱）的第一道防火墙。

• data/ 下三级划分： raw 是只读源头（如客户提供的 zip 包）， interim 是临时中间态（DVC 自动管理生命周期）， processed 是 pipeline 的稳定输入。这样设计，既满足审计要求（原始数据不可篡改），又保证 pipeline 可重复（ processed 由 interim 确定性生成）。

• params.yaml 是 pipeline 的“控制面板”：它不是硬编码在脚本里，而是被 dvc.yaml 显式声明为依赖。修改 params.yaml 中的 model.learning_rate: 0.01 ，再运行 dvc repro ，DVC 会自动检测到参数变更，只重跑 train_model 及其下游 stage——无需改任何 Python 代码。

实操心得：我曾在一个医疗影像项目中，把 params.yaml 里 augmentation.rotation_range 从 10 改成 30 ， dvc repro train_model 后，DVC 自动跳过了 prepare_data （因为原始数据和清洗脚本没变），只重跑了模型训练和评估，全程 4 分钟。如果手动管理，得先确认哪些文件受影响，再挨个删缓存、重跑，至少 15 分钟。

3.2 dvc.yaml 深度解析：如何写出健壮、可读、易维护的 pipeline？

dvc.yaml 是整个项目的“心脏”。一个写得好的 dvc.yaml ，应该让新成员打开后，5 分钟内就能画出完整的 DAG 图。以下是工业级写法的核心原则：

原则一：Stage 命名语义化，拒绝 stage1 , stage2

错误示范：

stages:
  stage1:
    cmd: python src/data/clean.py
    deps: [data/raw/dataset.csv]
    outs: [data/interim/cleaned.csv]

正确示范（体现意图+技术栈）：

stages:
  prepare_data:
    cmd: python src/data/clean.py --input data/raw/dataset.csv --output data/interim/cleaned.csv
    deps:
      - data/raw/dataset.csv
      - src/data/clean.py
      - src/data/__init__.py  # 确保模块导入正常
    outs:
      - data/interim/cleaned.csv
    always_changed: false  # 默认 false，显式声明更清晰

为什么重要？
prepare_data 直接告诉读者这个 stage 的业务目的； --input 和 --output 参数让命令意图一目了然；显式列出 __init__.py 是防止因 Python 包结构变更导致 stage 失败（DVC 会监控该文件哈希）。

原则二：强制使用 params 和 vars 解耦配置与逻辑

params.yaml 示例：

# params.yaml
data:
  input_path: "data/raw/dataset.csv"
  output_path: "data/interim/cleaned.csv"
  missing_threshold: 0.95

features:
  scaler: "standard"
  max_categories: 10

model:
  name: "xgboost"
  n_estimators: 100
  learning_rate: 0.05
  random_state: 42

evaluate:
  metrics: ["accuracy", "f1_weighted"]

dvc.yaml 中引用：

stages:
  prepare_data:
    cmd: python src/data/clean.py --input ${data.input_path} --output ${data.output_path} --threshold ${data.missing_threshold}
    deps:
      - ${data.input_path}
      - src/data/clean.py
    params:
      - data.input_path
      - data.output_path
      - data.missing_threshold
    outs:
      - ${data.output_path}

  train_model:
    cmd: python src/models/train.py --data ${data.output_path} --model_path models/xgb_model.pkl --params params.yaml
    deps:
      - ${data.output_path}
      - src/models/train.py
      - params.yaml
    params:
      - model.name
      - model.n_estimators
      - model.learning_rate
      - model.random_state
    outs:
      - models/xgb_model.pkl

关键优势：

• 修改参数只需改 params.yaml ，无需碰 dvc.yaml 或 Python 脚本；
• params 字段显式声明了哪些参数会影响 stage 执行，DVC 会自动将其加入依赖哈希计算；
• ${} 语法让配置复用成为可能（如多个 stage 共享 data.output_path ）。

原则三：善用 foreach 和 do 实现参数化并行

当需要对比多个模型时，不必写 train_xgb , train_lgbm , train_rf 三个 stage。用 foreach 一行搞定：

stages:
  train_models:
    foreach:
      model_name: ["xgboost", "lightgbm", "random_forest"]
      n_estimators: [100, 200]
    do:
      cmd: python src/models/train.py --model ${item.model_name} --n_estimators ${item.n_estimators} --data data/processed/features.csv --output models/${item.model_name}_${item.n_estimators}.pkl
      deps:
        - data/processed/features.csv
        - src/models/train.py
      params:
        - model_name
        - n_estimators
      outs:
        - models/${item.model_name}_${item.n_estimators}.pkl

DVC 会自动展开为 6 个独立 stage（3 模型 × 2 n_estimators），并行执行。 dvc repro train_models 就能一键训练全部组合。

注意： foreach 的 item 是 DVC 内置变量， ${item.xxx} 会自动替换。不要试图用 shell 变量（如 $MODEL_NAME ），DVC 不解析 shell 环境。

3.3 params.yaml 的进阶技巧：如何管理多环境、多实验配置？

params.yaml 不只是“一堆键值对”，它是 pipeline 的配置中枢。实际项目中，我用三层嵌套实现灵活管理：

# params.yaml
# === 全局基础配置 ===
global:
  random_state: 42
  debug: false

# === 数据层配置 ===
data:
  version: "v2.1"  # 数据版本号，便于回溯
  input_path: "data/raw/dataset_v2.1.csv"
  cleaning:
    drop_columns: ["id", "timestamp"]
    fill_strategy: "median"
  feature_engineering:
    use_pca: true
    pca_components: 20

# === 模型层配置 ===
models:
  xgboost:
    n_estimators: 100
    learning_rate: 0.05
    max_depth: 6
  lightgbm:
    num_leaves: 31
    learning_rate: 0.1

# === 评估层配置 ===
evaluate:
  cv_folds: 5
  scoring: ["roc_auc", "f1_macro"]
  threshold_tuning: true

# === 环境适配（通过 dvc exp run 切换）===
experiments:
  baseline:
    data.version: "v2.0"
    models.xgboost.n_estimators: 50
  ablation_pca:
    data.feature_engineering.use_pca: false
  production:
    global.debug: false
    evaluate.cv_folds: 3

如何切换实验？
用 dvc exp run -S experiments.baseline ，DVC 会自动将 experiments.baseline 下的所有子键（如 data.version , models.xgboost.n_estimators ）覆盖到对应路径。 -S 参数表示 “Set parameters”，它会临时修改 params.yaml ，运行完自动恢复，不污染主分支。

实操心得：在电商推荐项目中，我们用 dvc exp run -S experiments.production 一键切换到线上配置（关闭 debug、减少 CV 折数、启用缓存），比手动改 5 个地方快 10 倍，且零出错。

4. 实操过程详解：从初始化到首次 dvc repro 的完整 walkthrough

4.1 环境准备与初始化：3 条命令建立信任基线

第一步：初始化 Git 和 DVC（必须按顺序）

# 1. 初始化 Git 仓库（确保 .gitignore 已配置好，排除 __pycache__, *.log 等）
git init
echo "__pycache__/" >> .gitignore
echo "*.log" >> .gitignore

# 2. 初始化 DVC（指定远程存储，这里以 AWS S3 为例）
dvc init
dvc remote add -d myremote s3://my-bucket-name/my-project
dvc remote modify myremote region us-east-1

# 3. 提交初始配置（.dvc/config, .dvc/.gitignore）
git add .dvc/config .dvc/.gitignore
git commit -m "chore: init dvc with s3 remote"

为什么必须先 Git 再 DVC？
DVC 依赖 Git 的 hooks（如 pre-commit）来拦截未跟踪的大文件提交。如果先 dvc init 再 git init ，DVC 的 hook 无法注册，后续 dvc add 可能失败。

第二步：添加原始数据（ data/raw/ ）

# 假设你已下载好原始数据
mkdir -p data/raw
cp /path/to/downloaded/data.csv data/raw/

# 用 DVC 管理它（生成 .dvc 文件，上传到 S3）
dvc add data/raw/data.csv
# 输出：100%|██████████| data/raw/data.csv -> .dvc/cache/ab/cd... (上传中)

# 此时会生成 data/raw/data.csv.dvc 文件，把它加入 Git
git add data/raw/data.csv.dvc
git commit -m "feat: add raw dataset v1.0"

dvc add 的本质是：

1. 计算 data.csv 的 SHA256 哈希；
2. 将文件内容上传到 myremote （S3）的 ab/cd... 路径；
3. 在本地生成 data.csv.dvc ，内容是哈希值和远程路径的映射；
4. Git 只跟踪 .dvc 文件（几 KB），不跟踪原始 CSV（几 GB）。

提示： dvc add 后，本地 data/raw/data.csv 会被替换成一个指向缓存的硬链接（Linux/macOS）或复制（Windows）。别手动删它，否则 DVC 会报错“missing dependency”。

4.2 编写第一个 Stage： prepare_data （数据清洗）

Step 1：创建 Python 脚本（ src/data/clean.py ）

#!/usr/bin/env python3
"""
数据清洗脚本：删除缺失率 > threshold 的列，填充数值型缺失值为中位数
"""
import pandas as pd
import argparse
import sys

def clean_data(input_path: str, output_path: str, threshold: float = 0.95):
    df = pd.read_csv(input_path)
    print(f"原始形状: {df.shape}")
    
    # 删除高缺失率列
    missing_ratio = df.isnull().mean()
    cols_to_drop = missing_ratio[missing_ratio > threshold].index.tolist()
    df = df.drop(columns=cols_to_drop)
    print(f"删除 {len(cols_to_drop)} 列，剩余形状: {df.shape}")
    
    # 数值列用中位数填充
    numeric_cols = df.select_dtypes(include=['number']).columns
    for col in numeric_cols:
        if df[col].isnull().sum() > 0:
            median_val = df[col].median()
            df[col].fillna(median_val, inplace=True)
            print(f"列 '{col}' 填充中位数 {median_val:.2f}")
    
    df.to_csv(output_path, index=False)
    print(f"清洗后数据已保存至 {output_path}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", required=True, help="输入 CSV 路径")
    parser.add_argument("--output", required=True, help="输出 CSV 路径")
    parser.add_argument("--threshold", type=float, default=0.95, help="缺失率阈值")
    args = parser.parse_args()
    
    try:
        clean_data(args.input, args.output, args.threshold)
    except Exception as e:
        print(f"清洗失败: {e}")
        sys.exit(1)

Step 2：在 dvc.yaml 中定义 prepare_data stage

# dvc.yaml
stages:
  prepare_data:
    cmd: python src/data/clean.py --input data/raw/data.csv --output data/interim/cleaned.csv --threshold 0.95
    deps:
      - data/raw/data.csv
      - src/data/clean.py
      - src/data/__init__.py
    outs:
      - data/interim/cleaned.csv

Step 3：首次运行 dvc repro

# 运行 pipeline（会自动创建 data/interim/ 目录）
dvc repro prepare_data

# 查看执行日志
# INFO: Stage 'prepare_data' is up to date. (如果之前跑过且没变)
# INFO: Running command: python src/data/clean.py ...
# INFO: Output 'data/interim/cleaned.csv' didn't change. Skipping upload.

# 检查产出
ls -lh data/interim/
# cleaned.csv  (约 120MB)

# 查看 DVC 缓存（.dvc/cache/...）
dvc cache dir  # 输出: /path/to/.dvc/cache

关键观察点：

• DVC 自动创建 data/interim/ 目录（如果不存在）；
• cleaned.csv 被写入本地，同时其哈希值被计算，内容被上传到 S3 缓存；
• dvc repro 成功后， data/interim/cleaned.csv 会变成一个指向缓存的硬链接（节省磁盘）；
• 如果再次运行 dvc repro prepare_data ，DVC 发现 deps 哈希未变，会直接跳过（ up to date ）。

4.3 构建完整 pipeline：串联 feature_engineering → train_model → evaluate

Step 1：定义 feature_engineering stage

# dvc.yaml
stages:
  prepare_data:
    # ... 同上

  feature_engineering:
    cmd: python src/features/construct.py --input data/interim/cleaned.csv --output data/processed/features.csv
    deps:
      - data/interim/cleaned.csv
      - src/features/construct.py
      - src/features/__init__.py
    params:
      - features.scaler
      - features.max_categories
    outs:
      - data/processed/features.csv

src/features/construct.py 示例（简化版）：

import pandas as pd
from sklearn.preprocessing import StandardScaler, OneHotEncoder
from sklearn.compose import ColumnTransformer
import argparse

def construct_features(input_path, output_path, scaler_type="standard", max_categories=10):
    df = pd.read_csv(input_path)
    # ... 特征工程逻辑（标准化、独热编码等）
    df_processed.to_csv(output_path, index=False)

Step 2：定义 train_model stage（支持参数化）

  train_model:
    cmd: python src/models/train.py --data data/processed/features.csv --model_path models/model.pkl --params params.yaml
    deps:
      - data/processed/features.csv
      - src/models/train.py
      - params.yaml
    params:
      - model.name
      - model.n_estimators
      - model.learning_rate
      - model.random_state
    outs:
      - models/model.pkl

Step 3：定义 evaluate stage（生成 metrics.json ）

  evaluate:
    cmd: python src/evaluation/assess.py --model models/model.pkl --data data/processed/features.csv --output metrics.json
    deps:
      - models/model.pkl
      - data/processed/features.csv
      - src/evaluation/assess.py
    params:
      - evaluate.scoring
      - evaluate.cv_folds
    outs:
      - metrics.json

src/evaluation/assess.py 关键逻辑：

import json
from sklearn.metrics import accuracy_score, f1_score
import joblib

def assess_model(model_path, data_path, output_path, scoring=["accuracy"]):
    model = joblib.load(model_path)
    X, y = load_data(data_path)  # 加载特征和标签
    
    y_pred = model.predict(X)
    metrics = {}
    for metric in scoring:
        if metric == "accuracy":
            metrics["accuracy"] = accuracy_score(y, y_pred)
        elif metric == "f1_weighted":
            metrics["f1_weighted"] = f1_score(y, y_pred, average="weighted")
    
    with open(output_path, "w") as f:
        json.dump(metrics, f, indent=2)
    print(f"指标已写入 {output_path}")

if __name__ == "__main__":
    # ... argparse 解析
    assess_model(...)

Step 4：一键运行全链路

# 运行整个 pipeline（从头开始）
dvc repro

# 或只运行从某个 stage 开始（及其下游）
dvc repro train_model

# 查看 pipeline 状态图（ASCII）
dvc dag

# 输出：
#                    +----------------+
#                    |  prepare_data  |
#                    +----------------+
#                             |
#                    +----------------+
#                    | feature_engineering |
#                    +----------------+
#                             |
#                    +----------------+
#                    |   train_model  |
#                    +----------------+
#                             |
#                    +----------------+
#                    |   evaluate     |
#                    +----------------+

此时 metrics.json 已生成：

{
  "accuracy": 0.872,
  "f1_weighted": 0.865
}

CI/CD 系统可直接读取此文件做质量门禁（如 accuracy < 0.85 则失败）。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “Stage failed with code 1” —— 如何快速定位脚本错误？

这是新手最常遇到的报错。DVC 只显示 Stage 'xxx' failed with code 1 ，但不打印具体异常。 正确排查流程：

1. 先看 DVC 日志（最直接）

   dvc repro --verbose train_model
   # 会显示完整命令和 stderr 输出
   

2. 手动复现命令（最可靠）

   # 进入项目根目录，复制 dvc.yaml 中的 cmd
   cd /path/to/my_ml_project
   python src/models/train.py --data data/processed/features.csv --model_path models/model.pkl --params params.yaml
   

   这样能获得完整的 traceback，看到是 ImportError 、 FileNotFoundError 还是 ValueError 。

3. 检查依赖路径是否正确（90% 的问题根源）

   • deps 列表中的路径必须是相对于 dvc.yaml 所在目录（通常是项目根目录）；
   • cmd 中的路径也必须是相对路径，不能用绝对路径（ /home/user/... ）；
   • 如果脚本里用 os.path.join("data", "raw") ，确保当前工作目录是项目根目录（DVC 默认保证这点）。

实操心得：我在一个 NLP 项目中， train.py 里写了 open("config.yaml") ，但忘了把 config.yaml 加入 deps 。DVC 运行时找不到该文件，报 FileNotFoundError 。解决方案：在 dvc.yaml 的 train_model stage 下添加 deps: ["config.yaml"] ，并 git add config.yaml 。

5.2 “Output 'xxx' is missing” —— 缓存丢失怎么办？

当 dvc repro 报这个错，说明 DVC 找不到某个 outs 文件的缓存副本。常见原因和解法：

关键命令：

• dvc status ：显示所有 stage 的状态（ ok , changed deps , missing ）；
• dvc pull -r myremote ：从指定远程拉取所有缺失的 outs ；
• dvc push -r myremote ：推送所有本地 outs 到远程。

注意： dvc pull 不会覆盖本地已存在的 outs 文件，只会下载缓存并建立链接。如果本地文件被意外修改，DVC 会检测到哈希不一致，报错提示。

5.3 “Pipeline is not up to date” —— 为什么明明没改代码，DVC 还要重跑？

DVC 判断是否重跑的依据是 所有 deps 的哈希值 。即使你没改代码，以下情况也会触发重跑：

• deps 中的文件被 touch（时间戳更新） ： touch src/data/clean.py 会让 DVC 认为文件变了；
• params.yaml 中的注释行被修改 ：YAML 注释不算内容，但 DVC 会计算整个文件哈希；
• cmd 字符串本身被修改 （如加了个空格）：DVC 把 cmd 也纳入依赖哈希；
• deps 列表中包含了不该包含的文件 （如日志文件、临时文件）。

诊断命令：

# 查看某个 stage 的依赖哈希详情
dvc dag --dot | dot -Tpng -o dag.png  # 生成 DAG 图（需安装 graphviz）
dvc repro --dry-run train_model  # 预览哪些 stage 会被执行（不真正运行）

终极解决方案：
在 dvc.yaml 中为 stage 添加 always_changed: false （默认值），并确保 deps 列表只包含真正影响逻辑的文件。例如，不要把 requirements.txt 加入 train_model 的 deps ，除非你真的用它来安装包（通常用 Conda/Pipenv 管理更合适）。

5.4 多人协作时的 Git 冲突：如何安全合并 dvc.yaml 和 .dvc 文件？

.dvc 文件是 YAML 格式，但内容是机器生成的哈希和路径， 切勿手动编辑 。Git 冲突时，正确做法是：

1. 先解决 dvc.yaml 冲突 （人工）：

   • dvc.yaml 是人写的，冲突时需人工合并 stage 定义、参数引用；
   • 使用 VS Code 的 Merge Editor 可视化对比，保留双方新增的 stage，协调参数名。

2. 再解决 .dvc 文件冲突（自动化） ：

   # 1. 放弃本地 .dvc 文件，用远程版本（因为哈希由内容决定，内容一致则哈希一致）
   git checkout --theirs data/raw/data.csv.dvc
   
   # 2. 或者，用 DVC 命令重新生成（推荐）
   dvc add data/raw/data.csv  # 会重新计算哈希，生成新 .dvc
   git add data/raw/data.csv.dvc
   

3. 最后，同步缓存 ：

   # 确保所有协作者都有最新缓存
   dvc pull
   

提示：在团队规范中，应约定 .dvc 文件只由 dvc add 或 dvc repro 自动生成，禁止手动修改。