Como executar uma avaliação e ver os resultados

Prévia

Este artigo descreve como executar uma avaliação e ver os resultados utilizando o Mosaic AI Agent Evaluation.

Para executar uma análise, o senhor deve especificar um conjunto de análise. Um conjunto de avaliação é um conjunto de solicitações típicas que um usuário faria ao seu aplicativo agêntico. O conjunto de avaliação também pode incluir o resultado esperado para cada solicitação de entrada. O objetivo do conjunto de avaliação é ajudar o senhor a medir e prever o desempenho do seu aplicativo agêntico testando-o em perguntas representativas.

Para obter mais informações sobre conjuntos de avaliação, incluindo o esquema necessário, consulte Conjuntos de avaliação.

Para iniciar a avaliação, o senhor usa o método mlflow.evaluate() da API do MLflow. mlflow.evaluate() calcula métricas de qualidade, latência e custo para cada entrada no conjunto de avaliação e também calcula métricas agregadas em todas as entradas. Essas métricas também são chamadas de resultados da avaliação. O código a seguir mostra um exemplo de chamada de mlflow.evaluate():

%pip install databricks-agents
dbutils.library.restartPython()

import mlflow
import pandas as pd

eval_df = pd.DataFrame(...)

# Puts the evaluation results in the current Run, alongside the logged model parameters
with mlflow.start_run():
        logged_model_info = mlflow.langchain.log_model(...)
        mlflow.evaluate(data=eval_df, model=logged_model_info.model_uri,
                       model_type="databricks-agent")

Neste exemplo, mlflow.evaluate() logs seus resultados de avaliação no anexo MLflow execução, juntamente com os registros de informações de outros comandos (por exemplo, parâmetros do modelo). Se o senhor chamar mlflow.evaluate() fora de uma execução do MLflow, ele começará uma nova execução e a avaliação do logs resultará nessa execução. Para obter mais informações sobre mlflow.evaluate(), incluindo detalhes sobre os resultados da avaliação que são registrados na execução, consulte a documentaçãoMLflow .

Requisitos

Os recursos assistivos de IA desenvolvidos por parceiros devem estar habilitados para seu espaço de trabalho.

Como fornecer entrada para uma execução de avaliação

Há duas maneiras de apresentar informações para uma execução de avaliação:

Passe o aplicativo como um argumento de entrada. mlflow.evaluate() chama o aplicativo para cada entrada no conjunto de avaliação e calcula as métricas na saída gerada. Essa opção é recomendada se o seu aplicativo foi registrado usando MLflow com MLflow Tracing ativado ou se o seu aplicativo foi implementado como uma função Python em um Notebook.
Fornecer outputs gerados anteriormente para comparar com o conjunto de avaliação. Essa opção é recomendada se o aplicativo tiver sido desenvolvido fora da Databricks, se o senhor quiser avaliar os resultados de um aplicativo que já foi implantado na produção ou se quiser comparar os resultados da avaliação entre as configurações de avaliação.

Os exemplos de código a seguir mostram um exemplo mínimo para cada método. Para obter detalhes sobre o esquema do conjunto de avaliação, consulte Esquema do conjunto de avaliação.

Para que a chamada mlflow.evaluate() gere os outputs, especifique o conjunto de avaliação e o aplicativo na chamada de função, conforme mostrado no código a seguir. Para obter um exemplo mais detalhado, consulte Exemplo: Aplicativo de execução de avaliação de agentes.
```
evaluation_results = mlflow.evaluate(
    data=eval_set_df,  # pandas Dataframe containing just the evaluation set
    model=model,  # Reference to the MLflow model that represents the application
    model_type="databricks-agent",
)
```
Para fornecer saídas geradas anteriormente, especifique somente o conjunto de avaliação conforme mostrado no código a seguir, mas é importante que contenha as saídas geradas. Para obter um exemplo mais detalhado, consulte Exemplo: Saídas geradas fornecidas anteriormente.
```
evaluation_results = mlflow.evaluate(
    data=eval_set_with_chain_outputs_df,  # pandas Dataframe with the evaluation set and application outputs
    model_type="databricks-agent",
)
```

Saídas de avaliação

Uma avaliação gera dois tipos de resultados:

Dados sobre cada solicitação no conjunto de avaliação, incluindo o seguinte:
- Entradas enviadas para o aplicativo agêntico.
- A saída do aplicativo response
- Todos os dados intermediários gerados pelo aplicativo, como retrieved_context, trace e assim por diante.
- Classificações e justificativas de cada juiz de LLM especificado pela Databricks e especificado pelo cliente. As classificações caracterizam diferentes aspectos de qualidade dos resultados do aplicativo, incluindo correção, fundamentação, precisão de recuperação e assim por diante.
- Outras métricas baseadas no rastreamento do aplicativo, incluindo latência e contagem de tokens para diferentes passos.
Valores de métrica agregados em todo o conjunto de avaliação, como contagem média e total de tokens, latências médias e assim por diante.

Esses dois tipos de saídas são retornados de mlflow.evaluate() e também são registrados em uma execução do MLflow. Você pode inspecionar os resultados no notebook ou na página da execução do MLflow correspondente.

Revisar os resultados no Notebook

O código a seguir mostra alguns exemplos de como revisar os resultados de uma avaliação executada em seu Notebook.

%pip install databricks-agents pandas
dbutils.library.restartPython()

import mlflow
import pandas as pd

###
# Run evaluation
###
evaluation_results = mlflow.evaluate(..., model_type="databricks-agent")

###
# Access aggregated metric values across the entire evaluation set
###
metrics_as_dict = evaluation_results.metrics
metrics_as_pd_df = pd.DataFrame([evaluation_results.metrics])

# Sample usage
print(f"The percentage of generated responses that are grounded: {metrics_as_dict['response/llm_judged/groundedness/percentage']}")


###
# Access data about each question in the evaluation set
###

per_question_results_df = evaluation_results.tables['eval_results']

# Show information about responses that are not grounded
per_question_results_df[per_question_results_df["response/llm_judged/groundedness/rating"] == "no"].display()

O dataframe por solicitação inclui todas as colunas no esquema de entrada e todas as métricas de computação específicas de cada solicitação. Para obter mais detalhes sobre cada métrica relatada, consulte Use agent métricas & LLM judges to evaluate app desempenho.

Revise a saída utilizando a interface do usuário do MLflow

Os resultados da sua avaliação também estão disponíveis na IU do MLflow. Para acessar a interface do usuário do MLflow, clique no ícone Experimentar na barra lateral direita do Notebook ou clique nos links que aparecem nos resultados da célula do Notebook na qual você executou mlflow.evaluate().

Métricas agregadas no conjunto de avaliação completo (MLflow UI)

Para ver os valores das métricas agregadas em todo o conjunto de avaliação, clique na página do experimento. Isso possibilita que você veja as métricas da execução selecionada e compare com execuções anteriores.

Você também pode ver os valores métricos agregados na página de execução, utilizando a tab Visão geral (para valores numéricos) ou a tab Métricas do modelo (para gráficos).

Métricas agregadas na tab Overview (Visão geral)

Métricas agregadas na tab Métricas do modelo

Dados sobre cada solicitação no conjunto de avaliação (MLflow UI)

Para ver os dados de cada solicitação individual no conjunto de avaliação, clique na tab Evaluation (Avaliação) na página Experiment (Experimente). Uma tabela mostra cada pergunta do conjunto de avaliação. Use os menus suspensos para selecionar as colunas a serem exibidas.

Perguntas individuais no conjunto de avaliação

Você também pode ver os resultados na página de execução. Clique na tab Artefatos e selecione o artefato eval_results.json.

tabela de resultados de avaliação na tab artefatos

Exemplos de chamadas`mlflow.evaluate()`

Esta seção inclui exemplos de código de chamadas mlflow.evaluate(), ilustrando opções para passar o aplicativo e o conjunto de avaliação para a chamada.

Exemplo: Aplicativo de execução de avaliação de agentes

%pip install databricks-agents pandas
dbutils.library.restartPython()

import mlflow
import pandas as pd

###
# mlflow.evaluate() call
###
evaluation_results = mlflow.evaluate(
    data=eval_set_df,  # pandas DataFrame with just the evaluation set
    model=model,  # Reference to the application
    model_type="databricks-agent",
)

###
# There are 4 options for passing an application in the `model` argument.
####

#### Option 1. Reference to a Unity Catalog registered model
model = "models:/catalog.schema.model_name/1"  # 1 is the version number

#### Option 2. Reference to a MLflow logged model in the current MLflow Experiment
model = "runs:/6b69501828264f9s9a64eff825371711/chain"
# `6b69501828264f9s9a64eff825371711` is the run_id, `chain` is the artifact_path that was
# passed when calling mlflow.xxx.log_model(...).
# If you called model_info = mlflow.langchain.log_model() or mlflow.pyfunc.log_model(), you can access this value using `model_info.model_uri`.

#### Option 3. A PyFunc model that is loaded in the notebook
model = mlflow.pyfunc.load_model(...)

#### Option 4. A local function in the notebook
def model_fn(model_input):
  # code that implements the application
  response = 'the answer!'
  return response

model = model_fn

###
# `data` is a pandas DataFrame with your evaluation set.
# These are simple examples. See the input schema for details.
####

# You do not have to start from a dictionary - you can use any existing pandas or
# Spark DataFrame with this schema.

# Minimal evaluation set
bare_minimum_eval_set_schema = [
    {
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
    }]

# Complete evaluation set
complete_eval_set_schema = [
    {
        "request_id": "your-request-id",
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "expected_retrieved_context": [
            {
                # In `expected_retrieved_context`, `content` is optional, and does not provide any additional functionality.
                "content": "Answer segment 1 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_1",
            },
            {
                "content": "Answer segment 2 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_2",
            },
        ],
        "expected_response": "There's no significant difference.",
    }]

#### Convert dictionary to a pandas DataFrame
eval_set_df = pd.DataFrame(bare_minimum_eval_set_schema)

#### Use a Spark DataFrame
import numpy as np
spark_df = spark.table("catalog.schema.table") # or any other way to get a Spark DataFrame
eval_set_df = spark_df.toPandas()

Exemplo: Saídas geradas fornecidas anteriormente

Para o esquema do conjunto de avaliação necessário, consulte Conjuntos de avaliação.

%pip install databricks-agents pandas
dbutils.library.restartPython()

import mlflow
import pandas as pd

###
# mlflow.evaluate() call
###
evaluation_results = mlflow.evaluate(
    data=eval_set_with_app_outputs_df,  # pandas Dataframe with the evaluation set and application outputs
    model_type="databricks-agent",
)

###
# `data` is a pandas DataFrame with your evaluation set and outputs generated by the application.
# These are simple examples. See the input schema for details.
####

# You do not have to start from a dictionary - you can use any existing pandas or
# Spark DataFrame with this schema.

# Bare minimum data
bare_minimum_input_schema = [
    {
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "response": "reduceByKey aggregates data before shuffling, whereas groupByKey shuffles all data, making reduceByKey more efficient.",
    }]

complete_input_schema  = [
    {
        "request_id": "your-request-id",
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "expected_retrieved_context": [
            {
                # In `expected_retrieved_context`, `content` is optional, and does not provide any additional functionality.
                "content": "Answer segment 1 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_1",
            },
            {
                "content": "Answer segment 2 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_2",
            },
        ],
        "expected_response": "There's no significant difference.",
        "response": "reduceByKey aggregates data before shuffling, whereas groupByKey shuffles all data, making reduceByKey more efficient.",
        "retrieved_context": [
            {
                # In `retrieved_context`, `content` is optional. If provided, the Databricks Context Relevance LLM Judge is executed to check the `content`'s relevance to the `request`.
                "content": "reduceByKey reduces the amount of data shuffled by merging values before shuffling.",
                "doc_uri": "doc_uri_2_1",
            },
            {
                "content": "groupByKey may lead to inefficient data shuffling due to sending all values across the network.",
                "doc_uri": "doc_uri_6_extra",
            },
        ],
    }]

#### Convert dictionary to a pandas DataFrame
eval_set_with_app_outputs_df = pd.DataFrame(bare_minimum_input_schema)

#### Use a Spark DataFrame
import numpy as np
spark_df = spark.table("catalog.schema.table") # or any other way to get a Spark DataFrame
eval_set_with_app_outputs_df = spark_df.toPandas()