Afzonderlijke interacties van geïmplementeerde modellen en agents evalueren met Microsoft Foundry SDK

Evalueer opgeslagen antwoorden of OpenTelemetry-traceringen van geïmplementeerde agents en modellen zonder de oorspronkelijke aanvragen opnieuw af te spelen.

Prerequisites

• Voltooi de vereisten voor cloudevaluatie en clientinstallatie.
• Opgeslagen antwoord-id's voor responsevaluatie of een Application Insights-resource die is verbonden met uw Foundry-project voor traceringsevaluatie.
• OpenTelemetry-spans die voldoen aan de vereisten voor tracegegevens wanneer u traceringen evalueert.

In de voorbeelden wordt de SDK-client gebruikt die is geconfigureerd in de SDK-client instellen.

Interacties evalueren op antwoord-id

Antwoorden van Foundry-agents ophalen en evalueren op basis van antwoord-id's met behulp van het azure_ai_responses gegevensbrontype. Gebruik dit scenario om specifieke agentinteracties te evalueren nadat deze zich hebben voorgedaan.

Een antwoord-id is een unieke id die wordt geretourneerd telkens wanneer een Foundry-agent een antwoord genereert. U kunt antwoord-id's verzamelen van agentinteracties met behulp van de Response-API of vanuit de traceringslogboeken van uw toepassing. Geef de id's inline op als bestandsinhoud.

Antwoord-id's verzamelen

Elke aanroep naar de Response-API retourneert een antwoordobject met een uniek id veld. Verzamel deze id's van de interacties van uw toepassing of genereer deze rechtstreeks:

# 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

U kunt ook antwoord-id's verzamelen van agentinteracties in de traceringslogboeken of bewakingspijplijn van uw toepassing. Elke antwoord-id identificeert een opgeslagen antwoord dat door de evaluatieservice kan worden opgehaald.

Evaluatie maken en uitvoeren

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

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

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
    ),
    TestingCriterionAzureAIEvaluator(
        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,
)

const evalObject = await openaiClient.evals.create({
    name: "Agent Response Evaluation",
    data_source_config: { type: "azure_ai_source", scenario: "responses" },
    testing_criteria: [
        {
            type: "azure_ai_evaluator",
            name: "coherence",
            evaluator_name: "builtin.coherence",
            initialization_parameters: { model: modelDeploymentName },
        },
        {
            type: "azure_ai_evaluator",
            name: "violence",
            evaluator_name: "builtin.violence",
        },
    ],
});

const responseEvalRun = await openaiClient.evals.runs.create(evalObject.id, {
    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" } },
                ],
            },
        },
    },
});
console.log(`Evaluation run created: ${responseEvalRun.id}`);

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

Zie sample_agent_response_evaluation.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd. Als u wilt controleren of het proces is voltooid en de resultaten wilt interpreteren, raadpleegt u Resultaten van cloudevaluatie ophalen.

Traceringen evalueren (preview)

Evalueer agentinteracties die Application Insights al heeft vastgelegd. Gebruik het azure_ai_traces gegevensbrontype. Dit scenario is handig voor evaluatie na de implementatie van echt productieverkeer. Je selecteert traces uit je monitoringpijplijn en voert er evaluaties op uit zonder verzoeken opnieuw uit te voeren.

Trace-evaluatie ondersteunt twee modi:

• Op trace-ID's - Beoordeel specifieke agentinteracties door hun operation_Id-waarden uit Application Insights op te geven.
• Op agentfilter : automatisch recente traceringen voor een bepaalde agent detecteren en evalueren, zonder handmatig tracerings-id's te verzamelen.

Intelligente steekproeven

Traceringsevaluatie ondersteunt intelligente steekproeven, die een representatieve subset van traceringen voor evaluatie selecteert in plaats van elke vastgelegde tracering te evalueren. Schakel de schakeloptie Intelligente steekproeven in de Foundry-portal in wanneer u een traceringsevaluatieuitvoering configureert. Intelligente steekproeven verlagen de evaluatiekosten en behouden traceringsdiversiteit, en zorgen ervoor dat randcases, foutpaden en gevarieerde gesprekspatronen worden opgenomen in de geëvalueerde set.

Hoe intelligente steekproeven werken

Het sampling-algoritme maakt gebruik van een minHash-meest-eerste diversiteitsbenadering die in meerdere fasen wordt uitgevoerd:

1. Exacte ontdubbeling : hiermee verwijdert u dubbele traceringen uit de pool.
2. Harde filters : verwijdert verbroken sessies, afgekapte traceringen en ongeldige hulpprogrammaaanroepen die niet geschikt zijn voor evaluatie.
3. Aggregatie : combineert signalen op traceringsniveau in een uniforme weergave.
4. MinHash farthest-first selectiemethode - Berekent localiteitsgevoelige hashes (MinHash-handtekeningen) van gebruikerstekst om de overeenkomst tussen sporen te schatten en selecteert vervolgens iteratief het minst vergelijkbare spoor uit de overige verzameling. Elke volgende keuze maximaliseert de afstand tot alle eerder geselecteerde sporen.

Deze benadering produceert aanzienlijk hogere lexicale diversiteit en bredere vocabulaire dekking vergeleken met willekeurige steekproeven, wat betekent dat de geëvalueerde set beter het volledige bereik van agentinteracties vertegenwoordigt, waaronder zeldzame, harde en nieuwe gevallen die willekeurige steekproeven vaak missen.

Intelligente steekproeven zijn met name effectief voor:

• Evaluatie en benchmarks : maximaliseert de dekking van de invoerdistributie, zodat evaluatiescores de echte diversiteit weerspiegelen.
• Rubriekgeneratie : produceert meer gerichte en bruikbare rubrieken door verschillende gesprekspatronen bloot te stellen.
• De curatie van gegevenssets verfijnen: selecteert traceringen waarmee modellen efficiënter kunnen leren.

Het algoritme wordt volledig uitgevoerd op lokale berekeningen zonder extra API-aanroepen, dus er worden geen extra modeldeductiekosten in rekening gebracht buiten de evaluatie zelf.

Voorbeeld van intelligente steekproeven

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

Tracering van gegevensvereisten

Traceringsevaluatie vereist dat uw agent spans verzendt die voldoen aan de semantische OpenTelemetry-conventies voor generatieve AI. De evaluatieservice leest met name invoke_agent reeksen uit Application Insights en extraheert gespreksgegevens uit hun attributen.

De volgende spankenmerken worden gebruikt:

Voor Python-agents die zijn gebouwd met de Azure AI Agent Server SDK, voegt u de [tracing] uitbreiding toe om automatische span-emissie mogelijk te maken.

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

Vereisten voor traceringsevaluatie

Naast de algemene vereisten, zijn voor traceringsevaluatie de volgende zaken vereist:

• Een Application Insights-resource die is verbonden met uw Foundry-project. Zie Tracering instellen in Microsoft Foundry.
• De beheerde identiteit van het project moet de rol Log Analytics Reader hebben voor zowel de Application Insights-resource als de gekoppelde Log Analytics werkruimte. Als de tabellen die uw traceringen opslaan, zijn beveiligd (het beveiligingsniveau is ingesteld op Beveiligd), wijst u ook de rol Privileged Monitoring Data Reader toe aan dezelfde bereiken, zodat de service de beveiligde traceringstabellen kan lezen.
• Het azure-monitor-query Python-pakket (alleen nodig als u tracerings-id's handmatig verzamelt).

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

Stel deze omgevingsvariabelen in:

• APPINSIGHTS_RESOURCE_ID: de Application Insights-resource-id (bijvoorbeeld /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — De agent-id die wordt verzonden door de traceringsintegratie (gen_ai.agent.id kenmerk), die wordt gebruikt om traceringen te filteren. Indeling: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Optioneel) Aantal uren om terug te kijken bij het uitvoeren van query's op traceringen. Wordt standaard ingesteld op 1.

Optie A: Evalueren op agentfilter

De eenvoudigste methode is om de service automatisch recente traceringen voor een specifieke agent te laten detecteren en evalueren. U hoeft geen tracerings-id's handmatig te verzamelen.

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

De service filtert invoke_agent spans op het gen_ai.agent.id kenmerk, monstert tot max_traces unieke trace-ID's en evalueert alle spans van deze traceringen.

Optie B: Evalueren met behulp van trace-ID's

Voor meer controle verzamelt u specifieke tracerings-id's van Application Insights en evalueert u deze. Deze methode is handig als u een samengestelde set interacties wilt evalueren, zoals traceringen die zijn gemarkeerd door waarschuwingen of een steekproef voor kwaliteitsbeoordeling.

Tracerings-ID's verzamelen uit Application Insights

Query uitvoeren op Application Insights voor operation_Id-waarden uit de traces van uw agent. Elk operation_Id vertegenwoordigt een volledige agentinteractie:

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

Evaluatie maken en uitvoeren met traceer-ID's

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

Beoordelaars en gegevenskoppelingen instellen

Wanneer u traceringen evalueert, extraheert de service automatisch gespreksgegevens uit de OpenTelemetry-spankenmerken. Gebruik deze veldnamen rechtstreeks in data_mapping (zonder de item. of sample. voorvoegsels die in andere scenario's worden gebruikt):

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    # Quality evaluators — require query and response from trace data
    TestingCriterionAzureAIEvaluator(
        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
    TestingCriterionAzureAIEvaluator(
        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},
    ),
]

Volgende stappen 

• Als u wilt controleren of het proces is voltooid en de resultaten wilt interpreteren, raadpleegt u Resultaten van cloudevaluatie ophalen.
• Zie sample_evaluations_builtin_with_traces.py op GitHub voor een volledig voorbeeld dat kan worden uitgevoerd.