Capítulo 2: Data Version Control (DVC)

Introdução

O DVC (Data Version Control) expande as capacidades do Git para lidar com arquivos grandes, conjuntos de dados e modelos de machine learning. Ele permite reprodutibilidade ao rastrear dados e modelos junto com o código.

Por que usar DVC?

O Problema de Arquivos Grandes no Git

Benefícios do DVC

Recurso	Benefício
Comandos semelhantes ao Git	Fluxo de trabalho familiar para desenvolvedores
Armazenamento externo	Dados permanecem fora do Git
Deduplicação	Mesmo dado armazenado apenas uma vez
Pipelines	Workflows de ML reprodutíveis
Armazenamento remoto	Suporte a S3, GCS, Azure, SSH

Configurando o DVC

Instalação

# Usando pip
pip install dvc

# Com suporte a armazenamento remoto
pip install "dvc[s3]"     # Amazon S3
pip install "dvc[gs]"     # Google Cloud Storage
pip install "dvc[azure]"  # Azure Blob Storage
pip install "dvc[ssh]"    # SSH remote
pip install "dvc[all]"    # Todos os remotos

# Inicialize o DVC no seu projeto
cd your-project
dvc init
git add .dvc .dvcignore
git commit -m "Initialize DVC"

Estrutura de Diretórios do DVC

Após a inicialização:

your-project/
├── .dvc/
│   ├── config        # Configuração do DVC
│   ├── .gitignore    # Arquivos que o DVC ignora em sua própria pasta
│   └── cache/        # Cache local (ignorado pelo git)
├── .dvcignore        # Arquivos que o DVC deve ignorar
└── ...

Rastreando Dados com DVC

Rastreando Dados Básicos

# Adicione um arquivo de dados ao rastreamento do DVC
dvc add data/training_data.csv

# Isso cria:
# - data/training_data.csv.dvc (arquivo de metadados)
# - data/.gitignore (impede o git de rastrear o arquivo real)

# Adicione os arquivos do DVC ao git
git add data/training_data.csv.dvc data/.gitignore
git commit -m "data: track training data with DVC"

Entendendo os Arquivos .dvc

# data/training_data.csv.dvc
outs:
- md5: a3f2b1c4d5e6f7g8h9i0j1k2
  size: 1073741824
  path: training_data.csv

O arquivo .dvc contém:

• md5: Hash do conteúdo do arquivo
• size: Tamanho do arquivo em bytes
• path: Caminho relativo para o arquivo

Rastreando Diretórios

# Rastreie diretórios inteiros
dvc add data/images/

# Cria data/images.dvc
git add data/images.dvc data/.gitignore
git commit -m "data: add image dataset"

Configurando Armazenamento Remoto

Configurando Remoto S3

# Adicione remoto S3
dvc remote add -d myremote s3://mybucket/dvc-storage

# Configure as credenciais (ou use IAM roles)
dvc remote modify myremote access_key_id 'YOUR_ACCESS_KEY'
dvc remote modify myremote secret_access_key 'YOUR_SECRET_KEY'

# Ou use perfil AWS
dvc remote modify myremote profile myprofile

# Habilite cache para operações mais rápidas
dvc remote modify myremote cache true

Configurando Remoto GCS

# Adicione remoto Google Cloud Storage
dvc remote add -d myremote gs://mybucket/dvc-storage

# Autentique usando conta de serviço
dvc remote modify myremote credentialpath /path/to/credentials.json

Configurando Remoto Azure Blob

# Adicione remoto Azure Blob Storage
dvc remote add -d myremote azure://mycontainer/dvc-storage

# Configure a conta
dvc remote modify myremote account_name 'myaccount'
dvc remote modify myremote account_key 'mykey'

Remoto Local (para desenvolvimento)

# Use diretório local como remoto (útil para desenvolvimento)
dvc remote add -d local /shared/dvc-storage

# Ou unidade de rede
dvc remote add -d network //server/dvc-storage

Enviando e Baixando Dados

Enviar Dados para o Remoto

# Envie todos os dados rastreados para o remoto padrão
dvc push

# Envie arquivo específico
dvc push data/training_data.csv.dvc

# Envie para remoto específico
dvc push -r myremote

Baixar Dados do Remoto

# Baixe todos os dados do remoto padrão
dvc pull

# Baixe arquivo específico
dvc pull data/training_data.csv.dvc

# Baixe de remoto específico
dvc pull -r myremote

Fazer Checkout de Versão Específica

# Troque para outro commit/branch do git
git checkout v1.0.0

# Faça checkout da versão correspondente dos dados
dvc checkout

Pipelines no DVC

Por que Pipelines?

Pipelines definem a sequência de etapas de processamento de dados, tornando experimentos reprodutíveis.

Definindo Pipelines

# dvc.yaml
stages:
  prepare:
    cmd: python src/data/prepare.py
    deps:
      - src/data/prepare.py
      - data/raw/
    params:
      - prepare.seed
      - prepare.split_ratio
    outs:
      - data/processed/train.csv
      - data/processed/test.csv

  featurize:
    cmd: python src/features/featurize.py
    deps:
      - src/features/featurize.py
      - data/processed/train.csv
      - data/processed/test.csv
    params:
      - featurize.max_features
    outs:
      - data/features/train_features.pkl
      - data/features/test_features.pkl

  train:
    cmd: python src/models/train.py
    deps:
      - src/models/train.py
      - data/features/train_features.pkl
    params:
      - train.n_estimators
      - train.max_depth
      - train.learning_rate
    outs:
      - models/model.pkl
    metrics:
      - metrics/train_metrics.json:
          cache: false

  evaluate:
    cmd: python src/models/evaluate.py
    deps:
      - src/models/evaluate.py
      - models/model.pkl
      - data/features/test_features.pkl
    metrics:
      - metrics/eval_metrics.json:
          cache: false
    plots:
      - metrics/plots/:
          cache: false

Arquivo de Parâmetros

# params.yaml
prepare:
  seed: 42
  split_ratio: 0.2

featurize:
  max_features: 1000

train:
  n_estimators: 100
  max_depth: 10
  learning_rate: 0.1

Executando Pipelines

# Execute todo o pipeline
dvc repro

# Execute estágio específico
dvc repro train

# Forçar execução (ignora cache)
dvc repro -f

# Visualize o pipeline
dvc dag

Visualização do Pipeline

$ dvc dag
         +----------+
         | prepare  |
         +----------+
              *
              *
              *
        +-----------+
        | featurize |
        +-----------+
              *
              *
              *
         +---------+
         |  train  |
         +---------+
              *
              *
              *
        +----------+
        | evaluate |
        +----------+

Experimentos com DVC

Executando Experimentos

# Execute experimento com parâmetros modificados
dvc exp run --set-param train.n_estimators=200

# Execute múltiplos experimentos em fila
dvc exp run --queue --set-param train.n_estimators=100
dvc exp run --queue --set-param train.n_estimators=200
dvc exp run --queue --set-param train.n_estimators=300

# Execute experimentos em fila
dvc exp run --run-all

# Liste experimentos
dvc exp show

Comparando Experimentos

# Mostre experimentos com métricas
dvc exp show --md

# Compare experimentos específicos
dvc exp diff exp-abc123 exp-def456

Gerenciando Experimentos

# Aplique experimento ao workspace
dvc exp apply exp-abc123

# Crie branch a partir do experimento
dvc exp branch exp-abc123 feature/best-model

# Remova experimentos
dvc exp remove exp-abc123

Métricas e Plots no DVC

Definindo Métricas

# src/models/train.py
import json

metrics = {
    "accuracy": 0.92,
    "f1_score": 0.89,
    "auc_roc": 0.95
}

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

Visualizando Métricas

# Mostre métricas
dvc metrics show

# Compare métricas entre commits
dvc metrics diff HEAD~1

Criando Plots

# src/models/evaluate.py
import json

# Dados da curva ROC
roc_data = [
    {"fpr": 0.0, "tpr": 0.0},
    {"fpr": 0.1, "tpr": 0.6},
    {"fpr": 0.2, "tpr": 0.8},
    {"fpr": 1.0, "tpr": 1.0}
]

with open("metrics/plots/roc.json", "w") as f:
    json.dump(roc_data, f)

# Gere plots
dvc plots show

# Compare plots entre experimentos
dvc plots diff exp-abc123 exp-def456

Boas Práticas

1. Organize os Diretórios de Dados

data/
├── raw/           # Dados originais, imutáveis
├── interim/       # Transformações intermediárias
├── processed/     # Dados finais e limpos para modelagem
└── external/      # Dados de fontes externas

2. Use Nomes Significativos para Arquivos .dvc

# Bom: nomes descritivos
dvc add data/customer_transactions_2024.parquet

# Evite: nomes genéricos
dvc add data/data.csv

3. Versione Dados com Metadados

# Marque versões de dados com git
git tag -a "data-v1.0.0" -m "Initial training dataset"
git push origin data-v1.0.0

4. Documente as Fontes de Dados

# data/README.md ou data/sources.yaml
sources:
  customer_transactions:
    description: "Histórico de transações de clientes"
    source: "Banco de dados PostgreSQL de produção"
    refresh_frequency: "diário"
    columns:
      - name: transaction_id
        type: string
        description: "Identificador único da transação"
      - name: amount
        type: float
        description: "Valor da transação em USD"

5. Automatize Operações do DVC

# .github/workflows/dvc.yml
name: DVC Pipeline
on:
  push:
    branches: [main]

jobs:
  dvc-pipeline:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: iterative/setup-dvc@v1
      
      - name: Configure DVC remote
        run: |
          dvc remote modify --local myremote access_key_id ${{ secrets.AWS_ACCESS_KEY }}
          dvc remote modify --local myremote secret_access_key ${{ secrets.AWS_SECRET_KEY }}
      
      - name: Pull data
        run: dvc pull
      
      - name: Run pipeline
        run: dvc repro
      
      - name: Push results
        run: dvc push

Solução de Problemas

Problemas Comuns

# Erro: "Unable to acquire lock"
rm .dvc/lock

# Erro: "Checkout failed"
dvc checkout -f

# Erro: "Push failed" (arquivos grandes)
dvc push --jobs 4  # Uploads em paralelo

# Verifique o status do cache
dvc cache dir

# Limpe cache não utilizado
dvc gc -w

Principais Pontos

Summary

1. DVC expande o Git para arquivos grandes sem inchar o repositório
2. Use armazenamento remoto para colaboração em equipe (S3, GCS, Azure)
3. Defina pipelines para workflows de ML reprodutíveis
4. Rastreie experimentos com comandos DVC exp
5. Versione dados junto com o código para reprodutibilidade total
6. Automatize operações do DVC em pipelines CI/CD

Exercício Prático

1. Inicialize o DVC em um novo projeto
2. Configure armazenamento remoto S3 ou local
3. Rastreie um dataset com DVC
4. Crie um pipeline simples de 3 estágios
5. Execute experimentos com diferentes parâmetros

---

Próximo: Capítulo 3: Versionamento de Modelos