工作原理

目录结构

DVCLive 会将记录的数据存储在传递给 Live() 的目录（dir）中。若未提供，则默认使用 dvclive。

目录内容取决于所使用的方法：

方法	写入位置
`Live.log_artifact()`	`{path}.dvc` 或 `dvclive/artifacts/{path}` `dvclive/artifacts/{path}.dvc`
`Live.log_metric()`	`dvclive/plots/metrics`
`Live.monitor_system()`	`dvclive/plots/metrics/system`
`Live.log_image()`	`dvclive/plots/images`
`Live.log_param()`	`dvclive/params.yaml`
`Live.log_plot()`	`dvclive/plots/custom`
`Live.log_sklearn_plot()`	`dvclive/plots/sklearn`
`Live.make_dvcyaml()`	`dvc.yaml`
`Live.make_report()`	`dvclive/report.{md/html}`
`Live.make_summary()`	`dvclive/metrics.json`
`Live.next_step()`	`dvc.yaml` `dvclive/metrics.json` `dvclive/report.{md/html}`
`Live.end()`	`dvc.yaml` `dvclive/metrics.json` `dvclive/report.{md/html}`

示例

以以下代码为例：

import random
from pathlib import Path

from dvclive import Live
from PIL import Image

EPOCHS = 2

with Live(report="notebook") as live:
    live.log_param("epochs", EPOCHS)

    for i in range(EPOCHS):
        live.log_metric("metric", i + random.random())
        live.log_metric("nested/metric", i + random.random())
        live.log_image(f"img/{live.step}.png", Image.new("RGB", (50, 50), (i, i, i)))
        Path("model.pt").write_text(str(random.random()))
        live.next_step()

    live.log_artifact("model.pt", type="model", name="mymodel")
    live.log_sklearn_plot("confusion_matrix", [0, 0, 1, 1], [0, 1, 0, 1])
    live.log_metric("summary_metric", 1.0, plot=False)
# live.end() has been called at this point

生成的目录结构如下：

dvc.yaml
dvclive
├── metrics.json
├── params.yaml
├── plots
│   ├── images
│   │   └── img
│   │       ├── 0.png
│   │       └── 1.png
│   ├── metrics
│   │   ├── metric.tsv
│   │   └── nested
│   │       └── metric.tsv
│   └── sklearn
│       └── confusion_matrix.json
└── report.md
model.pt
model.pt.dvc

Git 与 DVC 集成

DVCLive 与其他实验追踪工具不同，它依赖 Git 和 DVC 进行追踪，而非中央数据库。这使其与代码更紧密关联，但若你来自其他实验追踪工具，可能需要重新学习一些概念。

Git 集成

DVCLive 依赖 Git 来追踪其生成的目录，因此每次运行都会保存到同一路径并覆盖先前结果。DVCLive 使用 Git 管理结果、代码变更和数据变更（配合 DVC）。

默认情况下，DVCLive 会保存一个 DVC 实验，因此你无需手动为每个实验创建 Git 提交或分支。你可以使用 dvc exp 命令或 Git 来恢复这些实验。

使用 DVC 跟踪大型工件

模型和数据通常体积庞大，难以通过 Git 跟踪。Live.log_artifact("model.pt") 会使用 DVC 缓存 model.pt 文件，并让 Git 忽略该文件。它会生成一个 model.pt.dvc 元数据文件，该文件可被 Git 跟踪并成为实验的一部分。通过此元数据文件，你可以从 Git 提交中检索版本化的工件。你还可以使用 Live.log_artifact("model.pt", type="model") 将其添加到模型注册表。

使用 Live.log_image() 记录多张图像也可能导致数据过大而无法由 Git 跟踪，此时你可以使用 Live(cache_images=True) 来缓存这些图像。

配置以使用 DVC 运行

使用 DVC 运行实验可提供结构化且可复现的端到端模型训练流水线。要使用 DVC 运行实验，请使用 dvc stage add 或编辑 dvc.yaml 来定义流水线。一个模型训练的流水线阶段可能如下所示：

CLI

$ dvc stage add --name train \
  --deps data_dir --deps src/train.py \
  --outs model.pt --outs dvclive \
  python train.py

YAML

stages:
  train:
    cmd: python train.py
    deps:
      - train.py
      - data_dir
    outs:
      - model.pt
      - dvclive

将 DVCLive 目录添加到输出中，会将其加入 DVC 缓存（若你之前已在 Git 中跟踪该目录，则必须先停止在 Git 中的跟踪）。若希望保留其在 Git 中，可禁用缓存。你也可以选择仅缓存部分路径，例如将轻量级指标保留在 Git 中，而将更重的绘图数据加入缓存：

CLI

$ dvc stage add --name train \
  --deps data_dir --deps src/train.py \
  --outs model.pt --outs-no-cache dvclive/metrics.json \
  --outs dvclive/plots \
  python train.py

YAML

stages:
  train:
    cmd: python train.py
    deps:
      - train.py
      - data_dir
    outs:
      - model.pt
      - dvclive/metrics.json:
          cache: false
      - dvclive/plots

现在你可以使用 dvc exp run 运行实验。与 DVCLive 负责缓存和保存实验不同，DVC 会在每次运行结束时自动处理这些任务。请参阅如何将 DVCLive 添加到管道或将管道添加到 DVCLive 代码的示例，包括如何参数化你的代码以迭代实验。

你可能曾使用 Live.log_artifact() 跟踪输出，并生成了类似 model.pt.dvc 的 .dvc 文件。由于 model.pt.dvc 已经跟踪了 model.pt，DVC 不允许你再将其作为管道的输出添加。你必须先 dvc remove model.pt.dvc，然后才能将其添加到管道中。你也可以选择从代码中移除 Live.log_artifact()。