Avaliadores personalizados (pré-visualização)

Os avaliadores integrados fornecem uma forma fácil de monitorizar a qualidade das gerações da sua aplicação. Para personalizar as suas avaliações, pode criar os seus próprios avaliadores baseados em código, prompts ou endpoints.

Avaliadores personalizados permitem-lhe definir métricas de qualidade específicas de domínio que vão além do catálogo de avaliadores incorporado. Use um avaliador personalizado quando precisar de medir critérios únicos para a sua aplicação, como o tom da marca, a precisão específica do domínio ou a conformidade com o formato de saída.

Pode criar três tipos de avaliadores personalizados:

Depois de criares um avaliador personalizado, podes adicioná-lo ao catálogo de avaliadores no teu projeto Foundry e usá-lo em execuções de avaliação em lote.

Avaliadores baseados em código

Um avaliador baseado em código é uma função Python chamada grade que recebe dois parâmetros de dictado (sample e item) e devolve uma pontuação float entre 0,0 e 1,0 (maior é melhor). Na prática, todos os dados são acedidos através de item:

• Avaliação do conjunto de dados: Campos de entrada como response ou ground_truth podem ser recuperados no código Python como item.get("response") ou item.get("ground_truth").
• Avaliação do alvo do modelo ou agente: Para obter o texto de resposta gerado, use item.get("sample", {}).get("output_text").

O exemplo seguinte avalia as respostas com base no comprimento, preferindo respostas entre 50 e 500 caracteres:

def grade(sample: dict, item: dict) -> float:
    """Score based on response length (prefer 50-500 chars)."""
    # For dataset evaluation, access fields directly from item:
    response = item.get("response", "")

    # For model/agent target evaluation, use item.get("sample") instead:
    # response = item.get("sample", {}).get("output_text", "")

    if not response:
        return 0.0

    length = len(response)
    if length < 50:
        return 0.2
    elif length > 500:
        return 0.5
    return 1.0

Pacotes suportados e limites

Avaliadores baseados em código funcionam num ambiente Python sandbox com as seguintes restrições:

• O tamanho do código deve ser inferior a 256 KB.
• A execução está limitada a 2 minutos por chamada de avaliação.
• Não há acesso à rede disponível em tempo de execução.
• O limite de memória é de 2 GB, o limite de disco é de 1 GB e o CPU está limitado a 2 núcleos.

Os seguintes pacotes de terceiros estão disponíveis:

Os corpora punktNLTK , stopwords, wordnet, omw-1.4, e names estão pré-carregados.

Parâmetros de execução

pass_threshold e deployment_name são necessários como parâmetros de inicialização quando se cria um avaliador baseado em código. Embora os avaliadores baseados em código não chamem um LLM, o esquema da API de serviço requer deployment_name orquestração por execução de avaliação. Podes passar qualquer nome válido de implementação de modelo do teu projeto.

Avaliadores baseados em prompts

Um avaliador baseado em prompts utiliza um modelo de prompt de juiz que um LLM avalia para cada item. As variáveis modelo usam colchetes duplos (por exemplo, {{query}}) e mapeiam para os teus campos de dados de entrada.

Os avaliadores baseados em prompts suportam três métodos de pontuação:

• Ordinal: Pontuações inteiras numa escala discreta que defines (por exemplo, 1–5). Quanto mais alto, melhor.
• Contínuo: Pontuações de flutuação para medições de granulação fina num intervalo que definas (por exemplo, 0.0–1.0). Quanto mais alto, melhor.
• Binário (verdadeiro/falso): Resultado booleano para verificações baseadas em limiares.

O avaliador deve devolver um objeto JSON com result e reason. O tipo corresponde result ao teu método de pontuação: um inteiro para ordinal, um float para contínuo ou um booleano para binário.

O exemplo seguinte utiliza pontuação ordinal (1–5) para avaliar a amizade de uma resposta:

Friendliness assesses the warmth and approachability of the response.
Rate the friendliness of the response between one and five using the following scale:

1 - Unfriendly or hostile
2 - Mostly unfriendly
3 - Neutral
4 - Mostly friendly
5 - Very friendly

Assign a rating based on the tone and demeanor of the response.

Response:
{{response}}

Output Format (JSON):
{
  "result": <integer from 1 to 5>,
  "reason": "<brief explanation for the score>"
}

Parâmetros de execução

Tanto deployment_name como threshold são necessários como parâmetros de inicialização quando crias um avaliador baseado em prompts.

Avaliadores baseados em endpoints

Um avaliador baseado em endpoints delega a pontuação a um endpoint HTTP externo que possui e opera. O serviço de avaliação chama o seu endpoint para cada item (ou lote de itens), passando os dados de entrada mapeados como uma carga útil JSON. O seu endpoint processa os dados usando qualquer lógica que escolher e devolve uma resposta JSON com pontuações.

Use um avaliador baseado em endpoints quando precisar de:

• Acesso à rede a serviços externos ou bases de dados durante a pontuação.
• Modelos proprietários ou pipelines de ML alojados na sua própria infraestrutura.
• Lógica de pontuação complexa que ultrapassa os limites do avaliador baseado em código em formato sandbox.
• Integração com serviços de avaliação ou APIs existentes.

Como funciona

1. Implementa-se um endpoint HTTP que aceita pedidos POST com dados de avaliação.
2. Crias uma ligação no teu projeto Foundry que armazena a URL do endpoint e as credenciais de autenticação.
3. Registas um avaliador baseado no endpoint que faz referência à ligação.
4. Quando uma avaliação é executada, o serviço resolve a ligação, liga ao seu endpoint com os dados de entrada e regista a resposta como resultado da avaliação.

Esquema de pedido de endpoint

O serviço de avaliação envia um pedido POST ao seu endpoint com um corpo JSON contendo metadados de avaliação e os campos de entrada mapeados.

A tabela seguinte descreve os campos que o seu endpoint recebe:

Exemplo de pedido:

{
  "schema_version": "0.0.1",
  "evaluator_name": "my_endpoint_evaluator",
  "evaluator_version": "1",
  "evaluation_level": "turn",
  "data": {
    "item": {
      "query": "What is the capital of France?"
    },
    "sample": {
      "response": "Paris"
    }
  }
}

Esquema de resposta do endpoint

A tabela seguinte descreve os campos que o seu endpoint pode devolver:

Resposta de Sucesso:

O seu endpoint deve devolver um objeto JSON que cumpra o esquema padrão de resultados de avaliação:

{
  "schema_version": "0.0.1",
  "score": 0.95,
  "reason": "The response accurately answers the question using the provided context.",
  "status": "completed",
  "properties": {
    "confidence": 0.87,
    "source_coverage": "full"
  },
  "threshold": 3,
  "passed": true
}

Resposta ao Fracasso:

Em caso de erro, o seu endpoint precisa de devolver um objeto JSON que cumpra o seguinte esquema:

 {
   "schema_version": "0.0.1",
   "status": "error",
   "error": {
     "code": "500",
     "message": "Model inference failed"
   }
 }

Authentication

Os avaliadores baseados em endpoints suportam dois métodos de autenticação através de ligações de projeto:

Criar a ligação ao endpoint

As ligações armazenam a URL do endpoint e as credenciais de autenticação. Crie uma ligação usando o cliente de gestão Azure Cognitive Services:

Ligação à Chave API

from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
from azure.mgmt.cognitiveservices.models import ConnectionPropertiesV2BasicResource

mgmt_client = CognitiveServicesManagementClient(
    credential=credential,
    subscription_id=subscription_id,
)

connection = ConnectionPropertiesV2BasicResource(
    properties={
        "category": "ApiKey",
        "target": "https://your-endpoint.azurewebsites.net/api/evaluate",
        "authType": "ApiKey",
        "credentials": {
            "key": "<your-api-key>",
        },
    },
)

mgmt_client.account_connections.create(
    resource_group_name=resource_group,
    account_name=account_name,
    connection_name="my-endpoint-connection",
    connection=connection,
)

Microsoft Entra ID connection

connection = ConnectionPropertiesV2BasicResource(
    properties={
        "category": "CustomKeys",
        "target": "https://your-endpoint.azurewebsites.net/api/evaluate",
        "authType": "AAD",
        "credentials": {
            "Audience": "api://<your-app-registration-client-id>",
        },
    },
)

mgmt_client.account_connections.create(
    resource_group_name=resource_group,
    account_name=account_name,
    connection_name="my-endpoint-entra-connection",
    connection=connection,
)

Para a autenticação Entra ID, o seu endpoint deve estar configurado para aceitar tokens emitidos pela identidade gerida do projeto. Isto normalmente envolve:

• Registar uma aplicação no Microsoft Entra ID para o seu endpoint.
• Ativar a Autenticação Fácil (ou validação equivalente de tokens) no seu endpoint.
• Concedendo à identidade gerida do projeto uma atribuição de funções de aplicação na aplicação alvo.

Registe o avaliador

Após criar a ligação, regista um avaliador baseado em endpoint que a referencia:

endpoint_evaluator = project_client.beta.evaluators.create_version(
    name="my-endpoint-evaluator",
    evaluator_version={
        "name": "my-endpoint-evaluator",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "My Endpoint Evaluator",
        "description": "Scores responses using a custom evaluation endpoint",
        "definition": {
            "type": "endpoint",
            "connection_name": "my-endpoint-connection",
        },
    },
)

Execute uma avaliação com um avaliador baseado em endpoints

Use o data_mapping campo para especificar quais os campos de dados de entrada enviados para o seu endpoint:

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "endpoint_eval",
        "evaluator_name": "my-endpoint-evaluator",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "context": "{{item.context}}",
        },
    },
]

As data_mapping chaves tornam-se os campos JSON que o seu endpoint recebe. Mapeie-os para as colunas do seu conjunto de dados de avaliação usando {{item.<field_name>}} sintaxe.

Implemente o seu endpoint

O seu endpoint de avaliação pode ser qualquer serviço HTTP que aceite pedidos POST e devolve JSON. Opções comuns de alojamento incluem:

• Funções do Azure: Alojamento leve e serverless para lógica de pontuação simples.
• Serviço de Aplicações do Azure: Alojamento completo de aplicações web para pipelines de avaliação complexos.
• Azure Container Apps: Alojamento baseado em containers para inferência de modelos de ML.

O endpoint deve responder dentro do timeout do serviço de avaliação (30 segundos) e devolver uma resposta JSON válida para cada pedido.

Crie um avaliador personalizado com o SDK

Pré-requisitos e configuração

Instala o SDK e configura o teu cliente:

pip install "azure-ai-projects>=2.0.0"

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import EvaluatorCategory, EvaluatorDefinitionType
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (required for prompt-based evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Create the project client
project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

Crie um avaliador baseado em código

Passa a grade() função como uma cadeia no code_text campo. Defina o data_schema para declarar os campos de entrada que a sua função espera, e o metrics para descrever a pontuação que a sua função devolve. Os avaliadores baseados em código utilizam o continuous tipo métrico com um intervalo de 0,0 a 1,0.

Primeiro, defina o esquema da versão do avaliador:

code_evaluator = project_client.beta.evaluators.create_version(
    name="response_length_scorer",
    evaluator_version={
        "name": "response_length_scorer",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "Response Length Scorer",
        "description": "Scores responses based on length, preferring 50-500 characters",
        "definition": {
            "type": EvaluatorDefinitionType.CODE,
            "code_text": (
                'def grade(sample: dict, item: dict) -> float:\n'
                '    """Score based on response length (prefer 50-500 chars)."""\n'
                '    response = item.get("response", "")\n'
                '    if not response:\n'
                '        return 0.0\n'
                '    length = len(response)\n'
                '    if length < 50:\n'
                '        return 0.2\n'
                '    elif length > 500:\n'
                '        return 0.5\n'
                '    return 1.0\n'
            ),
            "init_parameters": {
                "type": "object",
                "properties": {
                    "deployment_name": {"type": "string"},
                    "pass_threshold": {"type": "number"},
                },
                "required": ["deployment_name", "pass_threshold"],
            },
            "metrics": {
                "result": {
                    "type": "continuous",
                    "desirable_direction": "increase",
                    "min_value": 0.0,
                    "max_value": 1.0,
                }
            },
            "data_schema": {
                "type": "object",
                "required": ["item"],
                "properties": {
                    "item": {
                        "type": "object",
                        "properties": {
                            "response": {"type": "string"},
                        },
                    },
                },
            },
        },
    },
)

Para um exemplo completo, veja o avaliador baseado em código código Python a amostra SDK.

Crie um avaliador baseado em prompts

Passa o enunciado do juiz no prompt_text terreno. Defina o data_schema para declarar os campos de entrada que o seu prompt espera, e metrics o para descrever o método de pontuação e o intervalo. Declaram init_parameters a implementação do modelo e o limiar que o avaliador precisa em tempo de execução.

prompt_evaluator = project_client.beta.evaluators.create_version(
    name="friendliness_evaluator",
    evaluator_version={
        "name": "friendliness_evaluator",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "Friendliness Evaluator",
        "description": "Evaluates the warmth and approachability of a response",
        "definition": {
            "type": EvaluatorDefinitionType.PROMPT,
            "prompt_text": (
                "Friendliness assesses the warmth and approachability of the response.\n"
                "Rate the friendliness of the response between one and five "
                "using the following scale:\n\n"
                "1 - Unfriendly or hostile\n"
                "2 - Mostly unfriendly\n"
                "3 - Neutral\n"
                "4 - Mostly friendly\n"
                "5 - Very friendly\n\n"
                "Assign a rating based on the tone and demeanor of the response.\n\n"
                "Response:\n{{response}}\n\n"
                "Output Format (JSON):\n"
                '{\n  "result": <integer from 1 to 5>,\n'
                '  "reason": "<brief explanation for the score>"\n}\n'
            ),
            "init_parameters": {
                "type": "object",
                "properties": {
                    "deployment_name": {"type": "string"},
                    "threshold": {"type": "number"},
                },
                "required": ["deployment_name", "threshold"],
            },
            "data_schema": {
                "type": "object",
                "properties": {
                    "response": {"type": "string"},
                },
                "required": ["response"],
            },
            "metrics": {
                "custom_prompt": {
                    "type": "ordinal",
                    "desirable_direction": "increase",
                    "min_value": 1,
                    "max_value": 5,
                }
            },
        },
    },
)

Para um exemplo completo, veja o avaliador baseado em prompts Python SDK sample.

Execute uma avaliação com um avaliador personalizado

Depois de criar avaliadores personalizados, use-os numa execução de avaliação da mesma forma que usa avaliadores incorporados. Pode incluir vários avaliadores numa única corrida.

O exemplo seguinte executa tanto o baseado response_length_scorer em código como o baseado friendliness_evaluator em prompts em conjunto.

Definir e executar a avaliação

# Define the data schema
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "response": {"type": "string"},
        },
        "required": ["response"],
    },
)

# Reference both custom evaluators in testing criteria
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "response_length_scorer",
        "evaluator_name": "response_length_scorer",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
            "pass_threshold": 0.5,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "friendliness_evaluator",
        "evaluator_name": "friendliness_evaluator",
        "data_mapping": {
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
            "threshold": 3,
        },
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="custom-eval-test",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Run the evaluation with inline data
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="custom-eval-run-01",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileContent(
            type="file_content",
            content=[
                SourceFileContentContent(
                    item={
                        "response": "I'm sorry this watch isn't working for you. I'd be happy to help you with a replacement!",
                    }
                ),
                SourceFileContentContent(
                    item={
                        "response": "I will not apologize for my behavior!",
                    }
                ),
            ],
        ),
    ),
)

Obtenha resultados

Consulta a avaliação até terminar, depois recupera os resultados por item e o URL do relatório.

while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=eval_object.id)
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)

# Get per-item results
output_items = list(
    client.evals.runs.output_items.list(run_id=run.id, eval_id=eval_object.id)
)

print(f"Status: {run.status}")
print(f"Report: {run.report_url}")

Recursos de limpeza

Elimine uma versão personalizada do avaliador e a avaliação quando deixar de precisar deles:

# Delete the custom evaluator version
project_client.beta.evaluators.delete_version(
    name="response_length_scorer",
    version=code_evaluator.version,
)

# Delete the evaluation
client.evals.delete(eval_id=eval_object.id)

Para mais informações sobre opções de fontes de dados, mapeamentos de avaliadores e cenários avançados, consulte Executar avaliações a partir do SDK.

Para exemplos adicionais, incluindo listagem, atualização e eliminação de avaliadores, consulte a evaluator catalog management Python SDK sample.

Crie um avaliador personalizado no portal

Pode criar avaliadores personalizados diretamente no portal Azure AI Foundry sem precisar de escrever código SDK.

1. No seu projeto Foundry, vá ao catálogo do Evaluation>Evaluator.
2. Selecione Avaliar>Personalizado Criar.
3. Preencha os seguintes campos:

Use um avaliador personalizado numa avaliação de portal

Depois de criar um avaliador personalizado, utilize-o numa execução de avaliação a partir do portal:

1. No seu projeto Foundry, vá a Avaliação e selecione Criar.
2. Siga o assistente de criação de avaliações. No passo de Critérios , selecione Adicionar avaliador.
3. Escolha o seu avaliador personalizado do catálogo de avaliadores.
4. Forneça os parâmetros de inicialização necessários. Para avaliadores baseados em prompts, forneça a implementação e o limiar do modelo. Para avaliadores baseados em código, forneça o limiar de aprovação.
5. Completa o feiticeiro e começa a execução de avaliação.

Para passos detalhados sobre avaliações em corrida no portal, consulte Avaliações em corrida no portal.

Avaliadores personalizados ao nível da conversa

Avaliadores personalizados podem pontuar conversas inteiras em vez de turnos individuais. Para permitir uma avaliação ao nível da conversa:

1. Set evaluation_level="conversation" na execução de avaliação
2. Desenha a tua grade() função para esperar item["messages"] como um array de conversa

Quando é executado ao nível da conversa, o item dict recebe o array completo de mensagens de conversa em vez de um único par de consulta/resposta. Isto permite-lhe criar métricas personalizadas que avaliam toda a interação do utilizador.

Exemplo: verificação de conformidade ao nível da sessão

Este exemplo verifica se o agente revelou um aviso obrigatório em algum momento durante a conversa:

def grade(sample: dict, item: dict) -> float:
    """Check if agent disclosed required disclaimer during conversation."""
    messages = item.get("messages", [])
    
    for msg in messages:
        if msg.get("role") == "assistant":
            content = msg.get("content", "")
            if isinstance(content, str) and "not financial advice" in content.lower():
                return 1.0
    
    return 0.0  # Disclaimer never provided

Exemplo: Pontuador do comprimento da conversa

Este exemplo pontua as conversas com base no facto de terem sido resolvidas dentro de um número alvo de turnos:

def grade(sample: dict, item: dict) -> float:
    """Score based on conversation length (prefer shorter resolutions)."""
    messages = item.get("messages", [])
    
    # Count user turns (excludes system messages)
    user_turns = sum(1 for msg in messages if msg.get("role") == "user")
    
    if user_turns <= 2:
        return 1.0  # Resolved quickly
    elif user_turns <= 4:
        return 0.7  # Reasonable length
    elif user_turns <= 6:
        return 0.4  # Getting long
    else:
        return 0.2  # Too many turns

Conteúdo relacionado

• Avaliações de execução a partir do SDK
• Avaliadores incorporados