Streaming SSE
Pe această pagină
Răspunsuri în timp real cu Server-Sent Events
În mod implicit, API-ul Chat Completions așteaptă ca modelul să termine de generat întregul răspuns înainte de a vi-l returna. Pentru o întrebare scurtă, nimeni nu observă întârzierea. Pentru un raport de o mie de cuvinte, însă, acest lucru înseamnă câteva secunde de ecran gol, lăsând utilizatorul să se întrebe dacă aplicația s-a blocat. Streaming-ul rezolvă această problemă prin trimiterea tokenilor pe măsură ce sunt generați, creând efectul familiar de mașină de scris întâlnit în interfețele conversaționale.
Protocolul utilizat este Server-Sent Events (SSE), un standard HTTP care permite serverului să împingă date către client în mod continuu, printr-o conexiune persistentă. Nu este nimic exotic aici: nu trebuie instalate WebSocket-uri, nici dependențe suplimentare.
Streaming vs. non-streaming
În modul non-streaming, care este cel implicit, clientul trimite cererea și așteaptă răspunsul complet:
Client ──── request ────► Server
(wait 3-10s)
Client ◄── complete response ── Server
Avantajul este simplitatea: răspunsul este atomic, un singur obiect JSON ușor de procesat, validat și stocat. Dezavantajul este la fel de clar: latența percepută este mare, deoarece utilizatorul nu vede nimic pe durata întregului proces de generare.
În modul streaming, serverul trimite tokenii unul câte unul, sau în grupuri mici:
Client ──── request ────► Server
Client ◄── chunk 1 ─────── Server (after ~200ms)
Client ◄── chunk 2 ─────── Server (after ~250ms)
Client ◄── chunk 3 ─────── Server (after ~300ms)
...
Client ◄── [DONE] ──────── Server
Latența percepută scade dramatic—primul caracter apare în câteva sute de milisecunde—îmbunătățind semnificativ experiența utilizatorului. În schimb, trebuie să reconstruiți mesajul latoarea clientului și să gestionați o stare care nu mai sosește ca un bloc unic.
Protocolul SSE în detaliu
Iată cum arată efectiv fluxul HTTP pe care îl primiți:
data: {"id":"cmpl-abc","choices":[{"delta":{"content":"Hello"}}],"usage":null}
data: {"id":"cmpl-abc","choices":[{"delta":{"content":" "}}],"usage":null}
data: {"id":"cmpl-abc","choices":[{"delta":{"content":"!"}}],"usage":null}
data: [DONE]
Fiecare linie începe cu data: urmat de un obiect JSON, iar liniile goale servesc drept separatori între evenimente. Rețineți detaliul care îi prinde pe toți la prima implementare: fragmentul de text se află în câmpul delta, nu în message ca în modul clasic. Fluxul se termină cu un eveniment data: [DONE], care semnalează explicit sfârșitul. Fără acesta, nu ați putea distinge o generare terminată de o conexiune întreruptă.
Activarea streaming-ului în Python
Cu SDK-ul Mistral, activați streaming-ul apelând chat.stream() în loc de chat.complete():
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
stream = client.chat.stream(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "Explain how an electric motor works."}
]
)
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
print(content, end="", flush=True)
print() # Final newline
Argumentul flush=True merită o explicație, deoarece uitarea lui este cauza clasică a unui streaming care „nu funcționează“. Fără el, Python păstrează caracterele în buffer și le afișează în blocuri. Acest lucru anulează vizual toate beneficiile streaming-ului, chiar dacă fragmentele sosesc corect.
Structura unui fragment (chunk)
Un fragment de streaming nu se citește ca un răspuns complet, iar căile de acces diferă:
# Non-streaming: response.choices[0].message.content
# Streaming: chunk.data.choices[0].delta.content
# Primul fragment conține adesea rolul
# chunk.data.choices[0].delta.role == "assistant"
# Fragmentele ulterioare conțin fragmente de text
# chunk.data.choices[0].delta.content == "Hello"
# Ultimul fragment conține finish_reason
# chunk.data.choices[0].finish_reason == "stop"
Primul fragment poartă de obicei rolul fără text, cele ulterioare conțin fragmente, iar ultimul oferă finish_reason. De aceea, verificarea if content: din codul anterior nu este o precauție inutilă: concatenarea unei valori None ar face bucla să eșueze la prima iterație.
Reconstrucția răspunsului complet
Afișarea fragmentelor nu este suficientă atunci când trebuie să păstrați răspunsul—de exemplu, pentru a-l adăuga la istoricul conversației, a-l jurnaliza sau a-l stoca într-o bază de date. Trebuie deci să acumulați textul în paralel cu afișarea acestuia:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
stream = client.chat.stream(
model="mistral-large-latest",
messages=[{"role": "user", "content": "List 5 programming languages."}]
)
full_response = ""
finish_reason = None
for chunk in stream:
delta = chunk.data.choices[0].delta
if delta.content:
full_response += delta.content
print(delta.content, end="", flush=True)
if chunk.data.choices[0].finish_reason:
finish_reason = chunk.data.choices[0].finish_reason
print(f"\n\nFinish reason: {finish_reason}")
print(f"Complete response ({len(full_response)} characters)")
Variabila finish_reason este capturată în aceeași buclă din același motiv ca în modul clasic: un răspuns trunchiat de max_tokens apare pe ecran exact ca un răspuns complet, iar doar acest câmp vă va spune diferența.
Când să utilizați streaming-ul
Streaming-ul nu este întotdeauna mai bun. Este indicat ori de câte ori un om privește ecranul, dar superfluu sau chiar dăunător atunci când o mașină procesează ieșirea.
| Caz de utilizare | Recomandare |
|---|---|
| Chatbot interactiv | Streaming (UX mai bun) |
| Procesare în lot (Batch) | Non-streaming (mai simplu) |
| API Backend pentru frontend | Streaming (SSE către browser) |
| Pipeline de date | Non-streaming (procesare atomică) |
| Extragere structurată | Non-streaming (parsare JSON mai fiabilă) |
Ultimul caz este cel mai instructiv. Dacă așteptați JSON, streaming-ul nu aduce nimic: nu puteți parsea un obiect incomplet și va trebui să așteptați oricum ultimul fragment. La fel de bine puteți păstra apelul atomic și codul simplu.
Puncte cheie
- Streaming-ul reduce latența percepută prin trimiterea tokenilor pe măsură ce sunt generați
- Protocolul SSE este un standard HTTP simplu și robust
- În modul streaming, utilizați
delta.contentîn loc demessage.content - Acumulați fragmentele latoarea clientului pentru a reconstrui răspunsul complet
- Preferați streaming-ul pentru interfețele cu utilizatorul și non-streaming-ul pentru procesarea automată