artifacts get

将模型注册表（model registry）中跟踪的某个 制品（artifact） 下载到当前工作目录（可选支持 DVC Studio）。

另请参阅我们的 Python API 函数 dvc.api.artifacts_show()。

概要

usage: dvc artifacts get [-h] [-q | -v]
                         [--rev [<version>]] [--stage [<stage>]]
                         [-o [<path>]] [--show-url] [-j <number>] [-f]
                         [--config CONFIG]
                         [--remote REMOTE] [--remote-config [REMOTE_CONFIG ...]]
                         url name

positional arguments:
  url                   Location of DVC repository to download from
  name                  Name of artifact in the repository

描述

提供一种方式，用于从模型注册表中下载制品。与 dvc get 不同，dvc artifacts get 支持通过名称而非路径来下载制品。同样，dvc artifacts get 支持下载已注册的制品版本或阶段（stage），而无需指定 Git 提交版本。

url 参数指定了包含该制品的 DVC 或 Git 仓库地址。支持 HTTP 和 SSH 协议（例如 [user@]server:project.git）。url 也可以是本地文件系统路径（包括当前项目，例如 .）。

name 参数指定了要下载的制品名称。默认情况下，DVC 会在 DVC 仓库根目录下的 dvc.yaml 文件中查找声明的制品。对于在其他 dvc.yaml 文件中声明的制品，应使用如下格式指定：path/to/dvc.yaml:artifact_name 或 path/to:artifact_name（省略了 dvc.yaml）。

dvc artifacts get 会优先尝试通过 DVC Studio REST API 下载制品。使用 Studio REST API 下载制品仅需一个有效的 DVC Studio 客户端访问令牌（client access token），以及一个配置了远程存储凭据的 Studio 项目，客户端本身无需拥有这些凭据。如果没有有效的 DVC Studio 令牌，或该制品未在模型注册表中跟踪，DVC 将回退到其常规的文件获取方法（参见 dvc get）。

选项

• --rev <version> - 要下载的制品版本。当未指定 rev 或 stage 时，默认使用制品的最新版本。

• --stage <stage> - 要下载的制品阶段。当未指定 rev 或 stage 时，默认使用制品的最新版本。

• -o <path>, --out <path> - 指定工作区中希望放置下载文件或目录的目标路径（替代使用当前工作目录）。该命令会自动创建路径中指定的所有目录。

• --show-url - 不下载文件或目录，仅打印目标数据的存储位置（URL）。

• -j <数字>，--jobs <数字> - DVC 从远程下载数据时使用的并行任务数量。默认值为 4 * cpu_count()。使用更多任务可能会加快操作速度。注意：可通过 dvc remote modify 的 jobs 配置选项在源仓库中设置默认值。

• -f, --force - 当使用 --out 指定本地目标文件或目录时，如果这些路径已存在，操作将失败。使用此标志会强制执行操作，导致命令覆盖现有的本地文件/目录。

• --config <path> - 指向 配置文件 的路径，该文件将与目标仓库中的配置合并。

• --remote <name> - 在目标仓库中设置为默认的 dvc remote 名称。仅在从 DVC 远程下载制品时适用。

• --remote-config [<name>=<value> ...] - 要与目标仓库中远程配置（默认或由 --remote 指定）合并的 dvc remote 配置选项。仅在从 DVC 远程下载制品时适用。

• -h, --help - 打印使用说明/帮助信息，然后退出。

• -q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。

• -v, --verbose - 显示详细的跟踪信息。

示例：从 DVC 远程下载制品

$ dvc artifacts get https://github.com/iterative/example-get-started.git text-classification --rev=v1.0.0
Downloaded 1 file(s) to 'model.pkl'

在此示例中，我们下载制品的 v1.0.0 版本。由于我们的环境中未设置 DVC Studio 凭据，dvc artifacts get 将从仓库中定义的默认 DVC 远程下载该制品。

示例：使用 DVC Studio 令牌下载制品

$ DVC_STUDIO_TOKEN=mytoken dvc artifacts get https://github.com/iterative/example-get-started.git text-classification --stage=prod
Downloaded 1 file(s) to 'model.pkl'

在此示例中，我们下载工件的 prod 阶段。由于我们已在 DVC_STUDIO_TOKEN 环境变量中设置了 Studio 访问令牌，dvc artifacts get 将通过模型注册表而非 DVC 远端下载该工件。

示例：下载在特定 dvc.yaml 文件中定义的工件

$ dvc artifacts get https://github.com/iterative/lstm_seq2seq.git results/dvc.yaml:best
Downloaded 1 file(s) to 'epoch=0-step=16.ckpt'

在此示例中，我们下载 best 工件的最新版本。此时，该工件定义在 results/dvc.yaml 中，因此在引用该工件时必须包含指向 dvc.yaml 文件的路径。由于未指定 --rev 或 --stage，dvc artifacts get 默认将下载该工件的最新版本。

示例：获取工件的存储 URL

我们可以使用 dvc artifacts get --show-url 来获取模型实际存储的位置：

$ dvc artifacts get https://github.com/iterative/example-get-started.git \
  text-classification --rev=v1.0.0 --show-url
https://remote.dvc.org/get-started/files/md5/cf/a72ff6e2575c44f78f423cada5b783