Batch API, Flex și niveluri de servicii (service_tier) pe Groq în Groq: LPU și GroqCloud API

client.files.create(file=open("cereri.jsonl", "rb"), purpose="batch")
client.batches.create(input_file_id=..., endpoint="/v1/chat/completions", completion_window="24h")
service_tier="on_demand" | "flex" | "performance" | "auto"

Batch API primește un fișier JSONL în care fiecare linie este o cerere (custom_id, method = POST, url, body). Endpoint-urile acceptate sunt /v1/chat/completions, /v1/audio/transcriptions și /v1/audio/translations. Prețul este cu 50% mai mic decât la cererile sincrone, iar loturile au limite separate, care nu consumă din limitele obișnuite pe model. Reducerea nu se cumulează cu prompt caching. Fișierul are cel mult 50.000 de linii și 200 MB; fereastra de procesare se alege între 24h și 7d.

Un lot trece prin stările validating, in_progress, finalizing, completed (sau failed, expired, cancelling, cancelled). La final primești output_file_id și, dacă au existat erori, error_file_id. Rezultatele nu vin în ordinea cererilor: le potrivești după custom_id. Dacă lotul expiră, plătești doar cererile terminate. Fișierele se păstrează cel mult 30 de zile.

Pentru cererile sincrone, parametrul service_tier alege nivelul: on_demand (implicit), flex (doar pentru clienții plătitori, limite de 10 ori mai mari la același preț, dar cererea poate fi respinsă rapid cu codul 498 capacity_exceeded când nu există capacitate), performance (doar Enterprise, capacitate rezervată, SLA de disponibilitate 99,9%, context necache-uit sub 8.192 de tokeni) și auto (cel mai bun nivel disponibil în limitele organizației). Batch API nu acceptă service_tier.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
custom_id	Identificatorul tău pentru fiecare linie; apare și în rezultat.
completion_window	De la 24h la 7d. Documentația recomandă ferestre mai lungi, ca lotul să nu expire.
endpoint	/v1/chat/completions, /v1/audio/transcriptions sau /v1/audio/translations.
client.batches.retrieve / list / cancel	Starea unui lot, lista loturilor (paginată cu cursor), anularea (poate dura până la 10 minute).
client.files.content	Descarcă fișierul de rezultate sau de erori.
service_tier="flex"	Limite de 10 ori mai mari, preț on-demand, eroare 498 la lipsă de capacitate.
service_tier="performance"	Enterprise; capacitate cumpărată ca debit rezervat, nu pe token.
service_tier="auto"	Folosește nivelul cel mai bun disponibil, cu trecere la on_demand.
429 / 498	429: limită de rată depășită. 498: capacitate Flex epuizată. SDK-ul reîncearcă automat 429, dar nu 498.

Exemple practice și scenarii reale

Exemplul 1: Un fișier JSONL de lot (cereri.jsonl)

{"custom_id": "r1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Clasifică: „Livrarea a întârziat”."}]}}
{"custom_id": "r2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Clasifică: „Produs excelent”."}]}}

Exemplul 2: Încărcare, lansare, verificare și descărcare

from groq import Groq

client = Groq()
fisier = client.files.create(file=open("cereri.jsonl", "rb"), purpose="batch")
lot = client.batches.create(
    input_file_id=fisier.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)

# mai târziu
lot = client.batches.retrieve(lot.id)
print(lot.status)
if lot.status == "completed" and lot.output_file_id:
    client.files.content(lot.output_file_id).write_to_file("rezultate.jsonl")

Exemplul 3: Cerere Flex cu reîncercare la codul 498

import random
import time
import groq

client = groq.Groq()

def cere_flex(messages, incercari=5):
    for i in range(incercari):
        try:
            return client.chat.completions.create(
                model="openai/gpt-oss-120b",
                messages=messages,
                service_tier="flex",
            )
        except groq.APIStatusError as e:
            if e.status_code != 498:
                raise
            time.sleep(2 ** i + random.random())   # backoff cu jitter
    raise RuntimeError("Capacitate Flex indisponibilă")

Greșeli frecvente și capcane

• Aștepți rezultatele în ordinea liniilor. Potrivește-le după custom_id.
• Trimiți service_tier în corpul cererilor de lot. Batch API nu îl acceptă.
• Folosești Flex pe un cont gratuit sau fără tratarea codului 498. Flex este doar pentru clienții plătitori și poate respinge cereri când capacitatea este ocupată.
• Pui în lot un model retras (de exemplu llama-3.1-8b-instant pe un cont developer). Lotul eșuează la validare sau pe linii; verifică lista de modele.

Noțiuni și module înrudite

• groq-prompt-caching
• groq-modele-deprecari
• groq-api-python