Pular para o conteúdo principal

Versão de acompanhamento API Referência

Visão geral​

MLflow O acompanhamento de versões permite que o senhor crie representações com versões de seus aplicativos GenAI usando a entidade LoggedModel. Esta página fornece a referência API para as versões do aplicativo de acompanhamento em MLflow.

Por que criar uma versão para seu aplicativo GenAI?​

Reprodutibilidade : Capture ou vincule o código exato (por exemplo, Git commit hash) e as configurações usadas para uma versão específica, garantindo que o senhor sempre possa reconstruí-la.

depuração Regressões : Acompanhe as versões do LoggedModel para comparar facilmente as versões problemáticas com as versões boas conhecidas, examinando as diferenças de código, configurações, resultados de avaliação e rastros.

Comparação objetiva : avalie sistematicamente as versões usando mlflow.genai.evaluate() para comparar métricas como pontuação de qualidade, custo e latência lado a lado.

Auditabilidade : Cada versão do LoggedModel serve como um registro auditável, vinculado a códigos e configurações específicos para compliance e investigação de incidentes.

Conceitos principais​

Modelo registrado​

Um LoggedModel no MLflow representa uma versão específica do seu aplicativo GenAI. Cada estado distinto do seu aplicativo que o senhor deseja avaliar, implantar ou consultar pode ser capturado como um novo LoggedModel.

Características principais:

  • Entidade central com controle de versão para seu aplicativo GenAI
  • Captura o estado do aplicativo , incluindo configuração e parâmetros
  • Links para código externo (normalmente via Git commit hash)
  • Acompanha o ciclo de vida desde o desenvolvimento até a produção

Métodos de acompanhamento da versão​

MLflow oferece duas abordagens para o acompanhamento da versão:

  1. set_active_model : Acompanhamento simples da versão que cria automaticamente um LoggedModel, se necessário, e vincula os rastreamentos subsequentes
  2. create_external_model : Controle total sobre a criação de versões com extensos metadados, parâmetros e tags

Referência da API​

definir_modelo_ativo​

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

criar modelo_externo​

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​

  1. Use o controle de versão semântico em nomes de modelos (por exemplo, " app-v1.2.3 ")
  2. Incluir o git commit nas tags para rastreabilidade
  3. Os parâmetros devem ser strings - converta 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 :

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

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

Próximas etapas​

Última atualização em