Condividi tramite

Introduzione alle distribuzioni batch di Azure OpenAI

L'API Batch OpenAI di Azure è progettata per gestire in modo efficiente le attività di elaborazione su larga scala e con grandi volumi. Elabora gruppi asincroni di richieste con quota separata, con obiettivo di evasione di 24 ore, a un costo inferiore del 50% rispetto allo standard globale. Con l'elaborazione in batch, anziché inviare una richiesta alla volta si inviano diverse richieste in un singolo file. Le richieste in batch globale hanno una quota di token accodata separata evitando eventuali interruzioni dei carichi di lavoro online.

I principali casi d'uso sono:

  • Elaborazione dei dati su larga scala: analizzare rapidamente grandi set di dati in parallelo.

  • Generazione di contenuti: creare grandi volumi di testo, ad esempio descrizioni di prodotti o articoli.

  • Revisione e riepilogo dei documenti: automatizzare la revisione e il riepilogo dei documenti lunghi.

  • Automazione del supporto tecnico per i clienti: gestire contemporaneamente numerose query per risposte più veloci.

  • Estrazione e analisi dei dati: estrarre e analizzare informazioni da grandi quantità di dati non strutturati.

  • Attività di elaborazione del linguaggio naturale (NLP): eseguire attività come l'analisi o la traduzione del sentiment su set di dati di grandi dimensioni.

  • Marketing e personalizzazione: generare contenuti e consigli personalizzati su larga scala.

Suggerimento

Se i processi batch sono così grandi che si raggiunge il limite di token accodato anche dopo aver esaurito la quota per la distribuzione, alcune regioni ora supportano una nuova funzionalità che consente di accodare più processi batch con un meccanismo di backoff esponenziale.

Quando la quota del token accodato è disponibile, è possibile creare e avviare automaticamente il prossimo processo batch. Per altre informazioni, vedere Automazione dei nuovi tentativi dei processi batch di grandi dimensioni con backoff esponenziale.

Importante

L'obiettivo è elaborare le richieste batch entro 24 ore; non scadono i processi che richiedono più tempo. È possibile annullare il processo in qualsiasi momento. Quando si annulla l'incarico, ogni lavoro rimanente viene annullato e il lavoro già completato viene restituito. Verranno addebitati dei costi per qualsiasi lavoro completato.

I dati archiviati a riposo rimangono nell'area geografica di Azure designata, mentre i dati possono essere elaborati per inferenze in qualsiasi posizione Azure OpenAI. Altre informazioni sulla residenza dei dati. 

Supporto batch

Disponibilità del modello batch globale

Regione o3, 2025-04-16 o4-mini, 2025-04-16 gpt-4.1, 2025-04-14 gpt-4.1-nano, 2025-04-14 gpt-4.1-mini, 2025-04-14 o3-mini, 2025-01-31 gpt-4o, 2024-05-13 gpt-4o, 2024-08-06 gpt-4o, 2024-11-20 gpt-4o-mini, 2024-07-18
australiaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Brasile meridionale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Canada Orientale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
francecentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Germania Ovest Centrale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
japaneast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
coreacentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Northcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Norvegia Est ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Polonia Centrale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Sudafrica Nord ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Southcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
India del Sud ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
SveziaCentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Svizzera settentrionale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Europa occidentale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

La registrazione è necessaria per l'accesso a o3-mini. Per altre informazioni, vedere la guida ai modelli di ragionamento.

I modelli seguenti supportano il batch globale:

Modello Versione Formato di input
o3-mini 31-01-2025 testo
gpt-4o 2024-08-06 Text/Image
gpt-4o-mini 18-07-2024 Text/Image
gpt-4o 13-05-2024 Text/Image

Supporto dell'API

Versione dell'API
Versione più recente dell'API GA: 2024-10-21
Versione più recente dell'API di anteprima supportata: 2025-04-01-preview

Nota

Sebbene Global Batch supporti le versioni precedenti dell'API, alcuni modelli richiedono versioni api di anteprima più recenti. Ad esempio, o3-mini non è supportato con 2024-10-21 perché è stato rilasciato dopo questa data. Per accedere ai modelli più recenti con batch globale, usare la versione più recente dell'API di anteprima.

Supporto delle funzionalità

Al momento non sono supportati gli elementi seguenti:

  • Integrazione con l'API Assistants.
  • Integrazione con la funzionalità Azure OpenAI sui tuoi dati.

Implementazione per lotti

Nota

Nel portale di Azure AI Foundry i tipi di distribuzione batch verranno visualizzati come Global-Batch e Data Zone Batch. Per altre informazioni sui tipi di distribuzione OpenAI di Azure, vedere la guida ai tipi di distribuzione.

Screenshot che mostra la finestra di dialogo di distribuzione del modello nel portale di Azure AI Foundry con il tipo di distribuzione Global-Batch evidenziato.

Suggerimento

Si consiglia di abilitare la quota dinamica per tutte le distribuzioni di modelli batch globali, al fine di evitare errori dei processi dovuti a una quota insufficiente di token accodati. L'uso della quota dinamica consente alla distribuzione di sfruttare in modo opportunistico un maggior numero di quote quando è disponibile capacità aggiuntiva. Quando la quota dinamica è disattivata, la distribuzione sarà in grado di elaborare solo le richieste fino al limite di token accodato definito al momento della creazione della distribuzione.

Prerequisiti

Preparazione del file batch

Analogamente all'ottimizzazione, il batch globale usa file in formato di righe JSON (.jsonl). Di seguito sono riportati alcuni file di esempio con diversi tipi di contenuto supportato:

Formato di input

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id è necessario per consentire di identificare la singola richiesta in batch corrispondente a una determinata risposta. Le risposte non verranno restituite in modo identico all'ordine definito nel file batch .jsonl.

L'attributo model deve essere impostato in modo da corrispondere al nome della distribuzione di batch globale da impostare come destinazione per le risposte di inferenza.

Importante

L'attributo model deve essere impostato in modo da corrispondere al nome della distribuzione batch globale che si desidera specificare come destinazione per le risposte di inferenza. Lo stesso nome di distribuzione del modello batch globale deve essere presente in ogni riga del file batch. Se si desidera specificare come destinazione una distribuzione diversa, è necessario eseguire questa operazione in un file/processo batch separato.

Per ottenere prestazioni ottimali, è consigliabile inviare file di grandi dimensioni per l'elaborazione batch, anziché un numero elevato di file di piccole dimensioni con poche righe in ogni file.

Creare un file di input

Per questo articolo verrà creato un file denominato test.jsonl e il contenuto sarà copiato dal blocco di codice di input standard precedente nel file. È necessario modificare e aggiungere il nome della distribuzione in batch globale a ogni riga del file.

Caricamento file batch

Dopo aver preparato il file di input, è prima necessario caricare il file per poter avviare un processo batch. Il caricamento dei file può essere eseguito sia a livello di codice che tramite il portale di Azure AI Foundry. Questo esempio illustra il caricamento di un file direttamente nella risorsa OpenAI di Azure. In alternativa, è possibile configurare Archiviazione BLOB di Azure per Azure OpenAI Batch.

  1. Accedere al portale di Azure AI Foundry.

  2. Selezionare la risorsa OpenAI di Azure in cui è disponibile una distribuzione globale del modello batch.

  3. Selezionare Processi in batch>+Crea processi in batch.

    Screenshot che mostra l'esperienza di creazione di processi batch nel portale di Azure AI Foundry.

  4. Nell'elenco a discesa in Dati batch>Carica file> selezionare Carica file e specificare il percorso del file test.jsonl creato nel passaggio precedente >Avanti.

    Screenshot che mostra l'esperienza di caricamento del file.

Creare un processo in batch

Selezionare Crea per avviare il processo in batch.

Screenshot dell'esperienza di creazione di un processo batch nel portale di Azure AI Foundry.

Tracciare l'avanzamento del processo batch

Dopo aver creato il processo è possibile monitorarne lo stato di avanzamento selezionando l'ID del processo creato più di recente. Per impostazione predefinita verrà visualizzata la pagina di stato del processo in batch creato più di recente.

Screenshot che mostra l'ID del processo in batch per un processo attualmente in fase di convalida.

È possibile tenere traccia dello stato del lavoro nel riquadro a destra.

Schermata che mostra lo stato del processo batch nel portale di Azure AI Foundry.

Recuperare il file di output del processo batch

Una volta completato o raggiunto lo stato conclusivo, il processo genererà un file di errore e un file di output che si possono scaricare per la revisione selezionando il rispettivo pulsante con l'icona della freccia verso il basso.

Screenshot che mostra l'output del processo in batch e i file di errore disponibili per il download.

Annullare un batch

Annullare un batch in corso. Il batch rimane in stato cancelling per un massimo di 10 minuti, prima di passare a cancelled, dove avrà risultati parziali (se presenti) disponibili nel file di output.

Screenshot che mostra il pulsante di annullamento del processo batch nel portale di Azure AI Foundry.

Prerequisiti

I passaggi descritti in questo articolo devono essere eseguiti in sequenza nei notebook di Jupyter. Verrà quindi creata un'istanza del client OpenAI di Azure una sola volta all'inizio degli esempi. Se si vuole eseguire un'istruzione non ordinata è spesso necessario configurare un client OpenAI di Azure nel corso di tale chiamata.

Anche se è già installata la libreria Python OpenAI, potrebbe essere necessario aggiornare l'installazione alla versione più recente:

!pip install openai --upgrade

Preparazione del file batch

Analogamente all'ottimizzazione, il batch globale usa file in formato di righe JSON (.jsonl). Di seguito sono riportati alcuni file di esempio con diversi tipi di contenuto supportato:

Formato di input

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id è necessario per consentire di identificare la singola richiesta in batch corrispondente a una determinata risposta. Le risposte non verranno restituite in modo identico all'ordine definito nel file batch .jsonl.

L'attributo model deve essere impostato in modo da corrispondere al nome della distribuzione di batch globale da impostare come destinazione per le risposte di inferenza.

Importante

L'attributo model deve essere impostato in modo da corrispondere al nome della distribuzione batch globale che si desidera specificare come destinazione per le risposte di inferenza. Lo stesso nome di distribuzione del modello batch globale deve essere presente in ogni riga del file batch. Se si desidera specificare come destinazione una distribuzione diversa, è necessario eseguire questa operazione in un file/processo batch separato.

Per ottenere prestazioni ottimali, è consigliabile inviare file di grandi dimensioni per l'elaborazione batch, anziché un numero elevato di file di piccole dimensioni con poche righe in ogni file.

Creare un file di input

Per questo articolo verrà creato un file denominato test.jsonl e il contenuto sarà copiato dal blocco di codice di input standard precedente nel file. È necessario modificare e aggiungere il nome della distribuzione in batch globale a ogni riga del file. Salvare questo file nella stessa directory in cui si sta eseguendo il notebook di Jupyter.

Caricamento file batch

Dopo aver preparato il file di input, è prima necessario caricare il file per poter avviare un processo batch. Il caricamento dei file può essere eseguito sia a livello di codice che tramite il portale di Azure AI Foundry. Questo esempio illustra il caricamento di un file direttamente nella risorsa OpenAI di Azure. In alternativa, è possibile configurare Archiviazione BLOB di Azure per Azure OpenAI Batch.

import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(
  azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"), 
  azure_ad_token_provider=token_provider,
  api_version="2025-04-01-preview"
)

# Upload a file with a purpose of "batch"
file = client.files.create(
  file=open("test.jsonl", "rb"), 
  purpose="batch",
  extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)


print(file.model_dump_json(indent=2))

print(f"File expiration: {datetime.fromtimestamp(file.expires_at) if file.expires_at is not None else 'Not set'}")

file_id = file.id

Rimuovendo il commento e aggiungendo extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}}, imposti il nostro file di caricamento per scadere in 14 giorni. È previsto un limite massimo di 500 file batch per risorsa quando non viene impostata alcuna scadenza. Impostando un valore per la scadenza, il numero di file batch per risorsa viene aumentato a 10.000 file per risorsa.

Prodotto:

{
  "id": "file-655111ec9cfc44489d9af078f08116ef",
  "bytes": 176064,
  "created_at": 1743391067,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "expires_at": 1744600667,
  "status_details": null
}
File expiration: 2025-04-13 23:17:47

Creare un processo in batch

Dopo aver caricato correttamente il file, è possibile inviare il file per l'elaborazione batch.

# Submit a batch job with the file
batch_response = client.batches.create(
    input_file_id=file_id,
    endpoint="/chat/completions",
    completion_window="24h",
    extra_body={"output_expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)


# Save batch ID for later use
batch_id = batch_response.id

print(batch_response.model_dump_json(indent=2))

Il limite predefinito di 500 file per risorsa si applica anche ai file di output. Puoi rimuovere il commento da questa riga per aggiungere extra_body={"output_expires_after":{"seconds": 1209600, "anchor": "created_at"}} in modo che i file di output scadano in 14 giorni. Impostando un valore per la scadenza, il numero di file batch per risorsa viene aumentato a 10.000 file per risorsa.

Nota

Attualmente la finestra di completamento deve essere impostata su 24h. Se si imposta un valore diverso da 24h, l'operazione avrà esito negativo. I processi che richiedono più di 24 ore continueranno a essere eseguiti fino all'annullamento.

Prodotto:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-655111ec9cfc44489d9af078f08116ef",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": null,
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": null,
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

Se i processi batch sono così grandi che si raggiunge il limite di token accodati anche dopo aver esaurito la quota per la distribuzione, determinate aree ora supportano una nuova funzionalità per il fallimento e risposta immediata agli errori che consente di accodare più processi batch con un meccanismo di backoff esponenziale, in modo che al completamento di un processo batch grande quello successivo può essere avviato automaticamente. Per altre informazioni sulle aree che supportano questa funzionalità e su come adattare il codice per sfruttarne i vantaggi, vedere Accodamento di processi batch.

Tracciare l'avanzamento del processo batch

Dopo aver creato correttamente il processo batch, è possibile monitorarne lo stato di avanzamento in Studio o a livello di codice. Quando si controlla lo stato del processo in batch, è consigliabile attendere almeno 60 secondi tra ogni chiamata di stato.

import time
import datetime 

status = "validating"
while status not in ("completed", "failed", "canceled"):
    time.sleep(60)
    batch_response = client.batches.retrieve(batch_id)
    status = batch_response.status
    print(f"{datetime.datetime.now()} Batch Id: {batch_id},  Status: {status}")

if batch_response.status == "failed":
    for error in batch_response.errors.data:  
        print(f"Error code {error.code} Message {error.message}")

Prodotto:

2024-07-31 21:48:32.556488 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: validating
2024-07-31 21:49:39.221560 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:50:53.383138 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:52:07.274570 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:53:21.149501 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:54:34.572508 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:55:35.304713 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:56:36.531816 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:57:37.414105 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: completed

Sono possibili i valori di stato seguenti:

Stato Descrizione
validating Il file di input viene convalidato prima che l'elaborazione in batch possa iniziare.
failed Il file di input non ha superato il processo di convalida.
in_progress Il file di input è stato convalidato correttamente e il batch è attualmente in esecuzione.
finalizing Il batch è stato completato e i risultati vengono preparati.
completed Il batch è stato completato e i risultati sono pronti.
expired Il batch non è stato completato entro l'intervallo di 24 ore.
cancelling Il batch è in fase di cancelled (potrebbe richiedere fino a 10 minuti).
cancelled Il batch è cancelled.

Per esaminare i dettagli dello stato del lavoro, puoi eseguire:

print(batch_response.model_dump_json(indent=2))

Prodotto:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "object": "batch",
  "status": "completed",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": 1722477429,
  "error_file_id": "file-c795ae52-3ba7-417d-86ec-07eebca57d0b",
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": 1722477177,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "file-3304e310-3b39-4e34-9f1c-e1c1504b2b2a",
  "request_counts": {
    "completed": 3,
    "failed": 0,
    "total": 3
  }
}

Tenere presente che sono presenti sia error_file_id che un output_file_id separato. Usare error_file_id per facilitare il debug di eventuali problemi che si verificano con il processo in batch.

Recuperare il file di output del processo batch

import json

output_file_id = batch_response.output_file_id

if not output_file_id:
    output_file_id = batch_response.error_file_id

if output_file_id:
    file_response = client.files.content(output_file_id)
    raw_responses = file_response.text.strip().split('\n')  

    for raw_response in raw_responses:  
        json_response = json.loads(raw_response)  
        formatted_json = json.dumps(json_response, indent=2)  
        print(formatted_json)

Prodotto:

Per brevità viene inclusa solo una singola risposta di completamento della chat dell'output. Se si seguono i passaggi descritti in questo articolo si dovrebbero avere tre risposte simili a quella seguente:

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "choices": [
        {
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          },
          "finish_reason": "stop",
          "index": 0,
          "logprobs": null,
          "message": {
            "content": "Microsoft was founded on April 4, 1975, by Bill Gates and Paul Allen in Albuquerque, New Mexico.",
            "role": "assistant"
          }
        }
      ],
      "created": 1722477079,
      "id": "chatcmpl-9rFGJ9dh08Tw9WRKqaEHwrkqRa4DJ",
      "model": "gpt-4o-2024-05-13",
      "object": "chat.completion",
      "prompt_filter_results": [
        {
          "prompt_index": 0,
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "jailbreak": {
              "filtered": false,
              "detected": false
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          }
        }
      ],
      "system_fingerprint": "fp_a9bfe9d51d",
      "usage": {
        "completion_tokens": 24,
        "prompt_tokens": 27,
        "total_tokens": 51
      }
    },
    "request_id": "660b7424-b648-4b67-addc-862ba067d442",
    "status_code": 200
  },
  "error": null
}

Comandi batch aggiuntivi

Annullare un batch

Annullare un batch in corso. Il batch rimane in stato cancelling per un massimo di 10 minuti, prima di passare a cancelled, dove avrà risultati parziali (se presenti) disponibili nel file di output.

client.batches.cancel("batch_abc123") # set to your batch_id for the job you want to cancel

Elenco dei batch

Elencare i processi batch per una determinata risorsa OpenAI di Azure.

client.batches.list()

I metodi della lista nella libreria Python sono suddivisi in pagine.

Per elencare tutte le attività:

all_jobs = []
# Automatically fetches more pages as needed.
for job in client.batches.list(
    limit=20,
):
    # Do something with job here
    all_jobs.append(job)
print(all_jobs)

Elenco batch (anteprima)

Usare l'API REST per elencare tutti i processi batch con opzioni di ordinamento/filtro aggiuntive.

Negli esempi seguenti viene offerta la generate_time_filter funzione per semplificare la costruzione del filtro. Se non si vuole usare questa funzione, il formato della stringa di filtro sarà simile a created_at gt 1728860560 and status eq 'Completed'.

import requests
import json
from datetime import datetime, timedelta
from azure.identity import DefaultAzureCredential

token_credential = DefaultAzureCredential()
token = token_credential.get_token('https://cognitiveservices.azure.com/.default')

endpoint = "https://{YOUR_RESOURCE_NAME}.openai.azure.com/"
api_version = "2025-03-01-preview"
url = f"{endpoint}openai/batches"
order = "created_at asc"
time_filter =  lambda: generate_time_filter("past 8 hours")

# Additional filter examples:
#time_filter =  lambda: generate_time_filter("past 1 day")
#time_filter =  lambda: generate_time_filter("past 3 days", status="Completed")

def generate_time_filter(time_range, status=None):
    now = datetime.now()
    
    if 'day' in time_range:
        days = int(time_range.split()[1])
        start_time = now - timedelta(days=days)
    elif 'hour' in time_range:
        hours = int(time_range.split()[1])
        start_time = now - timedelta(hours=hours)
    else:
        raise ValueError("Invalid time range format. Use 'past X day(s)' or 'past X hour(s)'")
    
    start_timestamp = int(start_time.timestamp())
    
    filter_string = f"created_at gt {start_timestamp}"
    
    if status:
        filter_string += f" and status eq '{status}'"
    
    return filter_string

filter = time_filter()

headers = {'Authorization': 'Bearer ' + token.token}

params = {
    "api-version": api_version,
    "$filter": filter,
    "$orderby": order
}

response = requests.get(url, headers=headers, params=params)

json_data = response.json()

if response.status_code == 200:
    print(json.dumps(json_data, indent=2))
else:
    print(f"Request failed with status code: {response.status_code}")
    print(response.text)

Prodotto:

{
  "data": [
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729011896,
      "completion_window": "24h",
      "created_at": 1729011128,
      "error_file_id": "file-472c0626-4561-4327-9e4e-f41afbfb30e6",
      "expired_at": null,
      "expires_at": 1729097528,
      "failed_at": null,
      "finalizing_at": 1729011805,
      "id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
      "in_progress_at": 1729011493,
      "input_file_id": "file-f89384af0082485da43cb26b49dc25ce",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-62bebde8-e767-4cd3-a0a1-28b214dc8974",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    },
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729016366,
      "completion_window": "24h",
      "created_at": 1729015829,
      "error_file_id": "file-85ae1971-9957-4511-9eb4-4cc9f708b904",
      "expired_at": null,
      "expires_at": 1729102229,
      "failed_at": null,
      "finalizing_at": 1729016272,
      "id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43",
      "in_progress_at": 1729016126,
      "input_file_id": "file-686746fcb6bc47f495250191ffa8a28e",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-04399828-ae0b-4825-9b49-8976778918cb",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    }
  ],
  "first_id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
  "has_more": false,
  "last_id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43"
}

Accodamento dei processi batch

Se i processi batch sono così grandi che si raggiunge il limite di token accodato anche dopo aver esaurito la quota per la distribuzione, alcune regioni ora supportano una nuova funzionalità per il fallimento e la risposta immediata agli errori che consente di accodare più processi batch con un meccanismo di backoff esponenziale. Una volta completato un processo batch di grandi dimensioni e la quota di token accodati è nuovamente disponibile, è possibile creare e avviare automaticamente il processo batch successivo.

Comportamento precedente:

  1. Processo batch di grandi dimensioni già in esecuzione e uso di tutti i token disponibili per la distribuzione.
  2. Nuovo processo batch inviato.
  3. Il nuovo processo batch entra nella fase di convalida, che può durare anche alcuni minuti.
  4. Il conteggio dei token per il nuovo processo viene verificato rispetto alla quota attualmente disponibile.
  5. Il nuovo processo batch non riesce con un errore che segnala il superamento del limite di token.

Nuovo comportamento:

  1. Processo batch di grandi dimensioni già in esecuzione e uso di tutti i token disponibili per la distribuzione
  2. Nuovo processo batch inviato
  3. Il conteggio approssimativo dei token del nuovo processo viene immediatamente confrontato con la quota batch attualmente disponibile; il processo fallisce e risponde immediatamente agli errori, consentendo di gestire con maggiore facilità i tentativi di ripetizione a livello di codice.

Supporto di area

Le seguenti regioni supportano il nuovo comportamento di fallimento e risposta immediata agli errori:

  • australiaeast
  • eastus
  • Germania Ovest Centrale
  • italynorth
  • Northcentralus
  • Polonia Centrale
  • SveziaCentral
  • Svizzera settentrionale
  • eastus2
  • westus

Il codice seguente illustra i meccanismi di base per gestire il comportamento di fallimento e risposta immediata agli errori per consentire l'automazione dei nuovi tentativi e l'accodamento di processi batch con backoff esponenziale.

A seconda delle dimensioni dei processi batch, potrebbe essere necessario aumentare notevolmente il max_retries e modificare ulteriormente questo esempio.

import time
from openai import BadRequestError

max_retries = 10
retries = 0
initial_delay = 5
delay = initial_delay

while True:
    try:
        batch_response = client.batches.create(
            input_file_id=file_id,
            endpoint="/chat/completions",
            completion_window="24h",
        )
        
        # Save batch ID for later use
        batch_id = batch_response.id
        
        print(f"✅ Batch created successfully after {retries} retries")
        print(batch_response.model_dump_json(indent=2))
        break  
        
    except BadRequestError as e:
        error_message = str(e)
        
        # Check if it's a token limit error
        if 'token_limit_exceeded' in error_message:
            retries += 1
            if retries >= max_retries:
                print(f"❌ Maximum retries ({max_retries}) reached. Giving up.")
                raise
            
            print(f"⏳ Token limit exceeded. Waiting {delay} seconds before retry {retries}/{max_retries}...")
            time.sleep(delay)
            
            # Exponential backoff - increase delay for next attempt
            delay *= 2
        else:
            # If it's a different error, raise it immediately
            print(f"❌ Encountered non-token limit error: {error_message}")
            raise

Prodotto:

⏳ Token limit exceeded. Waiting 5 seconds before retry 1/10...
⏳ Token limit exceeded. Waiting 10 seconds before retry 2/10...
⏳ Token limit exceeded. Waiting 20 seconds before retry 3/10...
⏳ Token limit exceeded. Waiting 40 seconds before retry 4/10...
⏳ Token limit exceeded. Waiting 80 seconds before retry 5/10...
⏳ Token limit exceeded. Waiting 160 seconds before retry 6/10...
⏳ Token limit exceeded. Waiting 320 seconds before retry 7/10...
✅ Batch created successfully after 7 retries
{
  "id": "batch_1e1e7b9f-d4b4-41fa-bd2e-8d2ec50fb8cc",
  "completion_window": "24h",
  "created_at": 1744402048,
  "endpoint": "/chat/completions",
  "input_file_id": "file-e2ba4ccaa4a348e0976c6fe3c018ea92",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": "",
  "errors": null,
  "expired_at": null,
  "expires_at": 1744488444,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

Prerequisiti

Preparazione del file batch

Analogamente all'ottimizzazione, il batch globale usa file in formato di righe JSON (.jsonl). Di seguito sono riportati alcuni file di esempio con diversi tipi di contenuto supportato:

Formato di input

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id è necessario per consentire di identificare la singola richiesta in batch corrispondente a una determinata risposta. Le risposte non verranno restituite in modo identico all'ordine definito nel file batch .jsonl.

L'attributo model deve essere impostato in modo da corrispondere al nome della distribuzione di batch globale da impostare come destinazione per le risposte di inferenza.

Importante

L'attributo model deve essere impostato in modo da corrispondere al nome della distribuzione batch globale che si desidera specificare come destinazione per le risposte di inferenza. Lo stesso nome di distribuzione del modello batch globale deve essere presente in ogni riga del file batch. Se si desidera specificare come destinazione una distribuzione diversa, è necessario eseguire questa operazione in un file/processo batch separato.

Per ottenere prestazioni ottimali, è consigliabile inviare file di grandi dimensioni per l'elaborazione batch, anziché un numero elevato di file di piccole dimensioni con poche righe in ogni file.

Creare un file di input

Per questo articolo verrà creato un file denominato test.jsonl e il contenuto sarà copiato dal blocco di codice di input standard precedente nel file. È necessario modificare e aggiungere il nome della distribuzione in batch globale a ogni riga del file.

Caricamento file batch

Dopo aver preparato il file di input, è prima necessario caricare il file per poter avviare un processo batch. Il caricamento dei file può essere eseguito sia a livello di codice che tramite il portale di Azure AI Foundry. Questo esempio illustra il caricamento di un file direttamente nella risorsa OpenAI di Azure. In alternativa, è possibile configurare Archiviazione BLOB di Azure per Azure OpenAI Batch.

Importante

Usare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente. Se si usa una chiave API, archiviarla in modo sicuro in Azure Key Vault. Per altre informazioni sull'uso sicuro delle chiavi API nelle app, vedere Chiavi API con Azure Key Vault.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files?api-version=2025-03-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -F "purpose=batch" \
  -F "file=@C:\\batch\\test.jsonl;type=application/json" \
  -F "expires_after.seconds=1209600" \
  -F "expires_after.anchor=created_at"

Il codice precedente presuppone un percorso di file specifico per il file test.jsonl. Modificare il percorso del file in base alle esigenze per il sistema locale.

Aggiungendo i parametri facoltativi "expires_after.seconds=1209600" e "expires_after.anchor=created_at" impostando il file di caricamento per la scadenza tra 14 giorni. È previsto un limite massimo di 500 file batch per risorsa quando non viene impostata alcuna scadenza. Impostando un valore per la scadenza, il numero di file batch per risorsa viene aumentato a 10.000 file per risorsa. È possibile impostare su un numero compreso tra 1209600 e 2592000. Equivale a 14-30 giorni.

Prodotto:

{
  "status": "processed",
  "bytes": 817,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1743398147,
  "object": "file"
}

Tenere traccia dello stato di caricamento dei file

A seconda delle dimensioni del file da caricare potrebbe essere necessario un certo tempo prima che venga completamente caricato ed elaborato. Per controllare lo stato di caricamento del file:

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{file-id}?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Prodotto:

{
  "status": "processed",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1721408291,
  "object": "file"
}

Creare un processo in batch

Dopo aver caricato correttamente il file, è possibile inviare il file per l'elaborazione batch.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/chat/completions",
    "completion_window": "24h",
    "output_expires_after": {
        "seconds": 1209600
    },
    "anchor": "created_at"
  }'

Il limite predefinito di 500 file per risorsa si applica anche ai file di output. Qui è possibile aggiungere "output_expires_after":{"seconds": 1209600}, facoltativamente e "anchor": "created_at" in modo che i file di output scadano in 14 giorni. Impostando un valore per la scadenza, il numero di file batch per risorsa viene aumentato a 10.000 file per risorsa.

Nota

Attualmente la finestra di completamento deve essere impostata su 24h. Se si imposta un valore diverso da 24h, l'operazione avrà esito negativo. I processi che richiedono più di 24 ore continueranno a essere eseguiti fino all'annullamento.

Prodotto:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:13:57.2491382+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:13:57.1918498+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_fe3f047a-de39-4068-9008-346795bfc1db",
  "in_progress_at": null,
  "input_file_id": "file-21006e70789246658b86a1fc205899a4",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

Tracciare l'avanzamento del processo batch

Dopo aver creato correttamente il processo batch, è possibile monitorarne lo stato di avanzamento in Studio o a livello di codice. Quando si controlla lo stato del processo in batch, è consigliabile attendere almeno 60 secondi tra ogni chiamata di stato.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Prodotto:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:33:29.1619286+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:33:29.1578141+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_e0a7ee28-82c4-46a2-a3a0-c13b3c4e390b",
  "in_progress_at": null,
  "input_file_id": "file-c55ec4e859d54738a313d767718a2ac5",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

Sono possibili i valori di stato seguenti:

Stato Descrizione
validating Il file di input viene convalidato prima che l'elaborazione in batch possa iniziare.
failed Il file di input non ha superato il processo di convalida.
in_progress Il file di input è stato convalidato correttamente e il batch è attualmente in esecuzione.
finalizing Il batch è stato completato e i risultati vengono preparati.
completed Il batch è stato completato e i risultati sono pronti.
expired Il batch non è stato completato entro l'intervallo di 24 ore.
cancelling Il batch è in fase di cancelled (l'operazione può richiedere fino a 10 minuti).
cancelled Il batch è cancelled.

Recuperare il file di output del processo batch

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{output_file_id}/content?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" > batch_output.jsonl

Comandi batch aggiuntivi

Annullare un batch

Annullare un batch in corso. Il batch rimane in stato cancelling per un massimo di 10 minuti, prima di passare a cancelled, dove avrà risultati parziali (se presenti) disponibili nel file di output.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}/cancel?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Elenco dei batch

Elencare i processi batch esistenti per una determinata risorsa OpenAI di Azure.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

La chiamata API elenco è impaginata. La risposta contiene un valore booleano has_more che indica quando sono presenti più risultati da iterare.

Elenco batch (anteprima)

Usare l'API REST per elencare tutti i processi batch con opzioni di ordinamento/filtro aggiuntive.

curl "YOUR_RESOURCE_NAME.openai.azure.com/batches?api-version=2025-03-01-preview&$filter=created_at%20gt%201728773533%20and%20created_at%20lt%201729032733%20and%20status%20eq%20'Completed'&$orderby=created_at%20asc" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Per evitare che gli spazi di errore URL rejected: Malformed input to a URL function vengano sostituiti con %20.

Limiti batch

Nome limite Valore limite
Numero massimo di file per risorsa 500
Dimensioni massime del file di input 200 MB
Numero massimo di richieste per file 100,000

Quota batch

La tabella mostra il limite di quota per il batch. I valori delle quote per il batch globale sono rappresentati in termini di token accodati. Quando si invia un file per l'elaborazione in batch, viene conteggiato il numero di token presenti nel file. Fino a quando il processo batch raggiunge uno stato conclusivo, questi token verranno conteggiati rispetto al limite totale di token accodati.

Batch globale

Modello Contratto Enterprise Predefinito Abbonamento mensili con carta di credito Sottoscrizioni MSDN Microsoft Azure for Students, versioni di prova gratuite
gpt-4.1 5 B 200 milioni 50 milioni 90.000 N/D
gpt-4.1 mini 15B 1B 50M 90.000 N/D
gpt-4.1-nano 15 B 1 B 50 milioni 90.000 N/D
gpt-4o 5 B 200 milioni 50 milioni 90.000 N/D
gpt-4o-mini 15 B 1 B 50 milioni 90.000 N/D
gpt-4-turbo 300 milioni 80 milioni 40 M 90.000 N/D
gpt-4 150 M 30 M 5 milioni 100 K N/D
gpt-35-turbo 10 B 1 B 100 M 2 milioni 50 K
o3-mini 15 B 1 B 50 milioni 90.000 N/D
o4-mini 15 B 1 B 50 milioni 90.000 N/D

B = miliardi | M = milioni | K = migliaia

Batch zona dati

Modello Contratto Enterprise Predefinito Abbonamento mensili con carta di credito Sottoscrizioni MSDN Microsoft Azure for Students, versioni di prova gratuite
gpt-4.1 500 milioni 30 M 30 M 90.000 N/D
gpt-4.1-mini 1.5 B 100 M 50 milioni 90.000 N/D
gpt-4o 500 milioni 30 M 30 M 90.000 N/D
gpt-4o-mini 1.5 B 100 M 50 milioni 90.000 N/D
o3-mini 1.5 B 100 M 50 milioni 90.000 N/D

Oggetto batch

Proprietà Tipo Definizione
id string
object string batch
endpoint string L'endpoint API utilizzato dal batch
errors oggetto
input_file_id string ID del file di input per il batch
completion_window string Intervallo di tempo entro il quale deve essere elaborato il batch
status string Stato corrente del batch. Valori possibili: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled.
output_file_id string ID del file contenente gli output delle richieste eseguite correttamente.
error_file_id string ID del file contenente gli output delle richieste con errori.
created_at integer Data e ora di creazione di questo batch (in epoche Unix).
in_progress_at integer Timestamp di quando questo batch ha iniziato ad avanzare (in periodi Unix).
expires_at integer Timestamp di quando questo batch scadrà (in periodi Unix).
finalizing_at integer Timestamp di quando questo batch ha iniziato la fase di finalizzazione (in periodi Unix).
completed_at integer Timestamp di quando questo batch ha iniziato la fase di finalizzazione (in periodi Unix).
failed_at integer Timestamp di quando questo batch non è riuscito (in periodi Unix)
expired_at integer Timestamp di quando questo batch è scaduto (in periodi Unix).
cancelling_at integer Timestamp all'avvio di questo batch cancelling (in periodi Unix).
cancelled_at integer Timestamp quando questo batch è stato cancelled (in periodi Unix).
request_counts oggetto Struttura dell'oggetto:

totalinteger
Numero totale di richieste nel batch.
completedinteger
Numero di richieste nel batch completate correttamente.
failedinteger
Il numero di richieste nel batch che non sono riuscite.
metadata map Un insieme di coppie chiave-valore che possono essere associate al batch. Questa proprietà può essere utile per archiviare informazioni aggiuntive sul batch in un formato strutturato.

Domande frequenti

Le immagini possono essere usate con l'API del batch?

Questa funzionalità è limitata a determinati modelli multimodali. Attualmente solo GPT-4o supporta le immagini nelle richieste batch. Le immagini possono essere fornite come input tramite URL dell'immagine o una rappresentazione con codifica base64 dell'immagine. Le immagini per batch non sono attualmente supportate con GPT-4 Turbo.

È possibile usare l'API batch con modelli ottimizzati?

Non supportato attualmente.

È possibile usare l'API batch per i modelli di incorporamento?

Non supportato attualmente.

Il filtro del contenuto funziona con la distribuzione Global Batch?

Sì. Analogamente ad altri tipi di distribuzione, è possibile creare filtri di contenuto e associarli al tipo di distribuzione Global Batch.

È possibile richiedere una quota aggiuntiva?

Sì, dalla pagina delle quote nel portale di Azure AI Foundry. L'allocazione della quota predefinita è disponibile nell'articolo Quota e limiti.

Cosa accade se l'API non completa la richiesta entro l'intervallo di tempo di 24 ore?

Cerchiamo di elaborare queste richieste entro 24 ore; i processi che richiedono più tempo non scadono. È possibile annullare il processo in qualsiasi momento. Quando si annulla l'incarico, ogni lavoro rimanente viene annullato e il lavoro già completato viene restituito. Verranno addebitati dei costi per qualsiasi lavoro completato.

Quante richieste è possibile accodare usando batch?

Non esiste un limite fisso per il numero di richieste che è possibile inviare in batch, ma dipenderà dalla quota di token accodati. La quota di token accodati include il numero massimo di token di input che è possibile accodare contemporaneamente.

Al termine della richiesta batch, il limite di frequenza batch viene reimpostato, perché i token di input vengono cancellati. Il limite dipende dal numero di richieste globali nella coda. Se la coda dell'API Batch elabora rapidamente i batch, il limite di velocità batch viene reimpostato più rapidamente.

Risoluzione dei problemi

Un lavoro ha esito positivo quando status è Completed. I processi riusciti genereranno comunque un error_file_id, ma verranno associati a un file vuoto con zero byte.

Quando si verifica un errore nel processo, sono disponibili informazioni dettagliate sull'errore nella proprietà errors:

"value": [
        {
          "id": "batch_80f5ad38-e05b-49bf-b2d6-a799db8466da",
          "completion_window": "24h",
          "created_at": 1725419394,
          "endpoint": "/chat/completions",
          "input_file_id": "file-c2d9a7881c8a466285e6f76f6321a681",
          "object": "batch",
          "status": "failed",
          "cancelled_at": null,
          "cancelling_at": null,
          "completed_at": 1725419955,
          "error_file_id": "file-3b0f9beb-11ce-4796-bc31-d54e675f28fb",
          "errors": {
                "object": “list”,
                "data": [
                {
               "code": "empty_file",
               "message": "The input file is empty. Please ensure that the batch contains at least one   request."
                    }
                ]
          },
          "expired_at": null,
          "expires_at": 1725505794,
          "failed_at": null,
          "finalizing_at": 1725419710,
          "in_progress_at": 1725419572,
          "metadata": null,
          "output_file_id": "file-ef12af98-dbbc-4d27-8309-2df57feed572",

            "request_counts": {
                "total": 10,
                "completed": null,
                "failed": null
            },
        }

Codici di errore

Codice errore Definizione
invalid_json_line Una riga (o più) nel file di input non è stata analizzata come json valido.

Verificare che non siano presenti errori di digitazione, che ci siano parentesi di apertura e chiusura appropriate e virgolette in base allo standard JSON e inviare di nuovo la richiesta.
too_many_tasks Il numero di richieste nel file di input supera il valore massimo consentito di 100.000.

Verificare che le richieste totali siano minori di 100.000 e inviare di nuovo il processo.
url_mismatch Una riga nel file di input ha un URL che non corrisponde al resto delle righe oppure l'URL specificato nel file di input non corrisponde all'URL dell'endpoint previsto.

Verificare che tutti gli URL delle richieste siano uguali e che corrispondano all'URL dell'endpoint associato alla distribuzione di Azure OpenAI.
model_not_found Il nome della distribuzione del modello OpenAI di Azure specificato nella proprietà model del file di input non è stato trovato.

Verificare che questo nome punti a una distribuzione valida del modello OpenAI di Azure.
duplicate_custom_id L'ID personalizzato per questa richiesta è un duplicato dell'ID personalizzato in un'altra richiesta.
empty_batch Controllare il file di input per verificare che il parametro ID personalizzato sia univoco per ogni richiesta nel batch.
model_mismatch Il nome della distribuzione del modello OpenAI di Azure specificato nella proprietà model di questa richiesta nel file di input non corrisponde al resto del file.

Verificare che tutte le richieste nel punto batch corrispondano alla stessa distribuzione del modello di Azure OpenAI in Modelli di Fonderia Azure AI nella proprietà model della richiesta.
invalid_request Lo schema della riga di input non è valido o l'SKU di distribuzione non è valido.

Verificare che le proprietà della richiesta nel file di input corrispondano alle proprietà di input previste e che l'SKU di distribuzione di OpenAI di Azure sia globalbatch per le richieste API batch.
input_modified L'input del BLOB è stato modificato dopo l'invio del processo batch.
input_no_permissions Non è possibile accedere al BLOB di input. Controllare le autorizzazioni e l'accesso alla rete tra l'account OpenAI di Azure e l'account di archiviazione di Azure.

Problemi noti

  • Le risorse distribuite con l'interfaccia della riga di comando di Azure non funzionano in modo predefinito con il batch globale di Azure OpenAI. È dovuto a un problema a causa del quale le risorse distribuite con questo metodo hanno sottodomini endpoint che non seguono il modello di https://your-resource-name.openai.azure.com. Una soluzione alternativa per questo problema consiste nel distribuire una nuova risorsa OpenAI di Azure usando uno degli altri metodi di distribuzione comuni che gestiranno correttamente l'installazione del sottodominio nel corso del processo di distribuzione.

  • I file con jsonl codifica UTF-8-BOM non sono supportati. I file di righe JSON devono essere codificati con UTF-8. L'uso di file codificati Byte-Order-Mark (BOM) non è ufficialmente supportato dalla specifica RFC JSON e Azure OpenAI attualmente considererà i file codificati BOM come non validi. Un file con codifica UTF-8-BOM restituirà attualmente il messaggio di errore generico: "Convalida non riuscita: non è stato possibile estrarre un nome di distribuzione del modello valido dal file di input. Assicurarsi che ogni riga nel file di input abbia un nome di distribuzione valido specificato nel campo "modello" e che il nome della distribuzione sia coerente in tutte le righe".

Vedi anche