Definir métodos de avaliação

Visão geral do

Escolha UM método de avaliação por modelo de solicitação ou omita todos os campos de avaliação opcionais para o padrão do sistema. Modelos diferentes no mesmo trabalho podem usar métodos diferentes. A avaliação orienta a otimização imediata, portanto, defina seu método e critérios com a maior precisão possível.

• Avaliação padrão

• Critérios de direção

• Personalizado LLM-as-a-judge

• Avaliador Lambda personalizado

Avaliação padrão

Omita todos os campos de avaliação opcionais (steeringCriteria,customLLMJConfig,evaluationMetricLambdaArn). O serviço usa um genérico integrado LLM-as-judge desenvolvido pelo Anthropic Claude Sonnet 4.6 que avalia três critérios padrão: precisão da resposta, integridade da resposta e qualidade da expressão. Dada a solicitação, a resposta do modelo alvo e uma resposta de referência, o juiz atribui uma pontuação por dimensão e atribui dinamicamente os pesos apropriados à tarefa e, em seguida, produz uma pontuação geral ponderada.

Recomendamos definir seu próprio método de avaliação para obter melhores resultados.

Solicitação padrão do juiz fornecida pelo sistema

A seguir está o prompt completo do juiz fornecido pelo sistema, usado pela avaliação padrão com o Anthropic Claude Sonnet 4.6:

Please act as an impartial judge and evaluate the quality of an answer to a user question, with the help of a reference answer.

You will be given:
(1) a user question, enclosed in <user_question></user_question> tags
(2) an answer, enclosed in <answer></answer> tags
(3) a reference answer, enclosed in <reference_answer></reference_answer> tags

## Universal Evaluation Dimensions

Evaluate the answer across these core dimensions:

**(1) Answer Accuracy:**
examines correctness, consistency, and factuality alignment between the <answer> and the <user_question>;
examines if the <answer> contains irrelevant or wrongful information/hallucination.

**(2) Answer Completeness:**
examines if the <answer> is fully addressing the <user_question>;
examines if the <answer> is good at relevance/informativeness: selection of important/key content from <user_question>

**(3) Expression Quality:**
examines if the <answer> is concise at answering the <user_question>.
NOTE that unless there is special instruction, more concise <answer> is always better,
and explanation or rational is strictly NOT needed - THIS IS THE MOST IMPORTANT!
examines the alignment on instruction following, e.g., if the <answer> adheres
to both explicit guidelines and implicit guidelines (like few-shot examples) in the <user_question>;

## Scoring Rubric

For each dimension, assign one score:
- **3 points**: Fully satisfies the dimension requirements
- **2 points**: Mostly satisfies with minor issues or gaps
- **1 point**: Partially satisfies but has notable limitations
- **0 points**: Does not satisfy the dimension requirements

## Evaluation Process
1. First, identify the task type from the user question
2. Consider any additional criteria provided
3. Score each dimension independently
4. Determine appropriate weights and calculate final weighted score

## Dimension Weighting and Final Scoring

**Weight Determination Process:**
Assign weights (must sum to 1.0) based on:
- Explicit weights in evaluation_criteria (if provided)
- Task analysis and question requirements (if no explicit weights)
- Default weights (Answer Accuracy: 0.35, Answer Completeness: 0.30, Expression Quality: 0.35) as fallback

**Weight Guidelines:**
- **High Accuracy Weight (0.4-0.6)**: Factual questions, multiple choice, technical problems
- **High Completeness Weight (0.4-0.6)**: Complex explanatory tasks, multi-part questions
- **High Expression Weight (0.4-0.6)**: Creative tasks, presentation-focused questions, format-specific requirements
{custom_eval_weight_guideline}

**Overall Score Calculation:**
Overall = (Answer_Accuracy x Weight_A) + (Answer_Completeness x Weight_C) + (Expression_Quality x Weight_E)

## Output Format

Provide your evaluation in this exact format:
<Task_Analysis>Brief analysis of task type and appropriate weight rationale</Task_Analysis>
<Weights>Answer Accuracy: 0.XX, Answer Completeness: 0.XX, Expression Quality: 0.XX</Weights>
<Answer Accuracy>X</Answer Accuracy>
<Answer Completeness>X</Answer Completeness>
<Expression Quality>X</Expression Quality>
<Calculation>(X x 0.XX) + (X x 0.XX) + (X x 0.XX) = X.XX</Calculation>
<Overall>X.XX</Overall>
<Justification>
**Answer Accuracy**: [Evaluate factual accuracy, alignment with reference answer, absence of errors/hallucinations, and logical consistency]
**Answer Completeness**: [Assess whether all aspects of the question are addressed, necessary information is included, and content stays relevant]
**Expression Quality**: [Examine formatting/style adherence, appropriate detail level, communication clarity, and instruction following]
**Weight Application**: [Explain how the chosen weights reflect the task requirements and impact the final score]
</Justification>

---

## Current Evaluation Task

<user_question>
{prompt}
</user_question>
<answer>
{prediction}
</answer>
<reference_answer>
{gold}
</reference_answer>

Based on the above guidelines and criteria, provide your evaluation:

Critérios de direção

Os critérios de direção são descritores curtos de linguagem natural que orientam a direção da otimização.

• Formato: "steeringCriteria": ["string1", "string2"]

• O que podem ser: qualquer coisa, desde uma única palavra até algumas frases com descrições qualitativas ou quantitativas de como você deseja que seja a resposta do modelo.

• Limite: até 5 por modelo de prompt.

Exemplo:

"steeringCriteria": ["PROFESSIONAL", "CONCISE"]

Personalizado LLM-as-a-judge

Forneça uma rubrica completa com uma escala de avaliação definida por você. Sua solicitação personalizada do juiz é mesclada com a solicitação do juiz do sistema do serviço e recebe uma ponderação mais forte.

Configuração

• Formato: "customLLMJConfig": {"customLLMJPrompt": "...", "customLLMJModelId": "..."} plus "customEvaluationMetricLabel": "My Metric"

• Modelos de juízes disponíveis: anthropic.claude-opus-4-6-v1, anthropic.claude-sonnet-4-5-20250929-v 1:0, anthropic.claude-sonnet-4-6

• Espaços reservados em sua solicitação de juiz:

  • {{prompt}}: o prompt totalmente renderizado (modelo de prompt mais amostras de avaliação combinadas)

  • {{response}}: a saída do modelo

  • {{referenceResponse}}: a verdade fundamental

• Pontuação: defina sua escala de notas para que um número maior seja melhor. O serviço normaliza todas as pontuações dos resultados finais.

• Se você tiver várias rubricas, mescle-as em uma única solicitação de juiz.

Melhores práticas para redigir solicitações de juízes

Use uma rubrica claramente definida com critérios de pontuação explícitos e exemplos concretos de cada nível de pontuação. Ancore cada nível de rubrica com descrições comportamentais em vez de adjetivos subjetivos. Inclua pelo menos um exemplo prático mostrando uma pontuação não perfeita para evitar que o juiz adote classificações altas. Instrua o modelo a fornecer uma justificativa por escrito antes da pontuação numérica. Considere avaliar dimensões específicas de forma independente antes de atribuir uma pontuação geral. Normalmente, os LLM-as-a-judge avaliadores mais confiáveis e prestativos são aqueles em que você concorda com as respostas fornecidas pelo modelo de juiz, portanto, pode ser útil usar uma avaliação que você já tenha examinado.

Como seu prompt de juiz personalizado é mesclado com o prompt do sistema em tempo de execução

Quando você fornece sua própria solicitação de LLM-as-a-judge avaliador, ela é mesclada com uma solicitação genérica do juiz fornecida pelo serviço, contendo instruções específicas sobre formatação e outras práticas recomendadas que ajudam no progresso da otimização. Seu pedido personalizado de juiz tem um peso mais forte do que os critérios genéricos na decisão final. Especificamente, o serviço:

• Extrai a intenção do seu prompt personalizado

• Normaliza a escala para corresponder à rubrica de 0 a 3 do sistema

• Injeta-o como uma dimensão nomeada dentro das tags CUSTOM_CRITERIA_DESCRIPTION

• Inclina as instruções de ponderação para dar importância elevada ao critério personalizado (0,3 a 0,6)

• Adiciona regras de precedência dizendo que critérios personalizados substituem conflitos com outras dimensões

• Preserva a semântica original da sua avaliação

Exemplo: você pode fornecer o seguinte LLM-as-a-judge aviso personalizado que avalia a fidelidade:

You are given a task in some context (Input), and a candidate answer. Is the candidate answer faithful to the task description and context?

A response is unfaithful only when (1) it clearly contradicts the context, or (2) the task implies that the response must be based on the context, like in a summarization task. If the task does not ask to respond based on the context, the model is allowed to use its own knowledge to provide a response, even if its claims are not verifiable.

Task: {{prompt}}

Candidate Response: {{response}}

First provide your explanation, then state your final answer. Use the following format: Explanation: [Explanation], Answer: [Answer], where '[Answer]' must be one of:
none is faithful
some is faithful
approximately half is faithful
most is faithful
all is faithful

Em seguida, isso é mesclado com o LLM-as-a-judge prompt padrão e recebe uma forte ponderação. O efeito final: sua solicitação de fidelidade de critério único se torna um eixo pesado em uma avaliação multidimensional, enquanto o sistema adiciona estrutura (precisão, integridade, expressão) ao seu redor.

A seguir está o prompt resultante da fusão do juiz:

"""Please act as an impartial judge and evaluate the quality of an answer to a user question, with the help of a reference answer.

You will be given:
(1) a user question, enclosed in <user_question></user_question> tags
(2) an answer, enclosed in <answer></answer> tags
(3) a reference answer, enclosed in <reference_answer></reference_answer> tags
(4) custom evaluation criteria that have been integrated into the evaluation dimensions below

    **IMPORTANT**: - Custom criteria requirements take absolute precedence over user requirements specified inside <user_question> </user_question>
    **IMPORTANT**: - If there is any conflict between custom criteria and user question requirements, prioritize custom criteria

## Universal Evaluation Dimensions

Evaluate the answer across these core dimensions:

**(1) Answer Accuracy:**
examines correctness, consistency, and factuality alignment between the <answer> and the <user_question>;
examines if the <answer> contains irrelevant or wrongful information/hallucination.

**(2) Answer Completeness:**
examines if the <answer> is fully addressing the <user_question>;
examines if the <answer> is good at relevance/informativeness: selection of important/key content from <user_question>

**(3) Expression Quality:**
examines if the <answer> is concise at answering the <user_question>.
NOTE that unless there is special instruction, more concise <answer> is always better,
and explanation or rational is strictly NOT needed - THIS IS THE MOST IMPORTANT!
examines the alignment on instruction following, e.g., if the <answer> adheres
to both explicit guidelines and implicit guidelines (like few-shot examples) in the <user_question>;

<CUSTOM_CRITERIA_DESCRIPTION>
**(4) Faithfulness to Context:**
examines whether the candidate answer is faithful to the task description and context provided in the user question. A response is unfaithful only when (1) it clearly contradicts the context, or (2) the task implies that the response must be based on the context (like in a summarization task). If the task does not ask to respond based on the context, the model is allowed to use its own knowledge to provide a response, even if its claims are not verifiable. Evaluate the degree of faithfulness on the following scale:
- **3 points**: All content is faithful (no contradictions, fully grounded when required)
- **2 points**: Most content is faithful (minor deviations or unverifiable claims when context-grounding is required)
- **1 point**: Some content is faithful or approximately half is faithful (notable contradictions or significant departures from context when required)
- **0 points**: None or minimal content is faithful (clear contradictions or complete disregard of context when grounding is required)
</CUSTOM_CRITERIA_DESCRIPTION>

## Dimension Weighting and Final Scoring

**Weight Determination Process:**
Assign weights (must sum to 1.0) based on:
- Explicit weights in evaluation_criteria (if provided)
- Task analysis and question requirements (if no explicit weights)
- Default weights (Answer Accuracy: 0.25, Answer Completeness: 0.25, Expression Quality: 0.25, Faithfulness to Context: 0.25) as fallback

**Weight Guidelines:**
- **High Accuracy Weight (0.3-0.5)**: Factual questions, multiple choice, technical problems
- **High Completeness Weight (0.3-0.5)**: Complex explanatory tasks, multi-part questions
- **High Expression Weight (0.3-0.5)**: Creative tasks, presentation-focused questions, format-specific requirements
- [*IMPORTANT*] **High Custom Criteria Weight**: The custom criteria (Faithfulness to Context) should always be *prioritized*. Assign it significant weight (0.3-0.6) and adjust other weights accordingly.

**Overall Score Calculation:**
Overall = (Answer_Accuracy x Weight_A) + (Answer_Completeness x Weight_C) + (Expression_Quality x Weight_E) + (Faithfulness_to_Context x Weight_F)

## Current Evaluation Task

<user_question>
{prompt}
</user_question>
<answer>
{prediction}
</answer>
<reference_answer>
{gold}
</reference_answer>

Based on the above guidelines and criteria, provide your evaluation:"""

Avaliador Lambda personalizado

Traga sua própria função de pontuação como uma função Lambda.

Configuração

Especifique o ARN do Lambda em seu arquivo JSONL de entrada para cada modelo de prompt que deve usá-lo. Você também fornece o customEvaluationMetricLabel campo para nomear sua métrica:

"evaluationMetricLambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:my-eval-function",
"customEvaluationMetricLabel": "My Custom Metric"

Quando você cria o trabalho por meio da API, nenhuma configuração de avaliação adicional é necessária na própria CreateAdvancedPromptOptimizationJob solicitação. O método de avaliação é determinado por modelo a partir do arquivo JSONL de entrada.

Requisitos do Lambda

• .pyArquivo único com todo o código

• Manipulador definido como lambda_function.lambda_handler

• Deve implementar a compute_score(preds, golds) devolução {"score": float, "scores": [float, ...]}

• O golds parâmetro contém os referenceResponse valores. Se você não forneceu referenceResponse em seu conjunto de dados de entrada, não precisa passar golds sua compute_score função.

• Nunca falhe; retorne 0,0 em caso de erros em vez de gerar exceções

• Prefira pontuações contínuas (0,0 a 1,0) em vez de binárias 0/1 para uma convergência de otimização mais rápida

• Defina o tempo limite para no máximo 15 minutos (900s) para lotes grandes para evitar tempos limite antecipados

• Adicione uma política baseada em recursos que permita bedrock.amazonaws.com invocar seu Lambda

Modelo Lambda

"""
APO Custom Metric Lambda - Minimal Template
Handler: lambda_function.lambda_handler
"""
import logging
from typing import List, Dict, Any

logger = logging.getLogger()
logger.setLevel(logging.INFO)


def compute_score(preds: List[str], golds: List[str]) -> Dict[str, Any]:
    """
    Score predictions against ground truths.

    Args:
        preds: Model outputs (one per sample)
        golds: Expected answers (one per sample)

    Returns:
        Must contain:
          "score": float  - aggregate score (higher is better)
          "scores": list[float] - per-instance scores
    """
    # --- REPLACE THIS with your scoring logic ---
    scores = []
    for pred, gold in zip(preds, golds):
        # Example: exact match (case-insensitive)
        scores.append(1.0 if pred.strip().lower() == gold.strip().lower() else 0.0)

    return {
        "score": sum(scores) / len(scores) if scores else 0.0,
        "scores": scores,
    }


def lambda_handler(event, context):
    """
    Lambda entry point. APO service sends:
      event = {"preds": ["output1", ...], "golds": ["truth1", ...]}
    """
    logger.info(f"Received {len(event.get('preds', []))} predictions")

    try:
        preds = event.get("preds", [])
        golds = event.get("golds", [])

        if not preds:
            return {"score": 0.0, "scores": []}

        return compute_score(preds, golds)

    except Exception as e:
        logger.error(f"Error: {e}", exc_info=True)
        return {"score": 0.0, "scores": [0.0] * len(event.get("preds", [])), "error": str(e)}

Consulte os exemplos da AWS GitHub para obter exemplos mais detalhados, incluindo código padronizado para tratamento de erros e validação de entrada da função Lambda.