Cosa ti offre lo streaming
Senza streaming, l'API trattiene l'intera risposta finché il modello non termina, poi la invia come un unico corpo JSON. Per una risposta lunga questo può significare molti secondi di schermo vuoto. Con stream: true il server invia la stessa risposta come una serie di piccoli eventi, ciascuno contenente alcuni caratteri della risposta, e la tua UI può stamparli mentre arrivano.
Il formato del wire sono gli eventi server-sent (SSE) su una normale risposta HTTP. Ogni evento è una riga che inizia con data: seguita da un chunk JSON, e lo stream termina con data: [DONE]. Raramente analizzi questo manualmente, perché gli SDK OpenAI lo fanno per te. Se vuoi vedere i byte grezzi, la panoramica per gli sviluppatori mostra la struttura dell'endpoint e la documentazione API elenca ogni parametro.
Ci sono due cose da decidere prima di scrivere il codice. Primo, chi legge lo stream: un browser che parla con il tuo server, o solo il tuo server. Secondo, cosa fare quando la connessione si interrompe a metà. Il resto di questa pagina copre entrambi i casi.
Python: streaming con l'SDK OpenAI
Installa l'SDK con pip install openai, crea un client con il nostro base URL e passa stream=True. L'ID del modello è uncensored.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key="YOUR_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
stream=True,
)
text = []
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text.append(piece)
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
print("tokens:", usage)
Nota il guard chunk.choices and .... L'ultimo chunk con usage può avere una lista choices vuota, causando un errore. Raccogliere i pezzi in una lista e unirli alla fine è più efficiente.
Node: la stessa chiamata in JavaScript
Con il pacchetto ufficiale openai per Node lo stream è un iteratore asincrono. Questo esempio usa i moduli ES.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses for a stream." }],
stream: true,
});
let full = "";
let usage = null;
for await (const chunk of stream) {
const piece = chunk.choices?.[0]?.delta?.content;
if (piece) {
full += piece;
process.stdout.write(piece);
}
if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);
Se non vuoi l'SDK, fetch funziona anche: invia lo stesso corpo JSON con stream: true, poi leggi response.body con un TextDecoder e dividi sulle righe vuote. L'SDK ti salva dalla gestione di eventi tagliati a metà al confine di un chunk, che è il bug usuale nei parser scritti a mano.
Lettura di utilizzo e saldo
L'utilizzo viene segnalato alla fine dello stream. Quello è il numero da registrare per il tracciamento dei costi, perché è quello contro cui viene addebitato il tuo saldo. A $0,15 per 1M token di input e $0,50 per 1M token di output, una risposta con 1.200 token di input e 800 token di output costa 1.200 x 0,15 / 1.000.000 + 800 x 0,50 / 1.000.000 = $0,00018 + $0,0004 = $0,00058.
Ogni risposta trasporta anche un'intestazione X-Balance-USD con il tuo credito residuo, così puoi mostrare un avviso di saldo basso senza una seconda richiesta. Puoi anche chiamare GET /v1/balance con un timer. Le richieste fallite o rifiutate non vengono addebitate, il che significa che un errore prima del primo token non costa nulla.
Le stesse intestazioni di risposta includono X-Request-Id. Salvalo accanto alla tua riga di log per ogni stream. Se uno stream si comporta in modo strano, quell'ID è quello che dai al supporto tecnico per trovare la richiesta.
Stream interrotti e cosa fare
Gli stream si interrompono. Un telefono passa dal Wi-Fi ai dati mobili, un proxy chiude una connessione inattiva, un utente chiude la scheda. Pianificalo fin dall'inizio.
Conserva il testo parziale
Accoda ogni pezzo a un buffer mentre arriva e salva il buffer quando il ciclo termina o genera un'eccezione. Se lo stream è fallito, hai una risposta parziale utilizzabile. Mostrala con un pulsante di retry invece di scartarla.
Riprova o continua
Il recupero più semplice è reinviare la richiesta originale. Per una risposta breve va bene. Per una lunga, puoi inviare il testo parziale salvato come messaggio dell'assistente e chiedere al modello di continuare da dove si è fermato. Il risultato potrebbe non corrispondere a quanto avrebbe prodotto il primo stream, quindi trattalo come un best effort e etichettalo nella tua UI se l'esattezza è importante.
Chiudi ciò che abbandoni
Una richiesta in streaming occupa il suo slot di concorrenza fino alla fine dello stream. Una chiave completa permette 8 richieste alla volta, e una chiave di prova solo 2. Se il tuo server continua a leggere uno stream per un utente che se n'è andato, quello slot rimane occupato. Annulla la richiesta quando il client si disconnette. In Python, chiama stream.close(); in Node, chiama stream.controller.abort().
Inoltro di uno stream a un browser
Non mettere mai la tua chiave API nel codice del browser. La configurazione usuale è un piccolo endpoint sul tuo server che chiama l'API con stream: true e inoltra ogni pezzo alla pagina. In Node con Express, imposta Content-Type: text/event-stream, scrivi ogni pezzo come data: ... seguito da una riga vuota, e ascolta l'evento close sulla richiesta per abortire la chiamata al server upstream. Sulla pagina, EventSource gestisce gli endpoint GET, mentre fetch con un reader gestisce i corpi POST, che è ciò di cui hai bisogno quando invii una cronologia dei messaggi.
Conserva la cronologia dei messaggi sul tuo server o nel corpo della richiesta, e taglia i turni più vecchi quando la conversazione diventa lunga. La finestra di contesto è di 100.000 token per prompt più completamento, che è molto per una chat, ma una sessione di lunga durata la raggiungerà prima o poi.
Limiti di velocità durante lo streaming
I limiti sono 300 richieste al minuto e 8 richieste concorrenti su una chiave completa, e 60 al minuto e 2 concorrenti su una chiave di prova. Superare i limiti restituisce HTTP 429. Il codice di errore ti dice quale limite hai colpito: rate_limited significa troppe richieste al minuto, e concurrency significa troppe contemporaneamente. In caso di sovraccarico temporaneo l'API restituisce anche 429 con un'intestazione Retry-After: 5.
Poiché un 429 arriva prima che vengano trasmessi token, gestiscilo prima di iniziare a leggere. Un piccolo wrapper di retry è sufficiente:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")
def open_stream(messages, tries=4):
for n in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, stream=True
)
except RateLimitError as e:
wait = 5 if n == 0 else 5 * (n + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
Per le app di chat con molti utenti, la vera soluzione per gli errori concurrency è una piccola coda dal tuo lato che permette non più di 8 stream live alla volta.
Checklist prima di rilasciare una chat in streaming
- Proteggi contro
choicesvuoti nell'ultimo chunk. - Bufferizza il testo parziale e persistilo in caso di errore.
- Annulla la richiesta upstream quando il browser si disconnette.
- Limita gli stream live al tuo limite di concorrenza.
- Registra l'utilizzo e l'ID della richiesta per ogni stream.
- Disabilita il buffering della risposta su qualsiasi reverse proxy davanti al tuo server, altrimenti i token arriveranno a raffiche.
L'ultimo punto crea problemi in molte prime implementazioni. Nginx, ad esempio, memorizza in buffer le risposte proxy per impostazione predefinita, quindi lo streaming funziona in localhost e sembra bloccato in produzione finché il buffering non viene disabilitato per quella route. Per l'output JSON invece che testo libero, vedi le note sulla modalità JSON. Per provare il codice sopra, crea una chiave API; i nuovi account possono richiedere $0,50 di credito di prova con un clic, valido per 7 giorni. Le ricariche sono solo in cripto (USDT su TRC20 o USDC su Base), da $20.
