Flux SSE
Pe această pagină
Primirea răspunsurilor în timp real
În mod implicit, API-ul așteaptă generarea completă a răspunsului înainte de a-l returna. Prin utilizarea fluxului (streaming), primiți tokenii pe măsură ce sunt generați. Această tehnică reduce timpul de așteptare perceput de utilizatori și vă permite să afișați răspunsurile progresiv, exact cum interfața Grok.
Cum funcționează fluxul
Fluxul utilizează protocolul Server-Sent Events (SSE). În loc de un singur răspuns HTTP, serverul trimite un flux continuu de evenimente. Fiecare eveniment conține un fragment al răspunsului, iar clientul le asamblează pentru a reconstrui textul complet.
Parametrul stream: true activează acest mod pentru orice endpoint de generare.
Fluxul în Python cu SDK-ul OpenAI
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
stream = client.chat.completions.create(
model="grok-4.5",
messages=[
{"role": "user", "content": "Explain the SOLID principles in programming."}
],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print() # Final line break
Cum funcționează codul
stream=Trueactivează fluxul- Răspunsul este un iterator de obiecte
chunk(fragmente) - Fiecare fragment conține un
deltacu noul conținut end=""previne adăugarea de rânduri noi între fragmenteflush=Trueforțează afișarea imediată
Fluxul cu endpoint-ul /v1/responses
stream = client.responses.create(
model="grok-4.5",
input="Describe the steps to deploy a web application.",
stream=True
)
for event in stream:
if hasattr(event, 'type') and event.type == 'response.output_text.delta':
print(event.delta, end="", flush=True)
print()
Endpoint-ul /v1/responses utilizează evenimente tipizate. Tipul response.output_text.delta conține fragmentele de text.
Fluxul cu cURL
cURL suportă nativ fluxul SSE. Adăugați "stream": true în corpul cererii:
curl -N https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.5",
"messages": [{"role": "user", "content": "Hello"}],
"stream": true
}'
Opțiunea -N dezactivează bufferizarea cURL, astfel încât evenimentele sunt afișate imediat ce sosesc.
Fiecare linie a fluxului SSE începe cu data: urmat de un obiect JSON. Ultimul eveniment este data: [DONE], care semnalează sfârșitul generării.
Când să utilizați fluxul
Decizia se reduce la o singură întrebare: există o persoană care urmărește sosirea răspunsului? Dacă da (un chatbot, un asistent, un instrument de scriere), fluxul este quasi-obligatoriu: utilizatorii văd textul apărând cuvânt cu cuvânt în loc să privească un ecran înghețat, iar la un răspuns lung, diferența dintre „primul cuvânt în 300 ms“ și „tot textul după 8 secunde“ schimbă complet experiența percepută.
Dacă nimeni nu urmărește, fluxul nu aduce niciun beneficiu și complică codul. Un job batch care populatează o bază de date, o pipeline automatizată care trebuie să parseze răspunsul complet înainte de a acționa, un apel care returnează doar câțiva cuvinte: în toate aceste cazuri, apelul clasic (o cerere, un răspuns complet) rămâne mai simplu de scris, testat și depanat.
Gestionarea erorilor în flux
În modul flux, erorile pot apărea la mijlocul stream-ului. Codul dumneavoastră trebuie să gestioneze aceste întreruperi:
try:
stream = client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": "Test"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
except Exception as e:
print(f"\nError during streaming: {e}")
Puncte cheie
- Adăugați
stream=Truepentru a primi tokenii pe măsură ce sunt generați - Protocolul utilizat este SSE (Server-Sent Events)
- În Python, iterați peste fragmente și afișați
delta.content - Cu cURL, utilizați
-Npentru a dezactiva bufferizarea - Rezervați fluxul pentru cazurile în care afișarea progresivă aduce valoare