Niestandardowe ewaluatory (wersja zapoznawcza)

Wbudowane ewaluatory zapewniają łatwy sposób monitorowania jakości generowania aplikacji. Aby dostosować oceny, możesz utworzyć własne ewaluatory oparte na kodzie, oparte na monitach lub ewaluatorach opartych na punktach końcowych.

Niestandardowe ewaluatory umożliwiają definiowanie metryk jakości specyficznych dla domeny wykraczających poza wbudowany wykaz ewaluatorów. Użyj niestandardowego ewaluatora, jeśli musisz zmierzyć kryteria unikatowe dla aplikacji, takie jak ton marki, dokładność specyficzna dla domeny lub zgodność formatu wyjściowego.

Możesz utworzyć trzy typy niestandardowych ewaluatorów:

Po utworzeniu niestandardowego ewaluatora można dodać go do wykazu ewaluatorów w projekcie Foundry i użyć go w przebiegach oceny wsadowej.

Ewaluatory oparte na kodzie

Ewaluator oparty na kodzie jest funkcją Python o nazwie grade, która odbiera dwa parametry dyktowania (sample i item) i zwraca wynik zmiennoprzecinkowy z zakresu od 0,0 do 1,0 (wyższa jest lepsza). W praktyce dostęp do wszystkich danych jest uzyskiwany za pośrednictwem usługi item:

• Wartość zestawu danych: Pola wejściowe, takie jak response lub ground_truth, można pobrać w kodzie Python, na przykład item.get("response") lub item.get("ground_truth").
• Ocena docelowa modelu lub agenta: aby pobrać wygenerowany tekst odpowiedzi, użyj polecenia item.get("sample", {}).get("output_text").

Poniższy przykład ocenia odpowiedzi na podstawie długości, preferując odpowiedzi z zakresu od 50 do 500 znaków:

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

Obsługiwane pakiety i limity

Ewaluatory oparte na kodzie działają w środowisku Python w trybie piaskownicy z następującymi ograniczeniami:

• Rozmiar kodu musi być mniejszy niż 256 KB.
• Wykonanie jest ograniczone do 2 minut na wywołanie klasyfikacji.
• Żaden dostęp do sieci nie jest dostępny w czasie wykonywania.
• Limit pamięci wynosi 2 GB, limit dysku wynosi 1 GB, a procesor JEST ograniczony do 2 rdzeni.

Dostępne są następujące pakiety innych firm:

Corpora punktNLTK , , stopwordswordnet, omw-1.4i names są wstępnie ładowane.

Parametry środowiska uruchomieniowego

pass_threshold i deployment_name są wymagane jako parametry inicjowania podczas tworzenia ewaluatora opartego na kodzie. Mimo że ewaluatory oparte na kodzie nie nazywają programu LLM, schemat interfejsu API usługi wymaga deployment_name orkiestracji przebiegu oceny. Z projektu można przekazać dowolną prawidłową nazwę wdrożenia modelu.

Ewaluatory oparte na monitach

Ewaluator oparty na monitach używa szablonu monitu sędziego, który program LLM ocenia dla każdego elementu. Zmienne szablonu używają podwójnych nawiasów klamrowych (na przykład {{query}}) i mapowania na pola danych wejściowych.

Ewaluatory oparte na monitach obsługują trzy metody oceniania:

• Porządkowe: liczba całkowita w zdefiniowanej skali dyskretnej (na przykład 1–5). Wyższe jest lepsze.
• Ciągły: wyniki zmiennoprzecinkowe dla dokładnego pomiaru w zdefiniowanym zakresie (na przykład 0,0–1,0). Wyższe jest lepsze.
• Binarne (prawda/fałsz): wynik logiczny dla testów opartych na progach.

Ewaluator musi zwrócić obiekt JSON z elementami result i reason. Typ result odpowiada metodzie oceniania: liczba całkowita dla porządkowych, zmiennoprzecinkowa dla wartości ciągłych lub wartość logiczna dla danych binarnych.

Poniższy przykładowy monit używa oceniania porządkowego (1–5), aby ocenić przyjazność odpowiedzi:

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

Parametry środowiska uruchomieniowego

Oba deployment_name elementy i threshold są wymagane jako parametry inicjowania podczas tworzenia ewaluatora opartego na monitach.

Ewaluatory oparte na punktach końcowych

Ewaluator oparty na punkcie końcowym deleguje ocenianie do zewnętrznego punktu końcowego HTTP, który jest właścicielem i działa. Usługa oceny wywołuje punkt końcowy dla każdego elementu (lub partii elementów), przekazując zamapowane dane wejściowe jako ładunek JSON. Punkt końcowy przetwarza dane przy użyciu dowolnej wybranej logiki i zwraca odpowiedź JSON z wynikami.

Jeśli potrzebujesz, użyj ewaluatora opartego na punkcie końcowym:

• Dostęp sieciowy do usług zewnętrznych lub baz danych podczas oceniania.
• Zastrzeżone modele lub potoki uczenia maszynowego hostowane we własnej infrastrukturze.
• Złożona logika oceniania, która przekracza limity ewaluatora opartego na kodzie w trybie piaskownicy.
• Integracja z istniejącymi usługami oceny lub interfejsami API.

Jak to działa

1. Wdrażasz punkt końcowy HTTP, który akceptuje żądania POST z danymi oceny.
2. W projekcie Foundry utworzysz połączenie, które przechowuje adres URL punktu końcowego i poświadczenia uwierzytelniania.
3. Rejestrujesz ewaluatora opartego na punkcie końcowym, który odwołuje się do połączenia.
4. Po uruchomieniu oceny usługa rozwiązuje połączenie, wywołuje punkt końcowy z danymi wejściowymi i rejestruje odpowiedź jako wynik oceny.

Schemat żądania punktu końcowego

Usługa oceny wysyła żądanie POST do punktu końcowego z treścią JSON zawierającą metadane oceny i zamapowane pola wejściowe.

W poniższej tabeli opisano pola odbierane przez punkt końcowy:

Przykładowe żądanie:

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

Schemat odpowiedzi punktu końcowego

W poniższej tabeli opisano pola, które punkt końcowy może zwrócić:

Odpowiedź na powodzenie:

Punkt końcowy musi zwrócić obiekt JSON zgodny ze standardowym schematem wyników oceny:

{
  "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 niepowodzenia:

W przypadku błędu punkt końcowy musi zwrócić obiekt JSON zgodny z następującym schematem:

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

Authentication

Ewaluatory oparte na punktach końcowych obsługują dwie metody uwierzytelniania za pośrednictwem połączeń projektu:

Tworzenie połączenia punktu końcowego

Połączenia przechowują adres URL punktu końcowego i poświadczenia uwierzytelniania. Utwórz połączenie przy użyciu klienta zarządzania usługami Cognitive Services Azure:

Połączenie klucza interfejsu 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,
)

połączenie 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,
)

W przypadku uwierzytelniania Entra ID punkt końcowy musi być skonfigurowany tak, aby akceptował tokeny wystawione przez tożsamość zarządzaną projektu. Zwykle obejmuje to:

• Rejestrowanie aplikacji w Microsoft Entra ID dla punktu końcowego.
• Włączenie funkcji Easy Auth (lub równoważnej weryfikacji tokenu) w punkcie końcowym.
• Udzielanie tożsamości zarządzanej projektu przypisanie roli aplikacji w aplikacji docelowej.

Rejestrowanie ewaluatora

Po utworzeniu połączenia zarejestruj ewaluator oparty na punkcie końcowym, który odwołuje się do niego:

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

Uruchamianie oceny przy użyciu ewaluatora opartego na punkcie końcowym

data_mapping Użyj pola, aby określić, które pola danych wejściowych są wysyłane do punktu końcowego:

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

Klucze data_mapping stają się polami JSON, które otrzymuje punkt końcowy. Zamapuj je na kolumny w zestawie danych oceny przy użyciu {{item.<field_name>}} składni.

Wdrażanie punktu końcowego

Punkt końcowy oceny może być dowolną usługą HTTP, która akceptuje żądania POST i zwraca kod JSON. Typowe opcje hostingu obejmują:

• Azure Functions: uproszczone hostowanie bezserwerowe dla prostej logiki oceniania.
• Azure App Service: Pełna aplikacja internetowa hostująca złożone potoki oceny.
• Azure Container Apps: hosting oparty na kontenerach na potrzeby wnioskowania modelu uczenia maszynowego.

Punkt końcowy musi odpowiadać w ramach limitu czasu usługi oceny (30 sekund) i zwrócić prawidłową odpowiedź JSON dla każdego żądania.

Tworzenie niestandardowego ewaluatora za pomocą zestawu SDK

Wymagania wstępne i konfiguracja

Zainstaluj zestaw SDK i skonfiguruj klienta:

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

Tworzenie ewaluatora opartego na kodzie

grade() Przekaż funkcję jako ciąg w code_text polu. Zdefiniuj wartość , data_schema aby zadeklarować pola wejściowe oczekiwane przez funkcję, a element metrics , aby opisać wynik zwracany przez funkcję. Ewaluatory oparte na kodzie używają continuous typu metryki z zakresem od 0,0 do 1,0.

Najpierw zdefiniuj schemat wersji ewaluatora:

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

Aby zapoznać się z kompletnym przykładem, zobacz przykład code Python SDK sample.

Tworzenie ewaluatora opartego na monitach

Przekaż monit sędziego prompt_text w polu. Zdefiniuj wartości , data_schema aby zadeklarować pola wejściowe oczekiwane przez monit, oraz opis metrics metody i zakresu oceniania. Zadeklarowanie init_parameters wdrożenia modelu i progu wymaganego przez ewaluatora w czasie wykonywania.

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

Aby zapoznać się z kompletnym przykładem, zobacz przykład prompt Python zestawu SDK.

Uruchamianie oceny przy użyciu niestandardowego ewaluatora

Po utworzeniu niestandardowych ewaluatorów użyj ich w ramach oceny w taki sam sposób, jak w przypadku wbudowanych ewaluatorów. W jednym przebiegu można uwzględnić wiele ewaluatorów.

W poniższym przykładzie jest uruchamiany zarówno kod oparty response_length_scorer na kodzie, jak i oparty na friendliness_evaluator monitach.

Definiowanie i uruchamianie oceny

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

Pobieranie wyników

Sonduj przebieg oceny do momentu zakończenia, a następnie pobierz wyniki dla poszczególnych elementów i adres URL raportu.

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

Czyszczenie zasobów

Usuń niestandardową wersję ewaluatora i ocenę, gdy nie są już potrzebne:

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

Aby uzyskać więcej informacji na temat opcji źródła danych, mapowań ewaluatorów i zaawansowanych scenariuszy, zobacz Run evaluations from the SDK (Uruchamianie ocen z zestawu SDK).

Aby uzyskać dodatkowe przykłady, takie jak wyświetlanie listy, aktualizowanie i usuwanie ewaluatorów, zobacz przykład evaluator catalog management Python SDK sample.

Tworzenie niestandardowego ewaluatora w portalu

Niestandardowe ewaluatory można tworzyć bezpośrednio w portalu Azure AI Foundry bez konieczności pisania kodu zestawu SDK.

1. W projekcie Foundry przejdź dokatalogu Ewaluator>.
2. Wybierz pozycję Utwórz ewaluator> niestandardowy.
3. Wypełnij następujące pola:

Używanie niestandardowego ewaluatora w ocenie portalu

Po utworzeniu niestandardowego ewaluatora użyj go w przebiegu oceny z poziomu portalu:

1. W projekcie Foundry przejdź do pozycji Ocena i wybierz pozycję Utwórz.
2. Postępuj zgodnie z instrukcjami kreatora tworzenia oceny. W kroku Kryteria wybierz pozycję Dodaj ewaluatora.
3. Wybierz niestandardowego ewaluatora z katalogu ewaluatora.
4. Podaj wymagane parametry inicjowania. W przypadku ewaluatorów opartych na monitach podaj wdrożenie ipróg modelu. W przypadku ewaluatorów opartych na kodzie podaj próg dostępu.
5. Zakończ pracę kreatora i uruchom przebieg oceny.

Aby uzyskać szczegółowe instrukcje dotyczące uruchamiania ocen z portalu, zobacz Uruchamianie ocen w portalu.

Niestandardowe ewaluatory na poziomie konwersacji

Niestandardowi ewaluatorzy mogą oceniać całe konwersacje zamiast poszczególnych kolei. Aby włączyć ocenę na poziomie konwersacji:

1. Ustaw evaluation_level="conversation" na przebiegu oceny
2. grade() Projektowanie funkcji zgodnie z oczekiwaniami item["messages"] jako tablicą konwersacji

Podczas uruchamiania na poziomie item konwersacji dykt odbiera pełną tablicę komunikatów konwersacji zamiast jednej pary zapytań/odpowiedzi. Dzięki temu można tworzyć metryki niestandardowe, które oceniają całą interakcję użytkownika.

Przykład: Sprawdzanie zgodności na poziomie sesji

Ten przykład sprawdza, czy agent ujawnił wymagane zastrzeżenie w dowolnym momencie podczas konwersacji:

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

Przykład: wskaźnik długości konwersacji

W tym przykładzie są oceniane konwersacje na podstawie tego, czy zostały rozwiązane w obrębie liczby docelowej:

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

Treści powiązane

• Uruchamianie ocen z zestawu SDK
• Wbudowane ewaluatory