Anpassade utvärderare (förhandsversion)

Inbyggda utvärderare är ett enkelt sätt att övervaka kvaliteten på programmets generationer. Om du vill anpassa dina utvärderingar kan du skapa dina egna kodbaserade, prompt-baserade eller slutpunktsbaserade utvärderare.

Med anpassade utvärderare kan du definiera domänspecifika kvalitetsmått som går utöver den inbyggda utvärderingskatalogen. Använd en anpassad utvärderare när du behöver mäta kriterier som är unika för ditt program, till exempel varumärkeston, domänspecifik noggrannhet eller efterlevnad av utdataformat.

Du kan skapa tre typer av anpassade utvärderare:

När du har skapat en anpassad utvärderare kan du lägga till den i utvärderingskatalogen i foundry-projektet och använda den i batchutvärderingskörningar.

Kodbaserade utvärderare

En kodbaserad utvärderare är en Python funktion med namnet grade som tar emot två diktametrar (sample och item) och returnerar en flyttalpoäng mellan 0,0 och 1,0 (högre är bättre). I praktiken används alla data via item:

• Dataset-utvärdering: Indatafält som response eller ground_truth kan hämtas i Python kod som item.get("response") eller item.get("ground_truth").
• Modell- eller agentmålutvärdering: Om du vill hämta genererad svarstext använder du item.get("sample", {}).get("output_text").

Följande exempel poängsätter svar baserat på längd och föredrar svar mellan 50 och 500 tecken:

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

Paket och begränsningar som stöds

Kodbaserade utvärderare körs i en Python miljö med följande begränsningar:

• Kodstorleken måste vara mindre än 256 KB.
• Körningen är begränsad till 2 minuter per bedömningsanrop.
• Ingen nätverksåtkomst är tillgänglig vid körning.
• Minnesgränsen är 2 GB, diskgränsen är 1 GB och processorn är begränsad till 2 kärnor.

Följande paket från tredje part är tillgängliga:

NLTK corpora punkt, stopwords, wordnet, omw-1.4och names är förinstallerade.

Körningsparametrar

pass_threshold och deployment_name krävs som initieringsparametrar när du skapar en kodbaserad utvärderare. Även om kodbaserade utvärderare inte anropar en LLM, kräver deployment_name tjänst-API-schemat för utvärderingskörningsorkestrering. Du kan skicka valfritt giltigt modelldistributionsnamn från projektet.

Frågebaserade utvärderare

En frågebaserad utvärderare använder en mall för domarprompt som en LLM utvärderar för varje objekt. Mallvariabler använder dubbla klammerparenteser (till exempel {{query}}) och mappar till dina indatafält.

Frågebaserade utvärderare stöder tre bedömningsmetoder:

• Ordningstal: Heltalspoäng på en diskret skala som du definierar (till exempel 1–5). Högre är bättre.
• Kontinuerlig: Flyttalpoäng för detaljerade mått på ett intervall som du definierar (till exempel 0,0–1,0). Högre är bättre.
• Binärt (sant/falskt): Booleskt resultat för tröskelvärdesbaserade kontroller.

Utvärderaren måste returnera ett JSON-objekt med result och reason. Typen matchar result din bedömningsmetod: ett heltal för ordningstal, en float för kontinuerlig eller boolesk för binärt värde.

I följande exempelprompt används ordningstalsbedömning (1–5) för att utvärdera ett svars vänlighet:

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

Körningsparametrar

Både deployment_name och threshold krävs som initieringsparametrar när du skapar en frågebaserad utvärderare.

Slutpunktsbaserade utvärderare

En slutpunktsbaserad utvärderare delegerar bedömning till en extern HTTP-slutpunkt som du äger och använder. Utvärderingstjänsten anropar slutpunkten för varje objekt (eller batch med objekt) och skickar de mappade indata som en JSON-nyttolast. Slutpunkten bearbetar data med valfri logik som du väljer och returnerar ett JSON-svar med poäng.

Använd en slutpunktsbaserad utvärderare när du behöver:

• Nätverksåtkomst till externa tjänster eller databaser under bedömning.
• Egna modeller eller ML-pipelines som finns i din egen infrastruktur.
• Komplex bedömningslogik som överskrider de kodbaserade utvärderargränserna i begränsat läge.
• Integrering med befintliga utvärderingstjänster eller API:er.

Så här fungerar det

1. Du distribuerar en HTTP-slutpunkt som accepterar POST-begäranden med utvärderingsdata.
2. Du skapar en anslutning i ditt Foundry-projekt som lagrar slutpunkts-URL:en och autentiseringsuppgifterna.
3. Du registrerar en slutpunktsbaserad utvärderare som refererar till anslutningen.
4. När en utvärdering körs löser tjänsten anslutningen, anropar slutpunkten med indata och registrerar svaret som utvärderingsresultat.

Schema för slutpunktsbegäran

Utvärderingstjänsten skickar en POST-begäran till slutpunkten med en JSON-brödtext som innehåller utvärderingsmetadata och de mappade indatafälten.

I följande tabell beskrivs de fält som slutpunkten tar emot:

Exempelbegäran:

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

Svarsschema för slutpunkt

I följande tabell beskrivs de fält som slutpunkten kan returnera:

Svar om lyckad åtgärd:

Slutpunkten måste returnera ett JSON-objekt som överensstämmer med standardutvärderingsresultatschemat:

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

Felresonering:

Vid fel måste slutpunkten returnera ett JSON-objekt som följer följande schema:

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

Authentication

Slutpunktsbaserade utvärderare stöder två autentiseringsmetoder via projektanslutningar:

Skapa slutpunktsanslutningen

Anslutningar lagrar slutpunkts-URL:en och autentiseringsuppgifterna. Skapa en anslutning med hjälp av Azure Cognitive Services-hanteringsklienten:

API-nyckelanslutning

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 anslutning

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

För Entra ID autentisering måste slutpunkten konfigureras för att acceptera token som utfärdats av projektets hanterade identitet. Detta omfattar vanligtvis:

• Registrera ett program i Microsoft Entra ID för slutpunkten.
• Aktivera Easy Auth (eller motsvarande tokenverifiering) på slutpunkten.
• Bevilja projektets hanterade identitet en approlltilldelning i målprogrammet.

Registrera utvärderaren

När du har skapat anslutningen registrerar du en slutpunktsbaserad utvärderare som refererar till den:

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

Köra en utvärdering med en slutpunktsbaserad utvärderare

Använd fältet data_mapping för att ange vilka indatafält som ska skickas till slutpunkten:

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

Nycklarna data_mapping blir de JSON-fält som slutpunkten tar emot. Mappa dem till kolumnerna i din utvärderingsdatauppsättning med hjälp av {{item.<field_name>}} syntax.

Distribuera din slutpunkt

Utvärderingsslutpunkten kan vara vilken HTTP-tjänst som helst som accepterar POST-begäranden och returnerar JSON. Vanliga värdalternativ är:

• Azure Functions: Enkel, serverlös värd för enkel bedömningslogik.
• Azure App Service: Fullständig värd för webbappar för komplexa utvärderingspipelines.
• Azure Container Apps: Containerbaserad värd för ML-modellinferens.

Slutpunkten måste svara inom tidsgränsen för utvärderingstjänsten (30 sekunder) och returnera ett giltigt JSON-svar för varje begäran.

Skapa en anpassad utvärderare med SDK

Krav och installation

Installera SDK:et och konfigurera klienten:

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

Skapa en kodbaserad utvärderare

grade() Skicka funktionen som en sträng i fältetcode_text. data_schema Definiera för att deklarera de indatafält som din funktion förväntar sig och metrics för att beskriva poängen som din funktion returnerar. Kodbaserade utvärderare använder continuous måtttypen med intervallet 0,0 till 1,0.

Definiera först utvärderingsversionsschemat:

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

Ett fullständigt exempel finns i kodsbaserad utvärderare Python SDK-exempel.

Skapa en promptbaserad utvärderare

Skicka domarens uppmaning i fältet prompt_text . data_schema Definiera för att deklarera de indatafält som din uppmaning förväntar sig och metrics för att beskriva bedömningsmetoden och intervallet. Deklarera init_parameters modelldistributionen och tröskelvärdet som utvärderaren behöver vid körning.

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

Ett fullständigt exempel finns i prompt-baserad utvärderare Python SDK-exempel.

Köra en utvärdering med en anpassad utvärderare

När du har skapat anpassade utvärderare använder du dem i en utvärderingskörning på samma sätt som du använder inbyggda utvärderare. Du kan inkludera flera utvärderare i en enda körning.

I följande exempel körs både kodbaserade response_length_scorer och promptbaserade friendliness_evaluator tillsammans.

Definiera och köra utvärderingen

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

Hämta resultat

Avsök utvärderingskörningen tills den är klar och hämta sedan resultatet per objekt och rapportens URL.

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

Rensa resurser

Ta bort en anpassad utvärderingsversion och utvärderingen när du inte längre behöver dem:

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

Mer information om alternativ för datakällor, utvärderingsmappningar och avancerade scenarier finns i Köra utvärderingar från SDK.

Ytterligare exempel, inklusive lista, uppdatering och borttagning av utvärderare, finns i evaluator kataloghantering Python SDK-exempel.

Skapa en anpassad utvärderare i portalen

Du kan skapa anpassade utvärderare direkt i Azure AI Foundry portalen utan att skriva SDK-kod.

1. I ditt Foundry-projekt går du tillutvärderingsutvärderingskatalogen>.
2. Välj Anpassad utvärderare>Skapa.
3. Fyll i följande fält:

Använda en anpassad utvärderare i en portalutvärdering

När du har skapat en anpassad utvärderare använder du den i en utvärderingskörning från portalen:

1. I ditt Foundry-projekt går du till Utvärdering och väljer Skapa.
2. Följ guiden för att skapa utvärderingar. I steget Villkor väljer du Lägg till utvärderare.
3. Välj din anpassade utvärderare från utvärderingskatalogen.
4. Ange nödvändiga initieringsparametrar. För frågebaserade utvärderare anger du modelldistributionen och tröskelvärdet. För kodbaserade utvärderare anger du tröskelvärdet för passering.
5. Slutför guiden och starta utvärderingskörningen.

Detaljerade anvisningar om hur du kör utvärderingar från portalen finns i Köra utvärderingar från portalen.

Anpassade utvärderare på konversationsnivå

Anpassade utvärderare kan poängsätta hela konversationer i stället för enskilda svängar. Så här aktiverar du utvärdering på konversationsnivå:

1. Ställ in evaluation_level="conversation" på utvärderingskörningen
2. Utforma din grade() funktion att förvänta dig item["messages"] som en konversationsmatris

När den körs på konversationsnivå tar diktamen item emot den fullständiga konversationsmeddelandematrisen i stället för ett enda fråge-/svarspar. På så sätt kan du skapa anpassade mått som utvärderar hela användarinteraktionen.

Exempel: Efterlevnadskontroll på sessionsnivå

Det här exemplet kontrollerar om agenten avslöjade en obligatorisk ansvarsfriskrivning när som helst under konversationen:

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

Exempel: Målgörare för konversationslängd

Det här exemplet poängsätter konversationer baserat på om de löstes inom ett målantal svängar:

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

Relaterat innehåll

• Köra utvärderingar från SDK
• Inbyggda utvärderare