Juízes de IA integrados (MLflow 2)

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 Juízes predefinidos &pontuadores.

Este artigo aborda os detalhes de cada um dos juízes de IA integrados ao Mosaic AI Agent Evaluation, incluindo as entradas necessárias e as métricas de saída.

Veja também:

• Como a qualidade, o custo e a latência são avaliados pela Avaliação do Agente (MLflow 2)
• Personalizar juízes de IA (MLflow 2)
• Referência do SDK Python para juízes chamáveis

Visão geral dos avaliadores de IA

Observação

Nem todos os avaliadores exigem rótulos de verdade absoluta. Juízes que não exigem rótulos são úteis quando você tem apenas um conjunto de solicitações para avaliar seu agente.

Nome do juiz	Aspecto de qualidade que o juiz avalia	Entradas necessárias	Requer a verdade absoluta
global_guideline_adherence	A resposta gerada segue as diretrizes globais?	request, response, global_guidelines (do evaluator_config)	Não, mas requer global_guidelines
guideline_adherence	A resposta gerada segue as diretrizes fornecidas por pergunta?	request, response ou guidelines_context, guidelines	Sim
correctness	A resposta gerada é precisa (em comparação com a verdade básica)?	requestresponse, expected_facts[]ouexpected_response	Sim
relevance_to_query	O endereço de resposta (é relevante para) a solicitação do usuário?	request, response	Não
context_sufficiency	O recuperador encontrou documentos com informações suficientes para produzir a resposta esperada?	request, retrieved_context, expected_response	Sim
safety	Há conteúdo nocivo ou tóxico na resposta?	request, response	Não
chunk_relevance	O recuperador encontrou partes úteis (relevantes) para atender à solicitação do usuário? Observação: este avaliador é aplicado separadamente a cada parte recuperada, produzindo uma pontuação e lógica para cada parte. Essas pontuações são agregadas em uma pontuação chunk_relevance/precision para cada linha que representa o % das partes relevantes.	request, retrieved_context	Não
groundedness	A resposta gerada é baseada no contexto recuperado (não é alucinante)?	request, response, trace[retrieved_context]	Não
document_recall	Quantos dos documentos relevantes conhecidos o recuperador encontrou?	retrieved_context, expected_retrieved_context[].doc_uri	Sim

Observação

Para conversas de vários turnos, os juízes de IA avaliam apenas a última entrada na conversa.

Saídas do avaliador de IA

Cada juiz usado na avaliação gera as seguintes colunas:

Campo de dados	Tipo	Descrição
response/llm_judged/{judge_name}/rating	string	yes se o juiz for aprovado, no se o juiz falhar.
response/llm_judged/{judge_name}/rationale	string	Raciocínio escrito do LLM para yes ou no.
response/llm_judged/{judge_name}/error_message	string	Se houver um erro ao calcular essa avaliação, os detalhes do erro estarão aqui. Se não houver erro, será NULL.

Cada juiz também produzirá uma métrica de agregação para toda a execução:

Nome da métrica	Tipo	Descrição
response/llm_judged/{judge_name}/rating/average	float, [0, 1]	Percentual de todas as avaliações que foram julgadas como yes.

Adesão de diretrizes

Definição: a resposta segue as diretrizes fornecidas?

Requer verdade básica: Não ao usarglobal_guidelines. Sim ao usar guidelines por linha.

A adesão à diretriz avalia se a resposta do agente segue restrições ou instruções específicas fornecidas nas diretrizes.

As diretrizes podem ser definidas de qualquer uma das seguintes maneiras:

• por linha: a resposta de uma solicitação específica deve seguir as diretrizes definidas nessa linha de avaliação.
• globalmente: todas as respostas para qualquer solicitação devem seguir as diretrizes globais.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• response se você não especificou o model parâmetro para mlflow.evaluate().
• por linha guidelines ou global_guidelines definido na configuração.
• [Somente juízes elegíveis] guidelines_context para fornecer contexto arbitrário ao juiz.
  • Esse recurso requer databricks-agents>=0.20.0.

Exemplos

Use a adesão de diretriz por linha de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris.",
  # You can also just pass an array of guidelines directly to guidelines, but Databricks recommends naming them with a dictionary.
  "guidelines": {
    "english": ["The response must be in English"],
    "clarity": ["The response must be clear, coherent, and concise"],
  }
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["guideline_adherence"]
      }
  }
)

Use a adesão de diretrizes globais de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris.",
}]

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

Use a adesão às diretrizes com o SDK do juiz chamável:

from databricks.agents.evals import judges

assessment = judges.guideline_adherence(
  request="What is the capital of France?",
  response="The capital of France is Paris.",
  # You can also just pass an array of guidelines directly to guidelines, but Databricks recommends naming them with a dictionary.
  guidelines={
    "english": ["The response must be in English"],
    "clarity": ["The response must be clear, coherent, and concise"],
    "grounded": ["The response must be grounded in the tool call result"],
  },
  # `guidelines_context` requires `databricks-agents>=0.20.0`
  guidelines_context={
    "tool_call_result": "{'country': 'France', 'capital': 'Paris'}",
  },
)
print(assessment)

O que fazer quando a resposta não segue as diretrizes?

Quando a resposta viola as diretrizes:

• Identifique qual diretriz foi violada e analise por que o agente não a acatou.
• Ajuste o prompt para enfatizar a adesão a diretrizes específicas ou treinar novamente o modelo com exemplos adicionais que se alinham com o comportamento desejado.
• Para diretrizes globais, verifique se elas são especificadas corretamente na configuração do avaliador.

Exatidão

Definição: o agente respondeu com uma resposta factualmente precisa?

Requer dados reais: Sim, expected_facts[] ou expected_response.

A correção compara a resposta real do agente a um rótulo de verdade absoluta e é uma boa maneira de detectar erros factuais.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• response se você não especificou o model parâmetro para mlflow.evaluate().
• dados_esperados ou resposta_esperada

Importante

O Databricks recomenda usar expected_facts[] em vez de expected_response. expected_facts[] representam o conjunto mínimo de fatos necessários em uma resposta correta e são mais fáceis para os especialistas do assunto fazerem a curadoria.

Se você precisar usar expected_response, ele deverá incluir apenas o conjunto mínimo de fatos necessários para uma resposta correta. Se você copiar uma resposta de outra fonte, edite a resposta para remover qualquer texto que não seja necessário para que uma resposta seja considerada 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.

Exemplos

Use a correção de um conjunto de avaliação:

import mlflow

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.",
  "expected_facts": [
    "reduceByKey aggregates data before shuffling",
    "groupByKey shuffles all data",
  ]
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["correctness"]
      }
  }
)

Use a correção com o SDK do juiz chamável:

from databricks.agents.evals import judges

assessment = judges.correctness(
  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.",
  expected_facts=[
    "reduceByKey aggregates data before shuffling",
    "groupByKey shuffles all data",
  ]
)
print(assessment)

O que fazer quando uma resposta está incorreta?

Quando um agente responde com uma resposta factualmente imprecisa, você deve:

• Entenda se qualquer contexto recuperado pelo agente é irrelevante ou inacurado. Para aplicativos RAG, você pode usar o juiz de suficiência de contexto para determinar se o contexto é suficiente para gerar o expected_facts ou expected_response.
• Se houver contexto suficiente, ajuste o prompt para incluir informações relevantes.

Relevância para consulta

Definição: a resposta é relevante para a solicitação de entrada?

Requer a verdade absoluta: Não.

A relevância garante que a resposta do agente resolva diretamente a entrada do usuário sem se desviar para tópicos não relacionados.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• response se você não especificou o model parâmetro para mlflow.evaluate().

Exemplos

Use a relevância de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris."
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["relevance_to_query"]
      }
  }
)

Use relevância com o SDK do juiz chamável:

from databricks.agents.evals import judges

assessment = judges.relevance_to_query(
  request="What is the capital of France?",
  response="The capital of France is Paris."
)
print(assessment)

O que fazer quando uma resposta não é relevante?

Quando o agente fornecer uma resposta irrelevante, considere as seguintes etapas:

• Avalie a compreensão do modelo da solicitação e ajuste seu recuperador, dados de treinamento ou instruções de solicitação adequadamente.

Suficiência de contexto

Definição: os documentos recuperados são suficientes para produzir a resposta esperada?

Requer dados reais: Sim, expected_facts ou expected_response.

A suficiência de contexto avalia se os documentos recuperados fornecem todas as informações necessárias para gerar a resposta esperada.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• response se você não especificou o model parâmetro para mlflow.evaluate().
• expected_facts ou expected_response. Veja expected_facts diretrizes e expected_response diretrizes.
• retrieved_context[].content se você não especificou o model parâmetro para mlflow.evaluate().

Exemplos

Use a suficiência de contexto de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris.",
  "retrieved_context": [
    {"content": "Paris is the capital city of France."}
  ],
  "expected_facts": [
    "Paris"
  ]
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["context_sufficiency"]
      }
  }
)

Use a suficiência de contexto com o SDK do juiz chamável:

from databricks.agents.evals import judges

assessment = judges.context_sufficiency(
  request="What is the capital of France?",
  retrieved_context=[
    {"content": "Paris is the capital city of France."}
  ]
)
print(assessment)

O que fazer quando o contexto é insuficiente?

Quando o contexto é insuficiente:

• Aprimore o mecanismo de recuperação para garantir que todos os documentos necessários sejam incluídos.
• Modifique o prompt de modelo para referenciar explicitamente as informações ausentes ou priorizar o contexto relevante.

Segurança

Definição: a resposta evita conteúdo nocivo ou tóxico?

Requer a verdade absoluta: Não.

A segurança garante que as respostas do agente não contenham conteúdo nocivo, ofensivo ou tóxico.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• response se você não especificou o model parâmetro para mlflow.evaluate().

Exemplos

Use a segurança de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris."
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["safety"]
      }
  }
)

Use a segurança com o SDK do juiz chamável:

from databricks.agents.evals import judges

assessment = judges.safety(
  request="What is the capital of France?",
  response="The capital of France is Paris."
)
print(assessment)

O que fazer quando a resposta não é segura?

Quando a resposta inclui conteúdo prejudicial:

• Analise a solicitação para identificar se ela pode levar inadvertidamente a respostas não seguras. Modifique a entrada, se necessário.
• Refinar o modelo ou prompt para evitar explicitamente a geração de conteúdo nocivo ou tóxico.
• Emprega mecanismos de segurança adicionais, como filtros de conteúdo, para interceptar respostas não seguras antes que elas cheguem ao usuário.

Fundamentação

Definição: a resposta é factualmente consistente com o contexto recuperado?

Requer a verdade absoluta: Não.

A fundamentação avalia se a resposta do agente está alinhada com as informações fornecidas no contexto recuperado.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• response se você não especificou o model parâmetro para mlflow.evaluate().
• retrieved_context[].content Se você não usar o argumento model na chamada para mlflow.evaluate().

Exemplos

Use a fundamentação de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris.",
  "retrieved_context": [
    {"content": "Paris is the capital city of France."}
  ]
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["groundedness"]
      }
  }
)

Use a fundamentação com o SDK do avaliador que pode ser chamado:

from databricks.agents.evals import judges

assessment = judges.groundedness(
  request="What is the capital of France?",
  response="The capital of France is Paris.",
  retrieved_context=[
    {"content": "Paris is the capital city of France."}
  ]
)
print(assessment)

O que fazer quando a resposta não tem fundamento?

Quando a resposta não estiver fundamentada

• Examine o contexto recuperado para garantir que ele inclua as informações necessárias para gerar a resposta esperada.
• Se o contexto for insuficiente, melhore o mecanismo de recuperação ou o conjunto de dados para incluir documentos relevantes.
• Modifique o prompt para instruir o modelo a priorizar usando o contexto recuperado ao gerar respostas.

Relevância da parte

Definição: as partes recuperadas são relevantes para a solicitação de entrada?

Requer a verdade absoluta: Não.

A relevância da parte mede se cada parte é relevante para a solicitação de entrada.

Entradas necessárias

O conjunto de avaliação de entrada deve ter as seguintes colunas:

• request
• retrieved_context[].content se você não especificou o model parâmetro para mlflow.evaluate().

Se você não usar o argumento model na chamada para mlflow.evaluate(), também deverá fornecer retrieved_context[].content ou trace.

Exemplos

Este exemplo usa o juiz de relevância de partes com uma métrica de precisão personalizada para calcular uma pontuação de precisão em nível de linha. Para obter mais detalhes sobre métricas personalizadas, consulte métricas personalizadas (MLflow 2)

import mlflow
from mlflow.evaluation import Assessment

eval_set = [{
  "request": "What is the capital of France?",
  "response": "The capital of France is Paris.",
  "retrieved_context": [
    {"content": "Paris is the capital city of France."},
    {"content": "The best baguettes are in Nice."},
    {"content": "Mount Everest is  the highest mountain in the world."},
  ],
}]

def judged_precision_at_k(request, retrieved_context, k):
  judged_precisions = [judges.chunk_relevance(request, [doc]) for doc in retrieved_context[:k]]
  precision_at_k = sum([1 if judgement[0].value =='yes' else 0 for judgement in judged_precisions]) / k

  rationales = [
    f"""## Chunk ID {i+1}: `{retrieved_context[i]['doc_uri']}`
    - **{judged_precisions[i][0].value}**: `{judged_precisions[i][0].rationale}`"""
    for i in range(0, k-1)]

  return Assessment(name=f'judged_precision_at_{k}', value=precision_at_k, rationale='\n'.join(rationales))

@metric
def judged_precision_at_3(request, retrieved_context):
  k = 3
  return judged_precision_at_k(request=request, retrieved_context=retrieved_context,  k=k)

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["chunk_relevance"]
      }
  },
  extra_metrics=[judged_precision_at_3]
)

Use chunk_relevance com o SDK do juiz chamável:

from databricks.agents.evals import judges

# NOTE: This callable judge returns an assessment per item in the retrieved context.
assessments = judges.chunk_relevance(
  request="What is the capital of France?",
  retrieved_context=[
    {"content": "Paris is the capital city of France."},
    {"content": "The chicken crossed the road."},
  ]
)
print(assessments)

O que fazer quando partes recuperadas são irrelevantes?

Quando partes irrelevantes são recuperadas:

• Avalie a configuração do recuperador e ajuste os parâmetros para priorizar a relevância.
• Refinar os dados de treinamento do recuperador para incluir exemplos mais diversos ou precisos.

Recall de documentos

Definição: quantos dos documentos relevantes conhecidos o recuperador encontrou?

Requer a verdade absoluta: Sim, expected_retrieved_context[].doc_uri.

O recall de documentos mede a proporção de documentos relevantes de verdade absoluta que foram recuperados em comparação com o número total de documentos relevantes na verdade absoluta.

Entradas necessárias

O conjunto de avaliação de entrada deve ter a seguinte coluna:

• expected_retrieved_context[].doc_uri

Além disso, se você não usar o argumento model na chamada para mlflow.evaluate(), também deverá fornecer retrieved_context[].doc_uri ou trace.

Exemplos

Use o recall de documentos de um conjunto de avaliação:

import mlflow

eval_set = [{
  "request": "What is the capital of France?",
  "expected_retrieved_context": [
    {"doc_uri": "doc_123"},
    {"doc_uri": "doc_456"}
  ],
  "retrieved_context": [
    {"doc_uri": "doc_123"}
  ]
}]

mlflow.evaluate(
  data=eval_set,
  model_type="databricks-agent",
  evaluator_config={
      "databricks-agent": {
          "metrics": ["document_recall"]
      }
  }
)

Não há nenhum SDK do avaliador que pode ser chamado para essa métrica, pois ela não usa um avaliador de IA.

O que fazer quando o recall de documentos é baixo?

Quando o recall é baixo:

• Verifique se os dados de verdade básica refletem com precisão documentos relevantes.
• Aprimore o recuperador ou ajuste os parâmetros de pesquisa para aumentar o recall.

Juízes de IA personalizados

Você também pode criar um juiz personalizado para executar avaliações específicas do seu caso de uso.

Para obter detalhes, confira:

• Crie juízes de IA com base em diretrizes.
• Converter make_genai_metric_from_prompt em uma métrica personalizada.
• Verifique se o contexto recuperado não tem PII