Versão acompanhamento e `LoggedModel`

O recurso de acompanhamento de versões MLflow permite criar representações versionadas de suas aplicações GenAI. O controle de versões oferece os seguintes benefícios:

Reprodutibilidade e auditabilidade. Cada versão de aplicativo ou modelo possui um link para seu código específico, como o hash do commit do Git, e sua configuração.
Auxílio na depuração. Compare o código, as configurações, os resultados da avaliação e os rastreamentos entre as versões do 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 uma versão de aplicativo ou modelo, você usa um LoggedModel. No MLflow, um LoggedModel representa uma versão específica do seu aplicativo GenAI. Cada estado distinto do seu aplicativo que você deseja avaliar, implantar ou ao qual deseja se referir pode ser capturado como um novo LoggedModel.

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

Métodos para envio de versão

MLflow oferece dois métodos para acompanhamento de versões:

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

`set_active_model`

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

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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`name`	`str \| None`	Não*	Nome do modelo. Se o modelo não existir, cria um novo
`model_id`	`str \| None`	Não*	ID de um LoggedModel existente

* name ou model_id devem ser fornecidos.

Valor de retorno

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

Exemplo de uso

Python
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).

Python
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

Parâmetro	Tipo	Obrigatório	Descrição
`name`	`str \| None`	Não	Nome do modelo. Se não for especificado, um nome aleatório será gerado
`source_run_id`	`str \| None`	Não	ID da execução associada. padrão para a ID de execução ativa se estiver em um contexto de execução
`tags`	`dict[str, str] \| None`	Não	par chave-valor para organização e filtragem
`params`	`dict[str, str] \| None`	Não	Parâmetros e configuração do modelo (devem ser strings)
`model_type`	`str \| None`	Não	Tipo definido pelo usuário para categorização (por exemplo, " agent ", " rag-system ")
`experiment_id`	`str \| None`	Não	Experimente se associar com. Usa experimento ativo se não for especificado

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 " READY " para modelos externos)
tags: Dicionário de tags
params: Dicionário de parâmetros

Exemplo de uso

Python
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 classe LoggedModel representa um modelo com versão no MLflow.

Propriedades

Propriedade	Tipo	Descrição
`model_id`	`str`	Identificador exclusivo para o modelo
`name`	`str`	Nome do modelo
`experiment_id`	`str`	ID do experimento associado
`creation_timestamp`	`int`	Tempo de criação (milissegundos desde a época)
`last_updated_timestamp`	`int`	Hora da última atualização (milissegundos desde a época)
`model_type`	`str \| None`	Tipo de modelo definido pelo usuário
`source_run_id`	`str \| None`	ID da execução que criou este modelo
`status`	`LoggedModelStatus`	Status do modelo (PRONTO, FAILED_REGISTRATION, etc.)
`tags`	`dict[str, str]`	Dicionário de tags
`params`	`dict[str, str]`	Dicionário de parâmetros
`model_uri`	`str`	URI para referenciar o modelo (por exemplo, modelos ": /model_id ")

Padrões comuns

Acompanhamento da versão com a integração Git

Python
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 traços a versões

Python
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ável de ambiente em vez de chamar set_active_model():

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

Melhores práticas

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

Problemas comuns

Tipos de parâmetros inválidos :

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

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

Próximos passos

Rastrear versões de aplicativos - Guia passo a passo para versionar seu aplicativo GenAI
Vincule rastreamentos de produção - conecte dados de produção às versões do aplicativo
pacote para implementação - aplicativos com versão implantada para o modelo de serviço

Métodos para envio de versão​

set_active_model​

Parâmetros​

Valor de retorno​

Exemplo de uso​

create_external_model​

Parâmetros​

Valor de retorno​

Exemplo de uso​

Classe LoggedModel​

Propriedades​

Padrões comuns​

Acompanhamento da versão com a integração Git​

Vinculando traços a versões​

Implantação de produção​

Melhores práticas​

Problemas comuns​

Próximos passos​

Métodos para envio de versão

`set_active_model`

Parâmetros

Valor de retorno

Exemplo de uso

`create_external_model`

Parâmetros

Valor de retorno

Exemplo de uso

Classe LoggedModel

Propriedades

Padrões comuns

Acompanhamento da versão com a integração Git

Vinculando traços a versões

Implantação de produção

Melhores práticas

Problemas comuns

Próximos passos