Como executar uma avaliação e exibir os resultados
Importante
Esse recurso está em uma versão prévia.
Este artigo descreve como executar uma avaliação e exibir os resultados à medida que você desenvolve seu aplicativo de IA. Para obter informações sobre como monitorar a qualidade dos agentes implantados no tráfego de produção, consulte Como monitorar a qualidade do seu agente no tráfego de produção.
Para usar a Avaliação do Agente durante o desenvolvimento do aplicativo, você deve especificar um conjunto de avaliação. Um conjunto de avaliação é um conjunto de solicitações típicas que um usuário faria ao seu aplicativo. O conjunto de avaliação também pode incluir a resposta esperada (verdade fundamental) para cada solicitação de entrada. Se a resposta esperada for fornecida, a Avaliação do Agente poderá calcular métricas de qualidade adicionais, como correção e suficiência de contexto. A finalidade do conjunto de avaliação é ajudar a medir e prever o desempenho do aplicativo agente testando-o em perguntas representativas.
Para obter mais informações sobre conjuntos de avaliação, consulte Conjuntos de avaliação. Para obter o esquema necessário, consulte Esquema de entrada de Avaliação do Agente.
Para iniciar a avaliação, use o método mlflow.evaluate() da API do MLflow. mlflow.evaluate() Calcula as avaliações de qualidade junto com as métricas de latência e custo para cada entrada no conjunto de avaliação e também agrega esses resultados em todas as entradas. Esses resultados também são chamados de resultados da avaliação. O código a seguir mostra um exemplo da chamada 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() registra seus resultados de avaliação na execução do MLflow delimitador, juntamente com as informações registradas por outros comandos (como parâmetros de modelo). Se você chamar mlflow.evaluate() fora de uma execução do MLflow, ela iniciará uma nova execução e registrará os resultados da avaliação nessa execução. Para obter mais informações sobre mlflow.evaluate(), incluindo detalhes sobre os resultados da avaliação registrados na execução, consulte a documentação do MLflow.
Requisitos
Os recursos auxiliares de IA da plataforma AI devem ser habilitados para o espaço de trabalho.
Como fornecer entrada para uma execução de avaliação
Há duas maneiras de fornecer entrada para uma execução de avaliação:
Forneça saídas geradas anteriormente para comparar com o conjunto de avaliação. Essa opção será recomendada se você quiser avaliar as saídas de um aplicativo que já estiver implantado na produção, ou se quiser comparar os resultados da avaliação entre as configurações de avaliação.
Com essa opção, você especifica um conjunto de avaliação, conforme mostrado no código a seguir. O conjunto de avaliação deve incluir saídas geradas anteriormente. Para obter exemplos mais detalhados, consulte Exemplo: Como passar saídas geradas anteriormente para a Avaliação do agente.
evaluation_results = mlflow.evaluate( data=eval_set_with_chain_outputs_df, # pandas DataFrame with the evaluation set and application outputs model_type="databricks-agent", )Passe o aplicativo como um argumento de entrada.
mlflow.evaluate()chama o aplicativo para cada entrada no conjunto de avaliação e relata avaliações de qualidade e outras métricas para cada saída gerada. Essa opção será recomendada se o seu aplicativo tiver sido registrado usando o MLflow com o Rastreamento do MLflow habilitado ou se ele for implementado como uma função Python em um notebook. Essa opção não é recomendada se o aplicativo foi desenvolvido ou estiver implantado fora do Databricks.Com essa opção, você especifica o conjunto de avaliação e o aplicativo na chamada de função, conforme mostrado no código a seguir. Para obter exemplos mais detalhados, consulte Exemplo: Como passar um aplicativo para a Avaliação do Agente.
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 obter detalhes sobre o esquema do conjunto de avaliação, consulte Esquema de entrada de Avaliação do Agente.
Saídas de avaliação
A Avaliação do Agente retorna suas saídas como mlflow.evaluate() dataframes e também registra essas saídas na execução do MLflow. Você pode inspecionar as saídas no notebook ou na página da execução do MLflow correspondente.
Revisar a saída no notebook
O código a seguir mostra alguns exemplos de como examinar os resultados de uma execução de avaliação do 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 evaluation results across the entire evaluation set
###
results_as_dict = evaluation_results.metrics
results_as_pd_df = pd.DataFrame([evaluation_results.metrics])
# Sample usage
print(f"The percentage of generated responses that are grounded: {results_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 per_question_results_df dataframe inclui todas as colunas no esquema de entrada e todos os resultados de avaliação específicos de cada solicitação. Para obter mais detalhes sobre os resultados calculados, consulte Como a qualidade, o custo e a latência são avaliados pela Avaliação do Agente.
Examinar a saída usando a interface do usuário do MLflow
Os resultados da avaliação também estão disponíveis na interface do usuário do MLflow. Para acessar a interface do usuário do MLflow, clique no ícone experimento 
na barra lateral direita do bloco de anotações e, em seguida, na execução correspondente, ou clique nos links que aparecem nos resultados da célula para a célula do notebook na qual você executou mlflow.evaluate().
Revisar os resultados da avaliação para uma única execução
Esta seção descreve como revisar os resultados da avaliação de uma execução individual. Para comparar os resultados entre execuções, consulte Comparar resultados de avaliação entre execuções.
Visão geral das avaliações de qualidade por juízes de LLM
As avaliações por juiz de solicitação estão disponíveis na databricks-agents versão 0.3.0 e superior.
Para ver uma visão geral da qualidade julgada pelo LLM de cada solicitação no conjunto de avaliação, clique na guia Resultados da avaliação na página Execução do MLflow. Esta página mostra uma tabela de resumo de cada execução de avaliação. Para obter mais detalhes, clique na ID de Avaliação de uma execução.
Esta visão geral mostra as avaliações de diferentes juízes para cada solicitação, o status de qualidade/reprovação de cada solicitação com base nessas avaliações e a causa raiz das solicitações com falha. Clicar em uma linha na tabela levará você à página de detalhes dessa solicitação, que inclui o seguinte:
- Saída do modelo: a resposta gerada do aplicativo agente e seu rastreamento, se incluído.
- Saída esperada: a resposta esperada para cada solicitação.
- Avaliações detalhadas: as avaliações dos juízes LLM sobre esses dados. Clique em Ver detalhes para exibir as justificativas fornecidas pelos juízes.
Resultados agregados em todo o conjunto de avaliação
Para ver os resultados agregados em todo o conjunto de avaliação, clique na guia Visão geral (para valores numéricos) ou na guia Métricas do modelo (para gráficos).
Compare os resultados da avaliação entre as execuções
É importante comparar os resultados da avaliação entre execuções para ver como seu aplicativo agente responde às alterações. Comparar resultados pode ajudá-lo a entender se suas alterações estão afetando positivamente a qualidade ou ajudar você a solucionar problemas de alteração de comportamento.
Comparar resultados por solicitação entre execuções
Para comparar dados de cada solicitação individual entre execuções, clique na guia Avaliação na página Experimento. Uma tabela mostra cada pergunta no conjunto de avaliação. Use os menus suspensos para selecionar as colunas a serem visualizadas.
Compare os resultados agregados entre as execuções
Você pode acessar os mesmos resultados agregados na página Experimento, que também permite comparar os resultados em diferentes execuções. Para acessar a página Experimento, clique no ícone Experimento na barra lateral direita do bloco de anotações ou clique nos links que aparecem nos resultados da célula para a célula do bloco de anotações na qual você executou mlflow.evaluate().
Na página Experimento, clique em 
. Isso permite que você visualize os resultados agregados para a execução selecionada e compare com as execuções anteriores.
Quais juízes são executados
Por padrão, para cada registro de avaliação, a Avaliação do Agente do Mosaic AI aplica o subconjunto de juízes que melhor corresponde às informações presentes no registro. Especificamente:
- Se o registro incluir uma resposta de verdade, a Avaliação do Agente aplicará os
context_sufficiencyjuízes ,groundedness,correctness, esafety. - Se o registro não incluir uma resposta de verdade, a Avaliação do Agente aplicará os
chunk_relevancejuízes ,groundedness,relevance_to_query, esafety.
Você também pode especificar explicitamente os juízes a serem aplicados a cada solicitação usando o evaluator_config argumento da mlflow.evaluate() seguinte maneira:
# Complete list of built-in LLM judges
# "chunk_relevance", "context_sufficiency", "correctness", "groundedness", "relevance_to_query", "safety"
evaluation_results = mlflow.evaluate(
data=eval_df,
model_type="databricks-agent",
evaluator_config={
"databricks-agent": {
# Run only LLM judges that don't require ground-truth. Use an empty list to not run any built-in judge.
"metrics": ["groundedness", "relevance_to_query", "chunk_relevance", "safety"]
}
}
)
Observação
Não é possível desabilitar as métricas de avaliadores não LLM para recuperação de partes, contagens de tokens de cadeia ou latência.
Além dos juízes integrados, você pode definir um juiz LLM personalizado para avaliar critérios específicos para seu caso de uso. Consulte Personalizar juízes do LLM.
Consulte Informações sobre os modelos que alimentam os avaliadores LLM para obter informações sobre confiança e segurança dos avaliadores LLM.
Para obter mais detalhes sobre os resultados e as métricas da avaliação, consulte Como a qualidade, o custo e a latência são avaliados pela Avaliação do Agente.
Exemplo: Como passar um aplicativo para a Avaliação do Agente
Para passar um aplicativo para mlflow_evaluate(), use o model argumento. Existem 5 opções para passar um aplicativo no model argumento.
- Um modelo registrado no Catálogo do Unity.
- Um modelo registrado do MLflow no experimento atual do MLflow.
- Um modelo PyFunc que é carregado no notebook.
- Uma função local no notebook.
- Um ponto de extremidade do agente implantado.
Consulte as seções a seguir para obter exemplos de código que ilustram cada opção.
Opção 1. Modelo registrado no Catálogo do Unity
%pip install databricks-agents pandas
dbutils.library.restartPython()
import mlflow
import pandas as pd
evaluation_results = mlflow.evaluate(
data=eval_set_df, # pandas DataFrame with just the evaluation set
model = "models:/catalog.schema.model_name/1" # 1 is the version number
model_type="databricks-agent",
)
Opção 2. Modelo registrado do MLflow no experimento atual do MLflow
%pip install databricks-agents pandas
dbutils.library.restartPython()
import mlflow
import pandas as pd
# In the following lines, `6b69501828264f9s9a64eff825371711` is the run_id, and `chain` is the artifact_path that was
# passed with 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`.
evaluation_results = mlflow.evaluate(
data=eval_set_df, # pandas DataFrame with just the evaluation set
model = "runs:/6b69501828264f9s9a64eff825371711/chain"
model_type="databricks-agent",
)
Opção 3. Modelo PyFunc carregado no notebook
%pip install databricks-agents pandas
dbutils.library.restartPython()
import mlflow
import pandas as pd
evaluation_results = mlflow.evaluate(
data=eval_set_df, # pandas DataFrame with just the evaluation set
model = mlflow.pyfunc.load_model(...)
model_type="databricks-agent",
)
Opção 4. Função local no notebook
A função recebe uma entrada formatada da seguinte maneira:
{
"messages": [
{
"role": "user",
"content": "What is MLflow?",
}
],
...
}
A função deve retornar um valor em um dos três formatos com suporte a seguir:
Cadeia de caracteres simples que contém a resposta do modelo.
Um dicionário em
ChatCompletionResponseformato. Por exemplo:{ "choices": [ { "message": { "role": "assistant", "content": "MLflow is a machine learning toolkit.", }, ... } ], ..., }Um dicionário em
StringResponseformato, como{ "content": "MLflow is a machine learning toolkit.", ... }.
O exemplo a seguir usa uma função local para encapsular um ponto de extremidade do modelo de base e avaliá-lo:
%pip install databricks-agents pandas
dbutils.library.restartPython()
import mlflow
import pandas as pd
def model(model_input):
client = mlflow.deployments.get_deploy_client("databricks")
return client.predict(endpoint="endpoints:/databricks-meta-llama-3-1-405b-instruct", inputs={"messages": model_input["messages"]})
evaluation_results = mlflow.evaluate(
data=eval_set_df, # pandas DataFrame with just the evaluation set
model = model
model_type="databricks-agent",
)
Opção 5. Ponto de extremidade do agente implantado
Essa opção só funciona quando você usa endpoints de agente que foram implantados usando databricks.agents.deploy e com databricks-agents a versão 0.8.0 do SDK ou superior. Para modelos de base ou versões mais antigas do SDK, use a Opção 4 para encapsular o modelo em uma função local.
%pip install databricks-agents pandas
dbutils.library.restartPython()
import mlflow
import pandas as pd
# In the following lines, `endpoint-name-of-your-agent` is the name of the agent endpoint.
evaluation_results = mlflow.evaluate(
data=eval_set_df, # pandas DataFrame with just the evaluation set
model = "endpoints:/endpoint-name-of-your-agent"
model_type="databricks-agent",
)
Como passar na avaliação definida quando o aplicativo é incluído na mlflow_evaluate() chamada
No código a seguir, data há um DataFrame do pandas com seu conjunto de avaliação. Estes são exemplos simples. Consulte o esquema de entrada para obter detalhes.
# 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: Como passar saídas geradas anteriormente para a Avaliação do Agente
Esta seção descreve como passar saídas geradas anteriormente na mlflow_evaluate() chamada. Para obter o esquema do conjunto de avaliação necessário, consulte Esquema de entrada de Avaliação do Agente.
No código a seguir, data há um DataFrame do pandas com seu conjunto de avaliação e saídas geradas pelo aplicativo. Estes são exemplos simples. Consulte o esquema de entrada para obter detalhes.
%pip install databricks-agents pandas
dbutils.library.restartPython()
import mlflow
import pandas as pd
evaluation_results = mlflow.evaluate(
data=eval_set_with_app_outputs_df, # pandas DataFrame with the evaluation set and application outputs
model_type="databricks-agent",
)
# You do not have to start from a dictionary - you can use any existing pandas or Spark DataFrame with this schema.
# Minimum required input
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.",
}]
# Input including optional arguments
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()
Exemplo: usar uma função personalizada para processar respostas do LangGraph
Os agentes do LangGraph, especialmente aqueles com funcionalidade de bate-papo, podem retornar várias mensagens para uma única chamada de inferência. É responsabilidade do usuário converter a resposta do agente em um formato compatível com a Avaliação do Agente.
Uma abordagem é usar uma função personalizada para processar a resposta. O exemplo a seguir mostra uma função personalizada que extrai a última mensagem de chat de um modelo LangGraph. Essa função é então usada para mlflow.evaluate() retornar uma única resposta de cadeia de caracteres, que pode ser comparada ground_truth à coluna.
O código de exemplo faz as seguintes suposições:
- O modelo aceita entrada no formato {"messages": [{"role": "user", "content": "hello"}]}.
- O modelo retorna uma lista de cadeias de caracteres no formato ["response 1", "response 2"].
O código a seguir envia as respostas concatenadas ao juiz neste formato: "response 1nresponse2"
import mlflow
import pandas as pd
from typing import List
loaded_model = mlflow.langchain.load_model(model_uri)
eval_data = pd.DataFrame(
{
"inputs": [
"What is MLflow?",
"What is Spark?",
],
"expected_response": [
"MLflow is an open-source platform for managing the end-to-end machine learning (ML) lifecycle. It was developed by Databricks, a company that specializes in big data and machine learning solutions. MLflow is designed to address the challenges that data scientists and machine learning engineers face when developing, training, and deploying machine learning models.",
"Apache Spark is an open-source, distributed computing system designed for big data processing and analytics. It was developed in response to limitations of the Hadoop MapReduce computing model, offering improvements in speed and ease of use. Spark provides libraries for various tasks such as data ingestion, processing, and analysis through its components like Spark SQL for structured data, Spark Streaming for real-time data processing, and MLlib for machine learning tasks",
],
}
)
def custom_langgraph_wrapper(model_input):
predictions = loaded_model.invoke({"messages": model_input["messages"]})
# Assuming `predictions` is a list of strings
return predictions.join("\n")
with mlflow.start_run() as run:
results = mlflow.evaluate(
custom_langgraph_wrapper, # Pass the function defined above
data=eval_data,
model_type="databricks-agent",
)
print(results.metrics)
Criar um painel com métricas
Ao iterar a qualidade do seu agente, talvez queira compartilhar um painel com as partes interessadas que mostre como a qualidade melhorou ao longo do tempo. Você pode extrair as métricas de suas execuções de avaliação do MLflow, salvar os valores em uma tabela Delta e criar um painel.
O exemplo a seguir mostra como extrair e salvar os valores de métrica da execução de avaliação mais recente em seu notebook:
uc_catalog_name = "catalog"
uc_schema_name = "schema"
table_name = "results"
eval_results = mlflow.evaluate(
model=logged_agent_info.model_uri, # use the logged Agent
data=evaluation_set, # Run the logged Agent for all queries defined above
model_type="databricks-agent", # use Agent Evaluation
)
# The `append_metrics_to_table function` is defined below
append_metrics_to_table("<identifier-for-table>", eval_results.metrics, f"{uc_catalog_name}.{uc_schema_name}.{table_name}")
O exemplo a seguir mostra como extrair e salvar valores de métrica para execuções anteriores que você salvou em seu experimento do MLflow.
import pandas as pd
def get_mlflow_run(experiment_name, run_name):
runs = mlflow.search_runs(experiment_names=[experiment_name], filter_string=f"run_name = '{run_name}'", output_format="list")
if len(runs) != 1:
raise ValueError(f"Found {len(runs)} runs with name {run_name}. {run_name} must identify a single run. Alternatively, you can adjust this code to search for a run based on `run_id`")
return runs[0]
run = get_mlflow_run(experiment_name ="/Users/<user_name>/db_docs_mlflow_experiment", run_name="evaluation__2024-10-09_02:27:17_AM")
# The `append_metrics_to_table` function is defined below
append_metrics_to_table("<identifier-for-table>", run.data.metrics, f"{uc_catalog_name}.{uc_schema_name}.{table_name}")
Agora você pode criar um painel usando esses dados.
O código a seguir define a função append_metrics_to_table usada nos exemplos anteriores.
# Definition of `append_metrics_to_table`
def append_metrics_to_table(run_name, mlflow_metrics, delta_table_name):
data = mlflow_metrics.copy()
# Add identifying run_name and timestamp
data["run_name"] = run_name
data["timestamp"] = pd.Timestamp.now()
# Remove metrics with error counts
data = {k: v for k, v in mlflow_metrics.items() if "error_count" not in k}
# Convert to a Spark DataFrame(
metrics_df = pd.DataFrame([data])
metrics_df_spark = spark.createDataFrame(metrics_df)
# Append to the Delta table
metrics_df_spark.write.mode("append").saveAsTable(delta_table_name)
Limitação
Para conversas de vários turnos, a saída da avaliação registra apenas a última entrada na conversa.
Informações sobre os modelos que alimentam os avaliadores LLM
- Os avaliadores LLM podem usar serviços de terceiros para avaliar os aplicativos GenAI, incluindo o Azure OpenAI operado pela Microsoft.
- Para o Azure OpenAI, a Databricks optou por não usar o Monitoramento de Abuso, portanto, nenhum prompt ou resposta é armazenado com o Azure OpenAI.
- Para workspaces da União Europeia (UE), os avaliadores LLM usam modelos hospedados na Europa. Todas as outras regiões usam modelos hospedados nos EUA.
- Desabilitar os Serviços de IA do Azure Recursos de assistência de IA impedem que o avaliador de LLM chame os modelos da plataforma de IA do Azure.
- Os dados enviados ao avaliador de LLM não são usados para nenhum treinamento de modelo.
- Avaliadores LLM destinam-se a ajudar os clientes a avaliar os aplicativos RAG, e os resultados dos avaliadores LLM não devem ser utilizados para treinar, melhorar ou fazer um ajuste fino no LLM.