Köra utvärderingar i molnet med hjälp av Microsoft Foundry SDK

I den här artikeln får du lära dig hur du kör utvärderingar i molnet för fördistributionstestning på en testdatauppsättning.

Använd molnutvärderingar för de flesta scenarier – särskilt när du testar i stor skala, integrerar utvärderingar i CI/CD-pipelines (kontinuerlig integrering och kontinuerlig leverans) eller utför fördistributionstestning. Att köra utvärderingar i molnet eliminerar behovet av att hantera lokal beräkningsinfrastruktur och stöder storskaliga, automatiserade testarbetsflöden. Du kan också schemalägga utvärderingar så att de körs regelbundet eller konfigurera kontinuerlig utvärdering för att automatiskt utvärdera provagentsvar i produktion.

Molnutvärderingsresultat lagras i ditt Foundry-projekt. Du kan granska resultaten i portalen, hämta dem via SDK eller dirigera dem till Application Insights om de är anslutna. Molnutvärdering stöder alla Microsoft-kurerade definierade utvärderare och dina egna anpassade utvärderare. Utvärderare hanteras i utvärderingskatalogen med samma projektomfattning, rollbaserad åtkomstkontroll.

Så här fungerar molnutvärdering

En molnutvärdering har tre steg:

1. Definiera vad som ska utvärderas. Beskriv din dataform () data_source_configoch utvärderarna (testkriterier) som bedömer den.
2. Skapa utvärderingen. Skicka in definitionen med hjälp av openai_client.evals.create().
3. Kör den och läs resultatet. Starta en körning genom att använda openai_client.evals.runs.create(), kontrollera regelbundet tills körningen har slutförts och läs de poängbedömda resultaten. Se Hämta resultat för resultatschemat.

Resten av det här avsnittet går igenom indata till steg 1: välj ett scenario och välj sedan utvärderare.

Välj startpunkt

Befintlig datauppsättning

Använd den här sökvägen när du redan har frågor och svar som samlats in i en fil (eller frågor plus grund sanning) och du bara vill att Foundry ska poängsätta dem. JSONL stöder både turbaserade rader och inmatning på konversationsnivå; CSV är endast turbaserat.

Data i Foundry eller Application Insights

Använd den här sökvägen när agenten redan körs och du vill utvärdera vad som faktiskt hände. I stället för att flytta ut data pekar du Foundry mot de data där de redan finns lagrade – med hjälp av Foundry-svars-ID eller Application Insights-spårnings-ID eller konversations-ID.

Indata utan svar

Använd den här sökvägen när du har indata men inga svar ännu. Foundry genererar svar mot en modell eller ett agentmål vid utvärderingstillfället och poängsätter dem sedan. Välj en rad utifrån om dina indata är förfrågningar (skickas som enskilda turer) eller scenariobeskrivningar (används för att styra en interaktion på konversationsnivå).

Inga data ännu

Använd den här sökvägen när du skapar en ny modell eller agent och inte har samlat in några indata. Foundry genererar testdata från grunden – välj syntetiska frågor för bred kvalitetstäckning eller kontradiktoriska uppmaningar för säkerhetstestning.

Välj utvärderare

Varje scenario binder utvärderarna till fält i dina data via kolumnmappningar. Vilka fält som är tillgängliga beror på datakällan. Datauppsättningsscenarier exponerar dina anpassade objektfält, medan målgenererade scenarier även exponerar modellen eller agentsvaret via ett exempelschema. Underavsnitten per scenario senare i den här artikeln visar kolumnmappningarna för varje ärende.

En översikt över tillgängliga utvärderare och hur du väljer dem finns i inbyggda utvärderare och anpassade utvärderare.

Förutsättningar

• Ett Foundry-projekt.

• En Azure OpenAI-distribution med en GPT-modell som stöder chattens slutförande (till exempel gpt-5-mini).

• Foundry-användarroll i Foundry-projektet.

  Viktigt

  Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

• Du kan också använda ditt eget lagringskonto för att köra utvärderingar.

Kom igång

Installera SDK:et och konfigurera klienten:

pip install "azure-ai-projects>=2.2.0"

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# 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 (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
openai_client = project_client.get_openai_client()

Förbereda indata

De flesta utvärderingsscenarier kräver indata. Du kan ange data på två sätt:

Ladda upp en datauppsättning (rekommenderas)

Ladda upp en JSONL- eller CSV-fil för att skapa en versionsdatauppsättning i foundry-projektet. Datauppsättningar stöder versionshantering och återanvändning i flera utvärderingskörningar. Använd den här metoden för produktionstestning och CI/CD-arbetsflöden.

Förbered en JSONL-fil med ett JSON-objekt per rad som innehåller de fält som utvärderarna behöver:

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

Eller förbered en CSV-fil med kolumnrubriker som matchar dina utvärderarfält:

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Ange data infogade

För snabbexperimentering med små testuppsättningar anger du data direkt i utvärderingsbegäran med hjälp av file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Skicka source som fältet "source" i konfigurationen av datakällan när du skapar en körning. Scenarioavsnitten som följer används file_id som standard.

Utvärdering av datauppsättning

Utvärdera förberäknade svar i en JSONL-fil med datakällans jsonl typ. Det här scenariot är användbart när du redan har modellutdata och vill utvärdera deras kvalitet.

Definiera dataschemat och utvärderarna

Ange det schema som matchar dina JSONL-fält och välj de utvärderare (testvillkor) som ska köras. Använd parametern data_mapping för att ansluta fält från dina indata till utvärderarparametrar med {{item.field}} syntax. Inkludera data_mapping alltid med de obligatoriska indatafälten för varje utvärderare. Fältnamnen måste matcha dem i JSONL-filen, till exempel om dina data har "question" i stället "query"för , använd "{{item.question}}" i mappningen. De obligatoriska parametrarna per utvärderare finns i inbyggda utvärderare.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "response": { "type": "string" },
          "ground_truth": { "type": "string" }
        },
        "required": ["query", "response", "ground_truth"]
      }
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
          "response": "{{item.response}}",
          "ground_truth": "{{item.ground_truth}}"
        }
      }
    ]
  }'

Skapa utvärdering och kör process

Skapa utvärderingen och starta sedan en exekvering mot din uppladdade datamängd. Körningen kör varje utvärderare på varje rad i datauppsättningen.

# Create the evaluation
eval_object = openai_client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

# Step 1: Create the evaluation
EVAL_ID=$(curl --silent --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "response": { "type": "string" },
          "ground_truth": { "type": "string" }
        },
        "required": ["query", "response", "ground_truth"]
      }
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": { "model": "gpt-5-mini" },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": { "model": "gpt-5-mini" },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
          "response": "{{item.response}}",
          "ground_truth": "{{item.ground_truth}}"
        }
      }
    ]
  }' | jq -r '.id')

# Step 2: Create a run against your dataset
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-run",
    "data_source": {
      "type": "jsonl",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      }
    }
  }'

Ett fullständigt körbart exempel finns i sample_evaluations_builtin_with_dataset_id.py på GitHub. För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

CSV-datauppsättningsutvärdering

Utvärdera förkomputerade svar i en CSV-fil med hjälp csv av datakällans typ. Det här scenariot fungerar på samma sätt som datamängdsutvärderingen men accepterar CSV-filer i stället för JSONL. Använd CSV när dina data redan är i kalkylblads- eller tabellformat.

Förbereda en CSV-fil

Skapa en CSV-fil med kolumnrubriker som matchar de fält som utvärderarna behöver. Varje rad representerar ett testfall.

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Ladda upp och kör

Ladda upp CSV-filen som en datauppsättning. Skapa sedan en utvärdering med hjälp csv av datakällans typ. Schemadefinitionen och utvärderarkonfigurationen är desamma som för JSONL-utvärderingar. Den enda skillnaden är "type": "csv" i datakällan.

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = openai_client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Utvärdering av modellmål

Skicka förfrågningar till en driftsatt modell vid körning. Utvärdera svaren med datakälltypen azure_ai_target_completions och målet azure_ai_model. Dina indata innehåller frågor. Modellen genererar svar som du sedan utvärderar.

Definiera meddelandemallen och målet

Mallen input_messages styr hur frågor skickas till modellen. Använd {{item.query}} för att referera till fält från dina indata. Ange den modell som ska utvärderas och valfria samplingsparametrar:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Konfigurera utvärderare och datamappningar

När modellen genererar svar vid körning använder du {{sample.output_text}} i data_mapping för att referera till modellens utdata. Använd {{item.field}} för att referera till fält från dina indata.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Skapa utvärdering och kör process

eval_object = openai_client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "model-target-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "input_messages": {
        "type": "template",
        "template": [
          {
            "type": "message",
            "role": "user",
            "content": {
              "type": "input_text",
              "text": "{{item.query}}"
            }
          }
        ]
      },
      "target": {
        "type": "azure_ai_model",
        "model": "gpt-5-mini",
        "sampling_params": {
          "top_p": 1.0,
          "max_completion_tokens": 2048
        }
      }
    }
  }'

Ett fullständigt körbart exempel finns i sample_model_evaluation.py på GitHub. För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Utvärdering av agentens mål

Skicka frågor till en Foundry-agent vid körning och utvärdera svaren med datakälltypen azure_ai_target_completions och målet azure_ai_agent. Det här scenariot fungerar för både prompt-agenter och värdagenter.

Definiera meddelandemallen och målet

Mallen input_messages styr hur frågor skickas till agenten. Använd {{item.query}} för att referera till fält från dina indata. Ange agenten som ska utvärderas med namn:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Konfigurera utvärderare och datamappningar

När agenten genererar svar under körtid använder du variablerna i {{sample.*}} och data_mapping för att referera till agentens utdata.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Skapa utvärdering och kör process

eval_object = openai_client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-target-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "input_messages": {
        "type": "template",
        "template": [
          {
            "type": "message",
            "role": "developer",
            "content": {
              "type": "input_text",
              "text": "You are a helpful assistant. Answer clearly and safely."
            }
          },
          {
            "type": "message",
            "role": "user",
            "content": {
              "type": "input_text",
              "text": "{{item.query}}"
            }
          }
        ]
      },
      "target": {
        "type": "azure_ai_agent",
        "name": "my-agent",
        "version": "1"
      }
    }
  }'

Ett fullständigt körbart exempel finns i sample_agent_evaluation.py på GitHub. För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Anropsprotokoll för värdbaserad agent

Värdbaserade agenter som använder anropsprotokollet stöder samma azure_ai_agent måltyp men använder ett frihandsformat input_messages . I stället för det strukturerade mallformatet anger du ett JSON-objekt som mappar direkt till agentens /invocations begärandetext. Använd {{item.*}} platshållare för att ersätta fält från dina indata.

Om en värdbaserad agent stöder både protokollen för svar och anrop använder tjänsten som standard anropsprotokollet.

Definiera meddelandeformatet och målet

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Skapa utvärdering och kör process

eval_object = openai_client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "hosted-agent-invocations-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "input_messages": {
        "message": "{{item.query}}"
      },
      "target": {
        "type": "azure_ai_agent",
        "name": "my-hosted-agent",
        "version": "1"
      }
    }
  }'

Konfigurationen av utvärderaren och datamappningarna är desamma som för utvärdering av promptagenten. Använd {{sample.output_text}} för agentens textsvar och {{sample.output_items}} för fullständiga strukturerade utdata, inklusive verktygsanrop.

Utvärdering av agentens svar

Hämta och utvärdera Foundry-agentsvar med svars-ID:t med hjälp av azure_ai_responses datakällans typ. Använd det här scenariot för att utvärdera specifika agentinteraktioner när de inträffar.

Ett svars-ID är en unik identifierare som returneras varje gång en Foundry-agent genererar ett svar. Du kan samla in svars-ID:n från agentinteraktioner med hjälp av svars-API :et eller från programmets spårningsloggar. Ange ID:n som inbäddat innehåll eller ladda upp dem som ett dataset (se Förbereda indata).

Samla in svars-ID:n

Varje anrop till svars-API:et returnerar ett svarsobjekt med ett unikt id fält. Samla in dessa ID:er från ditt programs interaktioner eller generera dem direkt:

# Generate response IDs by calling a model through the Responses API
response = openai_client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

Du kan också samla in svars-ID:er från agentinteraktioner i programmets spårningsloggar eller övervakningspipeline. Varje svars-ID identifierar unikt ett lagrat svar som utvärderingstjänsten kan hämta.

Skapa utvärdering och kör process

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = openai_client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-response-evaluation",
    "data_source": {
      "type": "azure_ai_responses",
      "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
          "type": "file_content",
          "content": [
            {"item": {"resp_id": "resp_abc123"}},
            {"item": {"resp_id": "resp_def456"}}
          ]
        }
      }
    }
  }'

Ett fullständigt körbart exempel finns i sample_agent_response_evaluation.py på GitHub. För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Utvärdering av spårning (förhandsversion)

Utvärdera agentinteraktioner som Application Insights redan har samlat in. Använd datakällans azure_ai_traces typ. Det här scenariot är användbart för utvärdering efter distributionen av verklig produktionstrafik. Du väljer spår från ditt övervakningsflöde och kör utvärderare på dem utan att köra om några förfrågningar.

Spårningsutvärdering stöder två lägen:

• Med spårnings-ID :n – Utvärdera specifika agentinteraktioner genom att ange deras operation_Id värden från Application Insights.
• Efter agentfilter – Identifiera och utvärdera de senaste spårningarna automatiskt för en viss agent, utan att manuellt samla in spårnings-ID:t.

Intelligent insamling

Spårningsutvärdering stöder intelligent sampling, som väljer en representativ delmängd av spårningar för utvärdering i stället för att utvärdera varje samlad spårning. Aktivera den här funktionen genom att aktivera växlingsknappen Intelligent sampling i Foundry-portalen när du konfigurerar en spårningsutvärderingskörning. Intelligent sampling minskar utvärderingskostnaden samtidigt som spårningsdiversitet bevaras – vilket säkerställer att gränsfall, felsökvägar och olika konversationsmönster ingår i den utvärderade uppsättningen.

Så här fungerar intelligent sampling

Urvalsalgoritmen använder en MinHash-baserad farthest-first-metod för diversitet som utförs i flera steg:

1. Exakt deduplicering – Tar bort duplicerade spårningar från poolen.
2. Hårda filter – Tar bort brutna sessioner, trunkerade spårningar och felformade verktygsanrop som inte är lämpliga för utvärdering.
3. Sammansättning – Kombinerar spårningsnivåsignaler till en enhetlig representation.
4. MinHash farthest-first-urval – Beräknar lokalitetskänsliga hashvärden (MinHash-signaturer) för användartext för att uppskatta likheten mellan spår, och väljer sedan iterativt det minst liknande spåret ur den återstående mängden. Varje efterföljande val maximerar avståndet från alla tidigare valda spårningar.

Denna metod ger betydligt högre lexikal mångfald och bredare vokabulärtäckning jämfört med slumpmässig sampling, vilket innebär att den utvärderade uppsättningen bättre representerar hela utbudet av agentinteraktioner - inklusive sällsynta, hårda och nya fall som slumpmässig sampling tenderar att missa.

Intelligent sampling är särskilt effektivt för:

• Utvärdering och riktmärken – Maximerar täckningen av indatafördelningen så att utvärderingspoängen återspeglar verklig mångfald.
• Generering av kriterier – Ger mer fokuserade och användbara kriterier genom att exponera olika konversationsmönster.
• Finjustering av datamängdskuration – Väljer spårningar som hjälper modeller att lära sig mer effektivt.

Algoritmen körs helt på lokal beräkning utan extra API-anrop, så det medför inte extra kostnader för modellinferens utöver själva utvärderingen.

Exempel på intelligent sampling

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# Compute time window in unix seconds
# Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
now_unix = int(time.time())
end_time = now_unix + 600
start_time = now_unix - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

Krav för spårningsdata

Spårningsutvärdering kräver att din agent genererar intervall som följer OpenTelemetry-semantiska konventioner för generativ AI. Mer specifikt läser utvärderingstjänsten intervall från Application Insights och extraherar konversationsdata från deras attribut.

Följande span-attribut används:

För Python-agenter som skapats med Azure AI Agent Server SDK, lägg till [tracing] extra för att aktivera automatisk spanemission:

pip install "azure-ai-agentserver-core[tracing]"

Krav för spårningsutvärdering

Förutom de allmänna kraven kräver spårningsutvärdering:

• En Application Insights-resurs som är ansluten till ditt Foundry-projekt. Se också Ställ in spårning i Microsoft Foundry.
• Projektets hanterade identitet måste ha rollen Log Analytics Reader på både Application Insights-resursen och dess länkade Log Analytics arbetsyta.
• paketet azure-monitor-query Python (behövs bara om du samlar in spårnings-ID manuellt).

pip install "azure-ai-projects>=2.2.0" azure-monitor-query

Ange följande miljövariabler:

• APPINSIGHTS_RESOURCE_ID – Application Insights-resurs-ID (till exempel /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — Agentidentifieraren som genereras av spårningsintegreringen (gen_ai.agent.id attributet), som används för att filtrera spårningar. Format: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Valfritt) Antal timmar att se tillbaka vid spårningsförfrågningar. Standardvärde för 1.

Alternativ A: Utvärdera efter agentfilter

Den enklaste metoden är att låta tjänsten automatiskt identifiera och utvärdera de senaste spårningarna för en specifik agent. Ingen manuell spårnings-ID-samling behövs.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Tjänsten filtrerar invoke_agent sträckor med gen_ai.agent.id attributet, analyserar upp till max_traces unika spårnings-ID:n och utvärderar alla sträckor från dessa spårningar.

Alternativ B: Utvärdera med spårnings-ID:n

Om du vill ha mer kontroll samlar du in specifika spårnings-ID:t från Application Insights och utvärderar dem. Den här metoden är användbar när du vill utvärdera en kuraterad uppsättning interaktioner, till exempel spårningar som flaggats av aviseringar eller samplats för kvalitetsgranskning.

Samla in spårnings-ID:t från Application Insights

Fråga Application Insights efter operation_Id värden från agentens spårningar. Varje operation_Id representerar en fullständig agentinteraktion.

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Skapa utvärdering och köra med spårnings-ID:t

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Konfigurera utvärderare och datamappningar

När du utvärderar spårningar extraherar tjänsten automatiskt konversationsdata från attributen OpenTelemetry span. Använd dessa fältnamn direkt i data_mapping (utan de item. prefix eller sample. prefix som används i andra scenarier):

testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",
        "evaluator_name": "builtin.intent_resolution",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "type": "azure_ai_evaluator",
        "name": "tool_call_accuracy",
        "evaluator_name": "builtin.tool_call_accuracy",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "model": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

Ett fullständigt körbart exempel finns i sample_evaluations_builtin_with_traces.py på GitHub. För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Utvärdering av syntetiska data (förhandsversion)

azure_ai_synthetic_data_gen_preview Använd datakällans typ för att generera syntetiska testfrågor, skicka dem till en distribuerad modell eller Foundry-agent och utvärdera svaren. Använd det här scenariot när du inte har någon testdatauppsättning. Tjänsten genererar frågor baserat på en uppmaning som du anger (och/eller från agentens instruktioner), kör dem mot målet och utvärderar svaren.

Så här fungerar syntetisk datautvärdering

1. Tjänsten genererar syntetiska frågor baserat på dina prompt och valfria startdatafiler.
2. Varje fråga skickas till det angivna målet (modell eller agent) för att generera ett svar.
3. Utvärderare bedömer varje svar med hjälp av den genererade frågan och svaret.
4. De genererade frågorna lagras som en datauppsättning i projektet för återanvändning.

Parametrar

Konfigurera utvärderare och datamappningar

Den syntetiska datageneratorn skapar frågor i fältet {{item.query}} . Målet genererar tillgängliga svar i {{sample.output_text}}. Mappa dessa fält till dina utvärderare:

data_source_config = {"type": "azure_ai_source", "scenario": "synthetic_data_gen_preview"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Skapa utvärdering och kör process

eval_object = openai_client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

# Step 1: Create the evaluation
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals?api-version=v1" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Synthetic Data Evaluation",
    "data_source_config": {
      "type": "azure_ai_source",
      "scenario": "synthetic_data_gen_preview"
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
          "model": "gpt-5-mini"
        },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{sample.output_text}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{sample.output_text}}"
        }
      }
    ]
  }'

# Step 2: Create a run with synthetic data generation
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=v1" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "synthetic-data-evaluation",
    "data_source": {
      "type": "azure_ai_synthetic_data_gen_preview",
      "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": "gpt-5-mini",
        "output_dataset_name": "my-synthetic-dataset"
      },
      "target": {
        "type": "azure_ai_model",
        "model": "gpt-5-mini"
      }
    }
  }'

För att fråga efter slutförande och tolka resultaten, se Hämta resultat. Svaret innehåller en output_dataset_id egenskap som innehåller ID:t för den genererade datamängden, som du kan använda för att hämta eller återanvända syntetiska data.

Utvärdering på konversationsnivå (förhandsversion)

Utvärdera fullständiga konversationer för att utvärdera agentkvaliteten i hela användarinteraktioner – inte bara enskilda svar. Använd utvärdering på samtalsnivå för att identifiera kvalitetsproblem som ofullständig uppgiftslösning, användarfrustration och regressioner i verktygsanrop som utvärdering på turnivå missar.

Tänk dig till exempel en supportagent där användaren blir frustrerad över flera svängar:

Tur 1 – Användare: "Jag måste återställa mitt lösenord." Agent: "Jag hittade ditt konto. Jag skickar en återställningslänk."

Omgång 2 — Användare: "Jag fick inte mejlet." Agent: "Jag har skickat länken igen. Kontrollera skräppost."

Tur 3 — Användare: "Fortfarande inget. Kan du bara återställa den direkt?" Agent: "Jag har skickat en annan återställningslänk."

En utvärderare på turnivå bedömer endast det sista svaret – som är artigt och agerar – så det får ett högt betyg. En utvärderare på konversationsnivå som bedömer kundnöjdhet genom hela konversationen flaggar att agenten upprepade samma misslyckade åtgärd tre gånger utan att försöka med något alternativt tillvägagångssätt, vilket lämnade användarens problem olöst.

Utvärdering på konversationsnivå skiljer sig från utvärdering på turnivå på flera sätt:

Utvärdering på konversationsnivå stöder fyra alternativ för datakälla:

Välj en utvärderingsnivå

Parametern evaluation_level för körningen avgör om utvärderarna ska bedöma enskilda turer eller hela konversationer:

Vanliga fel

Förbereda konversationsdata

Skapa en JSONL-fil där varje rad innehåller en fullständig konversation i fältet messages . Varje meddelande ska innehålla en role (användare, assistent eller system) och content. Ett fullständigt exempel finns i utvärderingsexemplen conversation i SDK:

 {"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": "Your current balance is $1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}]}

Du kan också inkludera verktygsdefinitioner och verktygsanrop om din agent använder verktyg:

{"messages": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris"}]}
{"messages": [{"role": "user", "content": "How do I reverse a string in Python?"}, {"role": "assistant", "content": "You can reverse a string in Python by using slicing: string[::-1]"}]}
{"messages": [{"role": "user", "content": "What are the main causes of climate change?"}, {"role": "assistant", "content": "The main causes of climate change are the increase in greenhouse gases in the atmosphere, primarily due to human activities such as burning fossil fuels and deforestation."}]}
{"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_account_balance", "arguments": "{\"account_id\": \"ACCT-7890\"}"}}]}, {"role": "tool", "tool_call_id": "call_abc123", "content": "{ \"balance\": 1234.56, \"currency\": \"USD\" }"}, {"role": "assistant", "content": "Your current balance is 1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}], "tool_definitions": [{"name": "get_account_balance", "description": "Retrieves the current balance for a customer account", "parameters": {"type": "object", "properties": {"account_id": {"type": "string"}}, "required": ["account_id"]}}]}
{"messages": [{"role": "user", "content": "Explain the theory of relativity in simple terms."}, {"role": "assistant", "content": "Einstein's theory of relativity shows that space and time are interconnected and relative to the observer's frame of reference."}]}
{"messages": [{"role": "user", "content": "What's the weather in Seattle?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_002", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Seattle, WA\"}"}}]}, {"role": "tool", "tool_call_id": "call_002", "content": "{ \"temperature\": 55, \"condition\": \"Cloudy\" }"}, {"role": "assistant", "content": "It's currently 55F and cloudy in Seattle."}], "tool_definitions": [{"name": "get_weather", "description": "Get the current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]}
{"messages": [{"role": "user", "content": "What is the tallest mountain in the world?"}, {"role": "assistant", "content": "Mount Everest is the tallest mountain in the world."}]}
{"messages": [{"role": "user", "content": "Is 4 x 2 = 16?"}, {"role": "assistant", "content": "No, 4 x 2 = 8."}]}
{"messages": [{"role": "user", "content": "What is the best Italian desert?"}, {"role": "assistant", "content": "Tiramisu is a popular Italian dessert."}]}
{"messages": [{"role": "user", "content": "What is the chemical formula for water?"}, {"role": "assistant", "content": "The chemical formula for water is H2O."}]}

Definiera dataschemat och utvärderarna

Ange schemat för konversationsdata, "meddelanden" och välj utvärderare som är utformade för utvärdering på konversationsnivå. Utvärderare på konversationsnivå utvärderar hela interaktionen snarare än enskilda svängar.

pip install "azure-ai-projects>=2.2.0"

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
                "tool_definitions": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "multiturn-conversation-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "messages": {"type": "array"},
          "tool_definitions": {"type": "array"}
        },
        "required": ["messages"]
      },
      "include_sample_schema": false
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "customer_satisfaction",
        "evaluator_name": "builtin.customer_satisfaction",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      },
      {
        "type": "azure_ai_evaluator",
        "name": "task_completion",
        "evaluator_name": "builtin.task_completion",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      },
      {
        "type": "azure_ai_evaluator",
        "name": "conversation_coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      },
      {
        "type": "azure_ai_evaluator",
        "name": "groundedness",
        "evaluator_name": "builtin.groundedness",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      }
    ]
  }'

Skapa utvärdering och kör process

from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileID,
)

# Upload conversation data
data_id = project_client.datasets.upload_file(
    name="multiturn-conversation-data",
    version="1",
    file_path="./sample_data_multiturn_conversations.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run with evaluation_level set to "conversation"
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="multiturn-conversation-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
    extra_body={"evaluation_level": "conversation"},
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "multiturn-conversation-run",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "jsonl",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      }
    }
  }'

För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Utvärdera konversationer efter ID från spårningar

Utvärdera specifika konversationer från Application Insights genom att ange deras konversations-ID: n. Använd det här alternativet för att hitta grundorsaken till problem eller verifiera korrigeringar för specifika interaktioner. Du kan till exempel undersöka en konversation som flaggas av en avisering eller verifiera en korrigering för ett känt problem.

Var du hittar konversations-ID:t

Hitta konversations-ID:t i:

• Application Insights-användargränssnittet för spårningsloggar – Bläddra till intressanta spårningar och leta upp conversation_id fältet i spårningsinformationen.
• Programmets loggningsutdata – Om du uttryckligen anger conversation_id när du skapar agentsvar hämtar du det från loggarna.
• OpenTelemetry-spårningskontext — conversation_id kan också härledas från traceparent-huvudet om agenten använder standardmässig spridning av spårningskontext.

Parametrar för konversations-ID-sökning

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "conversation-trace-eval",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_trace_data_source_preview",
      "trace_source": {
        "type": "conversation_id_source",
        "conversation_ids": ["conversation_1234", "conversation_5678"],
        "lookback_hours": 24,
        "end_time": "2026-05-21T00:00:00Z"
      }
    }
  }'

Utvärdera exempelkonversationer efter agentfilter

Utvärdera en exempeluppsättning konversationer från Application Insights genom att filtrera efter agentnamn. Använd det här alternativet för att utvärdera den övergripande agentkvaliteten i produktionstrafiken. Kör till exempel regelbundna kvalitetsbedömningar eller övervaka kvalitetsförsämring i produktionen.

Agenten som du anger för filtrering kan ingå i en konversation med flera agenter. Filtret matchar alla konversationer där agenten deltog.

Agentidentitetsfält

Ange vilken agent som ska filtreras med något av följande format:

Filterstrategier

Parametrar

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-quality-eval",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_trace_data_source_preview",
      "trace_source": {
        "type": "agent_filter",
        "agent_name": "my-support-agent",
        "agent_version": "1",
        "start_time": 1743465600,
        "end_time": 1743552600,
        "max_traces": 100,
        "filter_strategy": "random_sampling"
      }
    }
  }'

För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Konversationssimulering

Generera simulerade konversationer från scenariobeskrivningar och utvärdera dem på konversationsnivå. Använd det här scenariot för att testa agentens beteende i kontrollerade situationer före distributionen. Tjänsten genererar realistiska konversationer baserat på dina scenariobeskrivningar och utvärderar dem sedan.

Den här metoden är användbar för:

• Testning före distribution: Verifiera agentbeteendet i olika scenarier utan verklig användartrafik.
• Täckning av gränsfall: Testscenarier som sällan uppstår naturligt men är viktiga att hantera väl.
• Regressionstestning: Se till att agentuppdateringar inte försämrar prestanda i kända scenarier.
• Skaltestning: Generera många konversationer snabbt för att belastningstesta agentens kapacitet.

Så här fungerar konversationssimulering

1. Du anger en datauppsättning med scenariobeskrivningar – varje rad beskriver en situation som den simulerade användaren försöker utföra.
2. Tjänsten använder en simulatormodell för att spela rollen som användare och interagerar med din agent baserat på scenariot.
3. Varje scenario genererar en eller flera fullständiga konversationer.
4. Utvärderare på konversationsnivå utvärderar de genererade konversationerna.
5. Projektet lagrar både konversationer och utvärderingsresultat.

Förbereda scenariodata

Skapa en JSONL-fil där varje rad beskriver ett scenario för den simulerade användaren. Schemat kräver id, test_case_descriptionoch desired_num_turns. Inkludera information om användarens mål, kontext och eventuella begränsningar. Ett fullständigt exempel finns i utvärderingsexemplen conversation i SDK.

{"id": "contoso_refund_timeline", "test_case_description": "Customer returned an item to Contoso Electronics 5 days ago and hasn't received their refund yet. They want to know how long Contoso refunds take.", "desired_num_turns": 10}
{"id": "contoso_store_hours_lookup", "test_case_description": "Customer wants to know what time the Contoso Electronics store closes today. Simple single-fact question with possibly one clarifying turn about which location.", "desired_num_turns": 3}

Parametrar

Definiera utvärderare

Välj utvärderare som är utformade för utvärdering på konversationsnivå. De simulerade konversationerna mappas automatiskt till utvärderarna.

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator, PromptAgentDefinition

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_AGENT_NAME", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Simulation uses the same "custom" eval group type as dataset evaluation (S1),
    # since the generated conversations follow the same messages schema.
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "conversation-simulation-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "messages": {"type": "array"}
        },
        "required": ["messages"]
      },
      "include_sample_schema": false
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "customer_satisfaction",
        "evaluator_name": "builtin.customer_satisfaction",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      },
      {
        "type": "azure_ai_evaluator",
        "name": "task_completion",
        "evaluator_name": "builtin.task_completion",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      },
      {
        "type": "azure_ai_evaluator",
        "name": "conversation_coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      },
      {
        "type": "azure_ai_evaluator",
        "name": "groundedness",
        "evaluator_name": "builtin.groundedness",
        "initialization_parameters": {"model": "gpt-5-mini"},
        "data_mapping": {"messages": "{{item.messages}}"}
      }
    ]
  }'

Skapa utvärdering och kör process

# Create (or update) an agent to simulate against
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=model_deployment_name,
        instructions="You are a helpful customer service agent. Be empathetic and solution-oriented.",
    ),
)

# Upload scenario data
scenarios_id = project_client.datasets.upload_file(
    name="simulation-scenarios",
    version="1",
    file_path="./sample_data_simulation_scenarios.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Simulation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a simulation run
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="conversation-simulation-run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": scenarios_id,
        },
        "target": {
            "type": "azure_ai_agent",
            "name": agent.name,
            "version": agent.version,
        },
        "item_generation_params": {
            "type": "conversation_gen_preview",
            "model": model_deployment_name,
            "num_conversations": 2,
            "max_turns": 5,
            "sampling_params": {
                "temperature": 0.7,
                "top_p": 1.0,
                "max_completion_tokens": 800,
            },
            "data_mapping": {
                "test_case_description": "test_case_description",
                "id": "id",
                "desired_num_turns": "desired_num_turns",
            },
        },
    },
    extra_body={"evaluation_level": "conversation"},
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "conversation-simulation-run",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_SCENARIOS_DATASET_ID"
      },
      "target": {
        "type": "azure_ai_agent",
        "name": "my-agent",
        "version": "1"
      },
      "item_generation_params": {
        "type": "conversation_gen_preview",
        "model": "gpt-4.1",
        "num_conversations": 2,
        "max_turns": 5,
        "sampling_params": {
          "temperature": 0.7,
          "top_p": 1.0,
          "max_completion_tokens": 800
        },
        "data_mapping": {
        }
      }
    }
  }'

För att fråga efter slutförande och tolka resultaten, se Hämta resultat.

Hämta resultat

När en utvärderingskörning har slutförts hämtar du de poängsatta resultaten och granskar dem i portalen eller programmatiskt.

Sök efter resultat

Utvärderingskörningar är asynkrona. Kontrollera körstatus tills den är färdig och hämtade sedan resultatet.

import time
from pprint import pprint

while True:
    run = openai_client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    openai_client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Tolka resultat

För ett enda dataexempel matar alla utvärderare ut följande schema:

• Etikett: en binär "pass" eller "fail"-etikett som liknar enhetstestets utdata. Använd det här resultatet för att underlätta jämförelser mellan utvärderare.
• Poäng: en poäng från den naturliga skalan för varje utvärderare. Vissa utvärderare använder ett finkornigt kriterier, bedömning på en 5-poängsskala (kvalitetsutvärderingar) eller en 7-poängsskala (utvärderare för innehållssäkerhet). Andra, som textlikhetsutvärderare, använder F1-antal, som är decimaltal mellan 0 och 1. Alla ickebinära "poäng" binariseras till "pass" eller "fail" i fältet "label" baserat på "tröskelvärdet".
• Tröskelvärde: Alla ickebinära poäng binariseras till "pass" eller "fail" baserat på ett standardtröskelvärde som användaren kan åsidosätta i SDK-upplevelsen.
• Orsak: För att förbättra begripligheten genererar också alla utvärderare av LLM-domare ett resonemang för att förklara varför en viss poäng ges.
• Information: (valfritt) För vissa utvärderare, till exempel tool_call_accuracy, kan det finnas ett "informationsfält" eller flaggor som innehåller ytterligare information som hjälper användarna att felsöka sina program.

Exempelutdata (enskilt objekt)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Exempelutdata (samlad)

För aggregerade resultat över flera dataexempel (en datamängd) utgör den genomsnittliga frekvensen för exemplen med "pass" överföringshastigheten för datamängden.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Felsökning

Jobb som körs under en lång tid

Utvärderingsjobbet kan förbli i läget Körs under en längre period. Det här villkoret inträffar vanligtvis när Azure OpenAI-modelldistributionen inte har tillräckligt med kapacitet, vilket gör att tjänsten försöker igen.

Upplösning:

1. Avbryt det aktuella utvärderingsjobbet med openai_client.evals.runs.cancel(run_id, eval_id=eval_id).
2. Öka modellkapaciteten i Azure-portalen.
3. Kör utvärderingen igen.

Autentiseringsfel

Om du får ett 401 Unauthorized-fel eller 403 Forbidden-fel kontrollerar du att:

• Din DefaultAzureCredential är korrekt konfigurerad. Om du använder Azure CLI kör du az login.
• Ditt konto har rollen Foundry User i Foundry-projektet.
• Projektets slutpunkts-URL är korrekt och innehåller både konto- och projektnamnen.

Dataformatfel

Om utvärderingen misslyckas med ett schema- eller datamappningsfel:

• Kontrollera att JSONL-filen har ett giltigt JSON-objekt per rad.
• Bekräfta att fältnamnen i data_mapping matchar fältnamnen i JSONL-filen exakt (skiftlägeskänslig).
• Kontrollera att item_schema egenskaperna matchar fälten i datauppsättningen.

Hastighetsbegränsningsfel

Tenant-, prenumerations- och projektnivåer begränsar hur ofta utvärderingskörningar kan skapas. Om du får ett 429 Too Many Requests svar:

• retry-after Kontrollera rubriken i svaret för den rekommenderade väntetiden.
• Granska svarstexten för information om hastighetsbegränsning.
• Använd exponentiell backoff när du försöker utföra misslyckade begäranden igen.

Om ett utvärderingsjobb misslyckas med ett 429 fel under exekveringen:

• Minska storleken på din utvärderingsdatauppsättning eller dela upp den i mindre batchar.
• Öka TPM-kvoten (token per minut) för modelldistributionen i Azure-portalen.

Verktygsfel för agentutvärdering

Om en agentutvärderare returnerar ett fel för icke stödda verktyg:

• Kontrollera vilka verktyg som stöds för agentutvärderingar.
• Som en lösning kan du omsluta verktyg som inte stöds som användardefinierade funktionsverktyg så att utvärderaren kan utvärdera dem.

Relaterat innehåll

• Komplettera arbetsexempel
• Trace-baserat utvärderingsexempel
• Sätt upp spårning i Microsoft Foundry
• Konfigurera kontinuerlig utvärdering
• Se utvärderingsresultat i Foundry-portalen
• Kom igång med Foundry
• REST API-referens