Esquema de entrada da Agent Evaluation (MLflow 2)

importante

A Databricks recomenda usar o MLflow 3 para a avaliação e monitoramento de aplicativos GenAI. Esta página descreve o MLflow 2 Agent Evaluation.

Para uma introdução à avaliação e monitoramento no MLflow 3, consulte Avalie e monitore agentes de AI.
Para informações sobre a migração para o MLflow 3, consulte Migrar para o MLflow 3 a partir da Agent Evaluation.
Para informações sobre o MLflow 3 neste tópico, consulte Criando conjuntos de dados de avaliação do MLflow.

Este artigo explica o esquema de entrada exigido pelo Agent Evaluation para avaliar a qualidade, o custo e a latência do seu aplicativo.

Durante o desenvolvimento, a avaliação ocorre off-line, e um conjunto de avaliação é uma entrada obrigatória para a Agent Evaluation.
Quando um aplicativo está em produção, todas as entradas para o Agent Evaluation vêm de suas tabelas de inferência ou logs de produção.

O esquema de entrada é idêntico para avaliações online e offline.

Para informações gerais sobre conjuntos de avaliação, consulte Conjuntos de avaliação (MLflow 2).

Esquema de entrada da avaliação

A tabela a seguir mostra o esquema de entrada do Agent Evaluation. As duas últimas colunas da tabela referem-se a como a entrada é fornecida à chamada mlflow.evaluate(). Consulte Fornecer entradas para uma execução de avaliação para obter detalhes.

Coluna	Tipo de dados	Descrição	Aplicativo passado como argumento de entrada	Saídas geradas fornecidas anteriormente
request_id	string	Identificador único da solicitação.	Opcional	Opcional
solicitação	Consulte Esquema para solicitação.	Entrada para o aplicativo avaliar, pergunta ou consulta do usuário. Por exemplo, `{'messages': [{"role": "user", "content": "What is RAG"}]}` ou “O que é RAG?”. Quando `request` é fornecido como uma string, ele será transformado em `messages` antes de ser passado para seu agente.	Obrigatório	Obrigatório
Resposta	Consulte Esquema para resposta.	Resposta gerada pelo aplicativo que está sendo avaliado.	Gerado pela avaliação do agente	Opcional. Se não for fornecido, será derivado do Trace. É necessário `response` ou `trace`.
expected_facts	matriz de strings	Uma lista de fatos que são esperados na saída do modelo. Consulte diretrizes`expected_facts`.	Opcional	Opcional
expected_response	string	Resposta verdadeira (correta) para a solicitação de entrada. Consulte diretrizes`expected_response`.	Opcional	Opcional
diretrizes	`guidelines` diretrizes	Um dicionário nomeado ou uma lista de diretrizes às quais se espera que a saída do modelo adira. Consulte `guidelines` diretrizes.	Opcional	Opcional
expected_retrieved_context	matriz	Matriz de objetos que contém o contexto recuperado esperado para a solicitação (se o aplicativo incluir o passo de recuperação). Esquema de matriz	Opcional	Opcional
retrieved_context	matriz	Resultados de recuperação gerados pelo recuperador no aplicativo que está sendo avaliado. Se houver vários os passos de recuperação no aplicativo, estes são os resultados de recuperação do último o passo (cronologicamente no rastreamento). Esquema de array	Gerado pela avaliação do agente	Opcional. Se não for fornecido, será derivado do rastreamento fornecido.
trace	Cadeia de caracteres JSON de MLflow Trace	Rastreamento do MLflow da execução do aplicativo na solicitação correspondente.	Gerado pela avaliação do agente	Opcional. É necessário `response` ou `trace`.

`expected_facts` diretrizes

O campo expected_facts especifica a lista de fatos que se espera que apareça em qualquer resposta de modelo correta para a solicitação de entrada específica. Ou seja, uma resposta de modelo é considerada correta se contiver esses fatos, independentemente de como a resposta é formulada.

Incluir apenas os fatos necessários e omitir aqueles que não são estritamente exigidos na resposta permite que o Agent Evaluation forneça um sinal mais robusto sobre a qualidade da saída.

Você pode especificar no máximo um de expected_facts e expected_response. Se você especificar ambos, um erro será relatado. O Databricks recomenda usar expected_facts, pois é uma diretriz mais específica que ajuda o Agent Evaluation a julgar a qualidade das respostas geradas de forma mais eficaz.

`guidelines` diretrizes

O campo guidelines especifica um conjunto de diretrizes às quais qualquer resposta de modelo correta deve aderir. guidelines pode ser expresso em dois formatos:

A lista de diretrizes (List[str]) fornece um único conjunto de diretrizes.
As diretrizes nomeadas (Dict[str, List[str]]) fornecem um mapeamento de um nome de diretriz para um array de diretrizes para esse nome. As diretrizes nomeadas exigem databricks-agents >= 0.16.0.

As diretrizes podem se referir a vários aspectos da resposta, incluindo elementos estilísticos ou relacionados ao conteúdo. Para o sinal mais robusto sobre a conformidade com as diretrizes, a Databricks recomenda usar a seguinte linguagem:

“A resposta deve...”
“A resposta não deve…”
“A resposta pode, opcionalmente…”

Especificamente, você deve se referir à solicitação e resposta diretamente e deixar o mínimo de ambiguidade possível nas diretrizes. Para diretrizes que se aplicam a todo o seu conjunto de avaliação, como garantir que as respostas tenham um tom profissional ou estejam sempre em inglês, use o parâmetro global_guidelines na configuração do avaliador da seguinte forma:

Python
eval_set = [
    {
        "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.",
        # Note: You can also just pass an array to `guidelines`.
        "guidelines": {
            "english": ["The response must be in English"],
            "clarity": ["The response must be clear, coherent, and concise"],
        }
    }
]

mlflow.evaluate(
    data=pd.DataFrame(eval_set),
    model_type="databricks-agent",
    evaluator_config={
        &quot;databricks-agent&quot;: {
            # Note: You can also just pass an array to `guidelines`.
            &quot;global_guidelines&quot;: {
                &quot;english&quot;: [&quot;The response must be in English&quot;],
                &quot;clarity&quot;: [&quot;The response must be clear, coherent, and concise&quot;],
            }
        }
    }
)

`expected_response` diretrizes

O campo expected_response contém uma resposta totalmente formada que representa uma referência para respostas corretas do modelo. Ou seja, uma resposta do modelo é considerada correta se corresponder ao conteúdo da informação em expected_response. Em contraste, expected_facts lista apenas os fatos que são necessários para aparecer em uma resposta correta e não é uma resposta de referência totalmente formada.

Semelhante a expected_facts, expected_response deve conter apenas o conjunto mínimo de fatos necessário para uma resposta correta. Incluir apenas a informação necessária, e omitir a informação que não é estritamente necessária na resposta, permite que a Agent Evaluation forneça um sinal mais robusto sobre a qualidade da saída.

Esquema para solicitação

O esquema de solicitação pode ser um dos seguintes:

Um dicionário serializável arbitrário (por exemplo, Dict[str, Any])
Se o agente suportar o esquema de conclusão de chat da OpenAI, você pode passar uma strings simples. Este formato suporta somente conversas de turno único. Strings simples são convertidas para o formato messages com "role": "user" antes de serem passadas para o seu agente. Por exemplo, uma strings simples "What is MLflow?" é convertida para {"messages": [{"role": "user", "content": "What is MLflow?"}]} antes de ser passada para o seu agente.

Observe que os avaliadores integrados funcionam melhor com qualquer formato utilizando um esquema de conclusão de chat da OpenAI. O esquema de conclusão de chat da OpenAI deve ter uma matriz de objetos como um parâmetro messages. O campo messages pode codificar a conversa completa.

O exemplo a seguir mostra algumas opções possíveis na mesma coluna request do dataset de avaliação:

Python
import pandas as pd

data = {
  "request": [

      # Plain string. Plain strings are transformed to the `messages` format before being passed to your agent.
      "What is the difference between reduceByKey and groupByKey in Spark?",

      # OpenAI chat completion schema. Use the `messages` field for a single- or multi-turn chat.
      {
          "messages": [
              {
                  "role": "user",
                  "content": "How can you minimize data shuffling in Spark?"
              }
          ]
      },

      # SplitChatMessagesRequest. Use the `query` and `history` fields for a single- or multi-turn chat.
      {
          "query": "Explain broadcast variables in Spark. How do they enhance performance?",
          "history": [
              {
                  "role": "user",
                  "content": "What are broadcast variables?"
              },
              {
                  "role": "assistant",
                  "content": "Broadcast variables allow the programmer to keep a read-only variable cached on each machine."
              }
          ]
      },

      # Arbitrary format. These must be JSON-serializable and are passed directly to your agent.
      {
        "message_history": [
            {
                "user_0": "What are broadcast variables?",
                "assistant_0": "Broadcast variables allow the programmer to keep a read-only variable cached on each machine.",
            }
        ],
        "last_user_request": "How can you minimize data shuffling in Spark?"
      },
  ],

  "expected_response": [
    "expected response for first question",
    "expected response for second question",
    "expected response for third question",
    "expected response for fourth question",
  ]
}

eval_dataset = pd.DataFrame(data)

Esquema para resposta

O esquema de resposta, semelhante ao esquema de solicitação, pode ser um dos seguintes:

Um dicionário serializável arbitrário (por exemplo, Dict[str, Any]).
Se o agente suportar o esquema de conclusão de chat da OpenAI, você pode passar uma strings simples. Este formato suporta somente conversas de turno único. Strings simples são convertidas para o formato choices. Por exemplo, uma string simples "MLFlow is a framework." é convertida para {"choices": [{"message": {"content": "MLFlow is a framework."}}]}.

Esquema para matrizes na entrada de avaliação

O esquema das matrizes expected_retrieved_context e retrieved_context é apresentado na tabela a seguir:

Coluna	Tipo de dados	Descrição	Aplicativo passado como argumento de entrada	Saídas geradas fornecidas anteriormente
conteúdo	string	Conteúdo do contexto recuperado. Cadeia de caracteres em qualquer formato, como HTML, texto sem formatação ou Markdown.	Opcional	Opcional
doc_uri	string	Identificador exclusivo (URI) do documento pai de onde veio a parte.	Obrigatório	Obrigatório

Métricas computadas

As colunas na tabela a seguir indicam os dados incluídos na entrada, e ✓ indica que a métrica é suportada quando esses dados são fornecidos.

Para obter detalhes sobre o que essas métricas medem, consulte Como a qualidade, o custo e a latência são avaliados pelo Agent Evaluation (MLflow 2).

Métricas calculadas	`request`	`request` e `expected_response`	`request`, `expected_response`, `expected_retrieved_context`, e `guidelines`	`request` e `expected_retrieved_context`	`request` e `guidelines`
`response/llm_judged/relevance_to_query/rating`	✓	✓	✓
`response/llm_judged/safety/rating`	✓	✓	✓
`response/llm_judged/groundedness/rating`	✓	✓	✓
`retrieval/llm_judged/chunk_relevance_precision`	✓	✓	✓
`agent/total_token_count`	✓	✓	✓
`agent/input_token_count`	✓	✓	✓
`agent/output_token_count`	✓	✓	✓
`response/llm_judged/correctness/rating`		✓	✓
`retrieval/llm_judged/context_sufficiency/rating`		✓	✓
`retrieval/ground_truth/document_recall`			✓	✓
`response/llm_judged/guideline_adherence/rating`			✓		✓

Esquema de entrada da avaliação​

expected_facts diretrizes​

guidelines diretrizes​

expected_response diretrizes​

Esquema para solicitação​

Esquema para resposta​

Esquema para matrizes na entrada de avaliação​

Métricas computadas​