|横幅|

网站 <https://dvc.org>_ • 文档 <https://dvc.org/doc>_ • 博客 <http://blog.dataversioncontrol.com>_ • 教程 <https://dvc.org/doc/get-started>_ • 相关技术 <https://dvc.org/doc/user-guide/related-technologies>_ • DVC 工作原理_ • VS Code 扩展_ • 安装_ • 贡献代码_ • 社区与支持_

|CI| |Python 版本| |覆盖率| |VS Code| |DOI|

|PyPI| |PyPI 下载量| |软件包| |Brew| |Conda| |Choco| |Snap|

|

数据版本控制，简称 DVC，是一款命令行工具及 VS Code 扩展_，旨在帮助您开发可复现的机器学习项目：

#. 版本化您的数据和模型。 将它们存储在云端，但将版本信息保留在 Git 仓库中。

#. 使用轻量级流水线快速迭代。 当您进行更改时，仅运行受这些更改影响的步骤。

#. 在本地 Git 仓库中跟踪实验（无需服务器）。

#. 比较任何数据、代码、超参数、模型或性能图表。

#. 分享实验，并自动复现他人的实验。

快速入门

请参阅我们的 `命令参考 <https://dvc.org/doc/command-reference>`_ 以获取完整列表。

常见的 CLI 工作流程包括：

+-----------------------------------+----------------------------------------------------------------------------------------------------+ | 任务 | 终端 | +===================================+====================================================================================================+ | 跟踪数据 | | $ git add train.py params.yaml | | | | $ dvc add images/ | +-----------------------------------+----------------------------------------------------------------------------------------------------+ | 连接代码和数据 | | $ dvc stage add -n featurize -d images/ -o features/ python featurize.py | | | | $ dvc stage add -n train -d features/ -d train.py -o model.p -M metrics.json python train.py | +-----------------------------------+----------------------------------------------------------------------------------------------------+ | 进行更改并实验 | | $ dvc exp run -n exp-baseline | | | | $ vi train.py | | | | $ dvc exp run -n exp-code-change | +-----------------------------------+----------------------------------------------------------------------------------------------------+ | 比较并选择实验 | | $ dvc exp show | | | | $ dvc exp apply exp-baseline | +-----------------------------------+----------------------------------------------------------------------------------------------------+ | 分享代码 | | $ git add . | | | | $ git commit -m '基准模型' | | | | $ git push | +-----------------------------------+----------------------------------------------------------------------------------------------------+ | 分享数据和机器学习模型 | | $ dvc remote add myremote -d s3://mybucket/image_cnn | | | | $ dvc push | +-----------------------------------+----------------------------------------------------------------------------------------------------+

DVC 工作原理

我们建议您阅读我们的 `入门指南 <https://dvc.org/doc/get-started>`_，以便更好地理解 DVC 的功能及其如何适应您的场景。

描述 DVC 主要功能的最贴切类比是：

#. 数据版控 Git：存储和分享数据制品（类似 Git-LFS，但无需服务器）以及模型，并将其与 Git 仓库连接起来。数据管理与 GitOps 相结合！ #. 适用于机器学习的 Makefile：以标准格式描述如何从其他数据和代码构建数据或模型制品。现在您可以使用 Git 对数据流水线进行版本控制。 #. 本地实验跟踪：将您的机器变成一个机器学习实验管理平台，并利用现有的 Git 托管服务（如 GitHub、GitLab 等）与他人协作。

Git 通常用于存储和版本化代码（包括作为数据占位符的 DVC 元文件）。 DVC 无缝地将数据和模型文件 <https://dvc.org/doc/start/data-management>_ 存储在 Git 外部的缓存中，同时几乎保持与文件位于仓库内相同的用户体验。 为了共享和备份 数据缓存，DVC 支持多种远程存储平台——无论是云存储（S3、Azure、Google Cloud 等）还是本地网络存储（例如通过 SSH）。

|流程图|

DVC 流水线 <https://dvc.org/doc/start/data-management/data-pipelines>_（计算图）将代码和数据连接在一起。 它们指定了生成模型所需的所有步骤：输入依赖项（包括代码、数据、要执行的命令）以及需要保存的输出信息。

最后，但同样重要的是，DVC 实验版本控制 <https://dvc.org/doc/start/experiments>_ 让您可以准备和运行大量实验。 其结果可以根据超参数和指标进行筛选和比较，并通过多种图表进行可视化。

.. _VS Code Extension:

VS Code 扩展

|VS Code|

要直接在 VS Code IDE 中以图形界面使用 DVC，请从市场安装 DVC 扩展 <https://marketplace.visualstudio.com/items?itemName=Iterative.dvc>_。 目前它支持实验跟踪和数据管理，更多功能（如数据流水线支持等）也将很快推出！

|VS Code 扩展概览|

注意：您需要单独在系统上安装核心 DVC（如下所述）。如有需要，扩展会为您提供指导。

安装

安装 DVC 有多种方式：在 VS Code 中；使用 snap、choco、brew、conda、pip；或者通过特定操作系统的软件包管理器。 完整说明 在此处 <https://dvc.org/doc/get-started/install>_ 可用。

Snapcraft（Linux）

|Snap|

.. code-block:: bash

snap install dvc --classic

这对应于最新的标记版本。添加 --beta 可以获取最新的候选版本，而使用 --edge 则会安装最新的 main 分支版本。

Chocolatey（Windows）

|Choco|

.. code-block:: bash

choco install dvc

Brew（macOS）

|Brew|

.. code-block:: bash

brew install dvc

Anaconda（任意平台）

|Conda|

.. code-block:: bash

conda install -c conda-forge mamba # 安装速度远超 conda mamba install -c conda-forge dvc

根据您计划用于存储和共享数据的远程存储类型，可能需要安装可选依赖项：dvc-s3、dvc-azure、dvc-gdrive、dvc-gs、dvc-oss、dvc-ssh。

PyPI（Python）

|PyPI|

.. code-block:: bash

pip install dvc

根据您计划用于存储和共享数据的远程存储类型，可能需要指定其中一个可选依赖项：s3、gs、azure、oss、ssh。或者使用 all 来包含所有这些依赖项。命令应如下所示：pip install 'dvc[s3]'（在这种情况下，AWS S3 的依赖项如 boto3 将被自动安装）。

要安装开发版本，请运行：

.. code-block:: bash

pip install "dvc @ git+https://github.com/treeverse/dvc"

软件包（特定平台）

|Packages|

适用于 Linux、Windows 和 Mac 的自包含软件包现已提供。最新版本的软件包可在 GitHub 的 发布页面 <https://github.com/treeverse/dvc/releases>_ 上找到。

Ubuntu / Debian（deb） ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash

sudo wget https://dvc.org/deb/dvc.list -O /etc/apt/sources.list.d/dvc.list wget -qO - https://dvc.org/deb/iterative.asc | sudo apt-key add - sudo apt update sudo apt install dvc

Fedora / CentOS（rpm） ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash

sudo wget https://dvc.org/rpm/dvc.repo -O /etc/yum.repos.d/dvc.repo sudo rpm --import https://dvc.org/rpm/iterative.asc sudo yum update sudo yum install dvc

贡献

欢迎贡献！ 有关详细信息，请参阅我们的 贡献指南 <https://dvc.org/doc/user-guide/contributing/core>_。 感谢所有贡献者！

|Contribs|

社区与支持

• Twitter <https://twitter.com/DVCorg>_
• 论坛 <https://discuss.dvc.org/>_
• Discord 聊天 <https://dvc.org/chat>_
• 电子邮件 <mailto:support@dvc.org>_
• 邮件列表 <https://dvc.org/community#subscribe>_

版权

本项目采用 Apache 许可证 2.0 版本进行分发（请参阅项目根目录下的 LICENSE 文件）。

通过向本项目提交拉取请求，即表示您同意将您的贡献以 Apache 许可证 2.0 版本授权给本项目。

引用

|DOI|

Iterative, DVC: 数据版本控制 - 面向数据与模型的 Git (2020) DOI:10.5281/zenodo.012345 <https://doi.org/10.5281/zenodo.3677553>_。

Barrak, A., Eghan, E.E. 和 Adams, B. 关于 ML 管道与源代码的协同进化 - DVC 项目的实证研究 <https://mcis.cs.queensu.ca/publications/2021/saner.pdf>_ ，载于第 28 届 IEEE 国际软件分析、演化与再工程会议论文集，SANER 2021。美国夏威夷。

.. |Banner| image:: https://dvc.org/img/logo-github-readme.png :target: https://dvc.org :alt: DVC 标志

.. |VS Code 扩展概览| image:: https://raw.githubusercontent.com/treeverse/vscode-dvc/main/extension/docs/overview.gif :alt: VS Code 的 DVC 扩展

.. |CI| image:: https://github.com/treeverse/dvc/actions/workflows/tests.yaml/badge.svg :target: https://github.com/treeverse/dvc/actions/workflows/tests.yaml :alt: GHA 测试

.. |Python 版本| image:: https://img.shields.io/pypi/pyversions/dvc :target: https://pypi.org/project/dvc :alt: Python 版本

.. |Coverage| image:: https://codecov.io/gh/treeverse/dvc/branch/main/graph/badge.svg :target: https://codecov.io/gh/treeverse/dvc :alt: Codecov

.. |Snap| image:: https://img.shields.io/badge/snap-install-82BEA0.svg?logo=snapcraft :target: https://snapcraft.io/dvc :alt: Snapcraft

.. |Choco| image:: https://img.shields.io/chocolatey/v/dvc?label=choco :target: https://chocolatey.org/packages/dvc :alt: Chocolatey

.. |Brew| image:: https://img.shields.io/homebrew/v/dvc?label=brew :target: https://formulae.brew.sh/formula/dvc :alt: Homebrew

.. |Conda| image:: https://anaconda.org/conda-forge/dvc/badges/version.svg :target: https://anaconda.org/conda-forge/dvc :alt: Conda-forge

.. |PyPI| image:: https://img.shields.io/pypi/v/dvc.svg?label=pip&logo=PyPI&logoColor=white :target: https://pypi.org/project/dvc :alt: PyPI

.. |PyPI 下载量| image:: https://img.shields.io/pypi/dm/dvc.svg?color=blue&label=下载量&logo=pypi&logoColor=gold :target: https://pypi.org/project/dvc :alt: PyPI 下载量

.. |Packages| image:: https://img.shields.io/badge/deb|pkg|rpm|exe-blue :target: https://dvc.org/doc/install :alt: deb|pkg|rpm|exe

.. |DOI| image:: https://img.shields.io/badge/DOI-10.5281/zenodo.3677553-blue.svg :target: https://doi.org/10.5281/zenodo.3677553 :alt: DOI

.. |流程图| image:: https://dvc.org/img/flow.gif :target: https://dvc.org/img/flow.gif :alt: how_dvc_works

.. |Contribs| image:: https://contrib.rocks/image?repo=treeverse/dvc :target: https://github.com/treeverse/dvc/graphs/contributors :alt: 贡献者

.. |VS Code| image:: https://img.shields.io/visual-studio-marketplace/v/Iterative.dvc?color=blue&label=VSCode&logo=visualstudiocode&logoColor=blue :target: https://marketplace.visualstudio.com/items?itemName=Iterative.dvc :alt: VS Code 扩展

DVC 快速上手指南

DVC (Data Version Control) 是一个命令行工具和 VS Code 扩展，旨在帮助开发者构建可复现的机器学习项目。它让你能够像管理代码一样管理数据和模型，同时利用 Git 进行版本控制。

环境准备

• 操作系统: Linux, macOS, 或 Windows
• 前置依赖:
  • Git: 必须已安装并配置好。
  • Python: 推荐 Python 3.8 及以上版本（如果使用 pip 或 conda 安装）。
• 存储后端 (可选): 如果需要将数据推送到云端，需准备好相应的云存储账号（如 AWS S3, Google Cloud, Azure Blob, OSS 等）或 SSH 服务器。

安装步骤

你可以选择以下任意一种方式安装 DVC。国内用户推荐使用 pip 配合国内镜像源，或使用 conda。

方式一：使用 Pip (推荐)

建议使用国内镜像源（如清华源或阿里源）加速安装。如果你计划使用特定的云存储（如 S3），请安装对应的额外依赖。

# 基础安装
pip install dvc -i https://pypi.tuna.tsinghua.edu.cn/simple

# 如果需要使用 AWS S3，安装带 s3 支持的版本
pip install 'dvc[s3]' -i https://pypi.tuna.tsinghua.edu.cn/simple

# 如果需要所有云存储支持
pip install 'dvc[all]' -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Conda/Mamba

适用于已安装 Anaconda 或 Miniconda 的用户。

# 推荐使用 mamba 以获得更快的解析速度
conda install -c conda-forge mamba
mamba install -c conda-forge dvc

方式三：其他包管理器

• macOS (Homebrew):

  brew install dvc
  

• Windows (Chocolatey):

  choco install dvc
  

• Linux (Snap):

  snap install dvc --classic
  

提示: 安装完成后，运行 dvc --version 验证安装是否成功。

基本使用

以下是一个典型的工作流，展示如何追踪数据、构建流水线、运行实验并共享结果。

1. 初始化与数据追踪

在项目根目录初始化 DVC，并将大数据文件（如图片数据集）纳入版本控制。DVC 会将大文件存储在本地缓存中，并在 Git 中只记录一个轻量级的元数据文件 (.dvc)。

# 初始化 DVC (会在当前目录创建 .dvc 文件夹)
dvc init

# 将代码文件加入 Git
git add train.py params.yaml

# 将数据目录加入 DVC 追踪 (例如 images/ 文件夹)
dvc add images/

# 将生成的 .dvc 文件和 .gitignore 提交到 Git
git add images/.dvc images/.gitignore
git commit -m "Add dataset"

2. 构建数据处理流水线 (Pipeline)

定义数据处理的步骤，连接代码、输入数据和输出结果。当输入发生变化时，DVC 会自动判断需要重新运行哪些步骤。

# 步骤 1: 特征工程 (输入: images/, 输出: features/)
dvc stage add -n featurize -d images/ -o features/ python featurize.py

# 步骤 2: 模型训练 (输入: features/, train.py, 输出: model.p, metrics.json)
dvc stage add -n train -d features/ -d train.py -o model.p -M metrics.json python train.py

3. 运行实验与迭代

修改代码或参数后，运行实验并记录结果。DVC 可以在本地跟踪多次实验，无需额外服务器。

# 运行基准实验
dvc exp run -n exp-baseline

# 修改代码 (例如使用 vi 或编辑器修改 train.py)
vi train.py

# 运行新实验
dvc exp run -n exp-code-change

4. 比较与选择实验

查看不同实验的指标对比，并还原到某个特定的实验状态。

# 展示所有实验及其指标对比
dvc exp show

# 应用某个之前的实验结果到工作区
dvc exp apply exp-baseline

5. 共享代码与数据

将代码推送到 Git 仓库，将大型数据/模型推送到远程存储（如 S3）。

# 配置远程存储 (例如 AWS S3)
dvc remote add myremote -d s3://mybucket/image_cnn

# 推送数据到远程存储
dvc push

# 提交并推送代码到 Git
git add .
git commit -m 'Update model and pipeline'
git push

其他人克隆项目后，只需运行 dvc pull 即可自动下载对应版本的数据和模型，完美复现你的实验环境。