Partilhar via

Esquema de entrada de avaliação do agente

  • Artigo

Importante

Esta funcionalidade está em Pré-visualização Pública.

Este artigo explica o esquema de entrada exigido pela Avaliação do Agente 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 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.

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 mlflow.evaluate(). Consulte Forneça entradas para uma execução de avaliação para mais detalhes.

Coluna Tipo de dados Description Aplicativo passado como argumento de entrada Saídas geradas anteriormente fornecidas
request_id string Identificador único do pedido. Opcional Opcional
pedido Consulte o esquema para a solicitação. Entrada no aplicativo para 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 cadeia de caracteres, ele será transformado em messages antes de ser passado para o seu agente. Obrigatório Obrigatório
resposta string Resposta gerada pelo aplicativo que está sendo avaliado. Gerado pela Avaliação do Agente Opcional. Se não for fornecido, então derivado do Trace. Ou responsetrace é obrigatório.
expected_facts matriz da cadeia Uma lista de fatos esperados na saída do modelo. Consulte expected_facts diretrizes. Opcional Opcional
expected_response string Fundamento-verdade (correta) resposta para a solicitação de entrada. Consulte expected_response diretrizes. Opcional Opcional
Orientações matriz da cadeia Uma lista de diretrizes que se espera que o resultado do modelo cumpra. Consulte diretrizes. Opcional Opcional
expected_retrieved_context matriz Matriz de objetos contendo o contexto recuperado esperado para a 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 retriever no aplicativo que está sendo avaliado. Se várias etapas de recuperação estiverem no aplicativo, este é o resultado da recuperação da última etapa (cronologicamente no rastreamento). Esquema de matriz Gerado pela Avaliação do Agente Opcional. Se não fornecida, derivada do vestígio fornecido.
Rastreio Cadeia de caracteres JSON do MLflow Trace MLflow Trace da execução do aplicativo na solicitação correspondente. Gerado pela Avaliação do Agente Opcional. Ou responsetrace é obrigatório.

expected_facts Orientações

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

Incluir apenas os fatos exigidos e deixar de fora 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 dos expected_facts e expected_response. Se você especificar ambos, um erro será relatado. A Databricks recomenda o uso expected_factsdo , pois é uma diretriz mais específica que ajuda a Avaliação do Agente a julgar de forma mais eficaz a qualidade das respostas geradas.

guidelines Orientações

O campo guidelines especifica a lista de diretrizes que qualquer resposta de modelo correta deve seguir. As diretrizes podem se referir a várias características da resposta, incluindo elementos estilísticos ou relacionados ao conteúdo. Para obter o sinal mais robusto na adesão às diretrizes, a Databricks recomenda o uso da seguinte linguagem:

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

Especificamente, deve referir-se diretamente ao pedido e à resposta e deixar o mínimo possível de ambiguidade nas orientações. 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:

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.",
        "guidelines": [
            "The response must be in English",
            "The response must be clear, coherent, and concise",
        ]
    }
]

mlflow.evaluate(
    data=pd.DataFrame(eval_set),
    model_type="databricks-agent",
    evaluator_config={
        "databricks-agent": {
            "global_guidelines": [
                "The response must be in English",
                "The response must be clear, coherent, and concise",
            ],
        }
    }
)

expected_response Orientações

O expected_response campo 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. Em contrapartida, expected_facts enumera apenas os factos que devem constar de uma resposta correta e não é uma resposta de referência totalmente formada.

À semelhança do expected_facts, expected_response deve conter apenas o conjunto mínimo de factos necessários para uma resposta correta. Incluir apenas as informações necessárias, e deixar de fora 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.

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

Esquema para solicitação

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

  • O modelo de conclusão de chat OpenAI. O esquema de conclusão de bate-papo do OpenAI deve ter uma matriz de objetos como um parâmetro messages. O messages campo pode codificar a conversa completa.
  • Se o agente suportar o esquema de conclusão de chat do OpenAI, você poderá passar uma cadeia de caracteres simples. Este formato suporta apenas conversas de turno único. As cadeias de caracteres simples são convertidas para o formato com messages antes de serem passadas para o "role": "user" seu agente. Por exemplo, uma cadeia de caracteres "What is MLflow?" simples é convertida em {"messages": [{"role": "user", "content": "What is MLflow?"}]} antes de ser passada para o seu agente.
  • SplitChatMessagesRequest. Um query campo de cadeia de caracteres para a solicitação mais recente e um campo opcional history que codifica as voltas anteriores da conversa.

Para aplicativos de bate-papo multiturno, use a segunda ou terceira opção acima.

O exemplo a seguir mostra as três opções na mesma coluna request 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."
              }
          ]
      }
  ],

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

eval_dataset = pd.DataFrame(data)

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 Description Aplicativo passado como argumento de entrada Saídas geradas anteriormente fornecidas
content string Conteúdo do contexto recuperado. String em qualquer formato, como HTML, texto sem formatação ou Markdown. Opcional Opcional
doc_uri string Identificador exclusivo (URI) do documento pai de onde o fragmento 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 é 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 pela Avaliação do agente.

Métricas calculadas request request e expected_response request, expected_response, expected_retrieved_contexte 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 ✓ ✓