Groq API în Python: SDK-ul groq, streaming, AsyncGroq și limite de rată în Groq: LPU și GroqCloud API

pip install groq
from groq import Groq, AsyncGroq
client.chat.completions.create(model="openai/gpt-oss-20b", messages=[...])

GroqCloud expune un API compatibil OpenAI la https://api.groq.com/openai/v1. Biblioteca oficială groq (PyPI; versiunea 1.7.0 din 26 august 2026, prima versiune stabilă 1.0.0 în decembrie 2025) cere Python 3.10 sau mai nou și are un client sincron, Groq, și unul asincron, AsyncGroq, cu aceeași interfață. Cheia se citește implicit din variabila de mediu GROQ_API_KEY. Clientul asincron poate folosi aiohttp (pip install groq[aiohttp]) în locul lui httpx. Poți folosi și clientul OpenAI, cu base_url schimbat.

Pentru text, modelele de producție din octombrie 2026 sunt openai/gpt-oss-120b și openai/gpt-oss-20b. llama-3.3-70b-versatile și llama-3.1-8b-instant au fost retrase pentru planurile free și developer pe 16 august 2026, deepseek-r1-distill-llama-70b pe 2 octombrie 2025, iar modelele Llama 3.2 Vision pe 14 aprilie 2025. Lista actuală este pe pagina modele și deprecieri.

Răspunsul conține în usage, pe lângă numărul de tokeni, timpii queue_time, prompt_time, completion_time și total_time, deci viteza se calculează corect ca completion_tokens / completion_time. SDK-ul reîncearcă automat de 2 ori, cu backoff exponențial, erorile de conexiune și codurile 408, 409, 429 și 5xx; timeout-ul implicit este 1 minut. Limitele de rată se aplică la nivel de organizație (RPM, RPD, TPM, TPD, iar la audio ASH și ASD) și se văd în antetele x-ratelimit-*; la depășire primești 429, cu antetul retry-after.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
Groq(api_key=..., max_retries=2, timeout=60)	Clientul sincron. Fără api_key, folosește GROQ_API_KEY.
AsyncGroq()	Clientul asincron; apelurile se fac cu await.
model	ID-ul modelului, de exemplu openai/gpt-oss-20b.
stream=True	Întoarce un iterator de fragmente (chunk.choices[0].delta.content). Un fragment nu înseamnă un token.
max_completion_tokens	Limita de ieșire; max_tokens este depreciat.
temperature	Între 0 și 2; valoarea 0 este convertită în 1e-8.
with_raw_response	Dă acces la antete, de exemplu x-ratelimit-remaining-tokens; .parse() întoarce obiectul obișnuit.
x-ratelimit-limit-requests / -remaining-requests	Se referă mereu la cereri pe zi (RPD).
x-ratelimit-limit-tokens / -remaining-tokens	Se referă mereu la tokeni pe minut (TPM).
groq.RateLimitError, groq.APIStatusError, groq.APIConnectionError	Excepțiile pentru 429, alte coduri HTTP și probleme de rețea.
Parametri OpenAI neacceptați	logprobs, logit_bias, top_logprobs, messages[].name și n diferit de 1 întorc 400.

Exemple practice și scenarii reale

Exemplul 1: Prima cerere

from groq import Groq

client = Groq()   # cheia din variabila de mediu GROQ_API_KEY
r = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[
        {"role": "system", "content": "Ești un arhitect software. Răspunzi concis."},
        {"role": "user", "content": "Explică pe scurt principiile Clean Architecture."},
    ],
)
print(r.choices[0].message.content)

Exemplul 2: Streaming în terminal

flux = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[{"role": "user", "content": "Scrie un haiku despre latență."}],
    stream=True,
)
for chunk in flux:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Exemplul 3: Viteza și timpii unei cereri, din usage

r = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Descrie protocolul HTTP/3 în 150 de cuvinte."}],
)
u = r.usage
print(f"coadă {u.queue_time:.3f} s, prompt {u.prompt_time:.3f} s, generare {u.completion_time:.3f} s")
print(f"{u.completion_tokens / u.completion_time:.0f} tokeni/s la generare")

Exemplul 4: Cereri independente în paralel cu AsyncGroq

import asyncio
from groq import AsyncGroq

async def main():
    client = AsyncGroq()
    intrebari = ["Ce este TCP?", "Ce este UDP?", "Ce este QUIC?"]
    raspunsuri = await asyncio.gather(*[
        client.chat.completions.create(
            model="openai/gpt-oss-20b",
            messages=[{"role": "user", "content": q}],
        )
        for q in intrebari
    ])
    for q, r in zip(intrebari, raspunsuri):
        print(q, "->", r.choices[0].message.content[:80])

asyncio.run(main())

Exemplul 5: Antetele de limită de rată

raw = client.chat.completions.with_raw_response.create(
    model="openai/gpt-oss-20b",
    messages=[{"role": "user", "content": "Salut"}],
)
print(raw.headers.get("x-ratelimit-remaining-tokens"))
print(raw.headers.get("x-ratelimit-remaining-requests"))
r = raw.parse()

Greșeli frecvente și capcane

• Scrii cheia API direct în cod. Pune-o în GROQ_API_KEY (sau într-un fișier .env exclus din controlul versiunilor).
• Numeri fragmentele din stream ca tokeni. Un fragment poate conține mai mulți tokeni sau niciunul; folosește usage.completion_tokens și usage.completion_time.
• Folosești ID-uri vechi (llama-3.3-70b-versatile, deepseek-r1-distill-llama-70b). Pe planurile free și developer întorc erori.
• Te bazezi doar pe reîncercările automate la 429. Citește retry-after și antetele x-ratelimit-*, iar pentru volume mari folosește Batch sau Flex.

Noțiuni și module înrudite

• groq-modele-deprecari
• groq-tool-calling-json
• groq-reasoning
• groq-speech-whisper-tts