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örhandsversion) 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

Om du vill köra en molnutvärdering skapar du en utvärderingsdefinition med ditt dataschema och testkriterier (utvärderare) och skapar sedan en utvärderingskörning. Varje körning utförs av varje utvärderare mot dina data och returnerar poängsatta resultat som du kan kontrollera om de är klara.

Molnutvärdering stöder följande scenarier:

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

Varje utvärdering kräver en data_source_config som talar om för tjänsten vilka fält som ska förväntas i dina data:

• custom – Du definierar en item_schema med dina fältnamn och typer. Ange include_sample_schema till true när du använder ett mål så att utvärderare kan referera till genererade svar.
• azure_ai_source – Schemat härleds från tjänsten. Ange "scenario" till "responses" för utvärdering av agentsvar, "traces" för spårningsutvärdering, "synthetic_data_gen_preview" för utvärdering av syntetiska data (förhandsversion) eller "red_team" för röd teamindelning.

Varje scenario kräver utvärderare som definierar dina testkriterier. Vägledning om hur du väljer utvärderare finns i inbyggda 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).
• Azure AI User roll i Foundry-projektet.
• 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.0.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
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": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": 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": [
  }'

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 = 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 = 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": { "deployment_name": "gpt-5-mini" },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": { "deployment_name": "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örberäknade svar i en CSV-fil med datakällans csv 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 och skapa sedan en utvärdering med datakällans csv 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": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = 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 = 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 kontrollera slutförande och tolka resultat, se Hämta resultat.

Utvärdering av modellmål

Skicka frågor till en utplacerad modell under körning och utvärdera svaren med hjälp av azure_ai_target_completions datakällans typ och ett azure_ai_model mål. Dina indata innehåller frågor. modellen genererar svar som sedan utvärderas.

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": {
            "deployment_name": 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 = 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 = 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. Information om hur du söker efter slutförande och tolkning av resultat finns i Hämta resultat.

Utvärdering av agentens mål

Skicka frågor till en Foundry-agent vid körning och utvärdera svaren genom att använda azure_ai_target_completions datakällans typ med ett azure_ai_agent mål. 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": {
            "deployment_name": 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": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Skapa utvärdering och kör process

eval_object = 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 = 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. Information om hur du söker efter slutförande och tolkning av resultat finns i 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 = 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 = 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 = 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": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = 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 = 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. Information om hur du söker efter slutförande och tolkning av resultat finns i Hämta resultat.

Spårningsutvärdering

Utvärdera agentinteraktioner som redan har samlats in i Application Insights. Använd datakällans azure_ai_traces typ. Det här scenariot är användbart för utvärdering efter driftsättning av riktig produktionstrafik – du väljer spår från din övervakningspipeline och kör utvärderare mot dem utan att spela upp några begäranden igen.

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

• Med spårnings-ID : 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 samla in spårnings-ID manuellt.

Krav för spårningsdata

Spårningsutvärdering kräver att din agent genererar intervall enligt 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.0.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 – låt 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 = 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 = 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. Det här är användbart 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 = 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 = 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 OpenTelemetry span-attributen. 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": {
            "deployment_name": 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": {
            "deployment_name": 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. Information om hur du söker efter slutförande och tolkning av resultat finns i Hämta resultat.

Utvärdering av syntetiska data (förhandsversion)

Generera syntetiska testfrågor, skicka dem till en distribuerad modell eller Foundry-agent och utvärdera svaren med datakällans azure_ai_synthetic_data_gen_preview typ. Använd det här scenariot när du inte har någon testdatauppsättning – tjänsten genererar frågor baserat på en fråga som du anger (och/eller från agentens instruktioner), kör dem mot ditt mål 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": {
            "deployment_name": 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 = 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 = 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 = 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": {
          "deployment_name": "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"
      }
    }
  }'

Information om hur du söker efter slutförande och tolkning av resultat finns i 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.

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 = 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(
    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 icke-binära "poäng" binariseras till "pass" eller "fail" i fältet "label" baserat på "tröskelvärdet".
• Tröskelvärde: Alla icke-binä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. Detta 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 hjälp av 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 (kör az login om du använder Azure CLI).
• Ditt konto har rollen Azure AI 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

Skapandet av utvärderingskörningar är hastighetsbegränsade på klient-, prenumerations- och projektnivå. 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