Przejdź do głównej treści
Polski— Wybierz język
Menu

Strumieniowanie zoptymalizowane

Lekcja 5 z 20 Zaktualizowano 28 lipca 2026 Zaawansowany
Na tej stronie
  1. Co tak naprawdę zmienia strumieniowanie
  2. Pobieranie strumienia po stronie klienta
  3. Przekazywanie strumienia do przeglądarki
  4. Utrzymanie połączenia w czasie
  5. Kluczowe wnioski

Co tak naprawdę zmienia strumieniowanie

Strumieniowanie nie przyspiesza działania modelu: sprawia jedynie, że oczekiwanie jest znośne. Przy odpowiedzi generowanej przez pięć sekund użytkownik bez strumieniowania wpatruje się w pusty ekran przez cały ten czas, zanim otrzyma blok tekstu. Dzięki strumieniowaniu widzi pierwsze słowa już po kilkuset milisekundach i czyta na bieżąco, w miarę jak model pisze. Całkowity czas trwania jest identyczny, ale odczucie użytkownika zupełnie inne. Dlatego w środowisku produkcyjnym pominięcie strumieniowania to niemal zawsze błąd projektowy, a nie świadomy wybór.

Strumień musi jednak przepływać przez cały łańcuch. Strumień poprawnie wygenerowany przez API, ale zbuforowany przez serwer aplikacji lub serwer proxy, dotrze do użytkownika jako pojedynczy blok: zapłacisz cenę złożoności za wdrożenie strumieniowania, nie czerpiąc z niego żadnych korzyści. Ta lekcja prześledzi zatem całą ścieżkę, od wywołania API aż po przeglądarkę.

Pobieranie strumienia po stronie klienta

W przypadku Responses API ustawienie stream=True przekształca odpowiedź w sekwencję typowanych zdarzeń, przez które iterujesz w miarę ich napływania. Każdy fragment tekstu przychodzi w zdarzeniu response.output_text.delta; koniec strumienia sygnalizuje response.completed, które niesie pełny obiekt odpowiedzi, przydatny do pobrania zużycia tokenów.

import openai

client = openai.OpenAI()

def generate_streaming(prompt: str):
    """Generowanie strumieniowe z Responses API."""
    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()  # Nowa linia na końcu
            return event.response

Flaga flush=True nie jest kosmetyczna: bez niej Python sam buforuje wyjście i kończysz z zachowaniem blokowym, którego chciałeś uniknąć. Ten szczegół powtarza się na każdej warstwie łańcucha i stanowi główne wyzwanie przy strumieniowaniu.

Mechanizm ten obejmuje również wywołania funkcji. Argumenty narzędzi są budowane stopniowo, więc możesz wyświetlać je na bieżąco, sygnalizując użytkownikowi, że formułowane jest zapytanie wyszukiwania, zamiast zostawiać go z zamarzniętym interfejsem, podczas gdy model przygotowuje wywołanie.

tools = [
    {
        "type": "function",
        "name": "search_product",
        "description": "Wyszukuje produkt w katalogu.",
        "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":
                # Argumenty funkcji obecnie generowane
                print(f"[arg: {event.delta}]", end="")
            case "response.function_call_arguments.done":
                print(f"\n[Wywołanie funkcji zakończone]")

Przekazywanie strumienia do przeglądarki

Twój frontend nie rozmawia bezpośrednio z API OpenAI – komunikuje się z Twoim serwerem, który musi zatem przekazać strumień dalej. Server-Sent Events (SSE) są naturalnym formatem do tego celu: odpowiedź HTTP, która pozostaje otwarta, gdzie każda linia data: niesie fragment JSON. Poniższy przykład przekazuje tekst na bieżąco, a następnie emituje końcową wiadomość zawierającą liczbę tokenów, co pozwala na rozliczenie lub logowanie bez konieczności drugiego wywołania.

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",  # Ważne dla nginx
        },
    )

Pozostaje jeszcze serwer proxy zwrotny – zwykły podejrzany, gdy „strumieniowanie nie działa w produkcji, choć lokalnie działało“. Domyślnie nginx akumuluję odpowiedź z backendu przed jej transmisją. Poniższa konfiguracja wyłącza to zachowanie wyłącznie dla określonej ścieżki.

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;
}

Utrzymanie połączenia w czasie

Strumień otwarty przez kilkadziesiąt sekund jest bardziej narażony niż krótkie wywołanie: przerwa w sieci, osiągnięcie limitu quota i generowanie urywa się w połowie zdania. Twoja strategia ponawiania musi rozróżniać te dwa przypadki, ponieważ wymagają one różnych podejść. Błąd połączenia należy ponowić z wykładniczym opóźnieniem (exponential backoff), dając sieci czas na odzyskanie sprawności bez atakowania API; przekroczenie limitu quota należy ponowić po ustalonym czasie oczekiwania, ponieważ okno limitu szybkości resetuje się w regularnych odstępach.

import openai

def resilient_streaming(prompt: str, max_attempts: int = 3):
    """Strumieniowanie z obsługą błędów i ponawianiem."""
    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  # Sukces, wyjście

        except openai.APIConnectionError:
            if attempt < max_attempts - 1:
                import time
                time.sleep(2 ** attempt)  # Wykładnicze opóźnienie
            else:
                raise
        except openai.RateLimitError:
            import time
            time.sleep(5)  # Stałe oczekiwanie na limit szybkości

Ostatni zabieg poprawia komfort czytania. Emitowanie każdego tokenu powoduje szarpany tekst, zwłaszcza jeśli interfejs stosuje animację lub wynik trafia do syntezy mowy (text-to-speech). Akumulowanie do końca zdania nadaje rytm bliższy ludzkiemu czytaniu, kosztem niewielkiego dodatkowego opóźnienia przy pierwszym fragmencie.

def streaming_by_sentence(prompt: str):
    """Akumulowanie i zwracanie całych zdań."""
    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
            # Szukaj końca zdania
            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()

Zwróć uwagę na końcowe if buffer.strip(): bez niego odpowiedź, która nie kończy się mocnym znakiem interpunkcyjnym, straciłaby ostatnie słowa. Tego rodzaju przeoczenie umyka podczas testów i ujawnia się w produkcji przy odpowiedziach uciętych przez max_output_tokens.

Kluczowe wnioski

  • Zawsze używaj strumieniowania w produkcji, aby zmniejszyć postrzegane opóźnienie
  • Skonfiguruj nginx z proxy_buffering off dla SSE
  • Obsługuj błędy za pomocą ponawiania i wykładniczego opóźnienia
  • Akumuluj tekst do końca zdania dla bardziej naturalnego wyświetlania