Salt la conținutul principal
Română— Alege o limbă
Meniu

API Batch: Procesare Asincronă Masivă

Lecția 6 din 20 Actualizată 3 noiembrie 2026 Avansat
Pe această pagină
  1. Schimbați latența pe cost
  2. Construiți și lansați un Batch
  3. Planificați eșecurile parțiale
  4. Cumulați economiile
  5. Puncte cheie

Actualizat la 3 noiembrie 2026 pe baza ghidului Batch API și a structurii de răspuns a API-ului Responses: citirea rezultatelor nu mai presupune că primul element din output este mesajul (un element de raționament îl poate preceda), iar cheia codului de eroare, scrisă fără ghilimele, genera o eroare NameError. Sursă: Batch API.

Schimbați latența pe cost

API-ul Batch funcționează pe un principiu de piață simplu: acceptați ca cererile dumneavoastră să fie procesate asincron într-o fereastră de timp de până la douăzeci și patru de ore, iar în schimb, plătiți cu cincizeci la sută mai puțin. Orice nu necesită servirea unui om care așteaptă în fața ecranului intră în această categorie. La scară largă, aceasta nu este o micro-optimizare; vă înjumătățește linia bugetară.

Obiceiul de construit în cadrul unei echipe este să vă întrebați, pentru fiecare nouă sarcină de procesare, dacă cineva așteaptă rezultatul. Analiza unui stoc de contracte, generarea fișelor de produs pentru un catalog, rularea unui benchmark pe mii de cazuri de test, clasificarea unui backlog de tichete pe șase luni, extragerea câmpurilor dintr-un lot de facturi: în toate aceste cazuri, răspunsul ajunge într-un tablou de bord sau într-o bază de date, nu într-o interfață conversațională. Întârzierea este invizibilă, dar economiile nu sunt.

Construiți și lansați un Batch

Formatul de intrare este un fișier JSONL: o linie per cerere, unde fiecare linie este un obiect complet și independent. Câmpul custom_id este cel care vă permite să legați fiecare răspuns de cererea sa originală, deoarece nimic nu garantează ordinea fișierului de ieșire. Alegeți un ID stabil și semnificativ—un ID de document din baza dumneavoastră de date, nu un număr de iterație—altfel faza de reconciliere va deveni un coșmar.

import json

requests = [
    {
        "custom_id": f"doc-{i}",
        "method": "POST",
        "url": "/v1/responses",
        "body": {
            "model": "gpt-5.6-luna",
            "input": f"Summarize this document in 3 key points: {doc}",
            "max_output_tokens": 500,
        },
    }
    for i, doc in enumerate(documents_list)
]

# Scrieți fișierul JSONL
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

Fișierul este apoi încărcat și referențiat la crearea batch-ului. Metadatele nu servesc niciun scop tehnic, dar vă vor salva ziua când trei batch-uri rulează în paralel și trebuie să aflați care corespunde cărei versiuni de prompt.

import openai

client = openai.OpenAI()

# Încărcați fișierul
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Creați batch-ul
batch = client.batches.create(
    input_file_id=file_obj.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"project": "contract-analysis", "version": "2.1"},
)

print(f"Batch created: {batch.id}")
print(f"Status: {batch.status}")

Monitorizarea implică interogarea periodică (polling) a batch-ului până când iese din starea „în curs“, apoi descărcarea fișierului de ieșire, care este tot în format JSONL. Bucla de mai jos distinge trei rezultate finale—failed, expired, cancelled—și generează o excepție pentru fiecare: un batch expirat este unul în care fereastra de douăzeci și patru de ore s-a scurs înainte ca totul să fie procesat, iar tratarea acestuia ca un succes parțial silențios ar fi cea mai proastă opțiune.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Așteaptă finalizarea unui batch și returnează rezultatele."""
    while True:
        batch = client.batches.retrieve(batch_id)
        print(
            f"Status: {batch.status} | "
            f"Completed: {batch.request_counts.completed}/"
            f"{batch.request_counts.total} | "
            f"Failed: {batch.request_counts.failed}"
        )

        if batch.status == "completed":
            break
        elif batch.status in ("failed", "expired", "cancelled"):
            raise RuntimeError(f"Batch failed: {batch.status}")

        time.sleep(interval)

    # Descărcați rezultatele
    content = client.files.content(batch.output_file_id)
    results = []
    for line in content.text.strip().split("\n"):
        results.append(json.loads(line))

    return results


results = wait_for_batch(batch.id)

# Procesați rezultatele
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output poate conține alte elemente înainte de mesaj
        # (de exemplu, raționament): căutați textul mesajului
        text = next(
            part["text"]
            for item in response["body"]["output"] if item["type"] == "message"
            for part in item["content"] if part["type"] == "output_text"
        )
        print(f"{custom_id}: {text[:100]}...")
    else:
        print(f"{custom_id}: ERROR {response['status_code']}")

Planificați eșecurile parțiale

Într-un batch mare, unele cereri vor eșua: un document trunchiat, o depășire a contextului sau o eroare tranzitorie lato-sensu server. Un batch nu este deci niciodată simplu „reușit“ sau „eșuat“—este parțial reușit, iar dumneavoastră trebuie să știți cum să izolați partea lipsă. Tiparul de adoptat este separarea imediată a succeselor de eșecuri și regenerarea unui fișier JSONL gata de relansare, în loc să săpați prin jurnale trei zile mai târziu pentru a reconstrui ce lipsește.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Separă succesele de eșecuri pentru reprocesare."""
    successes = []
    failures = []

    for r in results:
        if r["response"]["status_code"] == 200:
            successes.append(r)
        else:
            failures.append(r)

    if failures:
        print(f"Warning: {len(failures)} failed requests out of {len(results)}")
        # Rescrieți un fișier JSONL cu eșecurile pentru reîncercare
        with open("batch_retry.jsonl", "w") as f:
            for failure in failures:
                original_request = {
                    "custom_id": failure["custom_id"],
                    "method": "POST",
                    "url": "/v1/responses",
                    "body": failure["request"]["body"],
                }
                f.write(json.dumps(original_request) + "\n")

    return successes, failures

Cumulați economiile

La o rulare de procesare a zece mii de documente cu GPT-5.6 Luna, API-ul sincron reprezintă costul de bază, API-ul Batch reprezintă jumătate din acesta, iar cache-ul de prompt se adaugă peste, deoarece token-urile cached beneficiază și ele de propria reducere. Cele două mecanisme nu concurează: dacă cele zece mii de cereri ale dumneavoastră partajează același prompt de sistem lung, structurați-l ca un prefix stabil și veți cumula ambele efecte.

În final, există problema divizării. Un batch nu ar trebui să fie infinit și este mai confortabil să monitorizați mai multe batch-uri gestionabile decât un singur monolit a cărui defecțiune costă o zi întreagă. Funcția următoare taie o listă de cereri în batch-uri de dimensiune limitată.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Împarte în batch-uri de dimensiune optimă."""
    batches = []
    current_batch = []

    for request in requests:
        current_batch.append(request)
        if len(current_batch) >= max_size:
            batches.append(current_batch)
            current_batch = []

    if current_batch:
        batches.append(current_batch)

    return batches

Puncte cheie

  • API-ul Batch oferă o reducere de 50% pentru procesarea care nu necesită timp real
  • Pregătiți cererile într-un fișier JSONL cu un custom_id unic per cerere
  • Planificați un mecanism de reîncercare pentru cererile eșuate
  • Combinați cu cache-ul de prompt pentru a maximiza economiile