Usare Groq GPT-OSS 120B con l’SDK OpenAI: URL base, prezzi e caching

L’endpoint compatibile con OpenAI di Groq è davvero una sostituzione di una sola riga: imposta base_url su https://api.groq.com/openai/v1 e continua a usare l’SDK OpenAI. Al 17 giugno 2026, Groq indica openai/gpt-oss-120b a $0.15 per 1M token di input non in cache, $0.075 per 1M token di input in cache e $0.60 per 1M token di output nella sua pagina dei prezzi (Prezzi Groq).

Questa è la parte utile. La trappola è dare per scontato che “compatibile con OpenAI” significhi “comportamento identico e fatturazione identica”. Non è così. Devi comunque scegliere l’ID modello Groq, monitorare i cache hit, evitare parametri OpenAI non supportati e conteggiare separatamente le chiamate agli strumenti integrati.

Cosa stai effettivamente cambiando

La documentazione di Groq dice che la sua API è “per lo più compatibile con le librerie client di OpenAI” e mostra la configurazione esatta del client OpenAI: passa la tua chiave Groq e imposta base_url="https://api.groq.com/openai/v1" (Compatibilità OpenAI di Groq).

Installa l’SDK Python di OpenAI:

pip install openai
export GROQ_API_KEY="gsk_..."

Poi chiama GPT-OSS 120B tramite Groq:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {"role": "system", "content": "You are a concise senior backend engineer."},
        {"role": "user", "content": "Write a PostgreSQL index plan for a slow user_events query."},
    ],
)

print(response.choices[0].message.content)
print(response.usage)

La differenza importante è il model. Sulla piattaforma di OpenAI potresti usare il nome di un modello ospitato da OpenAI. Su Groq, GPT-OSS viene indirizzato come openai/gpt-oss-120b o openai/gpt-oss-20b.

OpenAI ha rilasciato gpt-oss-120b e gpt-oss-20b il 5 agosto 2025 come modelli di reasoning open-weight sotto licenza Apache 2.0 (OpenAI). OpenAI dichiara che gpt-oss-120b ha 117B parametri totali, 5.1B parametri attivi per token, 128 esperti, 4 esperti attivi per token e supporto nativo per lunghezze di contesto fino a 128k (OpenAI). La pagina modello di Groq indica per openai/gpt-oss-120b ospitato una finestra di contesto di 131,072 token e un massimo di token di output pari a 65,536 (scheda modello Groq).

Scegliere 120B o 20B

Usa 120B quando la qualità conta più del costo grezzo: pianificazione di agenti, task di coding più difficili, estrazione complessa o reasoning multi-step. Usa 20B quando ti serve throughput più economico per routing, riassunti, classificazione, assistenti brevi o job in background ad alto volume.

ID modello Groq	Velocità indicata	Input non in cache	Input in cache	Output
openai/gpt-oss-120b	500 TPS	$0.15 / 1M	$0.075 / 1M	$0.60 / 1M
openai/gpt-oss-20b	1,000 TPS	$0.075 / 1M	$0.0375 / 1M	$0.30 / 1M

Questi prezzi provengono dall’attuale tabella dei prezzi e dalla tabella di prompt caching di Groq (Prezzi Groq). Il modello 20B costa esattamente la metà del prezzo per token indicato per 120B. Questo lo rende un buon default per workflow “provalo prima”. Se la qualità della risposta non è sufficiente, promuovi quel percorso a 120B.

Ecco un piccolo switch che puoi tenere nella configurazione:

import os
from openai import OpenAI

MODEL = os.getenv("GROQ_MODEL", "openai/gpt-oss-20b")

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

def ask(prompt: str) -> str:
    response = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": "Answer with practical developer steps."},
            {"role": "user", "content": prompt},
        ],
    )
    return response.choices[0].message.content

print(ask("Give me a minimal Redis rate limiter design."))

Eseguilo con 20B:

GROQ_MODEL=openai/gpt-oss-20b python app.py

Eseguilo con 120B:

GROQ_MODEL=openai/gpt-oss-120b python app.py

Prezzare le richieste con cache hit

Il prompt caching di Groq è automatico per i modelli supportati, inclusi openai/gpt-oss-20b e openai/gpt-oss-120b. Groq dice che non sono necessarie modifiche al codice, che i cache hit usano il matching esatto del prefisso, che le parti in cache ottengono uno sconto del 50% sui token di input e che i dati in cache scadono automaticamente dopo 2 ore senza utilizzo (Prompt Caching Groq).

La regola pratica: metti prima il testo stabile.

Ordine corretto:

1. Prompt di sistema
2. Definizioni degli strumenti
3. Esempi few-shot
4. Documenti o schemi condivisi
5. Input specifico dell’utente
6. Timestamp, ID, dati per singola richiesta

Ordine sbagliato: mettere un timestamp, un ID richiesta o un campo specifico dell’utente prima di un prompt condiviso da 20,000 token. Questo rompe il prefisso.

Ecco un helper di costo per GPT-OSS 120B:

def groq_gpt_oss_120b_cost(prompt_tokens, cached_tokens, completion_tokens):
    uncached_tokens = max(prompt_tokens - cached_tokens, 0)

    return (
        uncached_tokens / 1_000_000 * 0.15
        + cached_tokens / 1_000_000 * 0.075
        + completion_tokens / 1_000_000 * 0.60
    )

Ed ecco una chiamata eseguibile che stampa l’utilizzo della cache se Groq lo restituisce:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

STATIC_POLICY = """
You are an internal code review assistant.
Always check correctness, security, performance, and migration risk.
Return JSON with keys: summary, risks, suggested_patch.
"""

def review(diff: str):
    response = client.chat.completions.create(
        model="openai/gpt-oss-120b",
        messages=[
            {"role": "system", "content": STATIC_POLICY},
            {"role": "user", "content": diff},
        ],
        response_format={"type": "json_object"},
    )

    usage = response.usage
    details = getattr(usage, "prompt_tokens_details", None)
    cached = getattr(details, "cached_tokens", 0) if details else 0

    print("prompt_tokens:", usage.prompt_tokens)
    print("cached_tokens:", cached)
    print("completion_tokens:", usage.completion_tokens)
    print("estimated_cost_usd:", groq_gpt_oss_120b_cost(
        usage.prompt_tokens,
        cached,
        usage.completion_tokens,
    ))

    return response.choices[0].message.content

La documentazione sul caching di Groq mostra cached_tokens sotto usage.prompt_tokens_details e definisce il cache hit rate come cached_tokens / prompt_tokens × 100% (Prompt Caching Groq). Non dare per scontato che ogni seconda richiesta sia più economica. I prefissi esatti contano.

Conteggiare separatamente le chiamate agli strumenti

I prezzi dei token non sono l’intera fattura se abiliti gli strumenti integrati. La pagina dei prezzi di Groq elenca separatamente i Built-In Tools per GPT-OSS: Browser Search basic search costa $5 / 1000 requests, Browser Search visit website costa $1 / 1000 requests e Code Execution Python costa $0.18 / hour (Prezzi Groq).

Questo cambia il modo in cui progetti gli agenti. Un bot di supporto che chiama la ricerca una volta per ogni messaggio utente ha una forma di costo diversa da un summarizer che usa solo token di prompt. La cache aiuta con schemi di strumenti ripetuti, ma non rende gratuite le chiamate a strumenti esterni.

Controlla anche la compatibilità prima di copiare e incollare codice OpenAI. La documentazione di compatibilità OpenAI di Groq elenca campi non supportati che possono restituire 400, tra cui logprobs, logit_bias, top_logprobs, messages[].name e valori di n diversi da 1 (Compatibilità OpenAI di Groq). Groq dice inoltre che temperature=0 viene convertito in 1e-8.

Una richiesta minima sicura appare così:

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    temperature=0.2,
    messages=[
        {"role": "system", "content": "Be precise. If unsure, say so."},
        {"role": "user", "content": "Explain this stack trace and suggest a fix: ..."},
    ],
)

Evita di migrare tutta l’app in un unico commit. Metti le impostazioni del provider dietro variabili d’ambiente:

LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_API_KEY=$GROQ_API_KEY
LLM_MODEL=openai/gpt-oss-120b

Poi collegale all’SDK:

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.environ["LLM_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[{"role": "user", "content": "Summarize this incident report."}],
)

Una via d’uscita pratica multi-provider

Se stai integrando tutto questo in produzione, non hardcodare assunzioni sul provider in tutta la codebase. Tieni base_url, api_key e model nella configurazione. Questo rende Groq facile da testare e rende anche il routing tra provider poco interessante.

Per i team che vogliono un unico endpoint compatibile con OpenAI per Claude, GPT e Gemini, onehop è la strada semplice: cambia l’URL base in https://api.onehop.ai/v1. È compatibile con OpenAI/Anthropic, costa meno dei provider first-party e i nuovi account ricevono $10 gratis senza carta richiesta.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

response = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[
        {"role": "user", "content": "Compare this API design against common REST mistakes."}
    ],
)

print(response.choices[0].message.content)

Usa Groq quando vuoi specificamente inference GPT-OSS veloce e lo stack di strumenti/caching di Groq. Usa onehop quando vuoi un’unica superficie di integrazione su Claude, GPT, Gemini e altri modelli ospitati senza riscrivere il codice client. Puoi chiamare Claude e altri modelli su onehop o registrarti per ottenere $10 di credito gratuito.

Checklist per la produzione

Prima del rilascio, esegui questa checklist:

• Fissa l’ID modello: openai/gpt-oss-120b per la qualità, openai/gpt-oss-20b per il costo inferiore.
• Mantieni per prime le sezioni stabili del prompt così Groq può riutilizzare i prefissi in cache.
• Logga prompt_tokens, cached_tokens e completion_tokens per ogni richiesta.
• Aggiungi una contabilità separata per Browser Search, Visit Website e Code Execution.
• Rimuovi i parametri OpenAI non supportati prima di instradare traffico verso Groq.
• Mantieni base_url configurabile così puoi testare Groq, API first-party o onehop senza toccare la logica di business.

L’intera migrazione può essere una riga. La migrazione affidabile è tre righe più contabilità: URL base, ID modello e telemetria dei costi. Parti da lì, poi decidi se la qualità di 120B vale la spesa in token di output per ogni percorso nella tua app. Se vuoi lo stesso pattern di URL base per accedere a più modelli, chiama Claude e altri modelli su onehop e registrati per ottenere $10 di credito gratuito.