参数

包含一个用于显示参数变化的命令：diff。

概要

usage: dvc params [-h] [-q | -v] {diff} ...

positional arguments:
  COMMAND
    diff         Show changes in params between commits in the
                 DVC repository, or between a commit and the workspace.

描述

参数可以是代码中用于影响结果的任意值（例如机器学习中的超参数）。DVC 可以从结构化的 YAML 1.2、JSON、TOML 1.0 或 Python 文件（默认为 params.yaml）中以键值对的形式跟踪这些参数。参数通常具有简单的名称，如 epochs、learning-rate、batch_size 等。示例：

epochs: 900
tuning:
  - learning-rate: 0.945
  - max_depth: 7
paths:
  - labels: 'materials/labels'
  - truth: 'materials/ground'

要开始跟踪参数，请在 dvc.yaml 的 params 字段下列出它们的名称（可手动操作，或使用 dvc stage add 命令的 -p/--params 选项）。例如：

stages:
  learn:
    cmd: python deep.py # reads params.yaml internally
    params:
      - epochs # specific param from params.yaml
      - tuning.learning-rate # nested param from params.yaml
      - paths # entire group from params.yaml
      - myparams.toml:
          - batch_size # param from custom file
      - config.json: # all params in this file

参见更多细节了解此语法。

一个流水线中的多个阶段都可以将同一个参数文件作为依赖项使用，但每个阶段仅受其中特定的值影响。

参数也可用于对模板化 dvc.yaml 本身（另见字典解包），这意味着你可以将它们作为命令行参数传递给你的阶段命令。你还可以使用 dvc.api.params_show() 在 Python 代码中加载它们。

可使用 dvc params diff 命令查看参数的变化，并显示其当前值和先前值。

DVC 会将参数名和值保存到 dvc.lock 中，以便随时间跟踪它们。当运行 dvc repro（或 dvc status）时，这些值将与最新的参数文件进行比较，以确定阶段是否已过期。

选项

-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。
-v, --verbose - 显示详细的跟踪信息。

示例

首先，让我们创建一个简单的 YAML 格式参数文件，使用默认文件名 params.yaml：

lr: 0.0041

train:
  epochs: 70
  layers: 9

process:
  thresh: 0.98
  bow: 15000

使用 dvc stage add 定义一个依赖于上述参数文件中 lr、layers 和 epochs 参数的阶段。应使用完整路径来指定 train 组中的 layers 和 epochs：

$ dvc stage add -n train -d train.py -d users.csv -o model.pkl \
                -p lr,train.epochs,train.layers \
                python train.py

请注意，我们也可以使用 JSON、TOML 或 Python 参数文件采用相同的参数寻址方式。

train.py 脚本将包含一些解析和加载所需参数的代码。你可以使用 dvc.api.params_show() 实现这一点：

import dvc.api

params = dvc.api.params_show()

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

你可以发现每个参数都在 dvc.yaml 中定义，并且其值也被保存到了 dvc.lock 中。当使用 dvc repro 时，这些值会与参数文件进行比较，以判断参数依赖是否发生了变化。

# dvc.yaml
stages:
  train:
    cmd: python train.py
    deps:
      - users.csv
    params:
      - lr
      - train.epochs
      - train.layers
    outs:
      - model.pkl

或者，也可以直接引用整个 train 参数组，而无需单独列出每个参数：

$ dvc stage add -n train -d train.py -d users.csv -o model.pkl \
                -p lr,train \
                python train.py

# in dvc.yaml
params:
  - lr
  - train

在上述示例中，使用了默认的参数文件名 params.yaml。注意，可以通过在 dvc stage add 命令的 -p 参数中添加前缀来重新定义该文件名。在我们的例子中：

$ dvc stage add -n train -d train.py -d logs/ -o users.csv -f \
                -p parse_params.yaml:threshold,classes_num \
                python train.py

示例：打印所有参数

根据前面的例子，我们可以使用 dvc params diff 列出工作区中所有可用的参数值：

$ dvc params diff
Path         Param           HEAD  workspace
params.yaml  lr              —     0.0041
params.yaml  process.bow     —     15000
params.yaml  process.thresh  —     0.98
params.yaml  train.epochs    —     70
params.yaml  train.layers    —     9

该命令显示工作区与上次提交的 params.yaml 文件版本之间的参数差异。在我们的示例中，由于不存在之前的版本，因此所有 Old 值均为 —。

示例：Python 参数文件

请注意，复杂的表达式（ast.literal_eval 不支持的）将不会被解析为 DVC 参数。

考虑以下名为 params.py 的 Python 参数文件：

# All standard variable types are supported.
BOOL = True
INT = 5
FLOAT = 0.001
STR = 'abc'
DICT = {'a': 1, 'b': 2}
LIST = [1, 2, 3]
SET = {4, 5, 6}
TUPLE = (10, 100)
NONE = None
UNARY_OP = -1

# Complex expressions will be ignored.
DICT_EXP = dict(a=1, b=2)

# DVC can retrieve class constants and variables defined in __init__
class TrainConfig:

    EPOCHS = 70

    def __init__(self):
        self.layers = 5
        self.layers = 9  # TrainConfig.layers param will be 9
        self.sum = 1 + 2  # Will NOT be found due to the expression
        bar = 3  # Will NOT be found since it's locally scoped


class TestConfig:

    TEST_DIR = 'path'
    METRICS = ['metric']

以下阶段依赖于参数 BOOL、INT，以及 TrainConfig 中的 EPOCHS 和 layers：

$ dvc stage add -n train -d train.py -d users.csv -o model.pkl \
                -p params.py:BOOL,INT,TrainConfig.EPOCHS,TrainConfig.layers \
                python train.py

生成的 dvc.yaml 和 dvc.lock 文件（注意 params 列表）：

stages:
  train:
    cmd: python train.py
    deps:
      - users.csv
    params:
      - params.py:
          - BOOL
          - INT
          - TrainConfig.EPOCHS
          - TrainConfig.layers
    outs:
      - model.pkl

schema: '2.0'
stages:
  train:
    cmd: python train.py
    deps:
      - path: users.csv
        md5: 23be4307b23dcd740763d5fc67993f11
    params:
      params.py:
        INT: 5
        BOOL: true
        TrainConfig.EPOCHS: 70
        TrainConfig.layers: 9
    outs:
      - path: model.pkl
        md5: 1c06b4756f08203cc496e4061b1e7d67

或者，可以引用整个 TestConfig 参数组（类）（也支持字典），而不是其中的各个参数：

$ dvc stage add -n train -d train.py -d users.csv -o model.pkl \
                -p params.py:BOOL,INT,TestConfig \
                python train.py

参数

概要

描述

选项

示例

示例：打印所有参数

示例：Python 参数文件

内容