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

Streaming optimizat

Lecția 5 din 20 Actualizată 28 iulie 2026 Avansat
Pe această pagină
  1. Ce modifică de fapt streamingul
  2. Consumul fluxului în partea client
  3. Transmiterea fluxului către browser
  4. Menținerea conexiunii în timp
  5. Puncte cheie

Ce modifică de fapt streamingul

Streamingul nu face modelul mai rapid: face așteptarea suportabilă. Pentru un răspuns care necesită cinci secunde pentru a fi generat, un utilizator fără streaming se uită la un ecran gol timp de cinci secunde înainte de a primi un bloc de text. Cu streaming, utilizatorul vede primele cuvinte după câteva sute de milisecunde și citește pe măsură ce modelul scrie. Durata totală este identică, dar percepția este complet diferită. De aceea, în producție, omiterea streamingului este aproape întotdeauna o eroare de design, nu o alegere conștientă.

Totuși, fluxul trebuie să traverseze întregul lanț. Un flux generat corect de API, dar acumulat de serverul aplicației sau stocat în tampon de proxy-ul invers, ajunge la utilizator într-un singur bloc: ați plătit prețul complexității pentru streaming fără a culege beneficiile. Această lecție urmărește therefore calea completă, de la apelul API până la browser.

Consumul fluxului în partea client

Cu API-ul Responses, setarea stream=True transformă răspunsul într-o secvență de evenimente tipizate pe care le parcurgeți pe măsură ce sosesc. Fiecare fragment de text sosește într-un eveniment response.output_text.delta; sfârșitul fluxului este semnalat de response.completed, care conține obiectul complet al răspunsului, util pentru recuperarea utilizării tokenilor.

import openai

client = openai.OpenAI()

def generate_streaming(prompt: str):
    """Generare cu streaming folosind API-ul Responses."""
    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)
        elif event.type == "response.completed":
            print()  # Linia nouă la final
            return event.response

Flag-ul flush=True nu este cosmetic: fără el, Python stochează ieșirea în tampon, iar dumneavoastră ajungeți cu comportamentul pe blocuri pe care încercați să îl evitați. Acest detaliu se repetă la fiecare strat al lanțului și reprezintă principala dificultate a streamingului.

Mecanismul acoperă, de asemenea, apelurile de funcții. Argumentele instrumentelor sunt construite progresiv, iar dumneavoastră le puteți afișa pe măsură ce sunt generate pentru a semnala utilizatorului că o căutare este în curs de formulare, în loc să îl lăsați să se uite la o interfață înghețată în timp ce modelul își pregătește apelul.

tools = [
    {
        "type": "function",
        "name": "search_product",
        "description": "Caută un produs în catalog.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "category": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

def streaming_with_tools(prompt: str):
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        tools=tools,
        stream=True,
    )

    for event in stream:
        match event.type:
            case "response.output_text.delta":
                print(event.delta, end="", flush=True)
            case "response.function_call_arguments.delta":
                # Argumentele funcției generate în prezent
                print(f"[arg: {event.delta}]", end="")
            case "response.function_call_arguments.done":
                print(f"\n[Apel funcție complet]")

Transmiterea fluxului către browser

Frontend-ul dumneavoastră nu vorbește direct cu API-ul OpenAI – vorbește cu serverul dumneavoastră, care trebuie, prin urmare, să retransmită fluxul. Server-Sent Events (SSE) sunt formatul natural pentru acest lucru: un răspuns HTTP care rămâne deschis, unde fiecare linie data: transportă un fragment JSON. Exemplul următor retransmite textul pe măsură ce sosește, apoi emite un mesaj final conținând numărul de tokeni, permițându-vă să facturați sau să înregistrați jurnale fără un al doilea apel.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import openai
import json

app = FastAPI()
client = openai.OpenAI()

@app.post("/api/chat")
async def chat_streaming(request: dict):
    prompt = request["message"]

    async def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt,
            stream=True,
        )

        for event in stream:
            if event.type == "response.output_text.delta":
                data = json.dumps({"text": event.delta})
                yield f"data: {data}\n\n"
            elif event.type == "response.completed":
                usage = event.response.usage
                data = json.dumps({
                    "end": True,
                    "input_tokens": usage.input_tokens,
                    "output_tokens": usage.output_tokens,
                })
                yield f"data: {data}\n\n"

    return StreamingResponse(
        generate(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",  # Important pentru nginx
        },
    )

Apoi există proxy-ul invers, suspectul obișnuit atunci când „streamingul nu funcționează în producție, deși a funcționat local“. Implicit, nginx acumulează răspunsul backend înainte de a-l transmite. Configurația de mai jos dezactivează acest comportament doar pentru ruta specifică.

location /api/chat {
    proxy_pass http://127.0.0.1:8000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection "";
    chunked_transfer_encoding on;
}

Menținerea conexiunii în timp

Un flux deschis timp de câteva zeci de secunde este mai expus decât un apel scurt: o cădere de rețea, atingerea unei cote, iar generarea se oprește la mijlocul unei propoziții. Strategia dumneavoastră de reîncercare trebuie să distingă între aceste două cazuri, deoarece necesită abordări diferite. O eroare de conexiune trebuie reîncercată cu o pauză exponențială (exponential backoff), oferind rețelei timp să se recupereze fără a agresa API-ul; depășirea cotei trebuie reîncercată după o așteptare fixă, deoarece fereastra limitei de rată se resetează la intervale regulate.

import openai

def resilient_streaming(prompt: str, max_attempts: int = 3):
    """Streaming cu gestionarea erorilor și reîncercare."""
    for attempt in range(max_attempts):
        try:
            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
                    yield event.delta

            return  # Succes, ieșire

        except openai.APIConnectionError:
            if attempt < max_attempts - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise
        except openai.RateLimitError:
            import time
            time.sleep(5)  # Așteptare fixă pentru limita de rată

O ultimă ajustare îmbunătățește confortul lecturii. Emiterea fiecărui token produce un text sacadat, mai ales dacă interfața dumneavoastră aplică o animație sau dacă rezultatul merge către sinteza vocală (text-to-speech). Acumularea până la sfârșitul unei propoziții oferă un ritm mai apropiat de lectura umană, cu costul unei ușoare întârzieri suplimentare la primul fragment.

def streaming_by_sentence(prompt: str):
    """Acumulează și livrează pe propoziții complete."""
    buffer = ""

    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            buffer += event.delta
            # Caută sfârșitul propoziției
            for separator in [".\n", "!\n", "?\n", ". ", "! ", "? "]:
                if separator in buffer:
                    parts = buffer.split(separator, 1)
                    yield parts[0] + separator.rstrip()
                    buffer = parts[1] if len(parts) > 1 else ""

    if buffer.strip():
        yield buffer.strip()

Rețineți condiția finală if buffer.strip(): fără ea, un răspuns care nu se termină cu o punctuație puternică și-ar pierde ultimele cuvinte. Acest gen de scăpare trece neobservat în testare și se manifestă în producție la răspunsurile trunchiate de max_output_tokens.

Puncte cheie

  • Utilizați întotdeauna streamingul în producție pentru a reduce latența percepută
  • Configurați nginx cu proxy_buffering off pentru SSE
  • Gestionați erorile cu reîncercare și pauză exponențială
  • Acumulați pe propoziții pentru o afișare mai naturală