Como versionar modelos ML com MLflow em Databricks: passo a passo

João Barros 15 de October de 2026 6 min de leitura

Este tutorial mostra como registar, versionar e carregar um modelo ML usando MLflow em Databricks, tornando mais simples promover modelos do desenvolvimento para produção. A capacidade de versionar modelos em Databricks com MLflow ajuda a rastrear experiências, comparar métricas e gerir deployments de forma controlada — fundamental quando existem várias iterações do mesmo modelo (por exemplo, 5–20 runs por experiência) e quando se pretende reproduzir resultados em produção.

Pré-requisitos

Conta Databricks com um Workspace configurado e permissões para criar modelos/experiências. Idealmente, um utilizador com permissões de Developer ou Admin.
Cluster Databricks em execução com runtime que inclua MLflow (ex.: Databricks Runtime ML). Um cluster com 4 cores e 16 GB de RAM é suficiente para este exemplo.
Noções básicas de Python e scikit-learn ou similar. Conhecimentos básicos de linha de comandos e da UI do Databricks ajudam na navegação.

Passo 1: Criar um experimento MLflow

Um experimento agrupa execuções (runs). Criar um experimento permite organizar e comparar modelos por objetivo (ex.: "classificacao_iris_v1"). Em ambientes reais, crie um experimento por projeto ou por pipeline (por exemplo, "fraude_cartoes_production").

import mlflow
mlflow.set_experiment("exemplo_classificacao_iris")

Porquê: com um experimento consegue filtrar facilmente runs por data, autor ou hiperparâmetros. Ex.: se gerar 10 runs com n_estimators = [10, 50, 100], consegue rapidamente comparar as métricas agregadas (mean/std) entre grupos.

Passo 2: Treinar e registar um modelo com uma run

Dentro de uma run, anotamos métricas, parâmetros e geramos o artefacto do modelo. Aqui usamos scikit-learn para um exemplo simples com o dataset Iris — útil para demonstrar o fluxo completo antes de aplicar em dados reais.

from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
import mlflow.sklearn

X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3, random_state=42)

with mlflow.start_run(run_name="rf_iris_v1") as run:
    params = {"n_estimators": 50, "random_state": 42}
    mlflow.log_params(params)

    model = RandomForestClassifier(**params)
    model.fit(X_train, y_train)

    preds = model.predict(X_test)
    acc = accuracy_score(y_test, preds)
    mlflow.log_metric("accuracy", acc)

    # Registar o modelo no MLflow Model Registry (name define o modelo versionado)
    mlflow.sklearn.log_model(model, artifact_path="model", registered_model_name="IrisRF")

    print(f"Run ID: {run.info.run_id}, accuracy: {acc}")

Detalhes práticos: o artefacto fica armazenado no armazenamento do workspace (DBFS ou OneLake conforme configuração). O campo registered_model_name cria uma entrada única no Model Registry chamada "IrisRF" e gera automaticamente uma nova versão (ex.: v1, v2) por cada log_model com o mesmo nome.

Passo 3: Ver as versões no Model Registry

Depois de registar, o modelo aparece no Model Registry do Databricks. A UI mostra versões, estágios (Staging, Production, Archived) e metadados como a data de criação, autor e notas. Utilizar a API permite automatizar verificações e gerar relatórios (por exemplo, listar todas as versões criadas nos últimos 30 dias).

from mlflow.tracking import MlflowClient
client = MlflowClient()

# Listar versões do modelo registado
for v in client.get_latest_versions("IrisRF"):
    print(v.version, v.current_stage, v.status)

# Obter informações de uma versão específica
ver = client.get_model_version("IrisRF", "1")
print(ver.version, ver.current_stage, ver.source)

Exemplo de output esperado: "1 Staging READY" ou "1 None READY". Se vir estados como PENDING_REGISTRATION ou FAILED, verifique logs da run para erros no upload do artefacto.

Passo 4: Promover uma versão para Staging/Production

Promover versões permite workflows de validação e deployment. A prática comum é promover primeiro para Staging para executar testes A/B ou validação em lote, e só depois mover para Production quando estiver validado. Use políticas de aprovação manual ou pipelines CI/CD para controlar quem pode promover.

# Promover a versão 1 para Staging
client.transition_model_version_stage(name="IrisRF", version="1", stage="Staging")

# Após testes, promover para Production
# client.transition_model_version_stage(name="IrisRF", version="1", stage="Production")

Boas práticas: inclua uma tag ou descrição com o commit do código e a hash do conjunto de dados usado (ex.: git_sha: abc123, data_snapshot: 2026-10-01) para total rastreabilidade.

Passo 5: Carregar uma versão específica para predição

Para fazer inferência, carregue a versão desejada do Model Registry. Pode usar o URI 'models:/<name>/<stage>' para apontar sempre para a versão em Production ou Staging, ou 'models:/<name>/<version>' para ligar a uma versão imutável (ex.: v1).

import mlflow
# Carregar a versão em Staging
model = mlflow.pyfunc.load_model("models:/IrisRF/Staging")

# Fazer uma previsão exemplo
import numpy as np
sample = X_test[0:2]
pred = model.predict(sample)
print(pred)

Note que carregar por stage é útil em deployment automático (serviço de inferência aponta para "models:/IrisRF/Production"). Se precisar de reprodutibilidade total, carregue por versão.

Verificar o resultado

Confirme na UI do Databricks: na secção Models deve aparecer 'IrisRF' com versões e stages. Na consola do notebook verá o Run ID, métricas (accuracy) e a previsão exemplo. Verifique também o tamanho do artefacto (por exemplo 2–10 MB para modelos simples) e metadados. Se a previsão devolver classes válidas e a versão aparecer no Registry, o processo funcionou.

Conclusão

Agora sabe registar, versionar, promover e carregar modelos com MLflow em Databricks, o que facilita rastreabilidade e deployment. Próximos passos práticos: automatizar avaliações por CI/CD, adicionar testes unitários de predição e integrar testes A/B nas versões. Dica final: mantenha convenções de nomes claras (ex.: projeto_modelo_versao) e registe sempre parâmetros, métricas e hashes de dados para evitar regressões ao longo do tempo.