DVC 入门:用途、原理和常用命令

数据集和模型文件不适合进 Git。一份 CSV 几百 MB,模型再大一些,仓库克隆、diff、回滚都会变得很慢。DVC(Data Version Control)把这些大文件留在 Git 外面,只把一个很小的指针交进仓库,并用同一套思路描述训练流水线:代码、参数或数据变了,就只重跑受影响的步骤。
它不替换 Git。Git 继续管代码和指针,DVC 管数据、模型和流水线产物。
用来做什么
日常就这四件事:
- 给数据和模型做版本。每次
dvc add或流水线重跑,都会留下内容哈希,能和某次 Git 提交对上。 - 在机器之间同步这些大文件。本地缓存一份,远端(磁盘、NFS、S3、SSH、WebDAV)再存一份。
- 把「准备数据 → 训练 → 写出指标」写成流水线。依赖没变的步骤不重跑。
- 换一版代码时,把对应的数据和模型一起换回来。
git checkout之后再dvc checkout。
Git LFS 也能把大文件换成指针,存储一般绑在 Git 托管平台上。DVC 的远端可以是你已经在用的对象存储或一台 SSH 机器,并且自带流水线:它知道训练依赖哪份数据、哪个脚本、哪几个参数。
原理
工作区、本地缓存、远端各有一份数据。Git 里只有指针。
flowchart LR workspace["工作区里的数据和模型"] -->|dvc add / dvc repro| cache["本地缓存 .dvc/cache"] cache -->|dvc push| remote["远端"] remote -->|dvc pull| cache cache -->|dvc checkout| workspace meta[".dvc、dvc.yaml、dvc.lock"] -->|git commit| gitrepo["Git 仓库"]
指针文件
dvc add data/raw.csv 做三件事:按文件内容算哈希,把文件放进 .dvc/cache,在旁边写下 data/raw.csv.dvc,并把 data/raw.csv 写进 .gitignore。
指针文件类似这样(哈希和大小由命令生成):
1outs:
2- md5: 22a1a2931c8370d3aeedd7183606fd7f
3 size: 1048576
4 hash: md5
5 path: raw.csv
这个文件通常只有几行,可以提交。别人克隆仓库后看不到 CSV 本身,要执行 dvc pull,DVC 才按哈希去远端把内容取回来。
目录也一样。dvc add data/ 会跟踪整个目录,缓存里除了每个文件,还有一份目录清单。
内容寻址
缓存放在 .dvc/cache,按文件内容的 MD5 存储,而不是按文件名。同一份内容只存一份。文件改了一个字节,哈希就变,缓存里会多一个新对象,旧对象还在,直到你清理。回到旧提交时,只要缓存或远端还留着那个哈希,文件就能恢复。
工作区里的文件经常是缓存的硬链接,并且是只读的,避免改工作区时把缓存里的历史版本一起改掉。要修改已跟踪的数据,先 dvc unprotect,改完再 dvc add。
流水线记的是依赖,不是“再跑一遍全部”
流水线写在 dvc.yaml 里,每一段叫一个 stage,包含:
cmd:实际执行的命令deps:输入,数据文件或代码params:从params.yaml里依赖的参数outs:命令生成的数据或模型,DVC 会缓存metrics:指标文件。加上cache: false时不进缓存,小文件可以直接交给 Git
dvc repro 运行后生成 dvc.lock。锁文件记下这一次每个依赖和产物的哈希,也要提交。下次重跑时,DVC 对比工作区和锁里的哈希:
- 依赖、参数、命令都没变:跳过
- 某一段的输入变了:从那段开始,按依赖图往后跑
- 重跑前会先删除该阶段声明的
outs,再执行cmd。脚本需要自己创建输出目录,也不要往产物文件里追加写
dvc.yaml 描述「要做什么」,dvc.lock 描述「上次做成了什么样」。两者都进 Git。真正的 CSV 和 model.pkl 进缓存和远端。
指标文件如果设了 cache: false,哈希仍然写在 dvc.lock 里,文件本身留在工作区。这样不拉数据也能 dvc metrics diff,比较两次提交的 AUC。
配置放哪
dvc init 会建立 .dvc/。需要提交的是 .dvc/config(远端地址)。密钥写到 .dvc/config.local,这个文件默认被忽略。
一次完整的版本包含四样东西,缺一就对不齐:
| 放在哪 | 内容 |
|---|---|
| Git | 代码、params.yaml、dvc.yaml、dvc.lock、*.dvc、.dvc/config |
.dvc/cache | 数据、模型,按哈希存储 |
| 远端 | 缓存的副本,给别的机器 dvc pull |
.dvc/config.local | 访问远端的密钥,不进 Git |
常用命令
命令和 Git 是平行的:一边提交指针,一边推送数据。
初始化和远端
1dvc init
2
3# 本机或共享盘。-d 设为默认远端
4dvc remote add -d storage /mnt/dvc-storage
5
6# 对象存储。先装对应插件,密钥只写本地配置
7# pip install dvc-s3
8dvc remote add -d storage s3://team-ml/churn/dvc
9dvc remote modify --local storage access_key_id 'AKIA...'
10dvc remote modify --local storage secret_access_key '...'
11
12dvc remote list
13dvc remote default storage
SSH 远端写成 ssh://user@host/data/dvc-cache。团队共用哪一种,就固定哪一种,地址写在 .dvc/config 里提交。
群晖 WebDAV 作为 DVC 存储
家里或办公室已经有群晖时,不必再挂一块共享盘。DSM 自带的 WebDAV Server 就能当 DVC 远端,另一台机器用 dvc pull 把数据和模型拉下来。
群晖上先准备目录和账号:
- 套件中心安装 WebDAV Server。打开后启用 HTTPS,端口保持默认的
5006。只在局域网使用时可以同时开 HTTP5005。 - 控制面板 → 共享文件夹,新建一个只放缓存的文件夹,例如
dvc。编辑该文件夹时关掉回收站,后面清理旧版本才能把磁盘空间还回来。 - 控制面板 → 用户与群组,新建用户
dvc。共享文件夹权限给这个用户读写;用户的应用程序权限里允许 WebDAV Server。
项目里安装 WebDAV 插件,把地址写进仓库,把账号留在本机:
1pip install 'dvc[webdav]'
2
3dvc remote add -d nas-webdav webdavs://192.168.1.20:5006/dvc
4dvc remote modify --local nas-webdav user '你的用户名'
5dvc remote modify --local nas-webdav password '你的密码'
192.168.1.20 换成群晖的局域网地址,dvc 是共享文件夹名。只用 HTTP 时,协议和端口改成 webdav://192.168.1.20:5005/dvc。
DSM 默认证书是自签的。dvc push 报证书错误时,先把校验关掉,局域网里可以先这样用:
1dvc remote modify nas-webdav ssl_verify false
已经给群晖装了自己的证书,或者导出了 CA 时,把 ssl_verify 指到那个 pem 文件,不必关掉校验。
提交进去的是 .dvc/config:
1[core]
2 remote = nas-webdav
3['remote "nas-webdav"']
4 url = webdavs://192.168.1.20:5006/dvc
5 ssl_verify = false
账号在 .dvc/config.local,这个文件已经被忽略:
1['remote "nas-webdav"']
2 user = 你的用户名
3 password = 你的密码
然后和别的远端一样:
1dvc push
2dvc status --cloud
dvc push 列目录失败时,到 WebDAV Server 里打开「启用 Depth Infinity」,再推一次。前面如果用反向代理转到 443,代理上的上传大小要大于单个模型文件,内置的 5006 端口没有这条限制。
跟踪数据
1dvc add data/raw.csv # 生成 .dvc,写入缓存,忽略原文件
2dvc unprotect data/raw.csv # 数据是只读硬链接时,改之前先解锁
3dvc add data/raw.csv # 改完后更新哈希
4dvc commit # 已跟踪文件有改动时,把工作区写回缓存并更新指针
5dvc remove data/raw.csv.dvc # 停止跟踪,并处理对应的忽略规则
dvc add 用来纳入新数据,或更新一份由 .dvc 单独跟踪的文件。流水线产物不要手改,改依赖后用 dvc repro。
同步和切换版本
1dvc status # 工作区相对指针有没有变化
2dvc status --cloud # 本地缓存相对远端缺什么
3dvc push # 缓存 → 远端
4dvc fetch # 远端 → 缓存,不改工作区
5dvc pull # fetch 再 checkout
6dvc checkout # 按当前 Git 提交里的指针,从缓存恢复工作区
切代码和切数据是两条命令:
1git checkout <commit>
2dvc checkout
缓存里没有那个哈希时,dvc checkout 会提示缺失,接着 dvc pull。
流水线
可以手写 dvc.yaml,也可以用 dvc stage add 生成。下面这条和后文示例里的 train 阶段是一回事:
1dvc stage add -n train \
2 -d src/train.py -d data/train.csv -d data/test.csv \
3 -p train \
4 -o models/model.pkl \
5 -M metrics.json \
6 python src/train.py
-M 声明指标文件,默认 cache: false。
1dvc repro # 按依赖图重跑有变化的阶段
2dvc repro train # 只检查 train 及其上游
3dvc repro --dry # 只打印会执行的命令
4dvc dag # 看阶段依赖
5dvc metrics show # 当前指标
6dvc metrics diff HEAD # 工作区和某次提交比指标
7dvc params diff HEAD # 比参数
实验和缓存清理
参数还没想好、不想先提交时,用实验命令。它会记下一次运行,跑完把工作区留在原来的状态:
1dvc exp run -S train.max_depth=6
2dvc exp show
3dvc exp apply <实验名> # 把某次实验的结果拿回工作区,再自己 git commit
本地缓存会随版本变多。dvc gc 不带范围参数时什么都不删。-w 只保留工作区当前这份指针用到的对象,历史提交里的其他版本会从本地缓存去掉:
1dvc gc -w
这些对象如果已经 dvc push 过,以后还能 dvc fetch 回来。--cloud 会按同样的范围删除远端,删掉的历史版本这块远端就没有了,确认不再需要旧数据再使用。
一个常用例子
下面是一份流失预测数据。原始 CSV 用 DVC 跟踪,切分和训练写成两个阶段。换机器时 git clone 加 dvc pull 就能拿到同一份数据和模型。
仓库结构:
1.
2├── data/
3│ └── raw.csv
4├── src/
5│ ├── prepare.py
6│ └── train.py
7├── params.yaml
8├── dvc.yaml
9└── dvc.lock # dvc repro 之后生成
data/raw.csv 要有特征列和 label。下面三行只说明格式,真要跑通训练,两种 label 都得有足够行数,否则切分后某一边会缺类别:
1tenure,monthly_charges,label
23,29.85,0
312,56.95,0
41,89.10,1
params.yaml:
1prepare:
2 test_size: 0.2
3 seed: 7
4train:
5 max_depth: 4
6 seed: 7
src/prepare.py 只读参数和原始数据,写出两份切分结果:
1from pathlib import Path
2
3import pandas as pd
4import yaml
5from sklearn.model_selection import train_test_split
6
7
8def main():
9 with open("params.yaml") as f:
10 params = yaml.safe_load(f)["prepare"]
11 df = pd.read_csv("data/raw.csv")
12 train, test = train_test_split(
13 df,
14 test_size=params["test_size"],
15 random_state=params["seed"],
16 )
17 Path("data").mkdir(exist_ok=True)
18 train.to_csv("data/train.csv", index=False)
19 test.to_csv("data/test.csv", index=False)
20
21
22if __name__ == "__main__":
23 main()
src/train.py 读切分结果,写模型和指标:
1import json
2from pathlib import Path
3
4import joblib
5import pandas as pd
6import yaml
7from sklearn.metrics import roc_auc_score
8from sklearn.tree import DecisionTreeClassifier
9
10
11def main():
12 with open("params.yaml") as f:
13 params = yaml.safe_load(f)["train"]
14 train = pd.read_csv("data/train.csv")
15 test = pd.read_csv("data/test.csv")
16 features = [col for col in train.columns if col != "label"]
17
18 model = DecisionTreeClassifier(
19 max_depth=params["max_depth"],
20 random_state=params["seed"],
21 )
22 model.fit(train[features], train["label"])
23 proba = model.predict_proba(test[features])[:, 1]
24
25 Path("models").mkdir(exist_ok=True)
26 joblib.dump(model, "models/model.pkl")
27 Path("metrics.json").write_text(
28 json.dumps({"roc_auc": float(roc_auc_score(test["label"], proba))}, indent=2)
29 + "\n"
30 )
31
32
33if __name__ == "__main__":
34 main()
dvc.yaml:
1stages:
2 prepare:
3 cmd: python src/prepare.py
4 deps:
5 - src/prepare.py
6 - data/raw.csv
7 params:
8 - prepare
9 outs:
10 - data/train.csv
11 - data/test.csv
12 train:
13 cmd: python src/train.py
14 deps:
15 - src/train.py
16 - data/train.csv
17 - data/test.csv
18 params:
19 - train
20 outs:
21 - models/model.pkl
22 metrics:
23 - metrics.json:
24 cache: false
第一次把数据放进去
1git init
2dvc init
3pip install dvc pandas scikit-learn pyyaml joblib
4
5dvc add data/raw.csv
6git add data/raw.csv.dvc data/.gitignore .dvc
7git commit -m "track raw dataset with dvc"
8
9dvc remote add -d storage /mnt/dvc-storage
10git add .dvc/config
11git commit -m "add dvc remote"
12dvc push
群晖没有挂载成共享盘时,用前面的 WebDAV 远端代替 /mnt/dvc-storage,后面的 git add 和 dvc push 不变。
到这里,Git 里有指针和远端地址,远端里有 CSV 的内容。data/raw.csv 不会出现在 git status 的待提交列表里。
跑通流水线并提交
把上面的脚本、params.yaml、dvc.yaml 放好之后:
1dvc repro
2dvc metrics show
dvc repro 会先跑 prepare,再跑 train,并写下 dvc.lock。data/train.csv、data/test.csv、models/model.pkl 进入缓存;metrics.json 留在工作区。
1git add dvc.yaml dvc.lock params.yaml src metrics.json
2git commit -m "add prepare and train stages"
3dvc push
4git push
git commit 和 dvc push 都要做。只推 Git,别人知道哈希但拉不到文件。只推 DVC,别人看不到该用哪个哈希。
另一台机器
1git clone git@github.com:org/churn.git
2cd churn
3dvc pull # 按锁文件把 raw.csv、切分结果和模型拿回来
4dvc repro # 依赖没变,两个阶段都会跳过
改了参数
把 params.yaml 里的 train.max_depth 从 4 改成 8:
1dvc repro
2dvc metrics diff HEAD
3dvc params diff HEAD
prepare 的依赖没变,会跳过。train 的参数变了,会重跑。确认指标后:
1git add dvc.lock params.yaml metrics.json
2git commit -m "train with max_depth 8"
3dvc push
数据本身更新时,先改 data/raw.csv,再 dvc add data/raw.csv。哈希变了之后 dvc repro 会从 prepare 开始重跑。
想先对比几种深度、暂不提交:
1dvc exp run -S train.max_depth=6
2dvc exp show
看中某一次,再用 dvc exp apply 拿回工作区,按上面的方式提交和 dvc push。
回到上一版
1git checkout HEAD~1
2dvc checkout
代码、参数、dvc.lock 回到上一提交,工作区里的 CSV 和模型也回到当时的哈希。这就是 DVC 和一次 Git 提交绑在一起的用法。
官方命令说明在 DVC Command Reference,流水线字段在 dvc.yaml。先把「指针进 Git、内容进远端、重跑看锁文件」这条路径走通,再加实验和缓存清理。
评论