Usando o DVC para versionamento de arquivos em projetos

Com a crescente complexidade dos projetos de dados envolvendo múltiplos datasets, o versionamento dos dados usados (e gerados) se torna fundamental para manter a reprodutibilidade e a transparência dos resultados. O Data Version Control (DVC) é uma ferramenta para gerenciar e versionar datasets, permitindo que analistas e cientistas de dados acompanhem as mudanças nos dados de maneira similar ao versionamento de código. Além disso, o DVC se integra com sistemas de controle de versão como o Git e editores como o VS Code.

A seguir, veremos o processo de instalação e um exemplo de uso prático.

Instalação do DVC

O DVC é escrito em Python. Para evitar conflitos com outras bibliotecas do seu sistema, é recomendado instalá-lo usando o pipx.

O pipx permite que aplicações Python sejam executadas em ambientes isolados. A instalação é feita com os comandos:

No Ubuntu;

sudo apt update
sudo apt install pipx
pipx ensurepath

No Windows.

python3 -m pip install --user pipx

Com isso, o DVC pode ser instalado executando o comando:

pipx install dvc[all]

Obs: o trecho "[all]" permite configurar todos os armazenamentos remotos compatíveis com o DVC, como Amazon S3, Azure Blob Storage, Google Cloud, entre outros.

Para verificar se o DVC foi instalado corretamente, execute o comando dvc version.

Verificação da versão instalada do DVC. — Verificação da versão instalada do DVC

Configuração do Google Cloud como repositório remoto

Como usarei o Google Cloud para salvar as versões dos dados do projeto de exemplo, é necessário instalar alguns pacotes adicionais, pré-requisitos para o Google Cloud CLI:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates gnupg curl

Para seguir com a instalação do CLI, execute os seguintes comandos na sequência:

Importar a chave pública do Google Cloud;

curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg

Adicionar URL do gcloud CLI como fonte de instalação de pacotes;

echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

Instalar o gcloud CLI.

sudo apt-get update && sudo apt-get install google-cloud-cli

Com o CLI instalado, você deve executar gcloud init para escolher o login e projeto da sua conta Google Cloud.

Essas instalações adicionais foram necessárias porque o Google Cloud Storage foi escolhido como armazenamento remoto. Para usar outra opção, consulte a compatibilidade em DVC Remote Storage.

Configuração e uso do DVC

Para exemplificar, mostrarei como configurar o DVC com o Google Cloud Storage em um projeto fictício onde um notebook gera um arquivo .csv com dados numéricos aleatórios em 1000 linhas e 2 colunas:

├── .git/
├── .gitignore
├── .venv/
├── dados/
│   └── dados-aleatorios.csv
└── notebook/
    └── gera-dados.ipynb

O primeiro arquivo .csv gerado tem as seguintes 5 primeiras linhas:

Primeiras 5 linhas da primeira versão do arquivo .csv

O primeiro passo é ter o Git inicializado e vinculado ao repositório remoto. Depois, inicialize o DVC no mesmo repositório navegando até a pasta pelo terminal e executando dvc init.

Após a execução do comando, são gerados os arquivos ".dvcignore" e "dvc/config" e o arquivo ".gitignore" é alterado para incluir alguns arquivos temporários do próprio DVC.

Lista de arquivos criados e modificados ao inicializar o DVC no repositório

Após incluir esses arquivos no versionamento do Git e fazer o commit, você pode usar o comando dvc add dados/ para incluir a pasta com o arquivo .csv no versionamento do DVC.

Status de início de versionamento da pasta dados

Agora é hora de definir em qual bucket e pasta do Google Cloud os arquivos serão versionados. No meu caso, criei a pasta "dvc-tutorial" dentro do bucket "dvc-files". O comando para adicionar a pasta como repositório remoto é dvc remote add --default [nome do repositorio] gs://[nome do bucket]/[nome da pasta].

Adição da pasta no Google Cloud Storage como armazenamento remoto

Para autorizar o DVC a criar e excluir arquivos na sua conta, execute o comando gcloud auth application-default login.

Após a execução do comando, uma aba do navegador é aberta para inserir login e senha. Com isso, uma chave de acesso é salva no computador, permitindo que outros aplicativos interajam com os recursos do Google Cloud.

Agora, use o comando dvc push para sincronizar a pasta de dados com o repositório remoto.

Upload dos arquivos versionados para o armazenamento remoto

Um detalhe importante é que os dados que você versionar não são salvos no repositório remoto em seu formato e extensão originais. Executando o comando gsutil ls gs://[nome do bucket]/[nome da pasta]/** é possível ver que foram gerados dois arquivos para o meu csv:

Listagem de arquivos no bucket do Google Cloud

O versionamento dos arquivos é feito agora pelo arquivo com extensão ".dvc" recém criado na sua pasta de projeto, no meu caso "dados.dvc". Ele contém o hash MD5 do estado atual dos seus arquivos e deve ser incluído no GitHub juntamente com o arquivo ".gitignore" que foi alterado para não subir os dados da minha pasta "dados" diretamente no Git.

Lista de arquivos criados e modificados ao enviar os arquivos para o armazenamento remoto

Agora vou gerar um novo DataFrame na mesma estrutura mas com outros dados aleatórios e substituir o meu arquivo .csv.

Primeiras 5 linhas da segunda versão do arquivo .csv

Feito isso, com o comando dvc diff o DVC já identifica que houve mudanças na pasta dos dados.

Listagem dos arquivos e pastas modificados que foram identificados pelo DVC

O processo para salvar o estado atual dele é o mesmo para a primeira versão:

dvc add dados/ para adicionar ele;
dvc push para subir os arquivos para o bucket no Google Cloud;
Subir no GitHub o arquivo "dados.dvc"

Suponha que você tenha gerado dados de resposta de um modelo várias vezes e precise restaurar uma versão anterior de um arquivo já substituído.

O primeiro passo é identificar o hash do commit em que o arquivo .dvc foi enviado ao GitHub (daí a importância de commits bem descritivos). Para listar os últimos 2 commits, use git log -2 --format=oneline.

Listagem dos últimos dois commits feitos

Agora, restaure o arquivo "dados.dvc" da pasta raiz do projeto usando git checkout 196adf – dados.dvc (não é necessário usar o hash completo; os 6 primeiros caracteres são suficientes).

Com o arquivo "dados.dvc" apontando para a versão desejada, basta executar dvc pull para baixar o arquivo .csv do Google Cloud.

Status do download da primeira versão do arquivo csv que estava no armazenamento remoto

Por fim, vamos carregar novamente o arquivo .csv em um DataFrame do Pandas:

Carregamento do arquivo csv em um DataFrame do Pandas no Python

Aqui é possível ver que os dados são os mesmos da primeira versão gerada, mesmo o arquivo tendo sido sobrescrito.

Com todos os programas instalados, o uso do DVC é relativamente simples. Os comandos são semelhantes aos do Git e você tem a flexibilidade de versionar apenas os dados importantes do projeto, sem precisar recorrer a sufixos como "_v1", "_v2" nos nomes dos arquivos.

O fluxo para se usar o DVC pode ser resumido com os passos ilustrados na imagem a seguir:

Para mais detalhes, consulte a documentação oficial em DVC Documentation.