6.流水线核心原理
在机器学习项目中，我们经常会遇到一系列重复性的数据处理步骤：下载原始数据、清洗数据、提取特征、训练模型、评估结果。每次手动执行这些步骤不仅繁琐，还容易出错。更麻烦的是，当数据或代码发生变化时，很难判断哪些步骤需要重新运行。DVC 的流水线功能就是为了解决这些问题而设计的。
简单来说，DVC 流水线就像一份自动化的任务清单，它知道各个步骤之间的依赖关系，能够智能地决定哪些步骤需要执行，哪些可以跳过。这背后依赖的核心概念就是 DAG。
Pipeline DAG 概念
DAG 是 Directed Acyclic Graph 的缩写，中文叫"有向无环图"。这个听起来有点学术的名词其实很好理解：它描述了一组任务之间的先后顺序关系，并且这些关系不会形成循环。
在 DVC 中，流水线的每个阶段（Stage）是图中的一个节点，阶段之间的依赖关系构成了有向边。所谓"有向"，就是说依赖关系有明确的方向：A 依赖 B，意味着 B 必须在 A 之前执行。所谓"无环"，就是不能出现 A 依赖 B，B 依赖 C，C 又依赖 A 这样的情况，否则执行顺序会陷入死循环。
DVC 内部用 DAG 来表示整个流水线结构。当我们运行 dvc repro 时，DVC 会分析这个图，找出需要执行的阶段，并按照正确的顺序运行它们。如果某个阶段的输入没有变化，DVC 会直接跳过这个阶段，使用之前缓存的结果。
让我们看一个典型的例子：
flowchart LR
A[prepare] --> B[featurize]
B --> C[train]
C --> D[evaluate]
这个图表示了一个简单的机器学习流水线：数据准备阶段生成特征，特征提取阶段训练模型，训练阶段评估结果。每个箭头代表一个依赖关系，DVC 会按照这个顺序执行。
DAG 的优势在于它的自动化能力。假设我们修改了训练脚本，DVC 会自动识别出只有 train 和 evaluate 阶段需要重新运行，而 prepare 和 featurize 可以直接跳过。如果修改的是原始数据，那么所有下游阶段都会重新执行。
Stage 阶段定义
Stage 是流水线的基本构建块。每个 stage 封装了一个具体的命令、它的依赖项和输出项。在 DVC 中，我们可以通过 dvc stage add 命令或手动编辑 dvc.yaml 文件来定义 stage。
使用 dvc stage add 创建阶段
dvc stage add 是一个辅助命令，帮助我们在 dvc.yaml 文件中创建或更新阶段定义。它的基本语法很直观：
dvc stage add -n <name> -d <dependency> -o <output> <command>
让我们创建一个简单的阶段来统计文本文件的行数：
$ dvc stage add -n count \
-d test.txt \
-o lines \
"cat test.txt | wc -l > lines"
Creating 'dvc.yaml'
Adding stage 'count' in 'dvc.yaml'
这个命令做了几件事：指定阶段名称为 count，声明依赖文件 test.txt，声明输出文件 lines，并定义要执行的命令。执行后，DVC 会在当前目录生成一个 dvc.yaml 文件：
stages:
count:
cmd: 'cat test.txt | wc -l > lines'
deps:
- test.txt
outs:
- lines
生成的 dvc.yaml 文件结构清晰，包含了阶段的完整信息。注意，此时 lines 文件还没有生成，只有当我们运行 dvc repro 时，DVC 才会执行命令并创建输出文件。
Stage 的核心组成部分
每个 stage 必须包含一个 cmd 字段，这是阶段要执行的实际命令。命令可以是任何能在终端运行的内容：shell 内置命令、脚本文件、Python 程序等。如果命令包含特殊字符（如 | 或 >），需要用引号括起来。
依赖项通过 deps 字段定义。这些可以是数据文件、代码文件或配置目录。DVC 会监控这些文件的变化，一旦内容发生改变，就会认为该阶段需要重新执行。特别重要的是，我们应该将执行的脚本本身也列为依赖项，这样代码修改时 DVC 能够正确识别。
输出项通过 outs 字段定义。这些是阶段执行后生成的文件或目录。DVC 会自动追踪这些输出，并将它们缓存起来。当阶段需要重新运行时，DVC 会先删除旧的输出，然后执行命令重新生成。
更新已存在的 Stage
如果需要修改已存在的阶段，必须使用 -f 或 --force 选项来覆盖原有定义。例如，修改训练阶段的随机种子：
$ dvc stage add -n train --force \
-d train_model.py -d matrix-train.p -o model.p \
python train_model.py 18494003 model.p
这个操作会更新 dvc.yaml 中名为 train 的阶段定义，改变其命令参数。强制覆盖是为了防止意外修改，确保我们明确知道自己在更新现有阶段。
在子目录中创建 Stage
DVC 支持在项目任意位置创建阶段。如果我们在子目录中运行 dvc stage add，DVC 会在该目录下创建独立的 dvc.yaml 文件。这种方式适合管理大型项目，将不同模块的流水线定义分开存放。
$ cd more_stages/
$ dvc stage add -n process_data \
-d data.in \
-o result.out \
./my_script.sh data.in result.out
项目结构会变成：
.
├── dvc.yaml
├── dvc.lock
└── more_stages/
├── data.in
└── dvc.yaml
每个 dvc.yaml 文件定义了该目录下的阶段，DVC 会自动合并所有文件构建完整的流水线图。
依赖关系管理
依赖关系是 DVC 流水线最核心的概念之一。正确管理依赖关系让 DVC 能够智能地判断哪些阶段需要重新执行，从而实现高效的增量构建。
文件依赖
最简单的依赖类型是文件或目录依赖。当依赖文件的内容发生变化时，DVC 会认为依赖该文件的阶段已经过时，需要重新运行。DVC 通过计算文件的哈希值（默认是 MD5）来检测变化，而不是依赖文件的时间戳。这种方式比传统的构建工具（如 Make）更可靠，特别是在处理大文件时。
定义文件依赖很简单，在 dvc stage add 中使用 -d 选项：
$ dvc stage add -n extract \
-d Posts.xml.zip \
-o data/Posts.xml \
unzip Posts.xml.zip -d data/
这里 Posts.xml.zip 是依赖项，当它发生变化时，extract 阶段会重新执行。注意 DVC 不会自动将依赖文件传递给命令，命令需要自己读取这些文件。
输出作为下游依赖
流水线的强大之处在于阶段的串联。一个阶段的输出可以成为另一个阶段的输入，形成依赖链。DVC 自动识别这种关系，构建完整的 DAG。
# 第一阶段：解压数据
$ dvc stage add -n extract \
-d Posts.xml.zip \
-o data/Posts.xml \
unzip Posts.xml.zip -d data/
# 第二阶段：解析 XML
$ dvc stage add -n parse \
-d parsingxml.R -d data/Posts.xml \
-o data/Posts.csv \
Rscript parsingxml.R data/Posts.xml data/Posts.csv
在这个例子中，data/Posts.xml 既是 extract 阶段的输出，又是 parse 阶段的依赖。DVC 会自动建立这种连接，确保执行顺序正确。运行 dvc dag 可以看到生成的流水线结构：
$ dvc dag
+---------+
| extract |
+---------+
*
*
*
+---------+
| parse |
+---------+
参数依赖
在机器学习中，参数依赖比文件依赖更常见也更重要。我们通常会调整超参数、随机种子、配置选项等，这些变化应该触发相应的阶段重新执行，但不应该触发不相关的阶段。
DVC 支持将参数文件中的特定值作为依赖项。默认情况下，DVC 会读取 params.yaml 文件，但我们也可以指定其他格式的参数文件（JSON、TOML 等）。
首先创建一个 params.yaml 文件：
seed: 20180226
train:
lr: 0.0041
epochs: 75
layers: 9
processing:
threshold: 0.98
bow_size: 15000
然后在创建阶段时指定参数依赖：
$ dvc stage add -n train \
-d train_model.py -d matrix-train.p -o model.p \
-p seed,train.lr,train.epochs \
python train_model.py 20200105 model.p
参数依赖的语法很灵活：-p seed,train.lr,train.epochs 表示追踪 params.yaml 中的 seed、train.lr 和 train.epochs 三个值。DVC 会监控这些特定值的变化，只有当它们改变时才重新执行阶段。
在代码中，我们可以使用 dvc.api.params_show() 读取参数：
import dvc.api
params = dvc.api.params_show()
seed = params['seed']
lr = params['train']['lr']
epochs = params['train']['epochs']
这种方式将配置与代码分离，使得实验管理更加清晰。修改参数文件后，DVC 能够精确识别哪些阶段受到影响。
外部依赖
DVC 也支持外部依赖，即不在工作区内的文件或资源。这可以是云存储上的数据、数据库查询结果或远程 API。外部依赖让 DVC 能够追踪这些资源的变化，即使它们不在本地版本控制中。
stages:
prepare:
cmd:
- wget https://example.com/data.zip -O data.zip
- python prepare.py --bucket mybucket --prefix project-data
deps:
- prepare.py
- https://example.com/data.zip
outs:
- s3://mybucket/project-data/input_data:
cache: false
注意外部输出需要设置 cache: false，告诉 DVC 不要尝试缓存这些文件。
依赖管理的最佳实践
有几个重要的注意事项需要牢记：
首先，阶段执行前，DVC 会删除所有输出文件。这意味着代码每次运行时都必须重新创建所需的目录结构，不能假设目录已经存在。
其次，DVC 不会自动将依赖文件传递给命令。命令需要自己读取依赖文件，DVC 只负责监控变化。
最后，重命名依赖或输出需要手动更新 dvc.yaml 和项目缓存。这不是自动完成的，因为 DVC 需要保持缓存的一致性。
参数化配置
参数化配置是 DVC 流水线最强大的特性之一。它允许我们将超参数、配置选项与代码分离，实现灵活的实验管理。
参数文件结构
DVC 支持多种参数文件格式：YAML 1.2、JSON、TOML 1.0 和 Python 文件。最常用的是 YAML 格式，默认文件名为 params.yaml。
参数文件应该采用树状结构组织，使用点分隔的键名表示层级关系：
prepare:
split: 0.20
seed: 20170428
featurize:
max_features: 100
ngrams: 1
train:
seed: 20170428
n_est: 50
min_split: 2
这种结构清晰明了，便于管理不同模块的参数。在 dvc.yaml 中，我们使用点分隔的路径引用参数，如 featurize.max_features。
在 dvc.yaml 中定义参数依赖
参数依赖在 dvc.yaml 中通过 params 字段定义。有几种不同的语法形式：
stages:
preprocess:
cmd: bin/cleanup raw.txt clean.txt
deps:
- raw.txt
params:
- threshold # 追踪 params.yaml 中的 threshold
- nn.batch_size # 追踪 params.yaml 中的 nn.batch_size
- myparams.yaml: # 追踪自定义文件中的特定参数
- epochs
- config.json: # 追踪自定义文件中的所有参数
outs:
- clean.txt
第一种形式只写参数名，表示从默认的 params.yaml 中追踪。第二种形式使用文件名前缀，可以从自定义参数文件中追踪特定参数。第三种形式只写文件名和冒号，表示追踪该文件中的所有参数。
参数依赖的粒度优势
参数依赖的一个重要特点是粒度精细。多个阶段可以共享同一个参数文件，但每个阶段只关心自己需要的参数。当某个参数变化时，只有真正依赖它的阶段会重新执行。
例如，修改 train.n_est 只会触发 train 和 evaluate 阶段，而 prepare 和 featurize 阶段保持不变。这种精细的依赖追踪大大提高了迭代效率。
参数化配置的实践建议
在实际项目中，建议将所有可配置的参数都放入 params.yaml，避免在代码中硬编码。这样不仅便于实验管理，也让代码更加清晰。
对于复杂的项目，可以考虑将参数分成多个文件，如 data_params.yaml、model_params.yaml 等，在 dvc.yaml 中分别引用。
修改参数后，使用 dvc repro 执行流水线，DVC 会自动识别需要重新运行的阶段。结合 dvc metrics 和 dvc plots，可以快速评估参数变化对模型性能的影响。
流水线可视化 dag
当流水线包含多个阶段时，理解其结构变得困难。dvc dag 命令提供了直观的可视化方式，帮助我们在终端中查看流水线图。
基本用法
在项目根目录运行 dvc dag 会显示所有流水线的结构：
$ dvc dag
+---------+
| prepare |
+---------+
*
*
*
+-----------+
| featurize |
+-----------+
*
*
*
+-------+
| train |
+-------+
这个 ASCII 图形清晰地展示了三个阶段的执行顺序和依赖关系。每个星号 * 代表依赖连接的边。
查看特定阶段的流水线
如果只想查看某个特定阶段上游的流水线，可以将阶段名作为参数：
$ dvc dag train
这会显示所有影响 train 阶段的上游阶段，帮助我们理解哪些变化会触发重新训练。
输出视角的流水线图
默认情况下，dvc dag 显示的是阶段之间的依赖关系。使用 --outs 选项可以查看文件和目录级别的依赖图：
$ dvc dag --outs
+---------------+
| data/prepared |
+---------------+
*
*
*
+---------------+
| data/features |
**+---------------+**
**** * *****
***** * ****
**** * ****
*** +-----------+ ***
** | model.pkl | **
** +-----------+ **
** ** ** **
** ** ** **
** ** ** **
+-------------+ +----------+
| scores.json | | prc.json |
+-------------+ +----------+
这个视图展示了数据文件如何在不同阶段间流动，对于理解数据血缘特别有用。
导出为其他格式
dvc dag 支持将流水线图导出为多种格式，便于在其他工具中使用。
Mermaid 格式非常适合在 Markdown 文档中嵌入：
$ dvc dag --mermaid
flowchart TD
node1["data/data.xml.dvc"]
node2["evaluate"]
node3["featurize"]
node4["prepare"]
node5["train"]
node1-->node4
node3-->node2
node3-->node5
node4-->node3
node5-->node2
结合 --md 选项，可以直接生成 Markdown 代码块：
$ dvc dag --md
```mermaid
flowchart TD
node1["data/data.xml.dvc"]
node2["evaluate"]
node3["featurize"]
node4["prepare"]
node5["train"]
node1-->node4
node3-->node2
node3-->node5
node4-->node3
node5-->node2
这种格式在 GitHub 和 GitLab 中会自动渲染为图形，非常适合文档和代码审查。
DOT 格式则适合用 Graphviz 等专业工具进行高级可视化：
```bash
$ dvc dag --dot
digraph {
"data/data.xml.dvc" -> "prepare"
"featurize" -> "evaluate"
"featurize" -> "train"
"prepare" -> "featurize"
"train" -> "evaluate"
}
在 CI/CD 中使用
流水线可视化在持续集成中特别有用。我们可以将 dvc dag --md 的输出保存为文件，然后在 Pull Request 中自动评论：
$ dvc dag --md >> dag.md
$ cml send-comment dag.md
这样团队成员在审查代码时就能直观地看到流水线结构的变化。
总结
DVC 的流水线核心原理建立在 DAG 之上，通过阶段定义、依赖管理和参数化配置，实现了机器学习工作流的自动化和可重复性。每个阶段封装了命令、依赖和输出，DVC 根据依赖关系构建完整的执行图，智能地决定哪些阶段需要运行。
参数化配置让实验管理变得灵活，我们可以轻松调整超参数而无需修改代码。流水线可视化工具帮助我们理解和沟通复杂的流水线结构。
掌握了这些核心概念，我们就为下一章学习流水线的构建与执行打下了坚实基础。下一章将深入探讨如何使用 dvc repro 运行流水线，如何利用缓存机制加速执行，以及如何处理外部依赖和并行执行等高级话题。