Arnês de avaliação

A função mlflow.genai.evaluate() testa sistematicamente a qualidade do aplicativo GenAI, executando-o em relação aos dados de teste(conjunto de dados de avaliação) e aplicando pontuadores.

Referência rápida

Parâmetro	Tipo	Descrição
data	MLflow EvaluationDataset, List[Dict], Pandas DataFrame, Spark DataFrame	Dados de teste
predict_fn	Pode ser chamado	Seu aplicativo (somenteMode 1)
scorers	Lista [Marcador]	Qualidade métricas
model_id	str	Versão opcional acompanhamento

Como funciona

1. executar seu aplicativo em entradas de teste, capturando traços
2. Aplica pontuadores para avaliar a qualidade, criando feedback
3. Armazena os resultados em uma execução de avaliação

Pré-requisitos

1. Instale o site MLflow e o pacote necessário

   Bash

   pip install --upgrade "mlflow[databricks]>=3.1.0" openai "databricks-connect>=16.1"

2. Crie um experimento MLflow seguindo o início rápido de configuração do ambiente.

Dois modos de avaliação

Mode 1: Avaliação direta (recomendada)

O MLflow chama seu aplicativo GenAI diretamente para gerar e avaliar traços. O senhor pode passar o ponto de entrada do seu aplicativo envolvido em uma função Python (predict_fn) ou, se o seu aplicativo for implantado como um Databricks servindo o modelo endpoint, passar esse endpoint envolvido em to_predict_fn.

Benefícios:

• Permite que os avaliadores sejam facilmente reutilizados entre a avaliação off-line e o monitoramento da produção
• Paralelização automática da execução do seu aplicativo para uma avaliação mais rápida

Ao chamar seu aplicativo diretamente, esse modo permite que o senhor reutilize os avaliadores definidos para a avaliação off-line no monitoramento da produção, pois os traços resultantes serão idênticos.

Etapa 1: avaliação da execução

Python

import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your GenAI app with MLflow tracing
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    if "MLflow" in question:
        response = "MLflow is an open-source platform for managing ML and GenAI workflows."
    else:
        response = "I can help you with MLflow questions."

    return {"response": response}

# Evaluate your app
results = mlflow.genai.evaluate(
    data=[
        {"inputs": {"question": "What is MLflow?"}},
        {"inputs": {"question": "How do I get started?"}}
    ],
    predict_fn=my_chatbot_app,
    scorers=[RelevanceToQuery(), Safety()]
)

Etapa 2: visualizar os resultados na interface do usuário

Mode 2: Avaliação da folha de respostas

Forneça saídas pré-computadas ou traços existentes para avaliação quando não for possível executar seu aplicativo GenAI diretamente.

Casos de uso:

• Testando saídas de sistemas externos
• Avaliação de traços históricos
• Comparando saídas em diferentes plataformas

atenção

Se o senhor usar uma folha de respostas com traços diferentes dos do seu ambiente de produção, talvez seja necessário reescrever as funções do avaliador para usá-las no monitoramento da produção.

Exemplo (com entradas/saídas ):

Etapa 1: avaliação da execução

Python

import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery

# Pre-computed results from your GenAI app
results_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "outputs": {"response": "MLflow is an open-source platform for managing machine learning workflows, including tracking experiments, packaging code, and deploying models."},
    },
    {
        "inputs": {"question": "How do I get started?"},
        "outputs": {"response": "To get started with MLflow, install it using 'pip install mlflow' and then run 'mlflow ui' to launch the web interface."},
    }
]

# Evaluate pre-computed outputs
evaluation = mlflow.genai.evaluate(
    data=results_data,
    scorers=[Safety(), RelevanceToQuery()]
)

Etapa 2: visualizar os resultados na interface do usuário

Exemplo com traços existentes:

Python

import mlflow

# Retrieve traces from production
traces = mlflow.search_traces(
    filter_string="trace.status = 'OK'",
)

# Evaluate problematic traces
evaluation = mlflow.genai.evaluate(
    data=traces,
    scorers=[Safety(), RelevanceToQuery()]
)

parâmetros-chave

Python

def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],
    scorers: list[mlflow.genai.scorers.Scorer],
    predict_fn: Optional[Callable[..., Any]] = None,
    model_id: Optional[str] = None,
) -> mlflow.models.evaluation.base.EvaluationResult:

data

Sua avaliação dataset em um desses formatos:

• EvaluationDataset (recomendado)
• Lista de dicionários, Pandas DataFrame ou Spark DataFrame

Se o argumento de dados for fornecido como um DataFrame ou uma lista de dicionários, ele deverá seguir o seguinte esquema. Isso é consistente com o esquema usado pelo EvaluationDataset. Recomendamos o uso do site EvaluationDataset, pois ele aplicará a validação do esquema, além de acompanhar a linhagem de cada registro.

campo	Tipo de dados	Descrição	Necessário se o aplicativo for passado para predict_fn (modo 1)?	É necessário fornecer uma folha de respostas (modo 2)?
inputs	dict[Any, Any]	Um dict que será passado para seu predict_fn usando **kwargs. Deve ser serializável em JSON. Cada key deve corresponder a um argumento nomeado em predict_fn.	Obrigatório	inputs + outputs ou trace são obrigatórios. Não consigo ultrapassar os dois. Derivado de trace se não for fornecido.
outputs	dict[Any, Any]	Um dict com as saídas do seu aplicativo GenAI para o input correspondente. Deve ser serializável em JSON.	NÃO deve ser fornecido, gerado pelo MLflow a partir do Trace	inputs + outputs ou trace são obrigatórios. Não consigo ultrapassar os dois. Derivado de trace se não for fornecido.
expectations	dict[str, Any]	Um dict com rótulo de verdade correspondente a input. Usado por scorers para verificar a qualidade. Deve ser JSON serializável e cada key deve ser um str.	Opcional	Opcional
trace	mlflow.entities.Trace	O objeto de rastreamento da solicitação. Se o trace for fornecido, o expectations poderá ser fornecido como Assessments no trace em vez de como uma coluna separada.	NÃO deve ser fornecido, gerado pelo MLflow a partir do Trace	inputs + outputs ou trace são obrigatórios. Não consigo ultrapassar os dois.

predict_fn

O ponto de entrada do seu aplicativo GenAI (somente emMode 1). Deve:

• Aceitar a chave do dicionário inputs em data como argumentos de palavra-chave
• Retorna um dicionário serializável em JSON
• Ser instrumentado com o MLflow Tracing
• Emita exatamente um rastreamento por chamada

scorers

Lista de métricas de qualidade a serem aplicadas. Você pode fornecer:

• Marcadores predefinidos
• Marcadores personalizados

Consulte Marcadores para obter mais detalhes.

model_id

Identificador de modelo opcional para vincular os resultados à versão do seu aplicativo (por exemplo, "models:/my-app/1"). Consulte a versão de acompanhamento para obter mais detalhes.

Formatos de dados

Para avaliação direta (Mode 1)

campo	Obrigatório	Descrição
inputs	✅	Dicionário passado para o seu predict_fn
expectations	Opcional	Verdade básica opcional para marcadores

Para avaliação da folha de respostas (Mode 2)

Opção A - Forneça entradas e saídas:

campo	Obrigatório	Descrição
inputs	✅	Entradas originais para seu aplicativo GenAI
outputs	✅	Pré-computar os resultados de seu aplicativo
expectations	Opcional	Verdade básica opcional para marcadores

Opção B - Forneça traços existentes:

campo	Obrigatório	Descrição
trace	✅	Objetos de rastreamento do MLflow com entradas/saídas
expectations	Opcional	Verdade básica opcional para marcadores

Padrões comuns de entrada de dados

Avalie com um conjunto de dados de avaliação MLflow (recomendado)

MLflow O conjunto de dados de avaliação fornece controle de versão, acompanhamento de linhagem e integração com o site Unity Catalog para avaliação pronta para produção.

Python

import mlflow
from mlflow.genai.scorers import Correctness, Safety
from my_app import agent  # Your GenAI app with tracing

# Load versioned evaluation dataset
dataset = mlflow.genai.datasets.get_dataset("catalog.schema.eval_dataset_name")

# Run evaluation
results = mlflow.genai.evaluate(
    data=dataset,
    predict_fn=agent,
    scorers=[Correctness(), Safety()],
)

Use para:

• Necessidade de ter dados de avaliação com controle de versão e acompanhamento de linhagem
• Convertendo facilmente traços em registros de avaliação

Consulte Criar conjunto de dados de avaliação para criar um conjunto de dados a partir de rastros ou do zero.

Avalie com uma lista de dicionários

Use uma lista simples de dicionários para criar protótipos rapidamente sem criar uma avaliação formal dataset.

Python

import mlflow
from mlflow.genai.scorers import Correctness, RelevanceToQuery
from my_app import agent  # Your GenAI app with tracing

# Define test data as a list of dictionaries
eval_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "expectations": {"expected_facts": ["open-source platform", "ML lifecycle management"]}
    },
    {
        "inputs": {"question": "How do I track experiments?"},
        "expectations": {"expected_facts": ["mlflow.start_run()", "log metrics", "log parameters"]}
    },
    {
        "inputs": {"question": "What are MLflow's main components?"},
        "expectations": {"expected_facts": ["Tracking", "Projects", "Models", "Registry"]}
    }
]

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=agent,
    scorers=[Correctness(), RelevanceToQuery()],
)

Use para:

• Prototipagem rápida
• Conjunto de dados pequeno (< 100 examples)
• Teste de desenvolvimento ad-hoc

Para produção, converta para um conjunto de dados de avaliaçãoMLflow.

Avaliar com um Pandas DataFrame

Use Pandas DataFrames para avaliação quando estiver trabalhando com arquivos CSV ou com ciência de dados fluxo de trabalho existente.

Python

import mlflow
import pandas as pd
from mlflow.genai.scorers import Correctness, Safety
from my_app import agent  # Your GenAI app with tracing

# Create evaluation data as a Pandas DataFrame
eval_df = pd.DataFrame([
    {
        "inputs": {"question": "What is MLflow?"},
        "expectations": {"expected_response": "MLflow is an open-source platform for ML lifecycle management"}
    },
    {
        "inputs": {"question": "How do I log metrics?"},
        "expectations": {"expected_response": "Use mlflow.log_metric() to log metrics"}
    }
])

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_df,
    predict_fn=agent,
    scorers=[Correctness(), Safety()],
)

Use para:

• Prototipagem rápida
• Conjunto de dados pequeno (< 100 examples)
• Teste de desenvolvimento ad-hoc

Avaliar com um DataFrame do Spark

Use o Spark DataFrames para avaliações em larga escala ou quando os dados já estiverem no Delta Lake/Unity Catalog.

Python

import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery
from my_app import agent  # Your GenAI app with tracing

# Load evaluation data from a Delta table in Unity Catalog
eval_df = spark.table("catalog.schema.evaluation_data")

# Or load from any Spark-compatible source
# eval_df = spark.read.parquet("path/to/evaluation/data")

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_df,
    predict_fn=agent,
    scorers=[Safety(), RelevanceToQuery()],
)

Use para:

• Os dados já existem no Delta Lake ou no Unity Catalog
• Se for necessário filtrar os registros em um conjunto de dados MLflow Evaluation antes de executar a avaliação

Observação: o site DataFrame deve estar em conformidade com o esquema de avaliação dataset.

Padrões predict_fn comuns

Ligue diretamente para seu aplicativo

Passe seu aplicativo diretamente como predict_fn quando os nomes dos parâmetros corresponderem à sua chave de avaliação dataset.

Python

import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your GenAI app that accepts 'question' as a parameter
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    response = f"I can help you with: {question}"
    return {"response": response}

# Evaluation data with 'question' key matching the function parameter
eval_data = [
    {"inputs": {"question": "What is MLflow?"}},
    {"inputs": {"question": "How do I track experiments?"}}
]

# Pass your app directly since parameter names match
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_chatbot_app,  # Direct reference, no wrapper needed
    scorers=[RelevanceToQuery(), Safety()]
)

Use para:

• Aplicativos que têm nomes de parâmetros que correspondem à sua avaliação dataset's inputs

Embrulhe seu aplicativo em um aplicativo que pode ser chamado

Envolva seu aplicativo quando ele esperar nomes de parâmetros ou estruturas de dados diferentes da sua avaliação dataset's inputs.

Python

import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your existing GenAI app with different parameter names
@mlflow.trace
def customer_support_bot(user_message: str, chat_history: list = None) -> dict:
    # Your app logic here
    context = f"History: {chat_history}" if chat_history else "New conversation"
    return {
        "bot_response": f"Helping with: {user_message}. {context}",
        "confidence": 0.95
    }

# Wrapper function to translate evaluation data to your app's interface
def evaluate_support_bot(question: str, history: str = None) -> dict:
    # Convert evaluation dataset format to your app's expected format
    chat_history = history.split("|") if history else []

    # Call your app with the translated parameters
    result = customer_support_bot(
        user_message=question,
        chat_history=chat_history
    )

    # Translate output to standard format if needed
    return {
        "response": result["bot_response"],
        "confidence_score": result["confidence"]
    }

# Evaluation data with different key names
eval_data = [
    {"inputs": {"question": "Reset password", "history": "logged in|forgot email"}},
    {"inputs": {"question": "Track my order"}}
]

# Use the wrapper function for evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=evaluate_support_bot,  # Wrapper handles translation
    scorers=[RelevanceToQuery(), Safety()]
)

Use para:

• Incompatibilidades de nomes de parâmetros entre os parâmetros de seu aplicativo e a avaliação dataset input key (por exemplo, user_input vs. question)
• Conversões de formato de dados (strings para lista, JSON parsing)

Avaliar um endpoint implantado

Para o endpoint Databricks Agent Framework ou servindo modelo, use to_predict_fn para criar uma função de previsão compatível.

Python

import mlflow
from mlflow.genai.scorers import RelevanceToQuery

# Create predict function for your endpoint
predict_fn = mlflow.genai.to_predict_fn("endpoints:/my-chatbot-endpoint")

# Evaluate
results = mlflow.genai.evaluate(
    data=[{"inputs": {"question": "How does MLflow work?"}}],
    predict_fn=predict_fn,
    scorers=[RelevanceToQuery()]
)

Benefício: extrai automaticamente os rastros do endpoint habilitado para rastreamento para total observabilidade.

Avaliar um modelo registrado

Wrap logs MLflow modelos para traduzir entre os parâmetros nomeados da avaliação e a interface de parâmetro único do modelo.

A maioria dos modelos registrados (como os que usam PyFunc ou versões de registro como LangChain) aceita um único parâmetro de entrada (por exemplo, model_inputs para PyFunc), enquanto predict_fn espera parâmetros nomeados que correspondam à chave em sua avaliação dataset.

Python

import mlflow
from mlflow.genai.scorers import Safety

# Make sure to load your logged model outside of the predict_fn so MLflow only loads it once!
model = mlflow.pyfunc.load_model("models:/chatbot/staging")

def evaluate_model(question: str) -> dict:
    return model.predict({"question": question})

results = mlflow.genai.evaluate(
    data=[{"inputs": {"question": "Tell me about MLflow"}}],
    predict_fn=evaluate_model,
    scorers=[Safety()]
)

Próximas etapas

• Avalie seu aplicativo - Guia passo a passo para realizar sua primeira avaliação
• Criar conjunto de dados de avaliação - Criar dados de teste estruturados a partir da produção logs ou do zero
• Definir pontuadores personalizados - Criar métricas adaptadas ao seu caso de uso específico