Esquema de entrada de Avaliação do Agente (MLflow 2)

2025-06-26

Importante

Esta página descreve o uso da versão 0.22 de Avaliação do Agente com o MLflow 2. O Databricks recomenda o uso do MLflow 3, que é integrado à Avaliação do Agente >1.0. No MLflow 3, as APIs de Avaliação do Agente agora fazem parte do mlflow pacote.

Para obter informações sobre este tópico, consulte Compilando conjuntos de dados de avaliação do MLflow.

Este artigo explica o esquema de entrada exigido pela Avaliação do Agente para avaliar a qualidade, o custo e a latência do aplicativo.

Durante o desenvolvimento, a avaliação ocorre offline e um conjunto de avaliação é uma entrada necessária para a Avaliação do Agente.
Quando um aplicativo está em produção, todas as entradas para a Avaliação do Agente 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 obter informações gerais sobre conjuntos de avaliação, consulte Conjuntos de avaliação (MLflow 2).

Esquema de entrada de Avaliação

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

Coluna	Tipo de dados	Descrição	Aplicativo fornecido como argumento de entrada	Saídas geradas anteriormente fornecidas
request_id	cadeia de caracteres	Identificador exclusivo da solicitação.	Opcional	Opcional
request	Confira Esquema para solicitação.	Entrada para o aplicativo avaliar, como a pergunta ou consulta do usuário. Por exemplo, `{'messages': [{"role": "user", "content": "What is RAG"}]}` ou "O que é RAG?". Quando `request` for fornecido como uma cadeia de caracteres, ele será transformado em `messages` antes de ser passado para o agente.	Obrigatório	Obrigatório
resposta	Consulte Esquema para obter resposta.	Resposta gerada pelo aplicativo que está sendo avaliado.	Gerado pela Avaliação do Agente	Opcional. Se não for fornecido, é derivado do Rastreamento. `response` ou `trace` é necessário.
fatos_esperados	matriz de cadeias de caracteres	Uma lista de fatos esperados na saída do modelo. Consulte Diretrizes de `expected_facts`.	Opcional	Opcional
resposta_esperada	cadeia de caracteres	Resposta de verdade básica (correta) para a solicitação de entrada. Consulte Diretrizes de `expected_response`.	Opcional	Opcional
Diretrizes	`guidelines` Diretrizes	Um dicionário nomeado ou uma lista de diretrizes às quais a saída do modelo deve seguir. Consulte Diretrizes de `guidelines`.	Opcional	Opcional
expected_retrieved_context	matriz	Matriz de objetos que contêm o contexto recuperado esperado da solicitação (se o aplicativo incluir uma etapa 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 o aplicativo tiver múltiplas etapas de recuperação, estes são os resultados de recuperação da última etapa (em ordem cronológica no rastreamento). Esquema de matriz	Gerado pela Avaliação do Agente	Opcional. Se não for fornecido, é derivado do rastreamento fornecido.
rastreamento	Cadeia de caracteres JSON do Rastreamento do MLflow	Rastreamento do MLflow da execução do aplicativo na solicitação correspondente.	Gerado pela Avaliação do Agente	Opcional. `response` ou `trace` é necessário.

Diretrizes de `expected_facts`

O campo expected_facts especifica a lista de fatos que devem aparecer 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 deixar de fora os fatos que não são estritamente exigidos na resposta permite que a Avaliação do Agente forneça um sinal mais robusto sobre a qualidade da saída.

Você pode especificar no máximo um de expected_facts e de expected_response. Se você especificar ambos, um erro será relatado. O Databricks recomenda usar expected_facts, pois é uma diretriz mais específica que ajuda a Avaliação do Agente a julgar com mais eficiência a qualidade das respostas geradas.

Diretrizes de `guidelines`

O guidelines campo especifica um conjunto de diretrizes às quais qualquer resposta de modelo correta deve seguir. 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 uma matriz de diretrizes para esse nome. As diretrizes nomeadas exigem databricks-agents >= 0.16.0.

As diretrizes podem se referir a várias características da resposta, incluindo elementos estilísticos ou relacionados ao conteúdo. Para o sinal mais robusto sobre a adesão às diretrizes, o Databricks recomenda usar o seguinte idioma:

"A resposta deve..."
"A resposta não deve..."
"A resposta pode, opcionalmente..."

Especificamente, você deve consultar a solicitação e a resposta diretamente e deixar o mínimo de ambiguidade possível nas diretrizes. Para obter diretrizes que se aplicam a todo o 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 maneira:

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

Diretrizes de `expected_response`

O campo expected_response contém uma resposta totalmente formada que representa uma referência para respostas corretas do modelo. Ou seja, uma resposta de modelo é considerada correta se corresponder ao conteúdo da informação em expected_response. Por outro lado, expected_facts lista apenas os fatos que devem 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ários para uma resposta correta. Incluir apenas as informações necessárias e deixar de fora as informações que não são estritamente exigidas na resposta permite que a Avaliação do Agente 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 der suporte ao esquema de conclusão de chat do OpenAI, você poderá passar uma cadeia de caracteres simples. Esse formato dá suporte apenas a conversas de uma única rodada. As cadeias de caracteres simples são convertidas para o formato messages com "role": "user" antes de serem passadas para o agente. Por exemplo, uma cadeia de caracteres "What is MLflow?" simples é convertida para {"messages": [{"role": "user", "content": "What is MLflow?"}]} antes de ser passada para o agente.

Observe que os juízes integrados funcionam melhor com qualquer formato usando um esquema de conclusão de chat do OpenAI. O esquema de conclusão de chat do 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 request coluna do conjunto de dados de avaliação:

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 de 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 der suporte ao esquema de conclusão de chat do OpenAI, você poderá passar uma cadeia de caracteres simples. Esse formato dá suporte apenas a conversas de uma única rodada. Cadeias de caracteres simples são convertidas no choices formato. Por exemplo, uma cadeia de caracteres "MLFlow is a framework." simples é convertida {"choices": [{"message": {"content": "MLFlow is a framework."}}]}em .

Esquema para matrizes na entrada de avaliação

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

Coluna	Tipo de dados	Descrição	Aplicativo fornecido como argumento de entrada	Saídas geradas anteriormente fornecidas
conteúdo	cadeia de caracteres	Conteúdo do contexto recuperado. Cadeia de caracteres em qualquer formato, como HTML, texto sem formatação ou Markdown.	Opcional	Opcional
doc_uri	cadeia de caracteres	Identificador exclusivo (URI) do documento pai de onde a parte veio.	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 tem suporte 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 pela Avaliação do Agente (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`			✓		✓

Compartilhar via

Esquema de entrada de Avaliação do Agente (MLflow 2)

Esquema de entrada de Avaliação

Diretrizes de expected_facts

Diretrizes de guidelines

Diretrizes de expected_response