Streaming: Primirea răspunsurilor în timp real
Pe această pagină
Streaming: Primirea răspunsurilor în timp real
Streaming-ul vă permite să primiți răspunsul token cu token, în loc să așteptați finalizarea întregii generări. Aceasta nu este doar o îmbunătățire a interfeței: este ceea ce face diferența dintre un chatbot care pare lent și unul care pare rapid, chiar și atunci când performanța serverului este identică.
De ce să folosiți streaming
Fără streaming, utilizatorii privesc uneori un ecran gol timp de zece până la treizeci de secunde înainte ca întregul răspuns să apară dintr-o dată. Cu streaming, primele cuvinte apar în mai puțin de o secundă, iar citirea începe în timp ce generarea continuă. Durata totală este aceeași; percepția nu este. Activarea necesită un singur parametru, stream=True, care transformă valoarea returnată de create() într-un iterator de evenimente.
from openai import OpenAI
client = OpenAI()
# FĂRĂ streaming — așteptați totul
response = client.responses.create(
model="gpt-5.6-terra",
input="Write a paragraph about artificial intelligence."
)
print(response.output_text) # Apare totul dintr-o dată după așteptare
# CU streaming — token cu token
stream = client.responses.create(
model="gpt-5.6-terra",
input="Write a paragraph about artificial intelligence.",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
print() # Linia nouă la final
Evenimente tipizate, nu un flux nediferențiat
Fluxul nu transportă doar text. Vă notifică atunci când răspunsul este creat, când fiecare element de ieșire este adăugat, când sosesc fragmente și când are loc finalizarea — evenimentul final include metricile de utilizare. Filtrați după event.type pentru a ști ce gestionați. Această structură vă permite, de exemplu, să afișați un indicator de încărcare imediat ce se declanșează response.created și să numărați tokenii la final fără o a doua apelare API.
stream = client.responses.create(
model="gpt-5.6-terra",
input="Hello!",
stream=True
)
for event in stream:
match event.type:
case "response.created":
print(f"[Response created] ID: {event.response.id}")
case "response.output_item.added":
print(f"[New output item]")
case "response.output_text.delta":
print(f"[Text] {event.delta}", end="")
case "response.output_text.done":
print(f"\n[Text complete]")
case "response.completed":
print(f"[Done] Tokens: {event.response.usage.total_tokens}")
# Output:
# [Response created] ID: resp_abc123
# [New output item]
# [Text] Hello[Text] ! [Text] How[Text] can[Text] I...
# [Text complete]
# [Done] Tokens: 25
Într-o aplicație reală, veți dori aproape întotdeauna să faceți două lucruri simultan: să afișați fragmentele și să reconstruiți textul complet pentru a-l putea arhiva sau returna apelantului. Regula este simplă: acumulați în timp ce iterați, deoarece odată ce fluxul este consumat, acesta nu poate fi derulat înapoi.
def stream_and_collect(prompt: str) -> str:
"""Stream the response while collecting it."""
stream = client.responses.create(
model="gpt-5.6-terra",
input=prompt,
stream=True
)
full_text = ""
for event in stream:
if event.type == "response.output_text.delta":
full_text += event.delta
print(event.delta, end="", flush=True)
print() # Linia nouă
return full_text
result = stream_and_collect("List 3 European capitals.")
print(f"\nCollected text ({len(result)} characters)")
Streaming și apelarea funcțiilor
Apelurile de funcții sunt, de asemenea, transmise prin streaming, având propriile evenimente: argumentele sosesc în fragmente prin response.function_call_arguments.delta, iar response.function_call_arguments.done semnalează că JSON-ul este complet. Acest lucru are o consecință practică importantă — nu încercați niciodată să deserializați argumentele înainte de evenimentul done, altfel veți avea doar un JSON trunchiat.
stream = client.responses.create(
model="gpt-5.6-terra",
input="What time is it in Tokyo?",
tools=[{
"type": "function",
"name": "get_time",
"description": "Get the time in a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}],
stream=True
)
for event in stream:
match event.type:
case "response.output_text.delta":
print(event.delta, end="")
case "response.function_call_arguments.delta":
print(f"[Args] {event.delta}", end="")
case "response.function_call_arguments.done":
print(f"\n[Function call complete]")
# Output:
# [Args] {"city": "Tokyo"}
# [Function call complete]
Cazul asincron
Imediat ce aplicația dumneavoastră deservește mai mulți utilizatori simultan, treceți la AsyncOpenAI: clientul sincron ar bloca bucla de evenimente pe întreaga durată a generării, determinând celelalte cereri să aștepte. Sintaxa diferă prin doar două cuvinte cheie — await la creare și async for la iterare.
from openai import AsyncOpenAI
import asyncio
async_client = AsyncOpenAI()
async def stream_async(prompt: str):
"""Asynchronous streaming of the response."""
stream = await async_client.responses.create(
model="gpt-5.6-terra",
input=prompt,
stream=True
)
async for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
print()
asyncio.run(stream_async("Tell a short joke."))
Pe web, streaming-ul este inutil dacă se oprește la serverul dumneavoastră: trebuie să îl extindeți până la browser. FastAPI permite acest lucru cu StreamingResponse, alimentat de un generator care retransmite fragmentele pe măsură ce sosesc.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from openai import OpenAI
app = FastAPI()
client = OpenAI()
@app.get("/chat")
async def chat(question: str):
def generate():
stream = client.responses.create(
model="gpt-5.6-terra",
input=question,
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
yield event.delta
return StreamingResponse(generate(), media_type="text/plain")
Erori în timpul streaming-ului
Un detaliu merită atenția dumneavoastră: în streaming, o eroare poate apărea după ce fragmentele au fost deja afișate. Utilizatorul vede apoi un răspuns care începe, dar este întrerupt. Prin urmare, încadrați iterarea însăși, nu doar crearea fluxului, astfel încât să puteți semnala clar întreruperea, în loc să lăsați o propoziție neterminată.
from openai import APIError
def stream_with_errors(prompt: str):
"""Streaming with robust error handling."""
try:
stream = client.responses.create(
model="gpt-5.6-terra",
input=prompt,
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
print()
except APIError as e:
print(f"\nAPI error during streaming: {e.message}")
except Exception as e:
print(f"\nUnexpected error: {e}")
stream_with_errors("Explain streaming in 2 sentences.")
Puncte cheie
- Activați streaming-ul cu
stream=Truepentru o experiență în timp real - Filtrați evenimentele după
event.typepentru a gestiona corect fiecare tip de date response.output_text.deltaconține fragmente de textresponse.completedsemnalează sfârșitul și include metricile de utilizare- Utilizați
AsyncOpenAIpentru streaming în aplicațiile asincrone - Gestionați întotdeauna erorile, chiar și în modul streaming