Juízes de AI integrados (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 Avaliar e monitorar agentes de AI.
• Para obter informações sobre como migrar para o MLflow 3, consulte Migrar para o MLflow 3 a partir da Agent Evaluation.
• Para obter informações sobre este tópico no MLflow 3, consulte Pontuadores e juízes LLM.

Este artigo abrange os detalhes de cada um dos avaliadores de AI que são incorporados ao Agent Evaluation, incluindo entradas necessárias e métricas de saída.

Veja também:

• Como a qualidade, o custo e a latência são avaliados pela Agent Evaluation (MLflow 2)
• Personalizar juízes de IA (MLflow 2)
• Referência do SDK Python de avaliadores invocáveis

Visão geral de juízes de AI

nota

Nem todos os juízes exigem rótulos de verdade fundamental. 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	Exige verdade fundamental
global_guideline_adherence	A resposta gerada adere às diretrizes globais?	request, response, global_guidelines (do evaluator_config)	Não, mas requer global_guidelines
guideline_adherence	A resposta gerada adere às diretrizes fornecidas por pergunta?	request, response ou guidelines_context, guidelines	Sim
correctness	A resposta gerada é precisa (em comparação com a verdade fundamental)?	request, response, expected_facts[] ou expected_response	Sim
relevance_to_query	A resposta aborda (é 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 trechos que são úteis (relevantes) para responder à solicitação do usuário? Observação: Este juiz é aplicado separadamente a cada pedaço recuperado, produzindo uma pontuação e justificativa para cada pedaço. Essas pontuações são agregadas em uma pontuação de chunk_relevance/precision para cada linha que representa a % de fragmentos que são relevantes.	request, retrieved_context	Não
groundedness	A resposta gerada está fundamentada no contexto recuperado (sem alucinações)?	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

nota

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

Saídas do juiz de AI

Cada juiz usado na avaliação exibe 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 houve um erro ao calcular esta avaliação, os detalhes do erro estão aqui. Se não houver erro, será NULL.

Cada juiz também produzirá uma métrica agregada para a execução inteira:

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

Conformidade com as diretrizes

Definição : A resposta adere às diretrizes fornecidas?

**Requer verdade fundamental**: Não ao global_guidelines usar. Sim ao usar guidelines por linha.

Aderência às diretrizes 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 formas:

• per-row: A resposta de uma solicitação específica deve aderir às diretrizes definidas nessa linha de avaliação.
• Globalmente: Todas as respostas para qualquer solicitação devem aderir às diretrizes globais.

Entradas obrigatórias

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

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

Exemplos

Use a conformidade por linha com as diretrizes de um conjunto de avaliação:

Python

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"]
      }
  }
)

Utilize a aderência às diretrizes globais de um conjunto de avaliação:

Python

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 aderência às diretrizes com o SDK de juiz invocável:

Python

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 adere às diretrizes?

Quando a resposta viola as diretrizes:

• Identifique qual diretriz foi violada e analise por que o agente não a cumpriu.
• Ajuste o prompt para enfatizar a adesão a diretrizes específicas ou retreine o modelo com exemplos adicionais que se alinhem ao comportamento desejado.
• Para diretrizes globais, certifique-se de que estejam especificadas corretamente na configuração do avaliador.

Correção

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

Requer verdade fundamental : sim, expected_facts[] ou expected_response.

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

Entradas obrigatórias

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

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

importante

A 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 no assunto selecionarem.

Se você precisar expected_response usar, ele deve incluir *apenas* o conjunto mínimo de fatos que é exigido para uma resposta correta. Se você copiar uma resposta de outra fonte, edite a resposta para remover qualquer texto que não seja *exigido* 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 necessárias na resposta permite que o Agent Evaluation forneça um sinal mais robusto sobre a qualidade da saída.

Exemplos

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

Python

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 de juiz invocável:

Python

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, o senhor deve:

• Entenda se algum contexto recuperado pelo agente é irrelevante ou impreciso. Para aplicativos RAG, você pode usar o juiz de Suficiência de Contexto para determinar se o contexto é suficiente para gerar expected_facts ou expected_response.
• Se houver contexto suficiente, ajuste o prompt para incluir informação relevante.

Relevância para a consulta

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

Requer verdade fundamental : Não.

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

Entradas obrigatórias

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

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

Exemplos

Usar relevância de um conjunto de avaliação:

Python

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 a relevância com o SDK de juiz chamável:

Python

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 os seguintes passos:

• Avalie o entendimento do modelo sobre a solicitação e ajuste seu retriever, dados de treinamento ou instruções de prompt conforme necessário.

Suficiência de contexto

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

Requer verdade fundamental : 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 obrigatórias

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

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

Exemplos

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

Python

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 de juiz invocável:

Python

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 for insuficiente:

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

Segurança

Definição : A resposta evita conteúdo prejudicial ou tóxico?

Requer verdade fundamental : Não.

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

Entradas obrigatórias

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

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

Exemplos

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

Python

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 de avaliador chamável:

Python

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 incluir conteúdo prejudicial:

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

Fundamentação

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

Requer verdade fundamental : Não.

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

Entradas obrigatórias

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

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

Exemplos

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

Python

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"]
      }
  }
)

Usar fundamentação com o SDK do juiz chamável:

Python

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 fundamentação?

Quando a resposta não estiver fundamentada:

• Revise o contexto recuperado para garantir que ele inclua a informação necessária para gerar a resposta esperada.
• Se o contexto for insuficiente, melhore o mecanismo de recuperação ou o dataset para incluir documentos relevantes.
• Modifique o prompt para instruir o modelo a priorizar o uso do contexto recuperado ao gerar respostas.

Relevância do fragmento

Definição : Os segmentos recuperados são relevantes para a solicitação de entrada?

Requer verdade fundamental : Não.

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

Entradas obrigatórias

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

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

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

Exemplos

Este exemplo usa o avaliador de relevância de trecho com uma métricas de precisão personalizada para compute uma pontuação de precisão no nível da linha. Para obter mais detalhes sobre métricas personalizadas, consulte Métricas personalizadas (MLflow 2)

Python

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 de juiz invocável:

Python

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 os trechos recuperados são irrelevantes?

Quando blocos irrelevantes são recuperados:

• Avalie a configuração do recuperador e ajuste os parâmetros para priorizar a relevância.
• Refine 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 verdade fundamental**: expected_retrieved_context[].doc_uri Sim,.

A recuperação de documentos mede a proporção de documentos relevantes da verdade fundamental que foram recuperados em comparação com o número total de documentos relevantes na verdade fundamental.

Entradas obrigatórias

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

• expected_retrieved_context[].doc_uri

Além disso, caso não se utilize do argumento model na chamada para mlflow.evaluate(), deve-se também fornecer retrieved_context[].doc_uri ou trace.

Exemplos

Use a recuperação de documentos de um conjunto de avaliação:

Python

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á um SDK de juiz invocável para esta métrica, pois ela não usa um juiz de AI.

O que fazer quando o recall de documentos está baixo?

Quando o recall é baixo:

• Verifique se os dados da verdade fundamental refletem com precisão os documentos relevantes.
• Melhore o recuperador ou ajuste os parâmetros de pesquisa para aumentar o recall.

Juízes de AI personalizados

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

Para obter detalhes, consulte:

• Crie juízes de AI a partir de diretrizes.
• Converta make_genai_metric_from_prompt para uma métrica personalizada.
• Garanta que o contexto recuperado não contenha PII