Ottenere risultati di valutazione con Microsoft Foundry SDK

Monitorare le esecuzioni di valutazione asincrone, recuperare l’output dei singoli elementi e quello aggregato, esaminare la latenza e il costo del modello di destinazione, annullare le esecuzioni e risolvere gli errori di valutazione più comuni.

Prerequisiti

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

Eseguire il polling per un'esecuzione completata

Al termine dell'esecuzione di una valutazione, recuperare i risultati con punteggio ed esaminarli nel portale o a livello di codice.

I processi di valutazione sono asincroni. Eseguire il polling dello stato dell'esecuzione fino al completamento, quindi recuperare i risultati:

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", "canceled"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

if run.status != "completed":
    raise RuntimeError(f"Evaluation run ended in {run.status}: {run.error}")

# Retrieve results
# Iterating the list operation retrieves all pages.
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}")

Interpretare i risultati

Per un singolo esempio di dati, tutti gli analizzatori generano lo schema seguente:

  • Etichetta: un'etichetta binaria "pass" o "fail", simile all'output di uno unit test. Usare questo risultato per facilitare i confronti tra gli analizzatori.
  • Punteggio: punteggio della scala naturale di ogni valutatore. Alcuni analizzatori usano una rubrica con granularità fine, l'assegnazione di punteggi su una scala a 5 punti (analizzatori di qualità) o una scala a 7 punti (analizzatori di sicurezza del contenuto). Altri, come gli analizzatori di somiglianza testuale, usano punteggi F1, che sono float tra 0 e 1. Qualsiasi punteggio non binario viene binarizzato in "superato" o "non superato" nel campo "label" in base alla "soglia".
  • Soglia: tutti i punteggi non di associazione vengono binarizzati per "passare" o "fail" in base a una soglia predefinita, che l'utente può eseguire l'override nell'esperienza SDK.
  • Motivo: per migliorare l'intelligibilità, tutti gli analizzatori di giudici LLM generano anche un campo di ragionamento per spiegare perché viene assegnato un determinato punteggio.
  • Dettagli: (facoltativo) Per alcuni analizzatori, ad esempio tool_call_accuracy, potrebbe essere presente un campo o flag "dettagli" che contengono informazioni aggiuntive per consentire agli utenti di eseguire il debug delle applicazioni.

Esaminare un risultato di un elemento

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

Esaminare i risultati aggregati

Per i risultati aggregati su più esempi di dati (un set di dati), la frequenza media degli esempi con un "pass" costituisce la velocità di passaggio per tale set di dati.

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

Verifica la latenza del modello di destinazione e il costo stimato

Quando recuperi o elenchi le esecuzioni modello-destinazione completate, queste possono includere la latenza del target per l’intera esecuzione in latency.target e il costo di inferenza stimato in estimated_cost.target.

Entrambe le proprietà sono facoltative. Il servizio omette la latenza quando nessuna riga di valutazione ha una misurazione della latenza di destinazione utilizzabile. Omette il costo stimato quando l'esecuzione non è una valutazione rispetto a un modello di destinazione o quando non è possibile determinare il prezzo di alcun modello di destinazione. Il costo stimato è attualmente disponibile per le distribuzioni di modelli Standard globali quando l'esecuzione dispone dei dati di attribuzione e prezzi dei token di destinazione utilizzabili.

L'esempio seguente mostra la parte rilevante di un'esecuzione di valutazione completata:

{
  "latency": {
    "target": {
      "p50_ms": 812.25,
      "p95_ms": 2400.5,
      "sample_count": 47
    }
  },
  "estimated_cost": {
    "target": {
      "estimated_cost": 0.012346,
      "currency": "USD",
      "completeness": "partial",
      "pricing_version": "rate-card-version",
      "model_costs": [
        {
          "model_name": "gpt-5-mini",
          "estimated_cost": 0.012346,
          "prompt_tokens": 12000,
          "cached_tokens": 2000,
          "completion_tokens": 3000
        }
      ],
      "unpriced_models": [
        "unpriced-model"
      ]
    }
  }
}

I campi di latenza hanno i significati seguenti:

Campo Descrizione
p50_ms Latenza di destinazione end-to-end mediano, espressa in millisecondi. Il valore può includere millisecondi frazionari.
p95_ms Latenza di destinazione end-to-end del 95° percentile, in millisecondi. Il valore può includere millisecondi frazionari.
sample_count Numero di righe di valutazione che hanno contribuito a una misurazione della latenza di destinazione utilizzabile.

I campi dei costi stimati hanno i significati seguenti:

Campo Descrizione
estimated_cost Costo totale stimato dell'inferenza per i modelli di destinazione per i quali il servizio potrebbe calcolare un prezzo.
currency Codice valuta ISO 4217 per la stima.
completeness complete quando tutti i modelli di destinazione con attributi sono stati prezzi o partial quando almeno un modello non può essere costoso.
pricing_version Identificatore facoltativo per l'istantanea del listino prezzi utilizzata per la stima.
model_costs Suddivisione dei costi e del consumo di token per ciascun modello target a pagamento.
unpriced_models Elenco facoltativo di modelli di destinazione per cui non è disponibile alcun prezzo affidabile.

Ogni voce in model_costs contiene il supporto model_name, il relativo estimated_cost, l'input prompt_tokens non memorizzato in cache, cached_tokens e l'output completion_tokens. Per una distribuzione diretta, model_name è il modello di supporto risolto dai metadati della distribuzione. Per una destinazione model-router, il dettaglio identifica i modelli attribuiti dal runtime.

Quando completeness è partial, il costo complessivo e model_costs includono solo i modelli per i quali il servizio è stato in grado di determinare il prezzo. Controllare unpriced_models prima di usare la stima per confrontare le esecuzioni.

Estrarre la latenza e costi stimati

Dopo che l'esecuzione della valutazione è terminata ed è disponibile in run, converti la risposta dell'SDK in un dizionario e controlla la latenza target facoltativa:

run_data = run.to_dict()

target_latency = (run_data.get("latency") or {}).get("target")
if not target_latency:
    print("Target latency wasn't reported.")
else:
    p50_ms = target_latency.get("p50_ms")
    p95_ms = target_latency.get("p95_ms")
    sample_count = target_latency.get("sample_count", 0)
    if p50_ms is None or p95_ms is None:
        print("Target latency percentiles weren't reported.")
    else:
        print(
            f"Target latency: p50={p50_ms:,.2f} ms, "
            f"p95={p95_ms:,.2f} ms ({sample_count:,} samples)"
        )

Controlla il totale stimato per i modelli di destinazione per cui il servizio potrebbe calcolare un prezzo:

run_data = run.to_dict()
target_cost = (run_data.get("estimated_cost") or {}).get("target")
if not target_cost:
    print("Estimated target cost wasn't reported.")
else:
    currency = target_cost.get("currency", "USD")
    estimated_cost = target_cost.get("estimated_cost", 0)
    completeness = target_cost.get("completeness", "unknown")
    print(
        f"Estimated target cost: {estimated_cost:.6f} {currency} "
        f"({completeness})"
    )

Usa la ripartizione per modello per verificare l'attribuzione dei token e trovare i modelli a cui il servizio non ha potuto attribuire un prezzo:

run_data = run.to_dict()
target_cost = (run_data.get("estimated_cost") or {}).get("target")
if target_cost:
    currency = target_cost.get("currency", "USD")
    for model_cost in target_cost.get("model_costs") or []:
        prompt_tokens = model_cost.get("prompt_tokens", 0)
        cached_tokens = model_cost.get("cached_tokens", 0)
        completion_tokens = model_cost.get("completion_tokens", 0)
        total_tokens = prompt_tokens + cached_tokens + completion_tokens
        print(
            f"  {model_cost.get('model_name', 'unknown')}: "
            f"{model_cost.get('estimated_cost', 0):.6f} {currency}, "
            f"{total_tokens:,} tokens "
            f"({prompt_tokens:,} prompt, {cached_tokens:,} cached, "
            f"{completion_tokens:,} completion)"
        )

    unpriced_models = target_cost.get("unpriced_models") or []
    if unpriced_models:
        print(f"  Unpriced models: {', '.join(unpriced_models)}")

Per la risposta di esempio, l'output è simile al seguente:

Target latency: p50=812.25 ms, p95=2,400.50 ms (47 samples)
Estimated target cost: 0.012346 USD (partial)
  gpt-5-mini: 0.012346 USD, 17,000 tokens (12,000 prompt, 2,000 cached, 3,000 completion)
  Unpriced models: unpriced-model

La stima di primo livello è la somma delle voci in model_costs. Se completeness è partial, l'output identifica i modelli omessi in unpriced_models; non considerare la stima come il costo completo dell'esecuzione.

Importante

Il costo di destinazione è una stima basata sull'utilizzo dei token segnalati e sui prezzi di listino pubblicati. Sono esclusi l'utilizzo del modello di valutazione e i costi di runtime per la valutazione, e non si tiene conto dei prezzi negoziati, degli impegni contrattuali o degli sconti. Usa i dati di fatturazione di Azure per gli addebiti effettivi.

Annullare un'esecuzione

Annulla un'esecuzione che non è più necessaria:

openai_client.evals.runs.cancel(
    run_id=eval_run.id,
    eval_id=eval_object.id,
)

Risoluzione dei problemi di valutazione del cloud

Lavoro in esecuzione da molto tempo

Il processo di valutazione potrebbe rimanere nello stato In esecuzione per molto tempo. Questa condizione si verifica in genere quando la distribuzione del modello OpenAI Azure non dispone di capacità sufficiente, quindi il servizio ritenta le richieste.

Risoluzione:

  1. Annullare il processo di valutazione corrente usando openai_client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Aumentare la capacità del modello nel portale di Azure.
  3. Eseguire di nuovo la valutazione.

Errori di autenticazione

Se viene visualizzato l'errore 401 Unauthorized o 403 Forbidden, verificare che:

  • Hai configurato correttamente il tuo DefaultAzureCredential. Se si usa interfaccia della riga di comando di Azure, eseguire az login.
  • Il tuo account ha il ruolo di Utente Foundry nel progetto Foundry. Per tutti i requisiti del ruolo di valutazione, vedere Configurare le autorizzazioni per i flussi di lavoro di valutazione.
  • L'URL dell'endpoint del progetto è corretto e include sia l'account che i nomi dei progetti.

Errori di formato dati

Se la valutazione fallisce a causa di un errore di mapping dello schema o dei dati:

  • Verificare che il file JSONL abbia un oggetto JSON valido per riga.
  • Verificare che i nomi dei campi in data_mapping corrispondano esattamente ai nomi dei campi nel file JSONL (con distinzione tra maiuscole e minuscole).
  • Verificare che item_schema le proprietà corrispondano ai campi nel set di dati.

Errore HTTP 400 quando si usa file_id con valutazioni di risposta dell'agente

Le valutazioni delle risposte dell'agente (azure_ai_responses) supportano solo i dati in linea attraverso file_content. Se si forniscono ID risposta usando file_id, la richiesta restituisce un 400 Bad Request errore.

Risoluzione: Passare a file_content e fornire gli ID di risposta inline.

Errori di limitazione della velocità

I livelli "Utente", "Abbonamento" e "Progetto" limitano il numero di esecuzioni della valutazione. Se si riceve una 429 Too Many Requests risposta:

  • Controllare l'intestazione retry-after nella risposta per il tempo di attesa consigliato.
  • Esaminare il corpo della risposta per dettagli sulle limitazioni della velocità di risposta.
  • Usare il backoff esponenziale quando si ritentano richieste non riuscite.

Se un processo di valutazione fallisce a causa di un errore 429 durante l'esecuzione:

  • Ridurre le dimensioni del set di dati di valutazione o suddividerlo in batch più piccoli.
  • Aumenta la quota di token per minuto (TPM) per la distribuzione del modello nel portale di Azure.

Errori dello strumento di valutazione dell'agente

Se un valutatore agente restituisce un errore a causa degli strumenti non supportati:

  • Verifica gli strumenti supportati per i valutatori di agenti.
  • Come soluzione alternativa, incapsulare gli strumenti non supportati come funzioni definite dall'utente in modo che l'analizzatore possa valutarli.