Registro de Modelos: Versiona, Gestiona y Gobierna tus Modelos ML

Por Que Importa la Gobernanza de Modelos

En las etapas tempranas de una practica de machine learning, la gobernanza parece una carga innecesaria. Hay un solo modelo, un solo dataset y un data scientist que conoce cada detalle de ambos. Pero a medida que la practica crece, la complejidad se multiplica a un ritmo implacable. Varios equipos entrenan modelos sobre datasets que se solapan. Las versiones se multiplican conforme los experimentos se ramifican y fusionan. Un modelo desplegado hace seis meses empieza a degradarse, y nadie recuerda con que version del dataset fue entrenado, que hiperparametros lo produjeron ni que experimento demostro que era el mejor candidato.

Sin gobernanza, responder preguntas basicas se vuelve dificil o directamente imposible. Que modelo esta sirviendo actualmente el trafico de produccion? Con que datos fue entrenado? Quien lo aprobo para el despliegue? Que cambio entre la v2 y la v3? Si un auditor pregunta como se genero una prediccion concreta, puedes rastrearla hasta los datos de entrenamiento y la configuracion del algoritmo?

La gobernanza de modelos responde estas preguntas de forma sistematica. Proporciona una unica fuente de verdad para cada artefacto de modelo, su linaje, sus caracteristicas de rendimiento y su estado dentro del ciclo de vida. En industrias reguladas como finanzas y salud, la gobernanza no es opcional: las normativas exigen pistas de auditoria, explicabilidad y la capacidad de reproducir cualquier modelo que haya influido en una decision. Pero incluso en entornos no regulados, la gobernanza previene el caos organizacional que ralentiza a los equipos e introduce riesgos ocultos.

El registro de modelos de CorePlexML es el componente central de su framework de gobernanza. Cada modelo producido por un experimento o un trabajo de re-entrenamiento se registra automaticamente con metadata completa, y el registro rastrea el modelo a lo largo de todo su ciclo de vida, desde candidato hasta produccion y eventual retiro.

Versionado Semantico para Modelos ML

Los ingenieros de software llevan mucho tiempo utilizando el versionado semantico (major.minor.patch) para comunicar la naturaleza de los cambios entre versiones. CorePlexML aplica la misma convencion a los modelos ML, adaptandola a las caracteristicas propias de los cambios en modelos.

La version major (X.0.0) indica un cambio fundamental en el modelo. Esto incluye cambiar la familia de algoritmos (por ejemplo, de gradient boosting a una red neuronal), modificar la variable objetivo, alterar significativamente el conjunto de features o re-entrenar con un dataset fundamentalmente distinto. Los cambios de version major conllevan el mayor riesgo y normalmente requieren una validacion exhaustiva antes del despliegue.

La version minor (1.X.0) indica una mejora incremental. Esto incluye re-entrenar con datos actualizados manteniendo el mismo conjunto de features y algoritmo, agregar un numero reducido de nuevos features o ajustar hiperparametros. Se espera que las versiones minor sean retrocompatibles en cuanto a esquema de entrada y formato de salida.

La version patch (1.0.X) indica un cambio no funcional. Esto incluye actualizar la metadata del modelo, corregir documentacion o re-registrar un modelo con tags corregidos. Las versiones patch no modifican el artefacto del modelo en si.

from coreplexml import CorePlexClient

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

# Register a new model version
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}")

El registro impone la unicidad de versiones dentro de un modelo. No es posible registrar dos versiones con el mismo numero, lo que evita la confusion que surge cuando multiples artefactos afirman ser la misma version.

Gestion de Etapas

Cada version de modelo en el registro tiene una etapa de ciclo de vida que refleja su estado actual. CorePlexML define cuatro etapas con semantica clara y transiciones controladas.

Development es la etapa inicial para modelos recien registrados. El modelo ha sido entrenado y sus metricas registradas, pero aun no ha sido evaluado para su paso a produccion. La mayoria de los modelos permanecen en esta etapa durante toda su vida, ya que solo una fraccion de los modelos experimentales avanza mas alla.

Staging indica que el modelo ha sido seleccionado como candidato para produccion y se encuentra bajo validacion. Esta fase puede incluir evaluacion offline sobre datasets retenidos, shadow deployment contra el modelo de produccion actual o revision por parte de un comite de gobernanza. La transicion de development a staging es una decision deliberada que senala la intencion de desplegar.

Production significa que el modelo esta sirviendo predicciones activamente en un entorno de produccion. Solo una version de un modelo determinado deberia estar en produccion en cualquier momento. Al transicionar una nueva version a production, la version anterior pasa automaticamente a archived. Esto garantiza que los despliegues en produccion tengan una identidad de modelo clara e inequivoca.

Archived es la etapa terminal para modelos que ya no sirven trafico. Los modelos archivados permanecen en el registro con su metadata completa y linaje intacto, pero no pueden desplegarse sin transicionar primero de vuelta a traves de staging. Esto preserva la pista de auditoria e impide la reactivacion accidental de modelos retirados.

# Transition a model from development to staging
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"
)

# Later, promote from staging to production
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 across all segments.",
    approved_by="james.wu@company.com"
)

Las transiciones de etapa son eventos inmutables en el log de auditoria del registro. Cada transicion registra quien la inicio, cuando ocurrio y las notas proporcionadas. Esto crea una cadena de aprobacion completa que satisface los requisitos de cumplimiento normativo y proporciona responsabilidad organizacional.

Tarjetas de Modelo

Una tarjeta de modelo es un documento estructurado que acompana a una version de modelo y describe su proposito, capacidades, limitaciones y casos de uso apropiados. CorePlexML genera tarjetas de modelo automaticamente a partir de la metadata de entrenamiento y permite a los equipos complementarlas con contexto redactado por personas.

# Create a detailed model card
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. Not validated "
                       "for enterprise tier accounts.",
        "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}
        }
    }
)

Las tarjetas de modelo sirven a multiples audiencias. Los data scientists las usan para comprender las fortalezas y debilidades de un modelo antes de construir sobre el. Los product managers las usan para evaluar si un modelo es apropiado para un nuevo caso de uso. Los responsables de cumplimiento las usan para verificar que el modelo satisface los requisitos regulatorios. Al centralizar esta informacion en el registro, CorePlexML asegura que todos trabajen desde la misma fuente de verdad.

Rastreo de Linaje

El linaje del modelo responde a la pregunta: de donde proviene este modelo? CorePlexML rastrea el linaje de forma automatica, conectando cada version de modelo al experimento que lo produjo, la version del dataset con la que fue entrenado y la version padre del modelo de la que se derivo.

# Retrieve full lineage for a model version
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"  Algorithm: {lineage.experiment.algorithm}")
print(f"  Training time: {lineage.experiment.training_duration_secs}s")
print(f"  Max models evaluated: {lineage.experiment.max_models}")
print(f"Dataset version: {lineage.dataset_version_id}")
print(f"  Dataset: {lineage.dataset.name}")
print(f"  Rows: {lineage.dataset.row_count}")
print(f"  Created: {lineage.dataset.created_at}")
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')}")

La cadena de versiones proporciona un historial completo de la evolucion del modelo. Es posible rastrear un modelo de produccion a traves de cada iteracion hasta el dataset y experimento originales. Esto resulta invaluable para depuracion (en que momento se introdujo una regresion?), para cumplimiento normativo (demostrar que los datos de entrenamiento no contenian informacion prohibida) y para aprendizaje organizacional (que configuraciones de entrenamiento producen consistentemente los mejores resultados?).

El rastreo de linaje tambien habilita el analisis de impacto automatizado. Cuando se descubre que un dataset contiene errores o cuando una fuente de datos queda obsoleta, CorePlexML puede identificar cada modelo que fue entrenado con esos datos, incluyendo modelos actualmente en produccion. Esto convierte una investigacion potencialmente ardua en una simple consulta.

Busqueda y Organizacion con Tags

A medida que el registro de modelos crece, encontrar la version correcta se convierte en un problema de busqueda. El sistema de tagging de CorePlexML permite organizar modelos con etiquetas arbitrarias y filtrar por tag en las consultas.

# Search for models by tag
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)}")

# Search across all projects with filters
candidates = client.registry.search(
    query="churn",
    stage="staging",
    min_metric={"auc": 0.85},
    created_after="2026-01-01",
    tags=["candidate"]
)

Las convenciones comunes de tagging incluyen etiquetas de ciclo de vida como "champion", "candidate" y "baseline"; etiquetas organizacionales como nombres de equipo o unidades de negocio; y etiquetas tecnicas como "requires-gpu", "ensemble" o "lightweight". Los tags son de formato libre, de modo que los equipos pueden desarrollar convenciones que se ajusten a su flujo de trabajo sin verse limitados por la plataforma.

Comparacion de Versiones de Modelos

Antes de promover un modelo, es habitual compararlo contra la version de produccion actual u otros candidatos. CorePlexML ofrece una interfaz de comparacion dedicada que resalta las diferencias en metricas, parametros y linaje:

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}")

print(f"\nParameter changes:")
for param in comparison.parameter_diffs:
    print(f"  {param.name}: {param.values[0]} -> {param.values[1]}")

print(f"\nDataset changes:")
print(f"  v2.0.0 trained on: {comparison.datasets[0].name} "
      f"({comparison.datasets[0].row_count} rows)")
print(f"  v2.1.0 trained on: {comparison.datasets[1].name} "
      f"({comparison.datasets[1].row_count} rows)")

La salida de la comparacion deja claro que cambio y cual fue el impacto. Esto es particularmente util en reuniones de revision donde un equipo decide si promover un candidato a produccion. En lugar de comparar hojas de calculo, todos examinan la misma comparacion estructurada desde el registro.

Integracion con Despliegues

El registro de modelos esta estrechamente integrado con el sistema de despliegues de CorePlexML. Al crear un despliegue, se referencia una version de modelo registrada especifica. El sistema de despliegues valida que la version existe, registra el vinculo en el registro y actualiza el historial de despliegues de la version.

# Deploy a registered model version
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
    }
)

# The registry now tracks this deployment
version_info = client.registry.get_version(
    model_id="model_xgb_churn",
    version="2.1.0"
)

print(f"Active deployments: {len(version_info.deployments)}")
for dep in version_info.deployments:
    print(f"  {dep.name} ({dep.strategy}) - {dep.status}")

Este vinculo bidireccional garantiza la consistencia. El registro sabe que versiones estan desplegadas y donde, y el sistema de despliegues conoce la procedencia completa del modelo que esta sirviendo. Cuando un despliegue se retira, el registro se actualiza automaticamente.

Mejores Practicas

Registra cada modelo, incluidos los experimentos fallidos. El registro no es solo para modelos de produccion. Registrar experimentos fallidos con sus metricas y notas genera conocimiento institucional sobre lo que no funciona, lo cual suele ser tan valioso como saber lo que si. Un data scientist junior que esta a punto de probar un enfoque que ya fue evaluado y descartado puede encontrar esa informacion en el registro.

Incrementa la version major para cambios de alto riesgo. Cuando cambias el algoritmo, el conjunto de features o la fuente de datos de entrenamiento, incrementa la version major. Esto comunica a los consumidores downstream que el comportamiento del modelo puede haber cambiado de maneras que requieren validacion. Las versiones minor deberian poder desplegarse de forma segura con procedimientos canary estandar.

Escribe tarjetas de modelo significativas. La metadata autogenerada es un punto de partida, no un sustituto del contexto humano. Las secciones mas valiosas de una tarjeta de modelo son las limitaciones (para que no deberia usarse el modelo) y las consideraciones eticas (que sesgos podrian estar presentes). Dedica el tiempo necesario a redactarlas con rigor.

Utiliza flujos de aprobacion para las transiciones a produccion. No permitas que ningun modelo alcance la etapa de produccion sin una aprobacion registrada por un revisor designado. El sistema de transicion de etapas de CorePlexML soporta esto mediante el campo approved_by y la persistencia de la aprobacion en el log de auditoria. Es un control de gobernanza ligero que previene despliegues accidentales o no autorizados.

Limpia versiones antiguas de forma periodica. Las versiones archivadas deben conservarse por motivos de cumplimiento y auditoria, pero las versiones en etapa de development provenientes de experimentos antiguos pueden acumularse rapidamente. Establece una politica de retencion (por ejemplo, archivar versiones de development con mas de 90 dias) y aplicala de forma consistente.

Estandariza los tags entre equipos. Los tags solo son utiles para la busqueda si los equipos los utilizan de forma consistente. Establece un vocabulario compartido para tags comunes y documentalo. La diferencia entre etiquetar un modelo como "prod-ready", "production-ready" o "approved" parece trivial, hasta que buscas todos los modelos aprobados para produccion y te pierdes la mitad.

Un registro de modelos es la columna vertebral de una practica ML madura. Transforma la gestion de modelos de un proceso ad-hoc que depende del conocimiento individual en una practica sistematica que escala con tu equipo y satisface los requisitos de gobernanza del ML empresarial. Cada modelo que toca datos de produccion deberia tener una version registrada con linaje completo, metricas y seguimiento de ciclo de vida.

Para mas informacion sobre las capacidades de gobernanza de modelos y MLOps de CorePlexML, visita la pagina de funcionalidades MLOps.