Introduzione alle distribuzioni batch di Azure OpenAI

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

I casi d'uso principali includono:

  • Elaborazione dati su larga scala: Analizzare rapidamente set di dati estesi in parallelo.

  • Generazione di contenuti: Creare volumi elevati 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: Gestire contemporaneamente numerose query per risposte più veloci.

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

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

  • Marketing e personalizzazione: Generare contenuti e raccomandazioni personalizzati su larga scala.

Suggerimento

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

Quando la quota di token accodati è disponibile, è possibile creare e avviare automaticamente il job batch successivo. Per altre informazioni, vedere Automazione dei tentativi di 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'attività, qualsiasi lavoro rimanente viene annullato e qualsiasi lavoro già completato viene restituito. Verrà addebitato qualsiasi lavoro completato.

I dati conservati a riposo rimangono nella geografia Azure designata, mentre possono essere elaborati, anche per l'inferenza, in qualsiasi sito Azure OpenAI.  Altre informazioni sulla residenza dei dati. 

Supporto batch

Disponibilità del modello batch globale

Regione gpt-5.1, 2025-11-13 gpt-5, 2025-08-07 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 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
brasilesouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Canada orientale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
centralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
francecentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
germania ovest centrale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
japaneast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
koreacentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
northcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
norvegiaest ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
poloniacentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southafricanorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southindia ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Swedencentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
SvizzeraNorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westeurope ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

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

Nota

Sebbene Global Batch supporti le versioni precedenti dell'API, alcuni modelli richiedono versioni api 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 Global Batch, usare l'API v1.

Supporto delle funzionalità

Al momento non sono supportati gli elementi seguenti:

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

Distribuzione in batch

Nota

Nel portale Microsoft foundry i tipi di distribuzione batch vengono visualizzati come Global-Batch e Data Zone Batch. Per altre informazioni sui tipi di distribuzione OpenAI Azure, vedere la guida deployment types.

Suggerimento

È consigliabile abilitare la quota dinamica per tutte le distribuzioni di modelli batch globali per evitare errori di processo a causa di una quota di token accodata insufficiente. 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

  • Sottoscrizione di Azure : Crearne una gratuitamente.
  • Risorsa con un modello del tipo di distribuzione GlobalBatch oppure distribuito DataZoneBatch.

Preparazione del file batch

Come l'ottimizzazione, batch 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

Risposte API

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

API di completamento della chat

{"custom_id": "task-0", "method": "POST", "url": "/v1/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": "/v1/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": "/v1/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 batch corrispondente a una determinata risposta. Le risposte non verranno restituite in modo identico all'ordine definito nel .jsonl file batch.

model L'attributo deve essere impostato in modo che corrisponda al nome dell'implementazione di Batch globale che desideri destinare per le risposte di inferenza.

Importante

L'attributo model deve essere impostato in modo che corrisponda al nome della distribuzione di Global Batch di destinazione per le risposte di inferenza. Lo stesso nome della distribuzione del modello Batch globale deve essere presente in ogni riga del file batch. Se si vuole 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, creeremo un file denominato test.jsonl e ne copieremo il contenuto dal blocco di codice di input standard sopra indicato nel file. Sarà necessario modificare e aggiungere il nome della distribuzione batch globale a ogni riga del file.

Creare un processo 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 Microsoft Foundry. Questo esempio illustra il caricamento di un file direttamente nella risorsa OpenAI Azure. In alternativa, è possibile configurare Archiviazione BLOB di Azure per Azure Batch OpenAI.

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).

  2. In alto a destra selezionare Compila

  3. Nel riquadro a sinistra selezionare Modelli

  4. Selezionare Processi batch>per creare un processo batch

    Screenshot della nuova esperienza di creazione batch di Foundry.

Tenere traccia dell'avanzamento del lavoro batch

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

È possibile tenere traccia dello stato dell'attività nel riquadro di destra.

Recuperare il file di output del job batch

Una volta completato o raggiunto lo stato del terminale, il processo genererà un file di errore e un file di output che può essere scaricato per la revisione selezionando il rispettivo pulsante con l'icona freccia verso il basso.

Annullare il batch

Annulla un batch in corso. Il batch sarà 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.

Prerequisiti

I passaggi descritti in questo articolo devono essere eseguiti in sequenza nei notebook di Jupyter. Per questo motivo istanzieremo il client Azure OpenAI solo una volta all'inizio degli esempi. Se si vuole eseguire un passaggio fuori sequenza, è spesso necessario configurare un client OpenAI Azure come parte di quella operazione.

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

!pip install openai --upgrade

Preparazione del file batch

Come la messa a punto, il batch globale usa i file in formato JSON lines (.jsonl). Di seguito sono riportati alcuni file di esempio con diversi tipi di contenuto supportato:

Formato di input

Risposte API

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

API di completamento della chat

{"custom_id": "task-0", "method": "POST", "url": "/v1/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": "/v1/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": "/v1/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 batch corrispondente a una determinata risposta. Le risposte non verranno restituite in modo identico all'ordine definito nel .jsonl file batch.

model L'attributo deve essere impostato in modo che corrisponda al nome dell'implementazione di Batch globale che desideri destinare per le risposte di inferenza.

Importante

L'attributo model deve essere impostato in modo che corrisponda al nome della distribuzione di Global Batch di destinazione per le risposte di inferenza. Lo stesso nome della distribuzione del modello Batch globale deve essere presente in ogni riga del file batch. Se si vuole 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 creeremo un file denominato test.jsonl e copieremo il contenuto dal blocco di codice di input standard precedente nel file. Sarà necessario modificare e aggiungere il nome della distribuzione batch globale a ogni riga del file. Salvare il file nella stessa directory in cui si esegue il Jupyter Notebook.

Caricare un 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 Microsoft Foundry. Questo esempio illustra il caricamento di un file direttamente nella risorsa OpenAI Azure. In alternativa, è possibile configurare Archiviazione BLOB di Azure per Azure Batch OpenAI.

import os
from datetime import datetime
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

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

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# 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

Decommentando e aggiungendo extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} imposti il nostro file di caricamento per scadere tra 14 giorni. È previsto un limite massimo di 500 file batch di input per risorsa quando non viene impostata alcuna scadenza. Impostando un valore per la scadenza, il numero di file batch di input per risorsa viene aumentato a 10.000 file per risorsa. Per rimuovere i limiti dei file di input batch, usare Batch con Archiviazione BLOB di Azure.

Output:

{
  "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 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", # While passing this parameter is required, the system will read your input file to determine if the chat completions or responses API is needed.  
    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))

Nota

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

Output:

{
  "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 accodato anche dopo il raggiungimento della quota massima per la distribuzione, alcune regioni supportano ora una nuova funzionalità di fail fast che consente di accodare più processi batch con backoff esponenziale, così una volta completato un processo batch di grandi dimensioni, il 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.

Tenere traccia dell'avanzamento del lavoro 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 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}")

Output:

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 batch possa iniziare.
failed Il file di input non è riuscito nel processo di convalida.
in_progress Il file di input è stato convalidato correttamente e il batch è attualmente in esecuzione.
finalizing L'elaborazione batch è stata completata e i risultati sono in fase di preparazione.
completed Il batch è stato completato e i risultati sono pronti.
expired Il batch non è stato in grado di essere completato entro l'intervallo di tempo di 24 ore.
cancelling Il batch è in fase di avvio cancelled (L'effetto potrebbe richiedere fino a 10 minuti per attivarsi).
cancelled il batch era cancelled.

Per esaminare i dettagli sullo stato del lavoro, è possibile eseguire:

print(batch_response.model_dump_json(indent=2))

Output:

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

Osservare che sia presente sia error_file_id che un oggetto separato output_file_id. Usare error_file_id per facilitare il debug di eventuali problemi che si verificano con il processo batch.

Recuperare il file di output del job 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)

Output:

Per brevità, includiamo solo una singola risposta di completamento della chat come output. Se si seguono i passaggi descritti in questo articolo, è necessario avere tre risposte simili a quella seguente:

Completamenti della chat

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

Risposte API

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "id": "resp_0e5c78eb05ee70cf00690cc6d988e4819587556df17436a206",
      "created_at": 1762445017.0,
      "error": null,
      "incomplete_details": null,
      "instructions": null,
      "metadata": {},
      "model": "gpt-4.1-batch",
      "object": "response",
      "output": [
        {
          "id": "msg_0e5c78eb05ee70cf00690cc6da3c548195aae483031113df16",
          "content": [
            {
              "annotations": [],
              "text": "Microsoft was founded on **April 4, 1975** by **Bill Gates** and **Paul Allen**.",
              "type": "output_text",
              "logprobs": []
            }
          ],
          "role": "assistant",
          "status": "completed",
          "type": "message"
        }
      ],
      "parallel_tool_calls": true,
      "temperature": 1.0,
      "tool_choice": "auto",
      "tools": [],
      "top_p": 1.0,
      "background": false,
      "max_output_tokens": null,
      "max_tool_calls": null,
      "previous_response_id": null,
      "prompt_cache_key": null,
      "reasoning": {
        "effort": null,
        "summary": null
      },
      "safety_identifier": null,
      "service_tier": "default",
      "status": "completed",
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "medium"
      },
      "top_logprobs": 0,
      "truncation": "disabled",
      "usage": {
        "input_tokens": 16,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 25,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 41
      },
      "user": null,
      "content_filters": null,
      "store": true
    },
    "request_id": "809b30c2-fa0b-4613-b5cc-c30f6b780c9a",
    "status_code": 200
  },
  "error": null
}

Comandi batch aggiuntivi

Annullare il batch

Annulla un batch in corso. Il batch sarà 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 batch

Elencare i processi batch per una determinata Azure risorsa OpenAI.

client.batches.list()

I metodi delle liste nella libreria Python sono paginati.

Per elencare tutti i lavori:

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://ai.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)

Output:

{
  "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 di lavori batch

Se i processi batch sono così grandi da raggiungere il limite di token accodati anche dopo aver utilizzato tutta la quota disponibile per la distribuzione, alcune regioni ora supportano una nuova funzionalità di fail fast che consente di accodare più processi batch con 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. Sono già in esecuzione grandi processi batch che utilizzano tutti i token disponibili per la distribuzione.
  2. Nuovo processo batch sottomesso.
  3. Il nuovo processo batch passa alla fase di convalida che può durare fino a pochi minuti.
  4. ** Il numero di token per il nuovo lavoro viene verificato rispetto alla quota attualmente disponibile.
  5. Il nuovo processo batch ha esito negativo e viene superato il limite di token di segnalazione errori.

Nuovo comportamento:

  1. Il processo Batch di grandi dimensioni è già in esecuzione e sta utilizzando tutti i token disponibili per il tuo deployment
  2. Nuovo processo batch inviato
  3. Il conteggio approssimativo dei token del nuovo processo viene immediatamente confrontato con la quota batch attualmente disponibile, facendo fallire rapidamente il processo se necessario, consentendoti di gestire i nuovi tentativi più facilmente a livello di codice.

Supporto per l'area

Le seguenti regioni supportano il nuovo comportamento di errore rapido:

  • australiaeast
  • eastus
  • germania ovest centrale
  • italynorth
  • northcentralus
  • poloniacentral
  • Swedencentral
  • SvizzeraNorth
  • eastus2
  • westus

Il codice seguente illustra i meccanismi fondamentali per gestire il comportamento di fail fast, consentendo di automatizzare i ritentativi e l'accodamento dei lotti con backoff esponenziale.

A seconda delle dimensioni dei processi batch, potrebbe essere necessario aumentare notevolmente il max_retries o 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

Output:

⏳ 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

Come la messa a punto, il batch globale usa i file in formato JSON lines (.jsonl). Di seguito sono riportati alcuni file di esempio con diversi tipi di contenuto supportato:

Formato di input

Risposte API

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

API di completamento della chat

{"custom_id": "task-0", "method": "POST", "url": "/v1/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": "/v1/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": "/v1/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 batch corrispondente a una determinata risposta. Le risposte non verranno restituite in modo identico all'ordine definito nel .jsonl file batch.

model L'attributo deve essere impostato in modo che corrisponda al nome dell'implementazione di Batch globale che desideri destinare per le risposte di inferenza.

Importante

L'attributo model deve essere impostato in modo che corrisponda al nome della distribuzione di Global Batch di destinazione per le risposte di inferenza. Lo stesso nome della distribuzione del modello Batch globale deve essere presente in ogni riga del file batch. Se si vuole 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 creeremo un file denominato test.jsonl e copieremo il contenuto dal blocco di codice di input standard precedente nel file. Sarà necessario modificare e aggiungere il nome della distribuzione batch globale a ogni riga del file.

Caricare un 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 Microsoft Foundry. Questo esempio illustra il caricamento di un file direttamente nella risorsa OpenAI Azure. In alternativa, è possibile configurare Archiviazione BLOB di Azure per Azure Batch OpenAI.

Importante

Usare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non pubblicarla 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 ChiaviAPI con Azure Key Vault.

Per altre informazioni sulla sicurezza dei servizi di intelligenza artificiale, vedere Autorizzazione delle richieste a Servizi di Azure AI.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files \
  -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", imposti la scadenza del file di caricamento a 14 giorni. È previsto un limite massimo di 500 file di input 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. Per rimuovere i limiti dei file di input batch, usare Batch con Archiviazione BLOB di Azure.

Output:

{
  "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 di caricamento, potrebbe essere necessario del tempo prima che venga completamente caricato ed elaborato. Per verificare lo stato di caricamento del file:

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files/{file-id} \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Output:

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

Creare un processo 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/v1/batches \
  -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"
  }'

Qui è possibile aggiungere "output_expires_after":{"seconds": 1209600}, facoltativamente e "anchor": "created_at" in modo che i file di output scadano in 14 giorni.

Nota

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

Output:

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

Tenere traccia dell'avanzamento del lavoro 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 batch, è consigliabile attendere almeno 60 secondi tra ogni chiamata di stato.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches/{batch_id} \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Output:

{
  "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 batch possa iniziare.
failed Il file di input non è riuscito nel processo di convalida.
in_progress Il file di input è stato convalidato correttamente e il batch è attualmente in esecuzione.
finalizing L'elaborazione batch è stata completata e i risultati sono in fase di preparazione.
completed Il batch è stato completato e i risultati sono pronti.
expired Il batch non è stato in grado di essere completato entro l'intervallo di tempo di 24 ore.
cancelling Il batch è in corso cancelled (l'applicazione delle modifiche può richiedere fino a 10 minuti per entrare in vigore).
cancelled il batch era cancelled.

Recuperare il file di output del job batch

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files/{output_file_id}/content \
  -H "api-key: $AZURE_OPENAI_API_KEY" > batch_output.jsonl

Comandi batch aggiuntivi

Annullare il batch

Annulla un batch in corso. Il batch sarà 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/v1/batches/{batch_id}/cancel \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Elenco batch

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches \
  -H "api-key: $AZURE_OPENAI_API_KEY"

La chiamata API della lista è paginata. La risposta contiene un valore booleano has_more che indica se ci sono 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-04-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 di Batch

Nome limite Valore limite
Numero massimo di file di input batch - (nessuna scadenza) 500
Numero massimo di file di input batch - (scadenza impostata) 10.000
Dimensioni massime del file di input 200 MB
Dimensioni massime del file di input - Bring Your Own Storage (BYOS) 1 GB
Numero massimo di richieste per file 100,000

Nota

I limiti dei file batch non si applicano ai file di output ( ad esempio , result.jsonle error.jsonl). Per rimuovere i limiti dei file di input batch, usare Batch con Archiviazione BLOB di Azure.

Quota batch

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

Batch globale

Modello Enterprise e MCA-E Predefinito Sottoscrizioni mensili basate su carta di credito Sottoscrizioni MSDN Azure per studenti, versioni di valutazione gratuite
gpt-4.1 5B 200 milioni 50M 90.000 N/D
gpt-4.1 mini 15B 1B 50M 90.000 N/D
gpt-4.1-nano 15B 1B 50M 90.000 N/D
gpt-4o 5B 200 milioni 50M 90.000 N/D
gpt-4o-mini 15B 1B 50M 90.000 N/D
gpt-4-turbo 300 milioni 80M 40M 90.000 N/D
gpt-4 150 milioni 30M 5M 100.000 N/D
o3-mini 15B 1B 50M 90.000 N/D
o4-mini 15B 1B 50M 90.000 N/D
gpt-5 5B 200 milioni 50M 90.000 N/D
gpt-5.1 5B 200 milioni 50M 90.000 N/D

B = miliardi | M = milioni | K = migliaia

Batch della zona dati

Modello Enterprise e MCA-E Predefinito Sottoscrizioni mensili basate su carta di credito Sottoscrizioni MSDN Azure per studenti, versioni di valutazione gratuite
gpt-4.1 500 milioni 30M 30M 90.000 N/D
gpt-4.1-mini 1,5 miliardi 100 mln 50M 90.000 N/D
gpt-4o 500 milioni 30M 30M 90.000 N/D
gpt-4o-mini 1,5 miliardi 100 mln 50M 90.000 N/D
o3-mini 1,5 miliardi 100 mln 50M 90.000 N/D
gpt-5 5B 200 milioni 50M 90.000 N/D
gpt-5.1 5B 200 milioni 50M 90.000 N/D

Oggetto Batch

Proprietà Digitare Definizione
id Stringa Identificatore del batch.
object Stringa batch
endpoint Stringa L'endpoint API utilizzato dal batch
errors Oggetto Informazioni sull'errore per il batch, se presenti.
input_file_id Stringa ID del file di input per il batch
completion_window Stringa Intervallo di tempo entro il quale deve essere elaborato il batch
status Stringa Stato corrente del batch. Valori possibili: validating, failedin_progress, finalizing, completed, expired, , cancelling, . cancelled
output_file_id Stringa ID del file contenente gli output delle richieste eseguite correttamente.
error_file_id Stringa ID del file contenente gli output delle richieste con errori.
created_at Intero Timestamp al momento della creazione del batch (in secondi dell'epoca Unix).
in_progress_at Intero Il timestamp di inizio elaborazione di questo batch (in secondi dell'era Unix).
expires_at Intero Un timestamp in secondi dell'epoca Unix che indica quando questo batch scadrà.
finalizing_at Intero Un timestamp in cui questo batch ha iniziato la finalizzazione (in secondi dell'epoca Unix).
completed_at Intero Un timestamp di quando questo batch è stato completato (in secondi dall'epoca Unix).
failed_at Intero Il timestamp in cui questo batch è fallito (in secondi dell'epoca Unix).
expired_at Intero Timestamp quando questo batch è scaduto (in secondi dell'epoca Unix).
cancelling_at Intero Timestamp all'avvio cancelling di questo batch (in secondi dell'epoca Unix).
cancelled_at Intero Un timestamp relativo al momento in cui questo batch è stato cancelled (in secondi dell'epoca Unix).
request_counts Oggetto Struttura dell'oggetto:

total intero
Numero totale di richieste nel batch.
completed intero
Numero di richieste nel batch completate correttamente.
failed intero
Numero di richieste nel batch che hanno fallito.
metadata Mappa 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 batch?

Questa funzionalità è limitata a determinati modelli multifunzionali. Le immagini possono essere fornite come input tramite l'URL dell'immagine o una rappresentazione con codifica Base64 dell'immagine.

È possibile usare l'API batch con modelli ottimizzati?

Questo non è attualmente supportato.

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

Questo non è attualmente supportato.

Il filtro del contenuto funziona con la distribuzione globale di 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 Foundry. L'allocazione della quota predefinita è disponibile nell'articolo quote e limiti.

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

Abbiamo lo scopo di elaborare queste richieste entro 24 ore; non scadono i processi che richiedono più tempo. È possibile annullare l'attività in qualsiasi momento. Quando si annulla l'attività, qualsiasi lavoro rimanente viene annullato e qualsiasi lavoro già completato viene restituito. Verrà addebitato qualsiasi lavoro completato.

Quante richieste posso 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 tuoi batch, il tuo limite di velocità per i batch viene reimpostato più rapidamente.

Risoluzione dei problemi

Un compito ha esito positivo quando status è completed. I processi riusciti genereranno comunque un oggetto error_file_id, ma verrà associato a un file vuoto con zero byte.

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

{
  "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 di errore Definizione
invalid_json_line Una riga (o più) nel file di input non è stata in grado di essere analizzata come json valido.

Assicurarsi che non siano presenti errori di digitazione, 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.

Assicurati che le richieste totali siano inferiori a 100.000 e reinvia il lavoro.
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.

Assicurarsi che tutti gli URL delle richieste siano uguali e che corrispondano all'URL dell'endpoint associato alla distribuzione Azure OpenAI.
model_not_found Impossibile trovare il nome di distribuzione del modello OpenAI Azure specificato nella proprietà />
Si assicuri che questo nome punti a una distribuzione valida di un modello OpenAI sul servizio Azure.
duplicate_custom_id L'ID personalizzato per questa richiesta è un duplicato dell'ID personalizzato in un'altra richiesta.
empty_file Il file di input è vuoto. Assicurarsi che il batch contenga almeno una richiesta.
model_mismatch Il nome di distribuzione del modello OpenAI Azure specificato nella proprietà model di questa richiesta nel file di input non corrisponde al resto del file.

Assicurarsi che tutte le richieste nel batch indirizzino allo stesso modello Azure OpenAI distribuito nelle Foundry Models nella proprietà model della richiesta.
invalid_request Lo schema della riga di input non è valido o lo SKU di distribuzione non è valido.

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

Problemi noti

  • Le risorse distribuite tramite interfaccia della riga di comando di Azure non saranno immediatamente compatibili con il batch globale di Azure OpenAI. Ciò è dovuto a un problema a causa del quale le risorse distribuite con questo metodo hanno sottodomini endpoint che non seguono il https://your-resource-name.openai.azure.com modello. Una soluzione alternativa per questo problema consiste nel distribuire una nuova risorsa OpenAI Azure usando uno degli altri metodi di distribuzione comuni che gestiranno correttamente l'installazione del sottodominio come parte 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 attualmente, Azure OpenAI considererà non validi i file codificati BOM. 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".

  • Quando si usa la propria risorsa di archiviazione per i dati di input batch, dopo l'invio del processo batch, se il BLOB di input viene modificato, il processo di assegnazione dei punteggi non sarà riuscito dal servizio.

Vedere anche

  • Last updated on