👌

DVC入門ガイド

2025/12/21に公開

Git

DVC

tech

DVC入門ガイド - バイナリデータ管理

DVCとは

概要

DVC (Data Version Control) は、機械学習プロジェクトのためのバージョン管理ツールです。

主な特徴:

大容量ファイル（データセット、モデル、画像など）をGitのように管理
Gitと連携して動作
AWS S3、Google Drive、Azure Blobなど様々なストレージに対応
データのバージョン管理と再現性を実現

なぜDVCが必要か？

Gitだけでは困る場面:

❌ 大きなデータセット（100MB以上）
❌ 機械学習モデルファイル（数GB）
❌ 画像・動画などのバイナリファイル
❌ 頻繁に更新されるデータ

DVCで解決:

✅ 大容量ファイルを効率的に管理
✅ データのバージョン履歴を追跡
✅ チーム間でデータを共有
✅ ストレージコストを最適化

GitとDVCの役割分担

Git:
├─ コード (.py, .js, .md)
├─ 設定ファイル (.yaml, .json)
└─ DVC管理ファイル (.dvc)

DVC:
├─ データセット (.csv, .parquet)
├─ 機械学習モデル (.pkl, .h5, .pt)
├─ 画像・動画 (.jpg, .mp4)
└─ その他バイナリ (.bin, .dat)

セットアップ

インストール

# pipでインストール
pip install dvc

# 特定のストレージサポートを追加
pip install 'dvc[s3]'      # AWS S3
pip install 'dvc[gs]'      # Google Cloud Storage
pip install 'dvc[azure]'   # Azure Blob Storage
pip install 'dvc[gdrive]'  # Google Drive
pip install 'dvc[all]'     # すべて

# バージョン確認
dvc version

初期化

# Gitリポジトリで初期化（Gitリポジトリが必要）
git init
dvc init

# 何が作成されたか確認
ls -la .dvc/

作成されるファイル:

.dvc/
├── config           # DVC設定ファイル
├── .gitignore       # DVCが自動管理するファイル
└── cache/           # ローカルキャッシュ

.dvcignore           # DVC無視ファイル

自動でGitに追加される:

git status
# .dvc/config
# .dvc/.gitignore
# .dvcignore

基本操作

ファイルをDVCで管理

1. データファイルの追加

# サンプルデータを作成
echo "id,name,age" > data.csv
echo "1,Alice,25" >> data.csv
echo "2,Bob,30" >> data.csv

# DVCで管理
dvc add data.csv

何が起こったか:

作成されたファイル:
1. data.csv.dvc     ← Gitで管理（メタデータ）
2. .gitignore       ← 更新される（data.csvを無視）

data.csv は .dvc/cache/ に移動

data.csv.dvcの中身:

outs:
- md5: a1b2c3d4e5f6...
  size: 45
  path: data.csv

2. Gitにコミット

# .dvcファイルをGitで管理
git add data.csv.dvc .gitignore
git commit -m "Add dataset with DVC"

# 実際のdata.csvはDVCのキャッシュに保存される

データの取得

# DVCで管理されているファイルを取得
dvc pull

# 特定のファイルのみ
dvc pull data.csv.dvc

データの更新

# データを変更
echo "3,Carol,28" >> data.csv

# DVCで再追加
dvc add data.csv

# Gitにコミット
git add data.csv.dvc
git commit -m "Update dataset: add new record"

データの削除

# DVCの管理から外す
dvc remove data.csv.dvc

# ファイルも削除
rm data.csv

# Gitから削除
git rm data.csv.dvc .gitignore
git commit -m "Remove dataset"

リモートストレージ設定

ローカルストレージ（練習用）

# ローカルディレクトリをリモートとして設定
mkdir -p /tmp/dvc-storage

dvc remote add -d myremote /tmp/dvc-storage

# 設定確認
dvc remote list
cat .dvc/config

.dvc/config:

[core]
    remote = myremote
['remote "myremote"']
    url = /tmp/dvc-storage

# リモートにプッシュ
dvc push

# リモートから取得
dvc pull

AWS S3

# S3バケットを設定
dvc remote add -d s3remote s3://my-bucket/dvc-storage

# 認証情報設定（オプション）
dvc remote modify s3remote access_key_id 'YOUR_ACCESS_KEY'
dvc remote modify s3remote secret_access_key 'YOUR_SECRET_KEY'

# または環境変数を使用（推奨）
export AWS_ACCESS_KEY_ID='YOUR_ACCESS_KEY'
export AWS_SECRET_ACCESS_KEY='YOUR_SECRET_KEY'

# プッシュ
dvc push

Google Drive

# Google Driveフォルダを設定
dvc remote add -d gdrive gdrive://folder-id

# 初回はブラウザで認証
dvc push

Azure Blob Storage

# Azureストレージを設定
dvc remote add -d azure azure://mycontainer/path

# 接続文字列を設定
dvc remote modify azure connection_string 'YOUR_CONNECTION_STRING'

# プッシュ
dvc push

Google Cloud Storage

# GCSバケットを設定
dvc remote add -d gcs gs://my-bucket/dvc-storage

# 認証（gcloudコマンドを使用）
gcloud auth application-default login

# プッシュ
dvc push

AIプロジェクトでの活用

機械学習プロジェクトの構成例

ml-project/
├── data/
│   ├── raw/              # 生データ（DVC管理）
│   ├── processed/        # 前処理済み（DVC管理）
│   └── external/         # 外部データ（DVC管理）
├── models/               # 学習済みモデル（DVC管理）
├── notebooks/            # Jupyter notebooks（Git管理）
├── src/                  # ソースコード（Git管理）
│   ├── data/
│   ├── features/
│   ├── models/
│   └── visualization/
├── .dvc/
├── .git/
├── dvc.yaml             # パイプライン定義
└── requirements.txt

データセットの管理

# 大きなデータセットを追加
dvc add data/raw/images.zip
dvc add data/raw/labels.csv

# 前処理済みデータ
dvc add data/processed/train.npz
dvc add data/processed/test.npz

# Gitにコミット
git add data/raw/*.dvc data/processed/*.dvc .gitignore
git commit -m "Add training datasets"

# リモートにプッシュ
dvc push

モデルファイルの管理

# 学習済みモデルを保存
python train.py  # model.h5を生成

# DVCで管理
dvc add models/model.h5

# バージョン情報と共にコミット
git add models/model.h5.dvc
git commit -m "Train model v1.0 - accuracy: 0.95"
git tag -a v1.0 -m "Model version 1.0"

# プッシュ
dvc push
git push --tags

モデルの切り替え

# 古いバージョンに戻る
git checkout v1.0
dvc checkout

# 最新に戻る
git checkout main
dvc checkout

実践的なワークフロー

ワークフロー1: データサイエンティストの日常

シナリオ: 新しいデータセットで実験

# 1. 新しいブランチを作成
git checkout -b experiment/new-dataset

# 2. 新しいデータを取得
wget https://example.com/new_data.csv -O data/raw/new_data.csv

# 3. DVCで管理
dvc add data/raw/new_data.csv
git add data/raw/new_data.csv.dvc .gitignore
git commit -m "Add new experimental dataset"

# 4. データ前処理
python src/data/preprocess.py

# 5. 前処理済みデータも管理
dvc add data/processed/new_data_processed.npz
git add data/processed/new_data_processed.npz.dvc
git commit -m "Add preprocessed data"

# 6. モデル学習
python src/models/train.py

# 7. モデルを管理
dvc add models/experiment_model.h5
git add models/experiment_model.h5.dvc
git commit -m "Train model on new dataset - acc: 0.87"

# 8. 結果が良ければメインにマージ
git checkout main
git merge experiment/new-dataset

# 9. リモートに同期
dvc push
git push

ワークフロー2: チーム開発

メンバーA: データ準備

# データ収集・前処理
dvc add data/raw/dataset_v2.parquet
git add data/raw/dataset_v2.parquet.dvc
git commit -m "Update dataset to v2"
dvc push
git push

メンバーB: データ取得・モデル学習

# 最新のコードとメタデータを取得
git pull

# データを取得
dvc pull

# モデル学習
python train.py

# モデルを共有
dvc add models/model_v2.pkl
git add models/model_v2.pkl.dvc
git commit -m "Train model on dataset v2"
dvc push
git push

ワークフロー3: パイプライン管理

DVCパイプラインを使って、データ処理からモデル学習まで自動化：

# dvc.yaml
stages:
  preprocess:
    cmd: python src/data/preprocess.py
    deps:
      - src/data/preprocess.py
      - data/raw/data.csv
    outs:
      - data/processed/train.npz
      - data/processed/test.npz

  train:
    cmd: python src/models/train.py
    deps:
      - src/models/train.py
      - data/processed/train.npz
    params:
      - train.learning_rate
      - train.epochs
    outs:
      - models/model.h5
    metrics:
      - metrics/train_metrics.json:
          cache: false

  evaluate:
    cmd: python src/models/evaluate.py
    deps:
      - src/models/evaluate.py
      - models/model.h5
      - data/processed/test.npz
    metrics:
      - metrics/eval_metrics.json:
          cache: false

# パイプライン実行
dvc repro

# 特定のステージのみ
dvc repro train

# メトリクスの確認
dvc metrics show

# 変更があった場合のみ再実行される（効率的）
dvc repro

AIエージェントとの協働パターン

パターン1: AIが生成したデータ処理スクリプト

# 1. AIにデータ処理を依頼
# "CSVを前処理してNumPy配列に変換するスクリプトを書いて"

# 2. 生成されたスクリプトを保存
# src/data/ai_preprocess.py

# 3. Gitで管理
git add src/data/ai_preprocess.py
git commit -m "Add AI-generated preprocessing script"

# 4. スクリプト実行
python src/data/ai_preprocess.py

# 5. 出力データをDVCで管理
dvc add data/processed/ai_processed.npy
git add data/processed/ai_processed.npy.dvc
git commit -m "Add AI-preprocessed data"
dvc push

パターン2: モデルの実験管理

# AIに複数のモデルアーキテクチャを試してもらう
git checkout -b experiment/ai-models

# モデル1
# AI生成コード → models/ai_model_v1.py
dvc add models/ai_model_v1.h5
git add models/ai_model_v1.h5.dvc models/ai_model_v1.py
git commit -m "AI model v1 - CNN - acc: 0.85"

# モデル2
# AI生成コード → models/ai_model_v2.py
dvc add models/ai_model_v2.h5
git add models/ai_model_v2.h5.dvc models/ai_model_v2.py
git commit -m "AI model v2 - ResNet - acc: 0.91"

# 最良のモデルをメインにマージ
git checkout main
git merge experiment/ai-models
dvc push

DVCとGitの統合ワークフロー

完全な開発サイクル

# === 準備 ===
# プロジェクト作成
mkdir ml-project && cd ml-project
git init
dvc init
git add .dvc .dvcignore
git commit -m "Initialize DVC"

# リモート設定
dvc remote add -d storage s3://my-bucket/dvc
git add .dvc/config
git commit -m "Configure remote storage"

# === データ追加 ===
# データをダウンロード
wget https://example.com/dataset.zip

# DVCで管理
dvc add dataset.zip
git add dataset.zip.dvc .gitignore
git commit -m "Add dataset"
dvc push

# === 開発 ===
# 機能ブランチ作成
git checkout -b feature/new-model

# コード作成（Git管理）
# ... コーディング ...
git add src/
git commit -m "Add new model architecture"

# データ処理
python src/preprocess.py

# 処理済みデータ（DVC管理）
dvc add data/processed/
git add data/processed.dvc
git commit -m "Add preprocessed data"

# モデル学習
python src/train.py

# モデル（DVC管理）
dvc add models/model.h5
git add models/model.h5.dvc
git commit -m "Train new model - acc: 0.92"

# プッシュ
dvc push
git push origin feature/new-model

# === マージ ===
git checkout main
git merge feature/new-model
dvc push
git push

# === 他のメンバーが取得 ===
git pull
dvc pull

ディレクトリの管理

フォルダ全体をDVCで管理

# 画像フォルダ全体を管理
dvc add data/images/

# 生成されるファイル
# data/images.dvc
# .gitignore（data/imagesが追加される）

# Gitにコミット
git add data/images.dvc .gitignore
git commit -m "Add image dataset (1000 images)"

大量のファイルを効率的に管理

# 構造例
data/
├── train/
│   ├── class_a/  (1000 images)
│   └── class_b/  (1000 images)
└── test/
    ├── class_a/  (200 images)
    └── class_b/  (200 images)

# フォルダごと管理
dvc add data/train
dvc add data/test

# メタデータのみGitで管理
git add data/train.dvc data/test.dvc

メトリクスとパラメータ管理

params.yaml

# params.yaml
model:
  learning_rate: 0.001
  batch_size: 32
  epochs: 100
  
data:
  train_split: 0.8
  validation_split: 0.1
  test_split: 0.1

メトリクスの記録

# train.py
import json

# 学習後
metrics = {
    "accuracy": 0.95,
    "loss": 0.12,
    "val_accuracy": 0.93,
    "val_loss": 0.15
}

with open("metrics/train_metrics.json", "w") as f:
    json.dump(metrics, f)

メトリクスの比較

# 現在のメトリクス
dvc metrics show

# 別のブランチと比較
dvc metrics diff main experiment/new-model

# 履歴を確認
dvc metrics show --all-branches

トラブルシューティング

よくある問題と解決法

問題1: "file is not tracked by DVC"

# 原因: .dvcファイルが存在しない、または同期していない

# 解決:
dvc checkout
# または
dvc pull

問題2: ストレージ容量不足

# キャッシュのクリーンアップ
dvc gc -w  # 作業スペースに無いファイルを削除

# 古いバージョンを削除
dvc gc --all-branches --all-tags

問題3: リモートへの接続エラー

# リモート設定確認
dvc remote list
cat .dvc/config

# 認証情報確認
dvc remote modify myremote --local access_key_id 'KEY'

# 接続テスト
dvc push --remote myremote

問題4: ファイルが重複管理されている

# Git と DVC で重複
# .gitignore を確認
cat .gitignore

# DVCで管理すべきファイルをGitから削除
git rm --cached large_file.bin
dvc add large_file.bin
git add large_file.bin.dvc .gitignore

問題5: マージコンフリクト（.dvcファイル）

# .dvcファイルでコンフリクト発生
git status

# 正しいバージョンを選択
# data.csv.dvc を編集してコンフリクトマーカーを削除

# DVCで再チェックアウト
dvc checkout data.csv.dvc

# マージ完了
git add data.csv.dvc
git commit -m "Resolve DVC conflict"

ベストプラクティス

1. .gitignoreとDVCの使い分け

# .gitignore (Git用)
*.pyc
__pycache__/
.env
.venv/
.DS_Store

# .dvcignore (DVC用)
*.tmp
*.log
.ipynb_checkpoints/

2. 適切なファイルサイズの基準

Git で管理:
- ソースコード
- 設定ファイル
- 小さなデータ（< 10MB）

DVC で管理:
- データセット（> 10MB）
- モデルファイル（> 10MB）
- 画像・動画・音声
- バイナリファイル

3. コミットメッセージの規約

# データの場合
git commit -m "data: Add training dataset v2 (10K samples)"

# モデルの場合  
git commit -m "model: Train ResNet50 - acc: 0.95, loss: 0.12"

# パイプラインの場合
git commit -m "pipeline: Update preprocessing steps"

4. ブランチ戦略

# データ実験
git checkout -b data/experiment-v2
dvc add data/experiment_v2.csv
git add data/experiment_v2.csv.dvc
git commit -m "data: Add experimental dataset v2"

# モデル実験
git checkout -b model/resnet-experiment
dvc add models/resnet_experiment.h5
git add models/resnet_experiment.h5.dvc
git commit -m "model: Train ResNet for experiment"

5. タグ付けでバージョン管理

# マイルストーン
git tag -a v1.0-data -m "Dataset version 1.0"
git tag -a v1.0-model -m "Model version 1.0 - prod ready"

# プロダクション
git tag -a prod-2024-01 -m "Production model January 2024"

# タグをプッシュ
git push --tags

まとめ

DVCを使うべき場面

✅ 使うべき:

機械学習プロジェクト
大容量データの管理
モデルのバージョン管理
データ処理パイプライン
チームでのデータ共有

❌ 不要な場合:

小さなプロジェクト（全て< 10MB）
バイナリファイルがない
1人だけの開発

重要コマンド一覧

# 初期化
dvc init

# ファイル管理
dvc add <file>
dvc push
dvc pull
dvc checkout

# リモート設定
dvc remote add -d <name> <url>
dvc remote list

# パイプライン
dvc repro
dvc dag

# メトリクス
dvc metrics show
dvc metrics diff

# メンテナンス
dvc gc
dvc status

次のステップ

実際のプロジェクトで試す
CML (Continuous Machine Learning) を学ぶ
DVC Studio でビジュアル管理
MLflow などとの連携

参考リンク

公式ドキュメント: https://dvc.org/doc
チュートリアル: https://dvc.org/doc/start
GitHub: https://github.com/iterative/dvc