Avaliadores personalizados (versão prévia)

Os avaliadores internos fornecem uma maneira fácil de monitorar a qualidade das gerações do aplicativo. Para personalizar suas avaliações, você pode criar seus próprios avaliadores baseados em código, baseados em prompt ou ponto de extremidade.

Os avaliadores personalizados permitem definir métricas de qualidade específicas do domínio que vão além do catálogo de avaliadores internos. Use um avaliador personalizado quando precisar medir critérios exclusivos para seu aplicativo, como tom de marca, precisão específica do domínio ou conformidade do formato de saída.

Você pode criar três tipos de avaliadores personalizados:

Depois de criar um avaliador personalizado, você pode adicioná-lo ao catálogo do avaliador em seu projeto do 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 ditado (sample e item) e retorna uma pontuação flutuante entre 0,0 e 1,0 (superior é melhor). Na prática, todos os dados são acessados por meio itemde:

• Dataset evaluation: 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 de destino do modelo ou agente: para buscar o texto de resposta gerado, use item.get("sample", {}).get("output_text").

O exemplo a seguir pontua 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 e limites com suporte

Os avaliadores baseados em código são executados em um ambiente de Python em área restrita com as seguintes restrições:

• O tamanho do código deve ter menos de 256 KB.
• A execução é limitada a 2 minutos por chamada de classificação.
• Nenhum acesso à rede está disponível em runtime.
• O limite de memória é de 2 GB, o limite de disco é de 1 GB e a CPU é limitada a 2 núcleos.

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

O NLTK corpora punkt, stopwords, wordnet, e omw-1.4names são pré-carregados.

Parâmetros de runtime

pass_threshold e deployment_name são necessários como parâmetros de inicialização ao criar um avaliador baseado em código. Mesmo que os avaliadores baseados em código não chamem uma LLM, o esquema da API de serviço requer deployment_name uma orquestração de execução de avaliação. Você pode passar qualquer nome de implantação de modelo válido do seu projeto.

Avaliadores baseados em prompt

Um avaliador baseado em prompt usa um modelo de prompt de juiz que um LLM avalia para cada item. As variáveis de modelo usam chaves duplas (por exemplo) {{query}}e são mapeadas para os campos de dados de entrada.

Os avaliadores baseados em prompt dão suporte a três métodos de pontuação:

• Ordinal: pontuações de inteiro em uma escala discreta que você define (por exemplo, 1 a 5). Mais alto é melhor.
• Contínuo: pontuações flutuantes para medição refinada em um intervalo definido (por exemplo, 0,0 a 1,0). Mais alto é melhor.
• Binário (true/false): resultado booliano para verificações baseadas em limite.

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

O prompt de exemplo a seguir usa pontuação ordinal (1 a 5) para avaliar a amigávelidade 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 runtime

Ambos deployment_name e threshold são necessários como parâmetros de inicialização quando você cria um avaliador baseado em prompt.

Avaliadores baseados em ponto de extremidade

Um avaliador baseado em ponto de extremidade delega a pontuação a um ponto de extremidade HTTP externo que você possui e opera. O serviço de avaliação chama seu ponto de extremidade para cada item (ou lote de itens), passando os dados de entrada mapeados como um conteúdo JSON. O ponto de extremidade processa os dados usando qualquer lógica escolhida e retorna uma resposta JSON com pontuações.

Use um avaliador baseado em ponto de extremidade quando precisar:

• Acesso de rede a serviços ou bancos de dados externos durante a pontuação.
• Modelos proprietários ou pipelines de ML hospedados em sua própria infraestrutura.
• Lógica de pontuação complexa que excede os limites do avaliador baseado em código em área restrita.
• Integração com APIs ou serviços de avaliação existentes.

Como funciona

1. Você implanta um ponto de extremidade HTTP que aceita solicitações POST com dados de avaliação.
2. Você cria uma conexão em seu projeto do Foundry que armazena a URL do ponto de extremidade e as credenciais de autenticação.
3. Você registra um avaliador baseado em ponto de extremidade que faz referência à conexão.
4. Quando uma avaliação é executada, o serviço resolve a conexão, chama o ponto de extremidade com os dados de entrada e registra a resposta como resultado da avaliação.

Esquema de solicitação de ponto de extremidade

O serviço de avaliação envia uma solicitação POST ao ponto de extremidade com um corpo JSON contendo metadados de avaliação e os campos de entrada mapeados.

A tabela a seguir descreve os campos que o ponto de extremidade recebe:

Solicitação de exemplo:

{
  "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 ponto de extremidade

A tabela a seguir descreve os campos que seu ponto de extremidade pode retornar:

Resposta de êxito:

O ponto de extremidade deve retornar um objeto JSON que esteja em conformidade com o esquema de resultados de avaliação padrã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
}

Reponse de falha:

Em caso de erro, o ponto de extremidade precisa retornar um objeto JSON que esteja em conformidade com o seguinte esquema:

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

Authentication

Os avaliadores baseados em ponto de extremidade dão suporte a dois métodos de autenticação por meio de conexões de projeto:

Criar a conexão de ponto de extremidade

As conexões armazenam a URL do ponto de extremidade e as credenciais de autenticação. Crie uma conexão usando o cliente de gerenciamento dos Serviços Cognitivos Azure:

Conexão de chave de 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,
)

conexão Microsoft Entra ID

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 Entra ID autenticação, seu ponto de extremidade deve ser configurado para aceitar tokens emitidos pela identidade gerenciada do projeto. Isso normalmente envolve:

• Registrando um aplicativo em Microsoft Entra ID para seu ponto de extremidade.
• Habilitar a Autenticação Fácil (ou validação de token equivalente) em seu ponto de extremidade.
• Concedendo à identidade gerenciada do projeto uma atribuição de função de aplicativo no aplicativo de destino.

Registrar o avaliador

Depois de criar a conexão, registre um avaliador baseado em ponto de extremidade que faça referência a ela:

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

Executar uma avaliação com um avaliador baseado em ponto de extremidade

Use o data_mapping campo para especificar quais campos de dados de entrada são enviados para o ponto de extremidade:

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 se tornam os campos JSON recebidos pelo ponto de extremidade. Mapeie-as para as colunas no conjunto de dados de avaliação usando {{item.<field_name>}} a sintaxe.

Implantar seu ponto de extremidade

O ponto de extremidade de avaliação pode ser qualquer serviço HTTP que aceite solicitações POST e retorne JSON. As opções comuns de hospedagem incluem:

• Azure Functions: hospedagem leve e sem servidor para lógica de pontuação simples.
• Serviço de Aplicativo do Azure: hospedagem completa do aplicativo Web para pipelines de avaliação complexos.
• Aplicativos de Contêiner do Azure: hospedagem baseada em contêiner para inferência de modelo de ML.

O ponto de extremidade deve responder dentro do tempo limite do serviço de avaliação (30 segundos) e retornar uma resposta JSON válida para cada solicitação.

Criar um avaliador personalizado com o SDK

Pré-requisitos e configuração

Instale o SDK e configure seu 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()

Criar um avaliador baseado em código

Passe a grade() função como uma cadeia de caracteres no code_text campo. Defina os data_schema campos de entrada que sua função espera e descreva metrics a pontuação retornada pela função. Os avaliadores baseados em código usam o continuous tipo de métrica com um intervalo de 0,0 a 1,0.

Primeiro, defina o esquema de 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 obter um exemplo completo, consulte o <> exemplo do SDK Python avaliador baseado em código.

Criar um avaliador baseado em prompt

Passe o prompt do juiz no prompt_text campo. Defina os data_schema campos de entrada que seu prompt espera e descreva o método de pontuação e o metrics intervalo. Declare init_parameters a implantação do modelo e o limite de que o avaliador precisa em runtime.

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 obter um exemplo completo, consulte o avaliador baseado em prompt Python exemplo de SDK.

Executar uma avaliação com um avaliador personalizado

Depois de criar avaliadores personalizados, use-os em uma execução de avaliação da mesma forma que você usa avaliadores internos. Você pode incluir vários avaliadores em uma única execução.

O exemplo a seguir executa o baseado em response_length_scorer código e o prompt em friendliness_evaluator 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!",
                    }
                ),
            ],
        ),
    ),
)

Obter resultados

Sondar a execução da avaliação até que ela seja concluída e recupere os resultados por item e a 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}")

Limpar recursos

Exclua uma versão personalizada do avaliador e a avaliação quando você não precisar mais delas:

# 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 obter mais informações sobre opções de fonte de dados, mapeamentos de avaliador e cenários avançados, consulte Executar avaliações do SDK.

Para obter exemplos adicionais, incluindo listagem, atualização e exclusão de avaliadores, consulte o exemplo Python de gerenciamento de catálogo de reavaliadores.

Criar um avaliador personalizado no portal

Você pode criar avaliadores personalizados diretamente no portal do Fábrica de IA do Azure sem escrever código SDK.

1. Em seu projeto do Foundry, vá para ocatálogo do Avaliador de >.
2. Selecione Criar avaliador> personalizado.
3. Preencha os seguintes campos:

Usar um avaliador personalizado em uma avaliação do portal

Depois de criar um avaliador personalizado, use-o em uma execução de avaliação do portal:

1. Em seu projeto do Foundry, vá para Avaliação e selecione Criar.
2. Siga o assistente de criação de avaliação. Na etapa Critérios , selecione Adicionar avaliador.
3. Escolha seu avaliador personalizado no catálogo do avaliador.
4. Forneça os parâmetros de inicialização necessários. Para avaliadores baseados em prompt, forneça a implantação e o limite do modelo. Para avaliadores baseados em código, forneça o limite de passagem.
5. Conclua o assistente e inicie a execução da avaliação.

Para obter etapas detalhadas sobre como executar avaliações do portal, consulte Executar avaliações do portal.

Avaliadores personalizados no nível da conversa

Os avaliadores personalizados podem pontuar conversas inteiras em vez de turnos individuais. Para habilitar a avaliação em nível de conversa:

1. Definir evaluation_level="conversation" na execução de avaliação
2. Projetar sua grade() função para esperar item["messages"] como uma matriz de conversa

Ao executar no nível da conversa, o item ditado recebe a matriz de mensagens de conversa completa em vez de um único par de consulta/resposta. Isso permite criar métricas personalizadas que avaliam toda a interação do usuário.

Exemplo: Verificação de conformidade no nível da sessão

Este exemplo verifica se o agente divulgou um aviso de isenção de responsabilidade necessá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: Marcador de comprimento da conversa

Este exemplo pontua conversas com base em se elas foram resolvidas em um número de destino 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

• Executar avaliações do SDK
• Avaliadores internos