Como configurar a monitorização com Weights & Biases (passo a passo)
Se você está gerenciando experiências de aprendizado de máquina e ainda registra tudo em planilhas ou arquivos de texto espalhados, está perdendo algo sério—configurar a monitorização do weights & biases vai te economizar dezenas de horas difíceis e noites sem dormir lutando com dados experimentais desorganizados.
O que você vai construir e por que isso é importante
Estamos configurando a monitorização do weights & biases para acompanhar, visualizar e depurar as sessões de treinamento de aprendizado de máquina de forma eficiente—sem métricas perdidas ou suposições sobre os hiperparâmetros que fizeram seu modelo falhar.
Pré-requisitos
- Python 3.8+ (Weights & Biases é bastante tolerante, mas mantenha-se na versão 3.8 ou posterior para compatibilidade)
- pip instalado, de preferência versão 23.0+ (as atualizações frequentemente corrigem bugs relacionados a dependências de pacotes)
- Crie uma conta gratuita no Weights & Biases em https://wandb.ai
- Conhecimento básico sobre scripts de treinamento em aprendizado de máquina (TensorFlow, PyTorch ou sklearn funcionam)
- Conhecimento das ferramentas de linha de comando (o CLI do weights & biases é essencial)
Configuração passo a passo
Passo 1: Instalar o pacote Python Weights & Biases
pip install wandbEste é o único pacote que você precisa para monitorar suas sessões de aprendizado de máquina. Ele se integra ao seu código e oferece painéis ao vivo, acompanhamento de métricas e gerenciamento de artefatos.
Por quê? Porque o cliente do wandb cuida de tudo relacionado ao upload, sincronização e vinculação ao servidor automaticamente. Isso evita a dor de cabeça de registro manual.
Armadilhas comuns: Se você receber um conflito de versão ou um problema de dependência falhada, atualize o pip e o setuptools:
pip install --upgrade pip setuptoolsPasso 2: Faça login na sua conta Wandb
wandb loginEste comando pedirá sua chave API. Vá até as configurações da sua conta em https://wandb.ai/settings e copie sua chave API. Cole-a quando o CLI solicitar.
Por quê? Você precisa autenticar sua ferramenta CLI com seu projeto na nuvem para que suas sessões sejam vinculadas à sua conta de usuário e projetos.
Atenção: Se você acidentalmente colar espaços em branco ou pressionar Enter muito cedo, o wandb rejeitará sua chave e exibirá um erro críptico sobre a falha na autenticação.
Passo 3: Inicializar Wandb no seu script de treinamento
import wandb
# Começar uma nova sessão
wandb.init(project="my-ml-project", entity="your-username")
# Exemplo: registrar os hiperparâmetros
config = wandb.config
config.learning_rate = 0.001
config.batch_size = 32
Inserir este fragmento no início do seu loop principal de treinamento permite que o wandb capture tudo que acontece nesta sessão.
Por quê? A etapa de inicialização cria um novo objeto de sessão no lado do servidor, permitindo registrar métricas e artefatos em tempo real. Sem isso, você não verá dados em seu espaço de trabalho.
Erro comum: Se você esquecer de chamar wandb.init(), suas chamadas para wandb.log() não farão nada e isso pode falhar silenciosamente. Sempre verifique isso.
Passo 4: Registrar métricas e hiperparâmetros durante o treinamento
for epoch in range(num_epochs):
# Treine seu modelo aqui
train_loss = compute_train_loss()
val_loss = compute_val_loss()
# Registrar métricas no wandb
wandb.log({
"epoch": epoch,
"train_loss": train_loss,
"val_loss": val_loss
})
Este fragmento deve estar dentro do seu loop principal de treinamento. wandb.log() envia os dados para o servidor de forma assíncrona.
Por quê? O registro permite acompanhar o desempenho do modelo passo a passo. Você pode identificar overfitting ou platôs e ajustar os hiperparâmetros de acordo.
Erro típico: Não enviar os logs com frequência suficiente, resultando em dados de sessão incompletos se sua tarefa falhar. Certifique-se de que wandb.log() seja chamado após cada atualização significativa (geralmente após cada época ou lote).
Passo 5: Registrar artefatos dos modelos para controle de versão
# Registrar o checkpoint do seu modelo localmente
torch.save(model.state_dict(), "model.pt")
# Fazer upload do checkpoint como um artefato no wandb
artifact = wandb.Artifact('model', type='model')
artifact.add_file("model.pt")
wandb.log_artifact(artifact)
Os artefatos wandb permitem que você acompanhe as versões dos modelos, conjuntos de dados ou outros resultados. Isso torna seu treinamento reproduzível e depurável.
Por quê? Os artefatos facilitam os fluxos de trabalho colaborativos e a integração com integração contínua/entrega contínua. Você pode comparar modelos e até voltar para checkpoints anteriores facilmente.
Atenção: Esquecer de chamar wandb.log_artifact() significa que seus arquivos registrados não aparecerão no painel do projeto. Além disso, artefatos grandes podem falhar silenciosamente se os limites de armazenamento forem atingidos—verifique os limites de uso do seu projeto.
Passo 6: Visualizar os resultados no painel Wandb
Abra https://wandb.ai e navegue até o seu projeto. Você verá gráficos ao vivo sendo atualizados com suas métricas, hiperparâmetros e artefatos registrados.
Por quê? A visualização é a funcionalidade chave que torna a configuração da monitorização através do weights & biases realmente valiosa—ver as tendências das suas métricas ajuda a entender o comportamento do modelo em tempo real.
Aviso: Se suas métricas não estiverem aparecendo, verifique se seu wandb.init() tem o nome de projeto correto e se você está conectado à conta correta (entidade). Verifique também se sua conexão de rede permite conexões na nuvem (às vezes, firewalls de empresas bloqueiam isso).
Passo 7: Integração avançada – Automação das execuções do Wandb com CI/CD
# Extrato de um workflow GitHub Actions
name: Executar o treinamento e registrar no W&B
on: [push]
jobs:
train:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Configurar Python
uses: actions/setup-python@v2
with:
python-version: 3.9
- name: Instalar dependências
run: pip install wandb torch
- name: Conectar ao Wandb
run: echo ${{ secrets.WANDB_API_KEY }} | wandb login
- name: Executar o script de treinamento
run: python train.py
Este script mostra um fluxo de trabalho CI automatizado com o GitHub executando seu treinamento e enviando os resultados para o wandb automaticamente.
Por quê? As equipes de nível produção precisam de monitorização que se integre aos pipelines — as execuções manuais são tediosas e sujeitas a erros.
Problemas potenciais: Você deve manter sua chave API Wandb em segurança como uma variável de ambiente secreta (nunca a comprometer). Esquecer isso significa que as tarefas CI falham silenciosamente na autenticação.
As armadilhas que ninguém te conta
- Quotas e limites: Seu nível gratuito do Wandb permite registrar cerca de alguns milhares de sessões por mês antes de atingir os limites de largura de banda ou armazenamento de artefatos. Se você rodar 10K+ épocas ou grandes conjuntos de dados, espere uma redução de taxa. Você não receberá avisos explícitos imediatamente; apenas verifique seu quota de projeto.
Solução: Limpe regularmente as sessões antigas e archive os grandes artefatos fora.
- Latência entre o registro e a atualização do painel: Wandb faz o upload de forma assíncrona, então às vezes suas últimas métricas aparecem alguns segundos atrasadas, o que é frustrante se você estiver depurando em um nível de granularidade de lote.
Solução: Adicione `wandb.log(…, commit=True)` para enviar dados em pontos críticos.
- Inconsistências do ambiente: Wandb monitora as versões dos pacotes do seu ambiente Python. Se seu código estiver sendo executado em um ambiente Docker ou remoto sem listas de pacotes exatas (requirements.txt), sua experiência pode não ser reprodutível apesar das métricas registradas.
Solução: Sempre fixe e registre as versões dos pacotes. - Problemas de rede em ambientes restritos: Servidores empresariais e acadêmicos frequentemente bloqueiam por padrão os uploads de telemetria do Wandb, causando falhas silenciosas ou suspensões indefinidas.
Solução: Utilize o modo offline local (`wandb.init(mode=”offline”`) e sincronize depois, ou adicione domínios à lista branca nos firewalls. - Registro de dados excessivos: Registrar cada métrica de lote pode inflar suas sessões e desacelerar sua interface de usuário. Utilize estatísticas de resumo ou amostre em intervalos.
Solução: Registre no nível da época ou a cada N lotes, não cada lote.
Exemplo completo de código funcional
import wandb
import torch
import torch.nn as nn
import torch.optim as optim
from torch.utils.data import DataLoader, TensorDataset
# Conjunto de dados fictício
X = torch.randn(100, 10)
y = torch.randint(0, 2, (100,))
dataset = TensorDataset(X, y)
loader = DataLoader(dataset, batch_size=16, shuffle=True)
# Classificador binário simples
class SimpleModel(nn.Module):
def __init__(self):
super().__init__()
self.fc = nn.Linear(10, 2)
def forward(self, x):
return self.fc(x)
model = SimpleModel()
criterion = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters(), lr=0.001)
# Inicializar a execução do wandb
wandb.init(project="my-ml-project", entity="your-username")
wandb.config.update({
"epochs": 5,
"batch_size": 16,
"learning_rate": 0.001,
})
for epoch in range(wandb.config.epochs):
running_loss = 0.0
for inputs, labels in loader:
optimizer.zero_grad()
outputs = model(inputs)
loss = criterion(outputs, labels)
loss.backward()
optimizer.step()
running_loss += loss.item()
avg_loss = running_loss / len(loader)
print(f"Época {epoch+1}, Perda: {avg_loss:.4f}")
wandb.log({"epoch": epoch + 1, "loss": avg_loss})
# Salvar e enviar o artefato do modelo
torch.save(model.state_dict(), "model.pt")
artifact = wandb.Artifact('simple-model', type='model')
artifact.add_file("model.pt")
wandb.log_artifact(artifact)
wandb.finish()
O que fazer em seguida
Uma vez que você tenha configurado seus pesos & viés para monitorar e registrar com eficácia, recomendo adicionar wandb Sweeps para automatizar o ajuste de hiperparâmetros. É muito melhor do que reiniciar manualmente scripts para cada combinação de parâmetros e isso permite que você se concentre nos resultados em vez de experiências delicadas.
FAQ
P: Posso usar weights & biases com outros frameworks que não sejam PyTorch?
R: Absolutamente. Wandb suporta TensorFlow, Keras, Hugging Face Transformers, sklearn, você escolhe. Isso basicamente envolve seu loop de treinamento e registra os dados. Você só precisa inserir chamadas semelhantes a wandb.init() e wandb.log() nos lugares certos.
P: Como proteger credenciais sensíveis ao usar wandb em pipelines CI?
R: Mantenha sua chave API Wandb no sistema de gerenciamento de segredos do seu provedor CI (por exemplo, GitHub Secrets, variáveis CI GitLab). Nunca codifique chaves no código-fonte. Em seguida, utilize variáveis de ambiente para fornecer chaves durante a execução do CI, como echo $WANDB_API_KEY | wandb login.
P: É possível executar o registro do wandb offline e sincronizar depois?
R: Sim. Você pode inicializar o wandb com wandb.init(mode="offline"), o que armazena os logs localmente. Depois, execute wandb sync para fazer o upload dos dados das execuções passadas quando o acesso à rede for restaurado. Isso é útil para ambientes isolados.
Projeto e dados de execução Wandb em um relance
Para entender por que a configuração de weights & biases para monitoramento supera o registro tradicional em planilhas, aqui está um quadro rápido comparando o acompanhamento manual típico com o monitoramento do wandb em métricas chave:
| Aspecto | Registro manual (Excel/CSV) | Monitoramento de Pesos & Viés |
|---|---|---|
| Visibilidade em tempo real | Não (é preciso esperar a abertura dos arquivos) | Sim (painéis ao vivo que se atualizam automaticamente) |
| Acompanhamento de hiperparâmetros | Frequentemente esquecido ou inconsistente | Automatizado; sempre vinculado às execuções |
| Versionamento de artefatos de modelo | Backups manuais de arquivos, sem metadados | Controle de versão de artefatos integrado |
| Colaboração | Enviar arquivos por e-mail ou compartilhar pastas | As equipes compartilham projetos em tempo real com acesso baseado em funções |
| Integração com CI/CD | Etapas manuais | Automatizado por meio de scripts e APIs |
| Limites de armazenamento | Espaço em disco local | Quotas em nuvem e opções de arquivamento |
Recomendações personalizadas para diferentes perfis de desenvolvedores
Se você é um hobbyista solitário com modelos pequenos em seu laptop, comece configurando o wandb localmente com o modo offline ativado para não se preocupar com problemas de rede. A interface e o registro darão às suas experiências um senso de organização que nenhuma planilha pode igualar.
Se você é um cientista de dados equilibrando vários modelos e colaboradores, invista tempo em integrar as execuções do wandb com os repositórios Git da sua equipe e a infraestrutura em nuvem. Automatize seu registro e seus artefatos – confie em mim, ninguém quer pedir uma nova exportação de CSV.
Para engenheiros de ML construindo pipelines de produção, integre os sweeps do wandb e a automação CI/CD desde o início do seu processo. Você vai querer um estado de experiência constante, opções de restauração e um monitoramento integrado nos ciclos de publicação para evitar depurar buracos negros semanas depois.
Dados a partir de 21 de março de 2026. Fontes: Site Oficial do Pesos & Viés, Documentação do Pesos & Viés
Artigos Relacionados
- Segurança de redes de bots de IA
- Governança da segurança de bots de IA
- Grammarly é IA? Como a ferramenta de escrita utiliza inteligência artificial
🕒 Published: