Aangepaste evaluators (preview)

Ingebouwde evaluators bieden een eenvoudige manier om de kwaliteit van de generaties van uw toepassing te bewaken. Als u uw evaluaties wilt aanpassen, kunt u uw eigen op code gebaseerde, op prompts gebaseerde of op eindpunten gebaseerde evaluators maken.

Met aangepaste evaluatoren kunt u domeinspecifieke metrische gegevens over kwaliteit definiëren die verder gaan dan de ingebouwde evaluatorcatalogus. Gebruik een aangepaste evaluator wanneer u criteria moet meten die uniek zijn voor uw toepassing, zoals merktoon, domeinspecifieke nauwkeurigheid of naleving van uitvoerindelingen.

U kunt drie typen aangepaste evaluators maken:

Nadat u een aangepaste evaluator hebt gemaakt, kunt u deze toevoegen aan de evaluatorcatalogus in uw Foundry-project en deze gebruiken in batchevaluatieuitvoeringen.

Op code gebaseerde evaluators

Een op code gebaseerde evaluator is een Python functie met de naam grade die twee dictparameters ontvangt (sample en item) en retourneert een floatscore tussen 0,0 en 1,0 (hoger is beter). In de praktijk worden alle gegevens geopend via item:

• Dataset-evaluatie: Invoervelden zoals response of ground_truth kunnen worden opgehaald in de Python-code, zoals item.get("response") of item.get("ground_truth").
• Evaluatie van model- of agentdoel: als u gegenereerde antwoordtekst wilt ophalen, gebruikt u item.get("sample", {}).get("output_text").

In het volgende voorbeeld worden antwoorden gescored op basis van lengte, die de voorkeur geven aan antwoorden tussen 50 en 500 tekens:

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

Ondersteunde pakketten en limieten

Op code gebaseerde evaluators worden uitgevoerd in een omgeving met sandbox-Python met de volgende beperkingen:

• De codegrootte moet kleiner zijn dan 256 kB.
• Uitvoering is beperkt tot 2 minuten per beoordelingsoproep.
• Er is geen netwerktoegang beschikbaar tijdens runtime.
• De geheugenlimiet is 2 GB, de schijflimiet is 1 GB en de CPU is beperkt tot 2 kernen.

De volgende pakketten van derden zijn beschikbaar:

De NLTK corporapunkt, stopwords, , wordneten omw-1.4names worden vooraf geladen.

Parameters voor uitvoeringstijd

pass_threshold en deployment_name zijn vereist als initialisatieparameters wanneer u een op code gebaseerde evaluator maakt. Hoewel op code gebaseerde evaluators geen LLM aanroepen, vereist deployment_name het service-API-schema voor de indeling van evaluatie-run. U kunt elke geldige modelimplementatienaam doorgeven vanuit uw project.

Op prompts gebaseerde evaluators

Een op prompt gebaseerde evaluator maakt gebruik van een rechterpromptsjabloon die door een LLM voor elk item wordt geëvalueerd. Sjabloonvariabelen maken gebruik van dubbele accolades (bijvoorbeeld {{query}}) en wijzen toe aan de invoergegevensvelden.

Op prompts gebaseerde evaluators ondersteunen drie scoremethoden:

• Rangschikk: Gehele getallen op een discrete schaal die u definieert (bijvoorbeeld 1-5). Hoger is beter.
• Doorlopend: Floatscores voor fijnmazige meting in een bereik dat u definieert (bijvoorbeeld 0,0–1,0). Hoger is beter.
• Binair (waar/onwaar): Booleaanse resultaten voor controles op basis van drempelwaarden.

De evaluator moet een JSON-object retourneren met result en reason. Het type result komt overeen met uw scoremethode: een geheel getal voor rangtelwoord, een float voor doorlopend of een booleaanse waarde voor binair.

In de volgende voorbeeldprompt wordt gebruikgemaakt van rangschikkelijk scoren (1-5) om de vriendelijkheid van een antwoord te evalueren:

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

Parameters voor uitvoeringstijd

deployment_name Beide threshold zijn vereist als initialisatieparameters wanneer u een op prompt gebaseerde evaluator maakt.

Op eindpunt gebaseerde evaluators

Een op eindpunt gebaseerde evaluator delegeert scoren naar een extern HTTP-eindpunt dat u bezit en beheert. De evaluatieservice roept uw eindpunt aan voor elk item (of batch met items), waarbij de toegewezen invoergegevens worden doorgegeven als een JSON-nettolading. Uw eindpunt verwerkt de gegevens met behulp van elke logica die u kiest en retourneert een JSON-antwoord met scores.

Gebruik een op eindpunt gebaseerde evaluator wanneer u het volgende nodig hebt:

• Netwerktoegang tot externe services of databases tijdens het scoren.
• Eigen modellen of ML-pijplijnen die worden gehost op uw eigen infrastructuur.
• Complexe scorelogica die de limieten voor op code gebaseerde evaluatie in de sandbox overschrijdt.
• Integratie met bestaande evaluatieservices of API's.

Hoe werkt het?

1. U implementeert een HTTP-eindpunt dat POST-aanvragen accepteert met evaluatiegegevens.
2. U maakt een verbinding in uw Foundry-project waarin de eindpunt-URL en verificatiereferenties worden opgeslagen.
3. U registreert een op eindpunt gebaseerde evaluator die verwijst naar de verbinding.
4. Wanneer een evaluatie wordt uitgevoerd, lost de service de verbinding op, roept het eindpunt aan met de invoergegevens en registreert het antwoord als het evaluatieresultaat.

Eindpuntaanvraagschema

De evaluatieservice verzendt een POST-aanvraag naar uw eindpunt met een JSON-hoofdtekst met evaluatiemetagegevens en de toegewezen invoervelden.

In de volgende tabel worden de velden beschreven die uw eindpunt ontvangt:

Voorbeeldaanvraag:

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

Eindpuntantwoordschema

In de volgende tabel worden de velden beschreven die uw eindpunt kan retourneren:

Geslaagd antwoord:

Uw eindpunt moet een JSON-object retourneren dat voldoet aan het standaardevaluatieresultaatschema:

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

Foutherponse:

In het geval van een fout moet uw eindpunt een JSON-object retourneren dat voldoet aan het volgende schema:

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

Authentication

Op eindpunten gebaseerde evaluators ondersteunen twee verificatiemethoden via projectverbindingen:

De eindpuntverbinding maken

Verbindingen slaan de eindpunt-URL en verificatiereferenties op. Maak een verbinding met behulp van de Azure Cognitive Services-beheerclient:

API-sleutelverbinding

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 verbinding

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

Voor Entra ID verificatie moet uw eindpunt worden geconfigureerd om tokens te accepteren die zijn uitgegeven door de beheerde identiteit van het project. Dit omvat meestal:

• Een toepassing registreren in Microsoft Entra ID voor uw eindpunt.
• Easy Auth (of equivalente tokenvalidatie) inschakelen op uw eindpunt.
• Het verlenen van de beheerde identiteit van het project aan een app-roltoewijzing voor de doeltoepassing.

De evaluator registreren

Nadat u de verbinding hebt gemaakt, registreert u een op eindpunt gebaseerde evaluator die ernaar verwijst:

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

Een evaluatie uitvoeren met een op eindpunt gebaseerde evaluator

Gebruik het data_mapping veld om op te geven welke invoergegevensvelden naar uw eindpunt worden verzonden:

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

De data_mapping sleutels worden de JSON-velden die uw eindpunt ontvangt. Wijs ze toe aan de kolommen in uw evaluatiegegevensset met behulp van {{item.<field_name>}} de syntaxis.

Uw eindpunt implementeren

Uw evaluatie-eindpunt kan elke HTTP-service zijn die POST-aanvragen accepteert en JSON retourneert. Algemene hostingopties zijn onder andere:

• Azure Functions: Lichtgewicht, serverloze hosting voor eenvoudige scorelogica.
• Azure App Service: Volledige web-app die als host fungeert voor complexe evaluatiepijplijnen.
• Azure Container Apps: Hosten op basis van containers voor ML-modeldeductie.

Het eindpunt moet reageren binnen de time-out van de evaluatieservice (30 seconden) en een geldig JSON-antwoord retourneren voor elke aanvraag.

Een aangepaste evaluator maken met de SDK

Vereisten en installatie

Installeer de SDK en stel uw client in:

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

Een op code gebaseerde evaluator maken

Geef de grade() functie door als een tekenreeks in het code_text veld. Definieer de data_schema invoervelden die uw functie verwacht en de metrics score die uw functie retourneert te beschrijven. Op code gebaseerde evaluators gebruiken het continuous metrische type met een bereik van 0,0 tot en met 1,0.

Definieer eerst het schema van de evaluatorversie:

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

Zie het codegebaseerd evaluatorvoorbeeld Python SDK voor een volledig voorbeeld.

Een op prompt gebaseerde evaluator maken

Geef de rechterprompt door in het prompt_text veld. Definieer de data_schema invoervelden die door de prompt worden verwacht en de beschrijving van de scoremethode en het metrics bereik. De init_parameters declareer de modelimplementatie en drempelwaarden die de evaluator tijdens runtime nodig heeft.

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

Zie voor een volledig voorbeeld het prompt-gebaseerde evaluator Python SDK-voorbeeld.

Een evaluatie uitvoeren met een aangepaste evaluator

Nadat u aangepaste evaluators hebt gemaakt, gebruikt u deze in een evaluatieuitvoering op dezelfde manier als u ingebouwde evaluators gebruikt. U kunt meerdere evaluators opnemen in één uitvoering.

In het volgende voorbeeld worden zowel de code als response_length_scorer de prompt friendliness_evaluator samen uitgevoerd.

De evaluatie definiëren en uitvoeren

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

Resultaten verkrijgen

Peil de evaluatieuitvoering totdat deze is voltooid en haal vervolgens de resultaten per item en de rapport-URL op.

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

Resources opschonen

Verwijder een aangepaste evaluatorversie en de evaluatie wanneer u deze niet meer nodig hebt:

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

Zie Evaluaties uitvoeren vanuit de SDK voor meer informatie over opties voor gegevensbronnen, evaluatortoewijzingen en geavanceerde scenario's.

Zie het catalogusbeheer voor Python SDK voor aanvullende voorbeelden, waaronder het weergeven, bijwerken en verwijderen van evaluators.

Een aangepaste evaluator maken in de portal

U kunt aangepaste evaluators rechtstreeks in de Azure AI Foundry-portal maken zonder SDK-code te schrijven.

1. Ga in uw Foundry-project naar deevaluatie-evaluatorcatalogus>.
2. Selecteer Aangepaste evaluator>Maken.
3. Vul de volgende velden in:

Een aangepaste evaluator gebruiken in een portal-evaluatie

Nadat u een aangepaste evaluator hebt gemaakt, gebruikt u deze in een evaluatieuitvoering vanuit de portal:

1. Ga in uw Foundry-project naar Evaluatie en selecteer Maken.
2. Volg de wizard voor het maken van de evaluatie. Selecteer In de stap Criteria de optie Evaluator toevoegen.
3. Kies uw aangepaste evaluator in de evaluatorcatalogus.
4. Geef de vereiste initialisatieparameters op. Geef voor op prompt gebaseerde evaluators de implementatie en drempelwaarde van het model op. Geef voor op code gebaseerde evaluators de drempelwaarde voor de doorgang op.
5. Voltooi de wizard en start de evaluatieuitvoering.

Zie Evaluaties uitvoeren vanuit de portal voor gedetailleerde stappen over het uitvoeren van evaluaties vanuit de portal.

Aangepaste evaluators op gespreksniveau

Aangepaste evaluators kunnen volledige gesprekken beoordelen in plaats van afzonderlijke beurten. Evaluatie op gespreksniveau inschakelen:

1. Instellen evaluation_level="conversation" op de evaluatieuitvoering
2. grade() Uw functie ontwerpen om te verwachten item["messages"] als een gespreksmatrix

Bij uitvoering op gespreksniveau ontvangt de dicteerfunctie item de volledige matrix met gespreksberichten in plaats van één query-/antwoordpaar. Hiermee kunt u aangepaste metrische gegevens maken waarmee de volledige gebruikersinteractie wordt beoordeeld.

Voorbeeld: Nalevingscontrole op sessieniveau

In dit voorbeeld wordt gecontroleerd of de agent op elk moment tijdens het gesprek een vereiste disclaimer heeft vrijgegeven:

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

Voorbeeld: Scorer voor gesprekslengte

In dit voorbeeld worden gesprekken gescored op basis van of ze binnen een doelaantal beurten zijn opgelost:

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

Verwante inhoud

• Evaluaties uitvoeren vanuit de SDK
• Ingebouwde evaluatoren