Salt la conținutul principal
Română— Alege o limbă
Meniu

Streaming: Primirea răspunsurilor în timp real

Lecția 8 din 22 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Streaming: Primirea răspunsurilor în timp real
  2. De ce să folosiți streaming
  3. Evenimente tipizate, nu un flux nediferențiat
  4. Streaming și apelarea funcțiilor
  5. Cazul asincron
  6. Erori în timpul streaming-ului
  7. Puncte cheie

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=True pentru o experiență în timp real
  • Filtrați evenimentele după event.type pentru a gestiona corect fiecare tip de date
  • response.output_text.delta conține fragmente de text
  • response.completed semnalează sfârșitul și include metricile de utilizare
  • Utilizați AsyncOpenAI pentru streaming în aplicațiile asincrone
  • Gestionați întotdeauna erorile, chiar și în modul streaming