Monitore os ambientes da versão &

O acompanhamento do ambiente de execução e da versão do aplicativo GenAI permite que o senhor depure problemas de desempenho e qualidade relativos ao código. Esses metadados permitem:

• Análise específica do ambiente em development, staging, e production
• acompanhamento do desempenho/qualidade e detecção de regressão entre as versões do aplicativo
• Análise mais rápida da causa raiz quando ocorrem problemas

MLflow usa metadados (par key-value) para armazenar informações contextuais sobre traços.

nota

Para obter uma visão geral abrangente de como funciona o controle de versão, consulte Acompanhamento de versão.

Metadados preenchidos automaticamente

Esses campos de metadados padrão são capturados automaticamente pelo MLflow com base em seu ambiente de execução.

important

Se a lógica de captura automática não atender aos seus requisitos, você poderá substituir esses metadados preenchidos automaticamente manualmente usando mlflow.update_current_trace(metadata={"mlflow.source.name": "custom_name"}).

Categoria	Campo de metadados	Descrição	Lógica de configuração automática
Ambiente de execução	mlflow.source.name	O ponto de entrada ou script que gerou o rastreamento.	Preenchido automaticamente com o nome do arquivo para scripts Python, nome do Notebook para Databricks/Jupyter Notebook.
	mlflow.source.git.commit	Hash do commit do Git.	Se o senhor executar a partir de um repositório Git, o hash commit será automaticamente detectado e preenchido.
	mlflow.source.git.branch	Ramo do Git.	Se o senhor executar a partir de um repositório Git, o nome da ramificação atual será automaticamente detectado e preenchido.
	mlflow.source.git.repoURL	URL do repositório Git.	Se o senhor executar a partir de um repositório Git, o URL do repositório será automaticamente detectado e preenchido.
	mlflow.source.type	Captura o ambiente de execução.	Automaticamente definido como NOTEBOOK se estiver sendo executado no Jupyter ou Databricks Notebook, LOCAL se estiver executando um script local Python, ou então UNKNOWN (detectado automaticamente). Em seu aplicativo implantado, sugerimos atualizar essa variável com base no ambiente, por exemplo, PRODUCTION, STAGING, etc.
Versão do aplicativo	metadata.mlflow.modelId	MLflow LoggedModel ID.	Definido automaticamente para o valor do ID do modelo na variável de ambiente MLFLOW_ACTIVE_MODEL_ID ou para o ID do modelo definido através da função mlflow.set_active_model() função.

Personalização de metadados preenchidos automaticamente

Você pode substituir qualquer um dos campos de metadados preenchidos automaticamente usandomlflow.update_current_trace(). Isso é útil quando a detecção automática não atende aos seus requisitos ou quando você deseja adicionar contexto adicional:

Python

import mlflow
import os

# We suggest populating metadata from environment variables rather than hard coding the values

@mlflow.trace
def my_app(user_question: str) -> dict:
    # Override automatically populated metadata and add custom context
    mlflow.update_current_trace(
        metadata={
            # Use any of the keys from above
            "mlflow.source.type": current_env = os.getenv("APP_ENVIRONMENT", "development"),  # Override default LOCAL/NOTEBOOK
        }
    )

    # Application logic

    return {"response": user_question + "!!"}

my_app("test")

Metadados totalmente personalizados

Você pode anexar metadados personalizados para capturar qualquer contexto específico do aplicativo. Para obter mais detalhes sobre como anexar metadados personalizados, consulte Anexar metadados personalizados/tags.

Por exemplo, o senhor pode querer anexar informações como:

• app_version: por exemplo, "1.0.0" (da variável de ambiente APP_VERSION )
• deployment_id: por exemplo, "deploy-abc-123" (da variável de ambiente DEPLOYMENT_ID )
• region: por exemplo, "us-east-1" (da variável de ambiente REGION )
• (Outras tags personalizadas, como sinalizadores de recurso, também podem ser adicionadas)

Python

import mlflow
import os

# We suggest populating metadata from environment variables rather than hard coding the values

@mlflow.trace
def my_app(user_question: str) -> dict:
    # Override automatically populated metadata and add custom context
    mlflow.update_current_trace(
        metadata={
            # Use any key
            "app_version": os.getenv("APP_VERSION", "development")
        }
    )

    # Application logic

    return {"response": user_question + "!!"}

my_app("test")

Exemplo de aplicativo web de produção

Em um aplicativo FastAPI de produção, o contexto pode ser derivado de variáveis de ambiente, cabeçalhos de solicitação ou configuração do aplicativo. O exemplo a seguir foi adaptado de Adicionar metadados e feedback do usuário aos rastreamentos e demonstra como capturar vários tipos de contexto:

Python

import mlflow
import os
from fastapi import FastAPI, Request, HTTPException # HTTPException might be needed depending on full app logic
from pydantic import BaseModel

# Initialize FastAPI app
app = FastAPI()

class ChatRequest(BaseModel):
    message: str

@mlflow.trace # Ensure @mlflow.trace is the outermost decorator
@app.post("/chat") # FastAPI decorator should be inner
def handle_chat(request: Request, chat_request: ChatRequest):
    # Retrieve all context from request headers
    client_request_id = request.headers.get("X-Request-ID")
    session_id = request.headers.get("X-Session-ID")
    user_id = request.headers.get("X-User-ID")

    # Update the current trace with all context and environment metadata
    # The @mlflow.trace decorator ensures an active trace is available
    mlflow.update_current_trace(
        client_request_id=client_request_id,
        metadata={
            # Session context - groups traces from multi-turn conversations
            "mlflow.trace.session": session_id,
            # User context - associates traces with specific users
            "mlflow.trace.user": user_id,
            # Override automatically popoulated environment metadata
            "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default LOCAL/NOTEBOOK
            # Add customer environment metadata
            "environment": "production",
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
            "region": os.getenv("REGION", "us-east-1")
        }
    )

    # --- Your application logic for processing the chat message ---
    # For example, calling a language model with context
    # response_text = my_llm_call(
    #     message=chat_request.message,
    #     session_id=session_id,
    #     user_id=user_id
    # )
    response_text = f"Processed message: '{chat_request.message}'"
    # --- End of application logic ---

    # Return response
    return {
        "response": response_text
    }

# To run this example (requires uvicorn and fastapi):
# uvicorn your_file_name:app --reload
#
# Example curl request with context headers:
# curl -X POST "http://127.0.0.1:8000/chat" \
#      -H "Content-Type: application/json" \
#      -H "X-Request-ID: req-abc-123-xyz-789" \
#      -H "X-Session-ID: session-def-456-uvw-012" \
#      -H "X-User-ID: user-jane-doe-12345" \
#      -d '{"message": "What is my account balance?"}'

Consultando e analisando dados de contexto

Usando a interface de usuário do MLflow

Na UI MLflow (Traces tab), o senhor pode view os metadados anexados:

Análise programática

Use o site MLflow SDK para análises mais complexas ou para integrar-se a outras ferramentas:

Python

from mlflow.client import MlflowClient

client = MlflowClient()

# Example 1: Compare error rates across app versions in production
def compare_version_error_rates(experiment_id: str, versions: list):
    error_rates = {}
    for version in versions:
        traces = client.search_traces(
            filter_string=f"metadata.`mlflow.source.type` = 'production' AND metadata.app_version = '{version}'"
        )
        if not traces:
            error_rates[version] = None # Or 0 if no traces means no errors
            continue

        error_count = sum(1 for t in traces if t.info.status == "ERROR")
        error_rates[version] = (error_count / len(traces)) * 100
    return error_rates

# version_errors = compare_version_error_rates("your_exp_id", ["1.0.0", "1.1.0"])
# print(version_errors)

# Example 2: Analyze performance for a specific feature flag
def analyze_feature_flag_performance(experiment_id: str, flag_name: str):
    control_latency = []
    treatment_latency = []

    control_traces = client.search_traces(
        filter_string=f"metadata.feature_flag_{flag_name} = 'false'",
        # extract_fields=["execution_time_ms"] # Not a real field, use span attributes if needed
    )
    for t in control_traces: control_latency.append(t.info.execution_time_ms)

    treatment_traces = client.search_traces(
        experiment_ids=[experiment_id],
        filter_string=f"metadata.feature_flag_{flag_name} = 'true'",
    )
    for t in treatment_traces: treatment_latency.append(t.info.execution_time_ms)

    avg_control_latency = sum(control_latency) / len(control_latency) if control_latency else 0
    avg_treatment_latency = sum(treatment_latency) / len(treatment_latency) if treatment_latency else 0

    return {
        f"avg_latency_{flag_name}_off": avg_control_latency,
        f"avg_latency_{flag_name}_on": avg_treatment_latency
    }

# perf_metrics = analyze_feature_flag_performance("your_exp_id", "new_retriever")
# print(perf_metrics)

Próximas etapas

• Implantar agentes com rastreamento - Entender os rastreamentos de registro na produção
• Acompanhe as sessões & dos usuários - Adicione observabilidade centrada no usuário aos seus rastreamentos
• Anexe tags e metadados personalizados - Saiba mais maneiras de enriquecer os traços com o contexto

referências de recursos

Para obter detalhes sobre os conceitos e recursos deste guia, consulte:

• Modelo de dados de rastreamento - entenda os metadados e como eles são armazenados nos rastreamentos
• Conceitos de acompanhamento da versão do aplicativo - Aprenda sobre estratégias de controle de versão
• Consulta de traços via SDK - Consulta avançada com filtros de metadados