Rastreamento de versões e LoggedModel

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

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

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

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

Métodos para controle de versão

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

• mlflow.set_active_model(): Rastreamento de versão simples. Cria automaticamente um LoggedModel se necessário e vincula rastreamentos subsequentes.
• mlflow.create_external_model(): Controle total sobre a criação da versão. Você pode fornecer metadados, parâmetros e tags extensos.

set_active_model

Vincula rastreamentos a uma versão específica LoggedModel . Se um modelo com o nome próprio 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 objeto ActiveModel (subclasse de LoggedModel) que pode ser usado como um gestor de contexto.

Exemplo de Utilização

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 único do modelo
• name: O nome do modelo atribuído
• experiment_id: ID do experimento associado
• creation_timestamp: Quando o modelo foi criado
• status: Estado do modelo (sempre "PRONTO" para modelos externos)
• tags: Dicionário de tags
• params: Dicionário de parâmetros

Exemplo de Utilização

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 versionado no MLflow.

Propriedades

Padrões comuns

Rastreamento de versão com integração com 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}
)

Ligando traços 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

Na 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"

Melhores práticas

1. Use o controle de versão semântico em nomes de modelo (por exemplo, "app-v1.2.3")
2. Incluir confirmações do git em tags para rastreabilidade
3. Os parâmetros devem ser strings - converter números e booleanos
4. Use model_type para categorizar aplicativos semelhantes
5. Defina o modelo ativo antes do rastreamento para garantir a ligação adequada

Problemas comuns

Tipos de parâmetros inválidos:

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

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

Próximos passos

• Acompanhe as versões do aplicativo - Guia passo a passo para a versão do seu aplicativo GenAI
• Vincular rastreios de produção - Ligue dados de produção a versões de aplicações
• Pacote para implantação - Implantar aplicativos com versão no Model Serving