Esquema de entrada de avaliação do agente

info

Visualização

Esse recurso está em Public Preview.

Este artigo explica o esquema de entrada exigido pela Avaliação de agentes 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 de agentes vêm das tabelas de inferência ou dos logs de produção.

O esquema de entrada é idêntico para avaliações on-line e off-line.

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 se referem à forma como a entrada é fornecida para a chamada mlflow.evaluate(). Para obter detalhes, consulte Fornecer entradas para uma execução de avaliação.

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 para avaliar a 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 transmitido ao seu 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, será derivado do Trace. É necessário response ou trace.
fatos esperados	matriz de cadeias de caracteres	Uma lista de fatos que são esperados na saída do modelo. Veja as diretrizesexpected_facts.	Opcional	Opcional
expected_response	string	Resposta verdadeira (correta) para a solicitação de entrada. Veja as diretrizesexpected_response.	Opcional	Opcional
diretrizes	guidelines diretrizes	Um ditado nomeado ou uma lista de diretrizes que se espera que a saída do modelo siga. Veja as diretrizesguidelines.	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 recuperador no aplicativo que está sendo avaliado. Se várias etapas de recuperação estiverem no aplicativo, esses são os resultados da recuperação da última etapa (cronologicamente no rastreamento). Esquema de matriz	Gerado pela avaliação do agente	Opcional. Se não for fornecido, será derivado do rastreamento fornecido.
trace	JSON strings de MLflow Trace	MLflow Trace da execução do aplicativo na solicitação correspondente.	Gerado pela avaliação do agente	Opcional. É necessário response ou trace.

Diretrizesexpected_facts

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

Incluir apenas os fatos necessários e omitir 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 uma das opções expected_facts e expected_response. Se você especificar ambos, um erro será relatado. A Databricks recomenda o uso do site expected_facts, pois é uma diretriz mais específica que ajuda o Agent Evaluation a julgar com mais eficiência a qualidade das respostas geradas.

Diretrizesguidelines

O campo guidelines especifica um conjunto de diretrizes que qualquer resposta correta do modelo 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 requerem 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 obter o sinal mais robusto sobre a 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, você deve consultar a solicitação e a 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={
        "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"],
            }
        }
    }
)

Diretrizesexpected_response

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

Assim como expected_facts, expected_response deve conter somente 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 necessárias na resposta permite que a Avaliação de agentes forneça um sinal mais robusto sobre a qualidade do resultado.

Você pode especificar no máximo uma das opções expected_facts e expected_response. Se você especificar ambos, um erro será relatado. A Databricks recomenda o uso do site expected_facts, pois é uma diretriz mais específica que ajuda o Agent Evaluation a julgar com mais eficiência a qualidade das respostas geradas.

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 for compatível com o esquema de conclusão de bate-papo da OpenAI, o senhor poderá passar uma cadeia de caracteres simples. Esse formato suporta apenas conversas em um único turno. O site strings simples é convertido para o formato messages com "role": "user" antes de ser transmitido ao seu agente. Por exemplo, uma cadeia de caracteres simples "What is MLflow?" é convertida em {"messages": [{"role": "user", "content": "What is MLflow?"}]} antes de ser passada ao seu agente.

Observe que os juízes integrados funcionam melhor com qualquer formato que use um esquema de conclusão de bate-papo da OpenAI. O esquema de conclusão de bate-papo do OpenAI deve ter uma matriz de objetos como 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 da avaliação dataset:

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 for compatível com o esquema de conclusão de bate-papo da OpenAI, o senhor poderá passar uma cadeia de caracteres simples. Esse formato suporta apenas conversas em um único turno. O site strings simples é convertido para o formato choices. Por exemplo, uma string simples "MLFlow is a framework." é convertida em {"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

computar métricas

As colunas da tabela a seguir indicam os dados incluídos na entrada e ✓ indica que as métricas são compatíveis 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 de agentes.

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			✓		✓