Introduzione alle distribuzioni batch globali di Azure OpenAI

  • Articolo

L'API Batch OpenAI di Azure è progettata per gestire in modo efficiente le attività di elaborazione su larga scala e con grandi volumi. Elaborare gruppi asincroni di richieste con quota separata, con turnaround di destinazione 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: generazione di contenuti e raccomandazioni personalizzati su larga scala.

Importante

Cerchiamo di elaborare le richieste in batch entro 24 ore; i processi che richiedono più tempo non scadono. È possibile annullare il processo in qualsiasi momento. Quando si annulla il processo i lavori rimanenti vengono annullati, mentre quelli già completati vengono restituiti. Verranno addebitati i costi relativi ai lavori completati.

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

Supporto batch globale

Supporto di area e modelli

Il batch globale è attualmente supportato nelle aree seguenti:

Area gpt-4o, 2024-05-13 gpt-4o, 2024-08-06 gpt-4o-mini, 2024-07-18 gpt-4, 0613 gpt-4, turbo-2024-04-09 gpt-35-turbo, 0613 gpt-35-turbo, 1106 gpt-35-turbo, 0125
australiaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
canadaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
northcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Stati Uniti centro-meridionali ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southindia ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Svezia centrale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Svizzera settentrionale ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

I modelli seguenti supportano il batch globale:

Modello Versione Formato di input
gpt-4o 2024-08-06 Text/Image
gpt-4o-mini 2024-07-18 Text/Image
gpt-4o 2024-05-13 Text/Image
gpt-4 turbo-2024-04-09 Testo
gpt-4 0613 Testo
gpt-35-turbo 0125 Testo
gpt-35-turbo 1106 Testo
gpt-35-turbo 0613 Testo

Per informazioni aggiornate sulle aree o sui modelli in cui è attualmente supportato il batch globale, vedere la pagina modelli.

Supporto dell'API

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

Supporto aggiunto per la prima volta in: 2024-07-01-preview

Supporto funzionalità

Al momento non sono supportati gli elementi seguenti:

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

Nota

Gli output strutturati sono ora supportati con Global Batch.

Distribuzione batch globale

Nell'interfaccia utente di Studio il tipo di distribuzione verrà visualizzato come Global-Batch.

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

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. La 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 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, è necessario caricare il file per poter avviare un processo in batch. Il caricamento dei file può essere eseguito sia a livello di codice che tramite Studio.

  1. Accedere a Studio AI.

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

  3. Selezionare Processi batch>+Crea processi batch.

    Screenshot che mostra l'esperienza della creazione del processo batch in Studio IA di Azure.

  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 in batch nell'interfaccia utente di Azure Studio.

Monitoraggio avanzamento processo in 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 processo nel riquadro di destra:

Screenshot che mostra l'esperienza dello stato del processo in batch in Studio AI della piattaforma Azure.

Recuperare il file di output del processo in 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 in batch in Studio AI della piattaforma Azure.

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 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. Sarà 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, è necessario caricare il file per poter avviare un processo in batch. Il caricamento dei file può essere eseguito sia a livello di codice che tramite Studio. In questo esempio vengono usate variabili di ambiente al posto dei valori di chiave ed endpoint. Se non si ha dimestichezza con l'uso delle variabili di ambiente con Python, fare riferimento a una delle guide introduttive in cui il processo di configurazione delle variabili di ambiente è illustrato dettagliatamente.

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="2024-10-21"
)

# Upload a file with a purpose of "batch"
file = client.files.create(
  file=open("test.jsonl", "rb"), 
  purpose="batch"
)

print(file.model_dump_json(indent=2))
file_id = file.id

Output:

{
  "id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "bytes": 815,
  "created_at": 1722476551,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": null,
  "status_details": null
}

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

# 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 avrà esito negativo. I processi che richiedono più di 24h 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-9f3a81d899b4442f98b640e4bc3535dd",
  "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
  }
}

Monitoraggio avanzamento processo in batch

Dopo aver creato correttamente il processo in batch è possibile monitorarne lo stato di avanzamento in Studio o a livello di programmazione. 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}")

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 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 sullo stato del processo, è 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
  }
}

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 in 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à 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 elenco nella libreria Python vengono impaginati.

Per elencare tutti i processi:

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 created_at gt 1728860560 and status eq 'Completed'a .

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 = "2024-10-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"
}

Prerequisiti

Preparazione 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. Sarà 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, è necessario caricare il file per poter avviare un processo in batch. Il caricamento dei file può essere eseguito sia a livello di codice che tramite Studio. In questo esempio vengono usate variabili di ambiente al posto dei valori di chiave ed endpoint. Se non si ha dimestichezza con l'uso delle variabili di ambiente con Python, fare riferimento a una delle guide introduttive in cui il processo di configurazione delle variabili di ambiente è illustrato dettagliatamente.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

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=2024-10-21 \
  -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"

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.

Output:

{
  "status": "pending",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "id": "file-21006e70789246658b86a1fc205899a4",
  "created_at": 1721408291,
  "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=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Output:

{
  "status": "processed",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "id": "file-21006e70789246658b86a1fc205899a4",
  "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=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/chat/completions",
    "completion_window": "24h"
  }'

Nota

Attualmente la finestra di completamento deve essere impostata su 24h. Se si imposta un valore diverso da 24h, il processo avrà esito negativo. I processi che richiedono più di 24h 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"
}

Monitoraggio avanzamento processo in batch

Dopo aver creato correttamente il processo in batch è possibile monitorarne lo stato di avanzamento in Studio o a livello di programmazione. 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=2024-10-21 \
  -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 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 tempo di 24 ore.
cancelling Il batch è in fase di cancelled (può richiedere fino a 10 minuti).
cancelled Il batch è cancelled.

Recuperare il file di output del processo in batch

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{output_file_id}/content?api-version=2024-10-21 \
  -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 https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}/cancel?api-version=2024-10-21 \
  -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=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY"

La chiamata API list è impaginata. La risposta contiene un valore booleano has_more che indica quando sono presenti più risultati per scorrere l'iterazione.

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=2024-10-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 globali dei 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 globale

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.

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

B = miliardi | M = milioni

Oggetto batch

Proprietà Type Definizione
id string
object string batch
endpoint string Endpoint API usato 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 Timestamp al momento della creazione di questo batch (in periodi 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:

total integer
Numero totale di richieste nel batch.
completed integer
Numero di richieste nel batch completate correttamente.
failed integer
Numero di richieste nel batch non riuscite.
metadata mappa Set di coppie chiave-valore che possono essere collegate 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ì, nella pagina delle quote, nell'interfaccia utente di Studio. 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 il processo i lavori rimanenti vengono annullati, mentre quelli già completati vengono restituiti. Verranno addebitati i 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 processo 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 AOAI 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.

Problemi noti

  • Le risorse distribuite con l'interfaccia della riga di comando di Azure (CLI) non funzionano in modo predefinito con il batch globale OpenAI di Azure. È 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.

Vedi anche