Pular para o conteúdo principal

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 com o valor da ID do modelo na variável de ambiente MLFLOW_ACTIVE_MODEL_ID ou com a ID do modelo definida por meio da função mlflow.set_active_model().

Personalização de metadados preenchidos automaticamente​

Você pode substituir qualquer um dos campos de metadados preenchidos automaticamente usando mlflow.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 do guia Production Observability with Tracing 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:

rastrear metadados

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​

Continue sua jornada com estas ações recomendadas e o tutorial.

Guia de referência​

Explore a documentação detalhada dos conceitos e recursos mencionados neste guia.

Última atualização em