Controle de versão e LoggedModel

O controle de versão do MLflow permite que você crie representações versionadas dos seus aplicativos GenAI. O controle de versão fornece os seguintes benefícios:

• Reprodutibilidade e auditabilidade. Cada versão de aplicativo ou modelo é vinculada ao seu código específico, como o hash de commit do Git e sua configuração.
• Ajuda com depuração. Comparar código, configurações, resultados de avaliação e rastreamentos entre versões de modelo.
• Avaliação sistemática. Use mlflow.genai.evaluate() para comparar métricas como pontuações de qualidade, custo e latência lado a lado.

Para criar um aplicativo ou uma versão de modelo, use um LoggedModel. No MLflow, um LoggedModel representa uma versão específica do seu aplicativo GenAI. Cada estado distinto do seu aplicativo para o qual você deseja avaliar, implantar ou fazer referência pode ser capturado como um novo LoggedModel.

Esta página é uma introdução ao acompanhamento de versão do MLflow. Para obter um tutorial passo a passo, consulte Acompanhar versões de aplicativos baseados em Git com o MLflow.

Métodos para acompanhamento de versão

O MLflow fornece dois métodos para acompanhamento de versão:

• mlflow.set_active_model(): rastreamento de versão simples. Cria automaticamente um LoggedModel se necessário e vincula os rastros subsequentes.
• mlflow.create_external_model(): controle total sobre a criação da versão de software. Você pode fornecer metadados extensivos, parâmetros e marcas.

set_active_model

Vincula rastreamentos a uma versão específica LoggedModel . Se um modelo com o nome fornecido não existir, ele criará automaticamente um.

def set_active_model(
    name: Optional[str] = None,
    model_id: Optional[str] = None
) -> ActiveModel:

Parâmetros

*Ou name ou model_id deve ser fornecido.

Valor de retorno

Retorna um ActiveModel objeto (subclasse de LoggedModel) que pode ser usado como um gerenciador de contexto.

Exemplo de Uso

import mlflow

# Simple usage - creates model if it doesn't exist
mlflow.set_active_model(name="my-agent-v1.0")

# Use as context manager
with mlflow.set_active_model(name="my-agent-v2.0") as model:
    print(f"Model ID: {model.model_id}")
    # Traces within this context are linked to this model

# Use with existing model ID
mlflow.set_active_model(model_id="existing-model-id")

create_external_model

Cria um novo LoggedModel para aplicativos cujo código e artefatos são armazenados fora do MLflow (por exemplo, no Git).

def create_external_model(
    name: Optional[str] = None,
    source_run_id: Optional[str] = None,
    tags: Optional[dict[str, str]] = None,
    params: Optional[dict[str, str]] = None,
    model_type: Optional[str] = None,
    experiment_id: Optional[str] = None,
) -> LoggedModel:

Parâmetros

Valor de retorno

Retorna um objeto LoggedModel com:

• model_id: identificador exclusivo para o modelo
• name: o nome do modelo atribuído
• experiment_id: ID do experimento associado
• creation_timestamp: quando o modelo foi criado
• status: status do modelo (sempre "PRONTO" para modelos externos)
• tags: Dicionário de etiquetas
• params: dicionário de parâmetros

Exemplo de Uso

import mlflow

# Basic usage
model = mlflow.create_external_model(
    name="customer-support-agent-v1.0"
)

# With full metadata
model = mlflow.create_external_model(
    name="recommendation-engine-v2.1",
    model_type="rag-agent",
    params={
        "llm_model": "gpt-4",
        "temperature": "0.7",
        "max_tokens": "1000",
        "retrieval_k": "5"
    },
    tags={
        "team": "ml-platform",
        "environment": "staging",
        "git_commit": "abc123def"
    }
)

# Within a run context
with mlflow.start_run() as run:
    model = mlflow.create_external_model(
        name="my-agent-v3.0",
        source_run_id=run.info.run_id
    )

Classe LoggedModel

A LoggedModel classe representa um modelo com versão no MLflow.

Propriedades

Padrões comuns

Controle de versão com a integração do Git

import mlflow
import subprocess

# Get current git commit
git_commit = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()[:8]

# Create versioned model name
model_name = f"my-app-git-{git_commit}"

# Track the version
model = mlflow.create_external_model(
    name=model_name,
    tags={"git_commit": git_commit}
)

Vinculando logs a versões

import mlflow

# Set active model - all subsequent traces will be linked
mlflow.set_active_model(name="my-agent-v1.0")

# Your application code with tracing
@mlflow.trace
def process_request(query: str):
    # This trace will be automatically linked to my-agent-v1.0
    return f"Processing: {query}"

# Run the application
result = process_request("Hello world")

Implantação de produção

Em produção, use variáveis de ambiente em vez de chamar set_active_model():

# Set the model ID that traces should be linked to
export MLFLOW_ACTIVE_MODEL_ID="my-agent-v1.0"

Práticas recomendadas

1. Usar controle de versão semântico em nomes de modelo (por exemplo, "app-v1.2.3")
2. Incluir commits do git em tags para rastreabilidade
3. Os parâmetros devem ser cadeias de caracteres – converter números e boolianos
4. Usar model_type para categorizar aplicativos semelhantes
5. Definir o modelo ativo antes do rastreamento para garantir a vinculação adequada

Problemas comuns

Tipos de parâmetro inválidos:

# Error: Parameters must be strings
# Wrong:
params = {"temperature": 0.7, "max_tokens": 1000}

# Correct:
params = {"temperature": "0.7", "max_tokens": "1000"}

Próximas etapas

• Acompanhar versões do aplicativo – guia passo a passo para versionar seu aplicativo GenAI
• Vincular rastreamentos de produção – Conectar dados de produção a versões do aplicativo
• Pacote para implantação – Implantar aplicativos com versão no Model Serving