Évaluateurs personnalisés (préversion)

Les évaluateurs intégrés offrent un moyen simple de surveiller la qualité des générations de votre application. Pour personnaliser vos évaluations, vous pouvez créer vos propres évaluateurs basés sur du code, basés sur des invites ou basés sur des points de terminaison.

Les évaluateurs personnalisés vous permettent de définir des métriques de qualité spécifiques au domaine qui vont au-delà du catalogue d’évaluateurs intégrés. Utilisez un évaluateur personnalisé lorsque vous devez mesurer les critères propres à votre application, tels que le ton de marque, la précision spécifique au domaine ou la conformité au format de sortie.

Vous pouvez créer trois types d’évaluateurs personnalisés :

Après avoir créé un évaluateur personnalisé, vous pouvez l’ajouter au catalogue d’évaluateurs dans votre projet Foundry et l’utiliser dans les exécutions d’évaluation par lots.

Évaluateurs basés sur du code

Un évaluateur basé sur le code est une fonction Python nommée grade qui reçoit deux paramètres de dictée (sample et item) et retourne un score float compris entre 0,0 et 1,0 (plus élevé est préférable). En pratique, toutes les données sont accessibles via item:

• évaluation Dataset : les champs d’entrée tels que response ou ground_truth peuvent être récupérés dans le code Python comme item.get("response") ou item.get("ground_truth").
• Évaluation cible du modèle ou de l’agent : pour extraire le texte de réponse généré, utilisez item.get("sample", {}).get("output_text").

L’exemple suivant note les réponses en fonction de la longueur, en préférant les réponses comprises entre 50 et 500 caractères :

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

Packages et limites pris en charge

Les évaluateurs basés sur le code s’exécutent dans un environnement de Python en bac à sable avec les contraintes suivantes :

• La taille du code doit être inférieure à 256 Ko.
• L’exécution est limitée à 2 minutes par appel de notation.
• Aucun accès réseau n’est disponible au moment de l’exécution.
• La limite de mémoire est de 2 Go, la limite de disque est de 1 Go et le processeur est limité à 2 cœurs.

Les packages tiers suivants sont disponibles :

Les groupes punktNLTK, , stopwordswordnet, omw-1.4et names sont préchargés.

Paramètres d’exécution

pass_threshold et deployment_name sont requis en tant que paramètres d’initialisation lorsque vous créez un évaluateur basé sur le code. Même si les évaluateurs basés sur le code n’appellent pas de LLM, le schéma de l’API de service nécessite deployment_name une orchestration d’évaluation. Vous pouvez transmettre n’importe quel nom de déploiement de modèle valide à partir de votre projet.

Programmes d'évaluation basés sur des invites

Un évaluateur basé sur les invites utilise un modèle d’invite de juge qu’un LLM évalue pour chaque élément. Les variables de modèle utilisent des accolades doubles (par exemple {{query}}) et mappent à vos champs de données d’entrée.

Les évaluateurs basés sur des invites prennent en charge trois méthodes de scoring :

• Ordinal : scores entiers sur une échelle discrète que vous définissez (par exemple, 1 à 5). Plus élevé est meilleur.
• Continu : scores flottants pour la mesure affinée sur une plage que vous définissez (par exemple, 0,0 à 1,0). Plus élevé est meilleur.
• Binaire (true/false) : résultat booléen pour les vérifications basées sur des seuils.

L’évaluateur doit retourner un objet JSON avec result et reason. Le type de correspondance correspond à votre méthode de result scoring : entier pour ordinal, float pour continu ou booléen pour le binaire.

L’exemple d’invite suivant utilise le scoring ordinal (1 à 5) pour évaluer la convivialité d’une réponse :

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

Paramètres d’exécution

Les deux deployment_name et threshold sont obligatoires en tant que paramètres d’initialisation lorsque vous créez un évaluateur basé sur des invites.

Évaluateurs basés sur des points de terminaison

Un évaluateur basé sur un point de terminaison délègue le scoring à un point de terminaison HTTP externe que vous possédez et utilisez. Le service d’évaluation appelle votre point de terminaison pour chaque élément (ou lot d’éléments), en passant les données d’entrée mappées en tant que charge utile JSON. Votre point de terminaison traite les données à l’aide de n’importe quelle logique que vous choisissez et retourne une réponse JSON avec des scores.

Utilisez un évaluateur basé sur un point de terminaison lorsque vous avez besoin des éléments suivants :

• Accès réseau aux services ou bases de données externes pendant le scoring.
• Modèles propriétaires ou pipelines ML hébergés sur votre propre infrastructure.
• Logique de scoring complexe qui dépasse les limites de l’évaluateur en mode bac à sable (sandbox).
• Intégration à des services ou API d’évaluation existants.

Fonctionnement

1. Vous déployez un point de terminaison HTTP qui accepte les requêtes POST avec des données d’évaluation.
2. Vous créez une connexion dans votre projet Foundry qui stocke l’URL du point de terminaison et les informations d’identification d’authentification.
3. Vous inscrivez un évaluateur basé sur un point de terminaison qui fait référence à la connexion.
4. Lorsqu’une évaluation s’exécute, le service résout la connexion, appelle votre point de terminaison avec les données d’entrée et enregistre la réponse en tant que résultat d’évaluation.

Schéma de demande de point de terminaison

Le service d’évaluation envoie une requête POST à votre point de terminaison avec un corps JSON contenant des métadonnées d’évaluation et les champs d’entrée mappés.

Le tableau suivant décrit les champs reçus par votre point de terminaison :

Exemple de demande :

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

Schéma de réponse de point de terminaison

Le tableau suivant décrit les champs que votre point de terminaison peut retourner :

Réponse de réussite :

Votre point de terminaison doit retourner un objet JSON conforme au schéma de résultat d’évaluation standard :

{
  "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 d’échec :

En cas d’erreur, votre point de terminaison doit retourner un objet JSON conforme au schéma suivant :

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

Authentication

Les évaluateurs basés sur des points de terminaison prennent en charge deux méthodes d’authentification par le biais de connexions de projet :

Créer la connexion de point de terminaison

Les connexions stockent l’URL du point de terminaison et les informations d’identification d’authentification. Créez une connexion à l’aide du client de gestion Azure Cognitive Services :

Connexion à la clé 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,
)

connexion 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,
)

Pour Entra ID l'authentification, votre point de terminaison doit être configuré pour accepter les jetons émis par l'identité managée du projet. Cela implique généralement les éléments suivants :

• Inscription d’une application dans Microsoft Entra ID pour votre point de terminaison.
• Activation de l’authentification simple (ou validation de jeton équivalente) sur votre point de terminaison.
• Octroi de l’identité managée du projet à une attribution de rôle d’application sur l’application cible.

Inscrire l’évaluateur

Après avoir créé la connexion, inscrivez un évaluateur basé sur un point de terminaison qui le référence :

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

Exécuter une évaluation avec un évaluateur basé sur un point de terminaison

Utilisez le data_mapping champ pour spécifier les champs de données d’entrée envoyés à votre point de terminaison :

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

Les data_mapping clés deviennent les champs JSON que votre point de terminaison reçoit. Mappez-les aux colonnes de votre jeu de données d’évaluation à l’aide {{item.<field_name>}} de la syntaxe.

Déployer votre point de terminaison

Votre point de terminaison d’évaluation peut être n’importe quel service HTTP qui accepte les requêtes POST et retourne JSON. Les options d’hébergement courantes sont les suivantes :

• Azure Functions : hébergement léger et serverless pour une logique de scoring simple.
• Azure App Service : hébergement complet d’applications web pour les pipelines d’évaluation complexes.
• Azure Container Apps : hébergement basé sur un conteneur pour l’inférence du modèle ML.

Le point de terminaison doit répondre dans le délai d’expiration du service d’évaluation (30 secondes) et retourner une réponse JSON valide pour chaque requête.

Créer un évaluateur personnalisé avec le Kit de développement logiciel (SDK)

Prérequis et configuration

Installez le Kit de développement logiciel (SDK) et configurez votre client :

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

Créer un évaluateur basé sur le code

Passez la grade() fonction en tant que chaîne dans le code_text champ. Définissez les data_schema champs d’entrée attendus par votre fonction et metrics décrivez le score retourné par votre fonction. Les évaluateurs basés sur le code utilisent le continuous type de métrique avec une plage comprise entre 0,0 et 1.0.

Tout d’abord, définissez le schéma de version de l’évaluateur :

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

Pour obtenir un exemple complet, consultez l’exemple d’évaluateur code Python SDK.

Créer un évaluateur basé sur les invites

Passez l’invite du juge dans le prompt_text champ. Définissez les data_schema champs d’entrée attendus par votre invite et metrics décrivez la méthode et la plage de scoring. Déclarer init_parameters le déploiement du modèle et le seuil dont l’évaluateur a besoin au moment de l’exécution.

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

Pour obtenir un exemple complet, consultez l’exemple évaluateur Python SDK.

Exécuter une évaluation avec un évaluateur personnalisé

Après avoir créé des évaluateurs personnalisés, utilisez-les dans une évaluation de la même façon que vous utilisez des évaluateurs intégrés. Vous pouvez inclure plusieurs évaluateurs dans une seule exécution.

L’exemple suivant exécute à la fois le code response_length_scorer et l’invite friendliness_evaluator ensemble.

Définir et exécuter l’évaluation

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

Obtenir les résultats

Interrogez l’exécution de l’évaluation jusqu’à ce qu’elle se termine, puis récupérez les résultats par élément et l’URL du rapport.

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

Nettoyer les ressources

Supprimez une version d’évaluateur personnalisée et l’évaluation lorsque vous n’en avez plus besoin :

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

Pour plus d’informations sur les options de source de données, les mappages d’évaluateurs et les scénarios avancés, consultez Exécuter des évaluations à partir du Kit de développement logiciel (SDK).

Pour obtenir d’autres exemples, notamment la liste, la mise à jour et la suppression d’évaluateurs, consultez l’exemple de gestion de catalogue Python évaluator.

Créer un évaluateur personnalisé dans le portail

Vous pouvez créer des évaluateurs personnalisés directement dans le portail Azure AI Foundry sans écrire de code SDK.

1. Dans votre projet Foundry, accédez aucatalogue évaluateur>.
2. Sélectionnez Évaluateur> personnaliséCréer.
3. Renseignez les champs suivants :

Utiliser un évaluateur personnalisé dans une évaluation du portail

Après avoir créé un évaluateur personnalisé, utilisez-le dans une exécution d’évaluation à partir du portail :

1. Dans votre projet Foundry, accédez à Évaluation et sélectionnez Créer.
2. Suivez l’Assistant Création d’évaluation. À l’étape Critères , sélectionnez Ajouter un évaluateur.
3. Choisissez votre évaluateur personnalisé dans le catalogue d’évaluateurs.
4. Fournissez les paramètres d’initialisation requis. Pour les évaluateurs basés sur les invites, fournissez le déploiement et le seuil du modèle. Pour les évaluateurs basés sur le code, fournissez le seuil de passage.
5. Terminez l’Assistant et démarrez l’exécution de l’évaluation.

Pour obtenir des étapes détaillées sur l’exécution d’évaluations à partir du portail, consultez Exécuter des évaluations à partir du portail.

Évaluateurs personnalisés au niveau de la conversation

Les évaluateurs personnalisés peuvent noter des conversations entières plutôt que des tours individuels. Pour activer l’évaluation au niveau de la conversation :

1. Définir evaluation_level="conversation" sur l’exécution de l’évaluation
2. Concevoir votre grade() fonction comme item["messages"] tableau de conversation

Lors de l’exécution au niveau de la conversation, la item dicte reçoit le tableau de messages de conversation complet au lieu d’une paire requête/réponse unique. Cela vous permet de créer des métriques personnalisées qui évaluent l’ensemble de l’interaction utilisateur.

Exemple : vérification de conformité au niveau de la session

Cet exemple vérifie si l’agent a divulgué une exclusion de responsabilité requise à tout moment pendant la conversation :

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

Exemple : scoreur de longueur de conversation

Cet exemple évalue les conversations selon qu’elles ont été résolues au sein d’un nombre cible de tours :

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

Contenu connexe

• Exécuter des évaluations à partir du Kit de développement logiciel (SDK)
• Évaluateurs intégrés