integrada AI juízes

info

Visualização

Esse recurso está em Public Preview.

Este artigo aborda os detalhes de cada um dos juízes do AI que estão integrados ao Mosaic AI Agent Evaluation, incluindo as métricas de entrada e saída necessárias.

Veja também:

AI visão geral dos juízes

nota

Nem todos os juízes exigem o rótulo ground-truth. Os juízes que não exigem rótulo são úteis quando o senhor 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 verdade fundamental
`global_guideline_adherence`	A resposta gerada segue as diretrizes globais?	`request`, `response`, `global_guidelines` (do `evaluator_config`)	Não, mas exige `global_guidelines`
`guideline_adherence`	A resposta gerada segue as diretrizes fornecidas por pergunta?	`request`, `response`, `guidelines`	Sim
`correctness`	A resposta gerada é precisa (em comparação com a verdade básica)?	`response`, `expected_facts[]` ou `expected_response`	Sim
`relevance_to_query`	A resposta aborda (é relevante para) a solicitação do usuário?	`response`, `request`	Não
`context_sufficiency`	O retriever encontrou documentos com informações suficientes para produzir a resposta esperada?	`retrieved_context`, `expected_response`	Sim
`safety`	Há conteúdo nocivo ou tóxico na resposta?	`response`	Não
`chunk_relevance`	O retriever encontrou partes que são úteis (relevantes) para responder à solicitação do usuário? Nota: Esse juiz é aplicado separadamente a cada pedaço recuperado, produzindo uma justificativa de pontuação & para cada pedaço. Essas pontuações são agregadas em uma pontuação `chunk_relevance/precision` para cada linha que representa a porcentagem de partes que são relevantes.	`retrieved_context`, `request`	Não
`groundedness`	A resposta gerada está baseada no contexto recuperado (não é alucinante)?	`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 com vários turnos, os juízes do AI avaliam apenas a última entrada na conversa.

AI saídas de juiz

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

Campo de dados	Tipo	Descrição
`response/llm_judged/{judge_name}/rating`	`string`	`yes` se o juiz passar, `no` se o juiz falhar.
`response/llm_judged/{judge_name}/rationale`	`string`	A justificativa por escrito do LLM para `yes` ou `no`.
`response/llm_judged/{judge_name}/error_message`	`string`	Se houve um erro ao calcular essa avaliação, os detalhes do erro estão aqui. Se não houver erro, isso é NULL.

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

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`.

Adesão às diretrizes

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

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

A adesão à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 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 tiver especificado o parâmetro model para mlflow.evaluate().
por linha guidelines ou global_guidelines definida na configuração.

Exemplos

Use a adesão à diretriz por linha 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"]
      }
  }
)

Use a adesão à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"]
      }
  }
)

Utilizar a adesão à diretriz com o SDK de juiz chamá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"],
  },
)
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 cumpriu.
Ajuste a solicitação 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 elas estejam especificadas corretamente na configuração do avaliador.

Exatidão

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

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

A correção compara a resposta real do agente a um rótulo de verdade básica 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 tiver especificado o parâmetro model para mlflow.evaluate().
factos_esperados ou resposta_esperada

important

A Databricks recomenda o uso de expected_facts[] em vez de expected_response. Os expected_facts[] representam o conjunto mínimo de fatos exigidos em uma resposta correta e são mais fáceis de serem analisados por especialistas no assunto.

Se você precisar usar expected_response, ele deve 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 necessárias na resposta permite que a Avaliação de agentes forneça um sinal mais robusto sobre a qualidade do resultado.

Exemplos

Use a exatidã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"]
      }
  }
)

Usar a correção com o SDK do juiz chamá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, você 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ções relevantes.

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 necessárias

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

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

Exemplos

Use a 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 do 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 fornece uma resposta irrelevante, considere as seguintes etapas:

Avalie o entendimento do modelo sobre a solicitação e ajuste o retriever, os dados de treinamento ou as instruções do prompt de acordo.

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 do 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 tiver especificado o parâmetro model para mlflow.evaluate().
expected_facts ou expected_response. Veja as diretrizesexpected_facts e expected_response.
retrieved_context[].content se você não tiver especificado 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"]
      }
  }
)

Usar a suficiência de contexto com o SDK de juiz chamá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 é insuficiente:

Melhore o mecanismo de recuperação para garantir que todos os documentos necessários sejam incluídos.
Modificar o prompt do modelo para fazer referência explícita às informações ausentes ou priorizar o contexto relevante.

Segurança

Definição : A resposta evita conteúdo nocivo 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 necessárias

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

request
response se você não tiver especificado 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"]
      }
  }
)

Usar a segurança com o SDK do juiz 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 inclui 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 a solicitação 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 elas cheguem ao usuário.

Aterramento

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 necessárias

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

request
response se você não tiver especificado o parâmetro model 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:

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 o groundedness 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 fundamento?

Quando a resposta não está fundamentada:

Revise o contexto recuperado para garantir que ele inclua as informações necessárias para gerar a resposta esperada.
Se o contexto for insuficiente, aprimore o mecanismo de recuperação ou o site 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 pedaços recuperados são relevantes para a solicitação de entrada?

Requer verdade fundamental: Não .

A relevância do bloco mede se cada bloco é 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 tiver especificado o parâmetro model 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 bloco com uma métrica de precisão personalizada para compute uma pontuação de precisão em nível de linha. Para obter mais detalhes sobre métricas personalizadas, consulte Métricas personalizadas

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

Usar chunk_relevance com o SDK do juiz chamá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 pedaços recuperados 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 retriever para incluir exemplos mais diversificados ou precisos.

Recuperação de documentos

Definição : Quantos dos documentos relevantes conhecidos o retriever encontrou?

Requer verdade fundamental : Sim, expected_retrieved_context[].doc_uri.

O recall 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 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 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á juiz convocável SDK para essa métrica, pois ela não usa um juiz AI.

O que fazer quando o recall de documentos é baixo?

Quando o recall é baixo:

Verifique se os dados reais refletem com precisão os documentos relevantes.
Melhore o recuperador ou ajuste os parâmetros de pesquisa para aumentar a recuperação.

Personalizado AI judges

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

Para obter detalhes, consulte:

AI visão geral dos juízes​

AI saídas de juiz​

Adesão às diretrizes​

Entradas necessárias​

Exemplos​

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

Exatidão​

Entradas necessárias​

Exemplos​

O que fazer quando uma resposta está incorreta?​

Relevância para a consulta​

Entradas necessárias​

Exemplos​

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

Suficiência de contexto​

Entradas necessárias​

Exemplos​

O que fazer quando o contexto é insuficiente?​

Segurança​

Entradas necessárias​

Exemplos​

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

Aterramento​

Entradas necessárias​

Exemplos​

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

Relevância do fragmento​

Entradas necessárias​

Exemplos​

O que fazer quando os pedaços recuperados são irrelevantes?​

Recuperação de documentos​

Entradas necessárias​

Exemplos​

O que fazer quando o recall de documentos é baixo?​

Personalizado AI judges​

AI visão geral dos juízes

AI saídas de juiz

Adesão às diretrizes

Entradas necessárias

Exemplos

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

Exatidão

Entradas necessárias

Exemplos

O que fazer quando uma resposta está incorreta?

Relevância para a consulta

Entradas necessárias

Exemplos

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

Suficiência de contexto

Entradas necessárias

Exemplos

O que fazer quando o contexto é insuficiente?

Segurança

Entradas necessárias

Exemplos

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

Aterramento

Entradas necessárias

Exemplos

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

Relevância do fragmento

Entradas necessárias

Exemplos

O que fazer quando os pedaços recuperados são irrelevantes?

Recuperação de documentos

Entradas necessárias

Exemplos

O que fazer quando o recall de documentos é baixo?

Personalizado AI judges