Registro de Modelos: Versione, Gerencie e Governe seus Modelos ML

Por Que a Governanca de Modelos Importa

Nos estagios iniciais de uma pratica de machine learning, a governanca parece uma carga desnecessaria. Ha um unico modelo, um unico dataset e um cientista de dados que conhece cada detalhe de ambos. Mas conforme a pratica cresce, a complexidade se multiplica. Varias equipes treinam modelos sobre datasets que se sobrepoem. As versoes se multiplicam conforme os experimentos se ramificam e fundem. Um modelo implantado ha seis meses comeca a se degradar, e ninguem lembra com qual versao do dataset foi treinado.

A governanca de modelos responde essas perguntas de forma sistematica. Fornece uma unica fonte de verdade para cada artefato de modelo, sua linhagem, suas caracteristicas de desempenho e seu estado dentro do ciclo de vida.

Versionamento Semantico para Modelos ML

O CorePlexML aplica o versionamento semantico (major.minor.patch) aos modelos ML:

A versao major (X.0.0) indica uma mudanca fundamental no modelo, como trocar a familia de algoritmos ou modificar a variavel alvo. A versao minor (1.X.0) indica uma melhoria incremental, como re-treinar com dados atualizados. A versao patch (1.0.X) indica uma mudanca nao funcional, como atualizar metadata.

from coreplexml import CorePlexClient

client = CorePlexClient(
    base_url="https://api.coreplexml.io",
    api_key="your-api-key"
)

version = client.registry.create_version(
    project_id="proj_abc123",
    model_id="model_xgb_churn",
    version="2.1.0",
    description="Retrained on Q4 2025 data with 3 new behavioral features",
    experiment_id="exp_q4_retrain",
    dataset_version_id="dsv_q4_2025",
    metrics={
        "auc": 0.912,
        "accuracy": 0.867,
        "precision": 0.843,
        "recall": 0.791,
        "f1": 0.816,
        "log_loss": 0.298
    },
    parameters={
        "algorithm": "xgboost",
        "max_depth": 6,
        "learning_rate": 0.1,
        "n_estimators": 250,
        "nfolds": 5,
        "stopping_metric": "AUC"
    },
    tags=["candidate", "q4-retrain", "behavioral-features"]
)

print(f"Registered: {version.model_id} v{version.version}")
print(f"Stage: {version.stage}")

Gestao de Estagios

Cada versao de modelo no registro possui um estagio de ciclo de vida:

Development e o estagio inicial para modelos recem-registrados. A maioria dos modelos permanece neste estagio durante toda sua vida.

Staging indica que o modelo foi selecionado como candidato para producao e esta sob validacao. A transicao de development para staging e uma decisao deliberada.

Production significa que o modelo esta servindo predicoes ativamente. Apenas uma versao deve estar em producao a qualquer momento. Ao transicionar uma nova versao para production, a anterior passa automaticamente para archived.

Archived e o estagio terminal para modelos que nao servem mais trafego. Modelos arquivados permanecem no registro com metadata completa e linhagem intacta.

client.registry.transition_stage(
    model_id="model_xgb_churn",
    version="2.1.0",
    target_stage="staging",
    notes="Approved for shadow deployment by ML review board. "
          "AUC improvement of 2.3% over current production model.",
    approved_by="maria.chen@company.com"
)

client.registry.transition_stage(
    model_id="model_xgb_churn",
    version="2.1.0",
    target_stage="production",
    notes="Shadow deployment completed successfully. "
          "7-day comparison shows consistent improvement.",
    approved_by="james.wu@company.com"
)

Cartoes de Modelo

Um cartao de modelo e um documento estruturado que acompanha uma versao de modelo e descreve seu proposito, capacidades, limitacoes e casos de uso apropriados:

client.registry.update_model_card(
    model_id="model_xgb_churn",
    version="2.1.0",
    model_card={
        "description": "Customer churn prediction model for subscription "
                       "products. Predicts probability of churn within "
                       "the next 30 days.",
        "intended_use": "Real-time scoring of active subscribers to "
                        "prioritize retention outreach.",
        "limitations": "Trained on US market data only. Performance may "
                       "degrade for international customers.",
        "ethical_considerations": "Model uses behavioral features only. "
                                  "No demographic or protected class "
                                  "features are included.",
        "training_data_summary": {
            "source": "Production subscription database",
            "date_range": "2025-01-01 to 2025-12-31",
            "total_rows": 247_500,
            "positive_class_ratio": 0.087,
            "feature_count": 18
        },
        "performance_by_segment": {
            "enterprise": {"auc": 0.89, "samples": 12_400},
            "professional": {"auc": 0.91, "samples": 85_300},
            "starter": {"auc": 0.93, "samples": 149_800}
        }
    }
)

Rastreamento de Linhagem

A linhagem do modelo responde a pergunta: de onde veio este modelo? O CorePlexML rastreia a linhagem automaticamente.

lineage = client.registry.get_lineage(
    model_id="model_xgb_churn",
    version="2.1.0"
)

print(f"Model: {lineage.model_id} v{lineage.version}")
print(f"Experiment: {lineage.experiment_id}")
print(f"Dataset version: {lineage.dataset_version_id}")
print(f"Parent version: {lineage.parent_version or 'None (initial)'}")
print(f"\nVersion chain:")
for ancestor in lineage.version_chain:
    print(f"  v{ancestor.version} ({ancestor.stage}) - "
          f"{ancestor.created_at.strftime('%Y-%m-%d')}")

O rastreamento de linhagem tambem habilita a analise de impacto automatizada. Quando se descobre que um dataset contem erros, o CorePlexML pode identificar cada modelo treinado com esses dados, incluindo modelos atualmente em producao.

Busca e Organizacao com Tags

champion_models = client.registry.list_versions(
    project_id="proj_abc123",
    tags=["champion"],
    stage="production"
)

for model in champion_models:
    print(f"{model.model_id} v{model.version} - "
          f"AUC: {model.metrics['auc']:.4f} - "
          f"Tags: {', '.join(model.tags)}")

Comparacao de Versoes de Modelos

comparison = client.registry.compare_versions(
    model_id="model_xgb_churn",
    versions=["2.0.0", "2.1.0"]
)

print(f"Comparing {comparison.versions[0]} vs {comparison.versions[1]}")
print(f"\n{'Metric':<20} {'v2.0.0':<12} {'v2.1.0':<12} {'Delta':<12}")
print("-" * 56)
for metric in comparison.metric_diffs:
    print(f"{metric.name:<20} {metric.values[0]:<12.4f} "
          f"{metric.values[1]:<12.4f} {metric.delta:+<12.4f}")

Integracao com Implantacoes

O registro esta estreitamente integrado com o sistema de implantacoes:

deployment = client.deployments.create(
    project_id="proj_abc123",
    registry_version={
        "model_id": "model_xgb_churn",
        "version": "2.1.0"
    },
    name="Churn Predictor Production",
    strategy="canary",
    canary_config={
        "stages": [
            {"traffic_percentage": 5, "duration_minutes": 60},
            {"traffic_percentage": 25, "duration_minutes": 120},
            {"traffic_percentage": 50, "duration_minutes": 180},
            {"traffic_percentage": 100, "duration_minutes": 0}
        ],
        "auto_advance": True,
        "auto_rollback": True
    }
)

Melhores Praticas

Registre cada modelo, incluindo experimentos falhados. Registrar experimentos falhados com suas metricas e notas gera conhecimento institucional sobre o que nao funciona.

Incremente a versao major para mudancas de alto risco. Quando muda o algoritmo, o conjunto de features ou a fonte de dados, incremente a versao major.

Escreva cartoes de modelo significativos. As secoes mais valiosas sao as limitacoes e consideracoes eticas. Dedique tempo para redigi-las com rigor.

Use fluxos de aprovacao para transicoes a producao. Nao permita que nenhum modelo alcance production sem aprovacao registrada.

Limpe versoes antigas periodicamente. Versoes archivadas devem ser conservadas por motivos de conformidade, mas versoes development de experimentos antigos podem se acumular rapidamente.

Padronize tags entre equipes. Tags so sao uteis para busca se as equipes as utilizam de forma consistente. Estabeleca um vocabulario compartilhado.

Um registro de modelos e a espinha dorsal de uma pratica ML madura. Transforma a gestao de modelos de um processo ad-hoc em uma pratica sistematica que escala com sua equipe e satisfaz os requisitos de governanca do ML empresarial.