stage add

用于在 dvc.yaml 中创建或更新阶段的辅助命令。

概要

usage: dvc stage add [-h] [-q | -v] -n <name> [-f]
                 [-d <path>] [-p [<filename>:]<params_list>]
                 [-o <filename>] [-O <filename>] [-c <filename>]
                 [--outs-persist <filename>]
                 [--outs-persist-no-cache <filename>]
                 [-m <path>] [-M <path>]
                 [--plots <path>] [--plots-no-cache <path>]
                 [-w <path>] [--always-changed] [--desc <text>]
                 [--run]
                 command

positional arguments:
  command               Command to execute

描述

将阶段定义写入 dvc.yaml（当前工作目录）。若要更新现有阶段，请使用 -f（--force）选项覆盖它。

必须提供阶段名称，可通过 -n（--name）选项指定。大多数其他选项用于定义阶段的各类依赖项和输出。在所有选项/标志之后提供的终端输入将作为必需的 command 参数。

在 command 之后传递的 -/-- 标志将作为命令本身的一部分，被 dvc stage add 忽略。

当某个阶段的输出成为其他阶段的依赖项时，它们构成流水线。例如：

$ dvc stage add -n printer -d write.sh -o pages ./write.sh
$ dvc stage add -n scanner -d read.sh -d pages -o signed.pdf ./read.sh pages

有关更多详情，请参阅定义流水线阶段指南。

可使用 dvc repro 重建此依赖关系图并运行阶段。

依赖项和输出

阶段依赖项可以是任意文件或目录，无论是未跟踪的，还是更常见的由 DVC 或 Git 跟踪的文件。当阶段运行时，输出将由 DVC 跟踪并缓存。每次重新生成阶段时，每个输出版本都会被缓存（另见 dvc gc）。相关说明：

通常，要运行的脚本（或可能包含源代码的目录）会被包含在指定的 -d 依赖项中。这确保当源代码更改时，DVC 知道需要重新生成该阶段。（您可以自行选择是否这样做。）
dvc stage add 在创建新阶段前会检查依赖关系图的完整性。例如：两个阶段不能指定相同的输出或重叠的输出路径，不能存在循环等。
DVC 不会将依赖文件传递给正在运行的命令。程序必须自行读取这些文件。
DVC 可以将阶段生成的整个目录作为输出进行跟踪，这会在缓存中生成一个单独的 .dir 条目（更多信息请参阅缓存目录结构）。
也支持外部依赖项和输出（位于工作区之外），但度量和图表除外。
由于在执行阶段命令前，输出会被从工作区中删除，因此底层代码每次被 DVC 执行时都必须重新创建所需的目录结构。
在某些情况下，我们之前已执行过某个阶段，但后来发现某些依赖项或输出未包含在 dvc.yaml 中。可以将它们添加到现有阶段。
重命名依赖项或输出需要通过手动流程更新 dvc.yaml 和项目缓存。

用于显示和比较数据科学实验

参数（-p/--params 选项）是一种特殊的键值依赖。可以在一个或多个结构化文件（默认为 params.yaml）中指定多个参数。这使得在机器学习中轻松跟踪实验超参数成为可能。

还支持特殊类型的输出文件：指标（-m 和 -M 选项）和图表（--plots 和 --plots-no-cache 选项）。指标和图表文件具有特定格式（JSON、YAML、CSV 或 TSV），可用于展示和比较数据科学实验结果。

选项

-n <stage>，--name <stage>（必需）— 为该命令生成的阶段指定名称（例如 -n train）。阶段名称只能包含字母、数字、连字符 - 和下划线 _。
-d <path>，--deps <path> — 指定阶段所依赖的文件或目录。可按如下方式指定多个依赖项：-d data.csv -d process.py。通常，每个依赖项是包含数据的文件或目录、代码文件或配置文件。DVC 还支持某些外部依赖项。

当您使用 dvc repro 时，依赖项列表帮助 DVC 分析是否有任何依赖项发生更改，从而决定是否需要执行相关阶段以重新生成其输出。
-o <path>，--outs <path> — 指定运行 command 后生成的文件或目录。可以指定多个输出：-o model.pkl -o output.log。DVC 基于这些输出和依赖项列表（参见 -d）构建依赖关系图（流水线）以连接各个阶段。DVC 会跟踪所有输出文件和目录，并将它们存入缓存（这与使用 dvc add 时的行为类似）。
-O <path>，--outs-no-cache <path> — 与 -o 相同，但输出不会被 DVC 跟踪。这意味着它们永远不会被缓存，由用户自行管理。当输出足够小，可直接由 Git 跟踪；或体积较大，但您希望每次重新生成它们时（参见 dvc repro）；或出于其他原因不希望存储时，此选项非常有用。使用此选项将禁用该阶段的运行缓存。
--outs-persist <path> — 声明一个在 dvc repro 启动时不会被删除的输出文件或目录（但仍可被阶段命令修改、覆盖或删除）。
--outs-persist-no-cache <path> — 与 -outs-persist 相同，但输出不会被 DVC 跟踪（与上述 -O 行为一致）。
-p [<path>:]<params_list>，--params [<path>:]<params_list> — 从结构化文件 path（默认为 ./params.yaml）中指定一个或多个参数依赖。方法是将逗号分隔的列表（params_list）作为参数传入，例如 -p learning_rate,epochs。可通过前缀指定自定义参数文件，例如 -p params.json:threshold。也可仅使用前缀加 : 来使用该文件中的所有参数，例如 -p myparams.toml:。
-m <path>, --metrics <path> - 指定由本阶段生成的指标文件。此选项的行为类似于 -o，但会将文件注册到 dvc.yaml 阶段中的 metrics 字段。指标通常是小型、人类可读的文件（JSON、TOML 或 YAML），包含标量数字或其他描述模型（或任何其他数据工件）的简单信息。有关指标的更多信息，请参阅 dvc metrics。
-M <path>, --metrics-no-cache <path> - 与 -m 相同，但 DVC 不跟踪指标文件（与上述 -O 相同）。这意味着这些文件永远不会被缓存，需由用户自行管理。由于指标文件通常足够小，可直接由 Git 跟踪，因此这种用法通常更合适。
--plots <path> - 指定由本阶段生成的图表文件或目录。此选项的行为类似于 -o，但会将文件或目录注册到 dvc.yaml 阶段中的 plots 字段。图表输出可以是存储在表格格式（CSV 或 TSV）或分层格式（JSON 或 YAML）文件中的数据序列，也可以是图像文件（JPEG、GIF、PNG 或 SVG）。有关图表的更多信息，请参阅可视化图表。
--plots-no-cache <path> - 与 --plots 相同，但 DVC 不跟踪图表文件（与上述 -O 和 -M 相同）。如果图表文件足够小，可直接由 Git 跟踪，则这种用法可能更合适。
-w <path>, --wdir <path> - 指定 command 执行时的工作目录（使用 dvc.yaml 中的 wdir 字段）。依赖项和输出文件（包括指标和图表）应相对于此目录指定。dvc repro 会在执行 command 前切换到此工作目录。
-f, --force - 无需确认，直接覆盖 dvc.yaml 文件中已存在的阶段。
--always-changed - 始终将此阶段视为已更改（在 dvc.yaml 中设置 always_changed 字段）。结果是，每次重新运行流水线时，DVC 都会执行该阶段。
--desc <text> - 阶段的用户描述（可选）。此选项不影响任何 DVC 操作。
--run - 生成阶段后立即执行它
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的跟踪信息。

示例

让我们创建一个阶段（统计 test.txt 文件中的行数）：

$ 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'

To track the changes with git, run:

	git add .gitignore dvc.yaml

$ tree
.
├── dvc.yaml
└── test.txt

这将在 dvc.yaml 中生成如下阶段条目：

stages:
  count:
    cmd: 'cat test.txt | wc -l > lines'
    deps:
      - test.txt
    outs:
      - lines

工作区中尚无 lines 文件，因为阶段尚未运行。该文件将在运行 dvc repro 时被创建并跟踪。

示例：覆盖现有阶段

以下阶段运行一个 Python 脚本，在训练数据集上训练机器学习模型（20180226 为随机种子值）：

$ dvc stage add -n train \
                -d train_model.py -d matrix-train.p -o model.p \
                python train_model.py 20180226 model.p

要更新已定义的阶段，需要使用 -f（--force）选项。我们来更新 train 阶段的种子值：

$ dvc stage add -n train --force \
                -d train_model.p -d matrix-train.p -o model.p \
                python train_model.py 18494003 model.p

示例：在子目录中分离阶段

让我们切换到一个子目录并在其中创建一个阶段。这将在该位置生成一个独立的 dvc.yaml 文件。该阶段命令本身会统计 test.txt 中的行数，并将结果写入 lines。

$ cd more_stages/
$ dvc stage add -n process_data \
                -d data.in \
                -o result.out \
                ./my_script.sh data.in result.out
$ tree ..
.
├── dvc.yaml
├── dvc.lock
├── file1
├── ...
└── more_stages/
    ├── data.in
    └── dvc.yaml

示例：串联阶段

DVC 流水线通过将某个阶段的输出连接到后续阶段的依赖项来构建。

让我们创建一个阶段，将归档文件中的 XML 文件提取到 data/ 文件夹：

$ dvc stage add -n extract \
                -d Posts.xml.zip \
                -o data/Posts.xml \
                unzip Posts.xml.zip -d data/

请注意，最后一个 -d 作用于阶段的命令（unzip），而非 dvc stage add。

此外，让我们添加另一个阶段，执行一个解析 XML 文件的 R 脚本：

$ 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

这些阶段尚未运行，因此尚无输出。但我们仍可通过 dvc dag 查看它们如何根据输出和依赖关系连接成流水线：

$ dvc dag
+---------+
| extract |
+---------+
      *
      *
      *
+---------+
|  parse  |
+---------+

我们可以使用 dvc repro 执行此流水线以获取输出。

示例：使用参数依赖

要在参数文件中使用特定值作为依赖项，请创建一个名为 params.yaml 的简单 YAML 文件（默认参数文件名，详见 dvc params）：

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

train_model.py 可使用 dvc.api.params_show() 解析参数：

import dvc.api

params = dvc.api.params_show()

seed = params['seed']
lr = params['train']['lr']
epochs = params['train']['epochs']

我们使用 ruamel.yaml，它支持 YAML 1.2（不同于更流行的 PyYAML）。

你也可以使用模板直接将参数从 params.yaml 注入到阶段中。

DVC 会监控这些参数值（与常规依赖文件相同），并在其发生变化时知道应重新运行该阶段。更多详情请参见 dvc params。