Evaluadores personalizados (versión preliminar)

Los evaluadores integrados proporcionan una manera sencilla de supervisar la calidad de las generaciones de la aplicación. Para personalizar las evaluaciones, puede crear sus propios evaluadores basados en código, basados en mensajes o en puntos de conexión.

Los evaluadores personalizados permiten definir métricas de calidad específicas del dominio que van más allá del catálogo de evaluadores integrado. Use un evaluador personalizado cuando necesite medir criterios únicos para la aplicación, como el tono de marca, la precisión específica del dominio o el cumplimiento del formato de salida.

Puede crear tres tipos de evaluadores personalizados:

Después de crear un evaluador personalizado, puede agregarlo al catálogo del evaluador en el proyecto foundry y usarlo en ejecuciones de evaluación por lotes.

Evaluadores basados en código

Un evaluador basado en código es una función Python denominada grade que recibe dos parámetros dict (sample y item) y devuelve una puntuación float entre 0,0 y 1,0 (es mejor). En la práctica, se accede a todos los datos a través de item:

• evaluación Dataset: los campos de entrada como response o ground_truth se pueden recuperar en el código de Python, como item.get("response") o item.get("ground_truth").
• Evaluación de destino del modelo o agente: para capturar texto de respuesta generado, use item.get("sample", {}).get("output_text").

En el ejemplo siguiente se puntúan las respuestas en función de la longitud, lo que prefiere entre 50 y 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

Paquetes y límites admitidos

Los evaluadores basados en código se ejecutan en un entorno de Python de espacio aislado con las siguientes restricciones:

• El tamaño del código debe ser inferior a 256 KB.
• La ejecución se limita a 2 minutos por llamada de calificación.
• No hay acceso a la red disponible en tiempo de ejecución.
• El límite de memoria es de 2 GB, el límite de disco es de 1 GB y la CPU está limitada a 2 núcleos.

Los siguientes paquetes de terceros están disponibles:

El nlTK corpora punkt, stopwords, wordnet, omw-1.4, y names se cargan previamente.

Parámetros de tiempo de ejecución

pass_threshold y deployment_name son necesarios como parámetros de inicialización al crear un evaluador basado en código. Aunque los evaluadores basados en código no llaman a un LLM, el esquema de la API de servicio requiere deployment_name para la orquestación de ejecución de evaluación. Puede pasar cualquier nombre de implementación de modelo válido desde el proyecto.

Evaluadores basados en solicitudes

Un evaluador basado en mensajes usa una plantilla de solicitud de juez que un LLM evalúa para cada elemento. Las variables de plantilla usan llaves dobles (por ejemplo, {{query}}) y se asignan a los campos de datos de entrada.

Los evaluadores basados en mensajes admiten tres métodos de puntuación:

• Ordinal: puntuaciones enteras en una escala discreta que defina (por ejemplo, 1–5). Más alto es mejor.
• Continuo: puntuaciones de float para la medición específica en un intervalo definido (por ejemplo, 0,0–1,0). Más alto es mejor.
• Binario (true/false): resultado booleano para comprobaciones basadas en umbrales.

El evaluador debe devolver un objeto JSON con result y reason. El tipo de coincide con el método de result puntuación: un entero para ordinal, un valor float para continuo o un valor booleano para binario.

En el siguiente símbolo del sistema de ejemplo se usa la puntuación ordinal (1–5) para evaluar la facilidad de uso de una respuesta:

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 tiempo de ejecución

Tanto deployment_name como threshold son necesarios como parámetros de inicialización al crear un evaluador basado en mensajes.

Evaluadores basados en puntos de conexión

Un evaluador basado en puntos de conexión delega la puntuación en un punto de conexión HTTP externo que posee y opera. El servicio de evaluación llama al punto de conexión para cada elemento (o lote de elementos), pasando los datos de entrada asignados como una carga JSON. El punto de conexión procesa los datos mediante cualquier lógica que elija y devuelve una respuesta JSON con puntuaciones.

Use un evaluador basado en puntos de conexión cuando necesite:

• Acceso de red a servicios externos o bases de datos durante la puntuación.
• Modelos propietarios o canalizaciones de ML hospedadas en su propia infraestructura.
• Lógica de puntuación compleja que supera los límites del evaluador basado en código de espacio aislado.
• Integración con los servicios de evaluación o las API existentes.

Cómo funciona

1. Implemente un punto de conexión HTTP que acepte solicitudes POST con datos de evaluación.
2. Cree una conexión en el proyecto foundry que almacene la dirección URL del punto de conexión y las credenciales de autenticación.
3. Registra un evaluador basado en punto de conexión que hace referencia a la conexión.
4. Cuando se ejecuta una evaluación, el servicio resuelve la conexión, llama al punto de conexión con los datos de entrada y registra la respuesta como resultado de la evaluación.

Esquema de solicitud de punto de conexión

El servicio de evaluación envía una solicitud POST al punto de conexión con un cuerpo JSON que contiene metadatos de evaluación y los campos de entrada asignados.

En la tabla siguiente se describen los campos que recibe el punto de conexión:

Solicitud de ejemplo:

{
  "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 respuesta del punto de conexión

En la tabla siguiente se describen los campos que puede devolver el punto de conexión:

Respuesta correcta:

El punto de conexión debe devolver un objeto JSON que se ajuste al esquema de resultados de evaluación estándar:

{
  "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
}

Repositorio de errores:

En caso de error, el punto de conexión debe devolver un objeto JSON que se ajuste al esquema siguiente:

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

Authentication

Los evaluadores basados en puntos de conexión admiten dos métodos de autenticación mediante conexiones de proyecto:

Creación de la conexión de punto de conexión

Las conexiones almacenan la dirección URL del punto de conexión y las credenciales de autenticación. Cree una conexión mediante el cliente de administración de Azure Cognitive Services:

Conexión de clave 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,
)

conexión de 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 autenticación, el punto de conexión debe configurarse para aceptar tokens emitidos por la identidad administrada del proyecto. Esto suele implicar lo siguiente:

• Registrar una aplicación en Microsoft Entra ID para el punto de conexión.
• Habilitación de Easy Auth (o validación de tokens equivalente) en el punto de conexión.
• Conceder a la identidad administrada del proyecto una asignación de roles de aplicación en la aplicación de destino.

Registro del evaluador

Después de crear la conexión, registre un evaluador basado en punto de conexión que haga referencia a ella:

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

Ejecución de una evaluación con un evaluador basado en puntos de conexión

Use el data_mapping campo para especificar qué campos de datos de entrada se envían al punto de conexión:

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

Las data_mapping claves se convierten en los campos JSON que recibe el punto de conexión. Asígnelos a las columnas del conjunto de datos de evaluación mediante {{item.<field_name>}} la sintaxis.

Implementación del punto de conexión

El punto de conexión de evaluación puede ser cualquier servicio HTTP que acepte solicitudes POST y devuelva JSON. Entre las opciones comunes de hospedaje se incluyen:

• Azure Functions: hospedaje ligero y sin servidor para una lógica de puntuación sencilla.
• Azure App Service: hospedaje completo de aplicaciones web para canalizaciones de evaluación complejas.
• Azure Container Apps: hospedaje basado en contenedores para la inferencia del modelo de ML.

El punto de conexión debe responder dentro del tiempo de espera del servicio de evaluación (30 segundos) y devolver una respuesta JSON válida para cada solicitud.

Creación de un evaluador personalizado con el SDK

Requisitos previos y configuración

Instale el SDK y configure el 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()

Creación de un evaluador basado en código

Pase la grade() función como una cadena en el code_text campo . Defina para data_schema declarar los campos de entrada que espera la función y para metrics describir la puntuación que devuelve la función. Los evaluadores basados en código usan el continuous tipo de métrica con un intervalo de 0,0 a 1,0.

En primer lugar, defina el esquema de versión del evaluador:

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 obtener un ejemplo completo, consulte el ejemplo de evaluador basado en código Python SDK.

Creación de un evaluador basado en mensajes

Pase el mensaje del juez en el prompt_text campo. data_schema Defina para declarar los campos de entrada que espera la solicitud y para metrics describir el método de puntuación y el intervalo. init_parameters Declara la implementación del modelo y el umbral que el evaluador necesita en tiempo de ejecución.

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 obtener un ejemplo completo, consulte el ejemplo prompt-based evaluador Python SDK.

Ejecución de una evaluación con un evaluador personalizado

Después de crear evaluadores personalizados, úselos en una ejecución de evaluación de la misma manera que usa evaluadores integrados. Puede incluir varios evaluadores en una sola ejecución.

En el ejemplo siguiente se ejecutan tanto el código basado en response_length_scorer código como el basado en friendliness_evaluator la solicitud.

Definición y ejecución de la evaluación

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

Obtención de resultados

Sondee la ejecución de evaluación hasta que finalice y recupere los resultados por elemento y la dirección URL del informe.

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

Limpieza de recursos

Elimine una versión del evaluador personalizado y la evaluación cuando ya no las necesite:

# 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 obtener más información sobre las opciones de origen de datos, las asignaciones de evaluadores y los escenarios avanzados, consulte Ejecución de evaluaciones desde el SDK.

Para obtener ejemplos adicionales, como enumerar, actualizar y eliminar evaluadores, consulte la evaluator catalog management Python ejemplo del SDK.

Creación de un evaluador personalizado en el portal

Puede crear evaluadores personalizados directamente en el portal de Fundición de IA de Azure sin escribir código del SDK.

1. En el proyecto foundry, vaya alcatálogo evaluador> evaluación.
2. Seleccione Personalizado evaluador>Crear.
3. Rellene los campos siguientes:

Uso de un evaluador personalizado en una evaluación del portal

Después de crear un evaluador personalizado, úselo en una ejecución de evaluación desde el portal:

1. En el proyecto Foundry, vaya a Evaluación y seleccione Crear.
2. Siga el Asistente para la creación de evaluaciones. En el paso Criterios , seleccione Agregar evaluador.
3. Elija el evaluador personalizado en el catálogo del evaluador.
4. Proporcione los parámetros de inicialización necesarios. En el caso de los evaluadores basados en mensajes, proporcione la implementación y el umbral del modelo. En el caso de los evaluadores basados en código, proporcione el umbral de paso.
5. Complete el asistente e inicie la ejecución de evaluación.

Para obtener pasos detallados sobre la ejecución de evaluaciones desde el portal, consulte Ejecución de evaluaciones desde el portal.

Evaluadores personalizados de nivel de conversación

Los evaluadores personalizados pueden puntuar conversaciones completas en lugar de turnos individuales. Para habilitar la evaluación de nivel de conversación:

1. Establecer evaluation_level="conversation" en la ejecución de evaluación
2. Diseñar la grade() función para esperar item["messages"] como una matriz de conversaciones

Cuando se ejecuta en el nivel de conversación, el item dict recibe la matriz de mensajes de conversación completa en lugar de un único par de consulta/respuesta. Esto le permite crear métricas personalizadas que evalúen toda la interacción del usuario.

Ejemplo: Comprobación de cumplimiento de nivel de sesión

En este ejemplo se comprueba si el agente ha divulgado una declinación de responsabilidad necesaria en cualquier momento durante la conversación:

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

Ejemplo: Scorer de longitud de conversación

En este ejemplo se puntúan las conversaciones en función de si se resuelven dentro de un número de turnos de destino:

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

Contenido relacionado

• Ejecución de evaluaciones desde el SDK
• Evaluadores integrados