Valutare le interazioni tra agente distribuito e modello

Valutare le risposte archiviate o le tracce OpenTelemetry da agenti e modelli distribuiti senza riprodurre le richieste originali.

Prerequisiti

• Completare i prerequisiti di valutazione cloud e la configurazione del client.
• ID delle risposte archiviati per la valutazione delle risposte o una risorsa Application Insights connessa al tuo progetto Foundry per la valutazione delle tracce.
• OpenTelemetry si estende per soddisfare i requisiti dei dati di traccia quando si valutano le tracce.

Gli esempi usano il client SDK configurato in Configurare il client SDK.

Valuta le interazioni per ID della risposta

Recuperare e valutare le risposte dell'agente Foundry in base agli ID risposta usando il azure_ai_responses tipo di origine del dato. Usare questo scenario per valutare interazioni specifiche dell'agente dopo che si verificano.

Un ID risposta è un identificatore univoco restituito ogni volta che un agente Foundry genera una risposta. È possibile raccogliere gli identificativi di risposta dalle interazioni dell'agente usando l'API Responses o dai log applicativi dell'applicazione. Specificare gli ID inline come contenuto del file.

Raccogliere gli ID delle risposte

Ogni chiamata all'API Risposte restituisce un oggetto risposta con un campo univoco id . Raccogliere questi ID dalle interazioni dell'applicazione o generarli direttamente:

# 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

È anche possibile raccogliere gli ID di risposta dalle interazioni dell'agente nei file di log o nel processo di monitoraggio dell'applicazione. Ogni ID risposta identifica in modo univoco una risposta archiviata che il servizio di valutazione può recuperare.

Creare una valutazione ed eseguire

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

Per un esempio eseguibile completo, vedere sample_agent_response_evaluation.py su GitHub. Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati della valutazione cloud.

Valutare le tracce (anteprima)

Valutare le interazioni dell'agente già acquisite da Application Insights. Utilizzare la tipologia di origine dati azure_ai_traces. Questo scenario è utile per la valutazione post-distribuzione del traffico di produzione reale. È possibile selezionare tracce dalla pipeline di monitoraggio ed eseguire analizzatori su di essi senza riprodurre alcuna richiesta.

La valutazione della traccia supporta due modalità:

• Per ID di traccia : valutare interazioni di agenti specifici fornendo i relativi operation_Id valori da Application Insights.
• Per filtro agente : consente di individuare e valutare automaticamente le tracce recenti per un determinato agente, senza raccogliere manualmente gli ID di traccia.

Campionamento intelligente

La valutazione della traccia supporta il campionamento intelligente, che seleziona un sottoinsieme rappresentativo di tracce per la valutazione anziché valutare ogni traccia acquisita. Attiva l'interruttore Campionamento intelligente nel portale Foundry quando configuri un'esecuzione di valutazione delle tracce. Il campionamento intelligente riduce i costi di valutazione mantenendo la diversità di traccia, assicurandosi che i casi perimetrali, i percorsi di errore e i vari modelli di conversazione siano inclusi nel set valutato.

Funzionamento del campionamento intelligente

L'algoritmo di campionamento usa un approccio di diversificazione MinHash con selezione dei punti più distanti, articolato in più fasi:

1. Deduplicazione esatta : rimuove le tracce duplicate dal pool.
2. Filtri severi - Rimuove sessioni interrotte, tracce troncate e chiamate agli strumenti mal formate che non sono idonee alla valutazione.
3. Aggregazione : combina i segnali a livello di traccia in una rappresentazione unificata.
4. Selezione minHash più lontana : calcola gli hash sensibili alla località (firme MinHash) del testo dell'utente per stimare la somiglianza tra le tracce, quindi seleziona in modo iterativo la traccia più diversa dal pool rimanente. Ogni selezione successiva ottimizza la distanza da tutte le tracce selezionate in precedenza.

Questo approccio produce una diversità lessicale significativamente superiore e una copertura del vocabolario più ampia rispetto al campionamento casuale, il che significa che il set valutato rappresenta meglio l'intera gamma di interazioni degli agenti, inclusi casi rari, difficili e nuovi casi che il campionamento casuale tende a perdere.

Il campionamento intelligente è particolarmente efficace per:

• Valutazione e benchmark : ottimizza la copertura della distribuzione di input, in modo che i punteggi di valutazione riflettano la diversità reale.
• Generazione di rubriche: produce rubriche più incentrate e interattive esponendo modelli di conversazione diversi.
• Selezione del set di dati per la messa a punto - Seleziona le tracce che aiutano i modelli ad apprendere in modo più efficiente.

L'algoritmo viene eseguito interamente sul calcolo locale senza chiamate API aggiuntive, quindi non comporta costi di inferenza del modello aggiuntivi oltre la valutazione stessa.

Esempio di campionamento intelligente

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

Requisiti dei dati di traccia

La valutazione della traccia richiede che l'agente crei intervalli che seguono le convenzioni semantiche OpenTelemetry per l'intelligenza artificiale generativa. In particolare, il servizio di valutazione legge le invoke_agent ampiezze da Application Insights ed estrae i dati della conversazione dai relativi attributi.

Vengono usati gli attributi di intervallo seguenti:

Per gli agenti Python creati con l'SDK Azure AI Agent Server, aggiungere il [tracing] aggiuntivo per abilitare l'emissione automatica di span:

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

Prerequisiti per la valutazione della traccia

Oltre ai prerequisiti generali, la valutazione della traccia richiede:

• Una risorsa di Application Insights connessa al progetto Foundry. Vedere Configurare il tracciamento in Microsoft Foundry.
• L'identità gestita del progetto deve avere il ruolo Log Analytics Reader sia nella risorsa di Application Insights che nell'area di lavoro Log Analytics collegata. Se le tabelle che archiviano le tracce sono protette (il livello di protezione è impostato su Protetto), assegnare anche il ruolo con autorizzazioni di lettura dati di monitoraggio con privilegi agli stessi ambiti in modo che il servizio possa leggere le tabelle di traccia protette.
• Pacchetto azure-monitor-query Python (necessario solo se si raccolgono gli ID di traccia manualmente).

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

Impostare queste variabili di ambiente:

• APPINSIGHTS_RESOURCE_ID : ID risorsa di Application Insights(ad esempio, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — Identificatore dell'agente generato dall'integrazione di tracciamento (gen_ai.agent.id attributo), usato per filtrare le tracce. Formato: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Facoltativo) Numero di ore da esaminare per effettuare query sulle tracce. Di default è 1.

Opzione A: Valutare tramite filtro agente

L'approccio più semplice consiste nell'consentire al servizio di individuare e valutare automaticamente le tracce recenti per un agente specifico. Non è necessario raccogliere manualmente gli ID di traccia.

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

Il servizio filtra le estensioni invoke_agent in base all'attributo gen_ai.agent.id, seleziona fino a max_traces ID di traccia univoci e valuta tutte le estensioni di tali tracce.

Opzione B: Valutare tramite gli identificatori di traccia

Per un maggiore controllo, raccogliere ID di traccia specifici da Application Insights e valutarli. Questo metodo è utile quando si vuole valutare un set curato di interazioni, ad esempio tracce contrassegnate da avvisi o campionate per la verifica della qualità.

Raccogliere gli ID di traccia da Application Insights

Esegui una query su Application Insights per ottenere valori operation_Id dalle tracce dell'agente. Ognuno operation_Id rappresenta un'interazione completa dell'agente:

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

Creare una valutazione ed eseguire un test con ID di traccia

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

Configurare valutatori e mappature dei dati

Quando si valutano le tracce, il servizio estrae automaticamente i dati della conversazione dagli attributi dell'intervallo OpenTelemetry. Usare questi nomi di campo direttamente in data_mapping (senza i prefissi item. o sample. utilizzati in altri scenari).

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},
    ),
    # Safety evaluators — work even with partial trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        initialization_parameters={"threshold": 4},
    ),
]

Passaggi successivi

• Per eseguire il polling per il completamento e interpretare i risultati, vedere Ottenere i risultati della valutazione cloud.
• Per un esempio eseguibile completo, vedere sample_evaluations_builtin_with_traces.py in GitHub.