exp run
无参数调用时，其效果等同于先执行 dvc repro，再执行 dvc exp save。
概要
usage: dvc exp run [-h] [-q | -v] [-f] [-i]
[-s] [-p] [-P] [-R]
[-n <name>] [-S [<filename>:]<override_pattern>]
[--queue] [--run-all] [-j <number>] [--temp]
[-r <experiment_rev>] [-C <path>]
[-m <message>]
[--downstream] [--force-downstream]
[--pull] [--dry] [--allow-missing]
[-k] [--ignore-errors]
[targets [targets ...]]
positional arguments:
targets Stages to reproduce. 'dvc.yaml' by default描述
在不污染仓库（如避免不必要的 Git 提交、分支、目录等）的前提下，执行并跟踪你的 仓库 中的 实验。
仅保存由 Git 或 DVC 跟踪的文件。如需保存未跟踪文件，请参见 dvc exp save --include-untracked。
当处理 targets 和阶段执行时，dvc exp run 的行为与 dvc repro 完全一致（例如恢复依赖图等）。
在准备实验时，会将任何已更改的数据 依赖项 提交到 DVC 缓存，此过程可能耗时较长。
使用 --set-param（-S）选项可快捷地在运行实验前 动态 修改 参数 值。
可通过 --queue 标志将实验 加入队列 以待后续执行。已入队的实验可通过 dvc queue start 启动，并使用其他 dvc queue 命令进行管理。
有关这些功能及其他特性的更多详情，请参阅 运行实验 指南。
使用 dvc exp show 查看 实验。成功的实验可通过 dvc exp branch 或 dvc exp apply 恢复并提交至 Git 仓库，从而 持久化；无需的实验可通过 dvc exp remove 清除。
选项
-
-S [<filename>:]<override_pattern>,--set-param [<filename>:]<override_pattern>- 为本次实验设置dvc params的值。该选项将在运行实验前更新参数文件（默认为params.yaml）。可选的[<filename>:]前缀可用于指定自定义参数文件。有效的
<override_pattern>可采用 Hydra 的 基础覆盖语法 定义（参见 示例）。Hydra 的 选择 和 范围 扫描覆盖也受支持，但必须同时提供--queue标志（参见 示例）。 -
-n <name>,--name <name>- 为本次实验指定一个 唯一名称。若未指定，将自动生成默认名称，如puffy-daks。实验名称会暴露在环境变量
DVC_EXP_NAME中。 -
--temp- 在工作区外（.dvc/tmp/exps）运行此实验。适用于在长时间实验运行时继续在其他终端中工作。 -
--queue- 将此实验添加至队列末尾以待后续执行，但暂不运行。使用dvc queue start处理队列。 -
--run-all- 运行所有排队的实验（参见--queue）以及工作区外的实验（位于.dvc/tmp/exps）。使用-j以并行方式执行。dvc exp run --run-all [--jobs]现在是dvc queue start [--jobs]后接dvc queue logs -f的快捷方式。未来 DVC 版本将弃用--run-all和--jobs选项。 -
-j <number>,--jobs <number>- 并行运行指定number个排队的实验。仅在与--run-all一起使用时生效。默认值为 1（队列按顺序处理）。 -
-f,--force- 即使未发现任何更改也重新生成流水线（等同于dvc repro -f）。 -
-C <path>,--copy-paths <path>- 要复制到临时目录的被忽略或未跟踪路径列表。仅在指定--temp或--queue时使用。 -
-m <message>,--message <message>- 保存实验时使用的自定义消息。若未提供，则使用dvc: commit experiment {hash}。 -
-i,--interactive— 在重现实验每个阶段前提示用户确认。只有当用户输入 "y" 时，该阶段才会被执行。 -
-s,--single-item— 关闭对依赖项变更的递归检查，仅重现实验单个阶段。如果提供了多个阶段名称作为targets，则这些阶段将被非递归地依次执行。 -
-p，--pipeline- 重新执行包含指定targets的完整管道。使用dvc dag <target>查看某个目标的父级管道。 -
-P，--all-pipelines- 重新执行 DVC 项目中所有dvc.yaml文件定义的全部管道。此选项下指定targets无效，因为所有可能的目标都会被包含。 -
-R,--recursive— 在作为targets提供的目录及其子目录中递归查找dvc.yaml文件并进行重现实验。如果目标中不包含任何目录，则此选项无效。 -
--downstream- 仅在其对应管道中执行给定targets之后的阶段，包括目标阶段本身。如果未提供targets，此选项无效。 -
--force-downstream- 在类似... -> A (已更改) -> B -> C的情况下，会先重新执行A，然后继续执行B，即使B此前已使用来自A的相同输入执行过（已被缓存）。准确地说，它会重新执行所有变更阶段的下游阶段，即使这些阶段的直接依赖项未发生变化。当所有阶段共享一个公共依赖时，这种方式非常有用，可仅在第一个相关阶段（如本例中的
A）声明该依赖，避免重复定义。例如，若已知所有阶段（A及其后续阶段）都依赖于requirements.txt，则只需在A中声明，在B和C中可省略。这是一种强制执行未变更阶段的方法。对于包含生成非确定性（半随机）输出的阶段的管道也很有用，因为每次执行输出都可能不同，因此无法信任此类阶段的缓存。
-
--pull- 按需尝试下载缺失的数据。包括：(1) 待运行阶段的依赖项，(2) 无需运行但需保留输出的阶段的输出，(3) [运行缓存] 中用于检出阶段的数据（除非传递了--no-run-cache）。 -
--allow-missing- 跳过仅有数据缺失而无其他变更的阶段。在 DVC>=3.0 版本中，
--allow-missing不会跳过由 DVC<3.0 保存的数据，因为在 DVC 3.0 中哈希类型发生了变化，DVC 将其视为数据变更。要将数据迁移到新的哈希类型，请运行dvc cache migrate --dvc-files。更多关于 从 DVC 2.x 升级到 3.0 的信息请参阅相关文档。 -
-k，--keep-going- 继续执行，跳过依赖于失败阶段的那些阶段。目标的其他依赖项仍将被执行。 -
--ignore-errors- 执行阶段时忽略所有错误。与--keep-going不同，即使阶段依赖于失败的阶段，也会继续执行。 -
-h,--help- 打印使用/帮助信息并退出。 -
-q，--quiet- 不向标准输出写入任何内容。如果所有阶段均已最新或全部成功执行，则以退出码 0 结束；否则以退出码 1 结束。阶段中定义的命令仍可自由输出信息，不受此标志影响。 -
-v,--verbose- 显示详细的跟踪信息。
示例
本示例基于 我们的入门指南，您可在其中找到实际源代码。
克隆 DVC 仓库并下载其依赖的数据：
$ git clone git@github.com:iterative/example-get-started.git
$ cd example-get-started
$ dvc pull我们还安装 Python 依赖项：
我们强烈建议先创建一个虚拟环境。
$ pip install -r src/requirements.txt让我们检查项目的最新指标：
$ dvc metrics show
Path avg_prec roc_auc
scores.json 0.60405 0.9608本次实验中，我们希望查看较小数据集输入的结果，因此将数据限制为 20 MB，并使用 dvc exp run 重新运行流水线：
$ truncate --size=20M data/data.xml
$ dvc exp run
...
Reproduced experiment(s): puffy-daks
Experiment results have been applied to your workspace.
$ dvc metrics diff
Path Metric HEAD workspace Change
scores.json avg_prec 0.60405 0.56103 -0.04302
scores.json roc_auc 0.9608 0.94003 -0.02077dvc metrics diff 命令显示了我们刚运行的实验（puffy-daks）的性能差异。
示例：动态修改参数
dvc exp run --set-param（-S）可避免在运行实验前手动编辑参数文件（参见 dvc params）。
此选项支持 Hydra 的基本覆盖语法。例如，它可以覆盖（train.epochs=10）、追加（+train.weight_decay=0.01）或删除（~model.dropout）参数：
dvc exp run -S 'prepare.split=0.1' -S 'featurize.max_features=100'
...请注意，您可以在同一命令中同时修改多个参数。
默认情况下，-S 会覆盖 params.yaml 中的值。如需使用其他参数文件，请添加 <filename>: 前缀。例如，向 train_config.json 追加一个新参数：
$ dvc exp run -S 'train_config.json:+train.weight_decay=0.001'
...
$ dvc params diff --targets train_config.json
Path Param HEAD workspace
train_config.json train.weight_decay - 0.001警告
示例：运行网格搜索
结合 --set-param 和 --queue，我们可以执行 网格搜索 来调整超参数。
DVC 支持 Hydra 的 选择 和 范围 扫描语法，以将多个实验添加到队列中。这些语法可同时用于多个参数，将所有组合添加到队列中：
$ dvc exp run -S 'train.min_split=8,64' -S 'train.n_est=range(100,500,100)' --queue
Queueing with overrides '{'params.yaml': ['train.min_split=8', 'train.n_est=100']}'.
Queued experiment 'azure-ices' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=8', 'train.n_est=200']}'.
Queued experiment 'zingy-peri' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=8', 'train.n_est=300']}'.
Queued experiment 'jammy-feds' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=8', 'train.n_est=400']}'.
Queued experiment 'lowse-shay' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=64', 'train.n_est=100']}'.
Queued experiment 'brown-hugs' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=64', 'train.n_est=200']}'.
Queued experiment 'local-scud' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=64', 'train.n_est=300']}'.
Queued experiment 'alpha-neck' for future execution.
Queueing with overrides '{'params.yaml': ['train.min_split=64', 'train.n_est=400']}'.
Queued experiment 'algal-hood' for future execution.
$ dvc queue start
...示例：仅按需拉取管道数据
你可以结合使用 --pull 和 --allow-missing 标志，在重现实验管道的同时，仅拉取实际需要的数据来运行已更改的阶段。
基于 example-get-started-experiments 中使用的管道：
$ dvc dag
+--------------------+
| data/pool_data.dvc |
+--------------------+
*
*
*
+------------+
| data_split |
+------------+
** **
** **
* **
+-------+ *
| train |* *
+-------+ **** *
* *** *
* **** *
* ** *
+-----------+ +----------+
| sagemaker | | evaluate |
+-----------+ +----------+如果我们处于一台所有数据均缺失的机器上：
$ dvc status
data_split:
changed deps:
deleted: data/pool_data
changed outs:
not in cache: data/test_data
not in cache: data/train_data
train:
changed deps:
deleted: data/train_data
changed outs:
not in cache: models/model.pkl
not in cache: models/model.pth
not in cache: results/train
evaluate:
changed deps:
deleted: data/test_data
deleted: models/model.pkl
changed outs:
not in cache: results/evaluate
sagemaker:
changed deps:
deleted: models/model.pth
changed outs:
not in cache: model.tar.gz
data/pool_data.dvc:
changed outs:
not in cache: data/pool_data我们可以修改 evaluate 阶段，DVC 将仅拉取运行该阶段所需的必要数据（models/model.pkl 和 data/test_data/），并跳过其余阶段：
$ dvc exp run --pull --allow-missing
Reproducing experiment 'hefty-tils'
'data/pool_data.dvc' didn't change, skipping
Stage 'data_split' didn't change, skipping
Stage 'train' didn't change, skipping
Running stage 'evaluate':
...更多详情请参阅用户指南中的 拉取缺失数据。
示例：包含未跟踪或被忽略的路径
如果您的代码依赖于某些被 Git 故意未跟踪或忽略的路径，您可以使用 -C/--copy-paths 确保在使用 --temp 或 --queue 标志时这些文件仍可访问：
$ dvc exp run --temp -C secrets.txt -C symlinked-directory这些路径将被复制到临时目录中，但 不会 被跟踪，以防止意外泄露。