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

Implementacja strumieniowania w Pythonie

Lekcja 6 z 16 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Od prototypu do produkcji
  2. Podstawowy wzorzec
  3. Kompleksowa obsługa błędów
  4. Strumieniowanie asynchroniczne z asyncio
  5. Integracja z FastAPI
  6. Pomiar wydajności
  7. Kluczowe wnioski

Od prototypu do produkcji

Poprzednia lekcja omawiała koncepcje strumieniowania SSE. Trudniejsza część dopiero przed Tobą: przekształcenie pętli demonstracyjnej w klienta, który wytrzyma duże obciążenie, przetrwa błędy sieciowe i zasili interfejs webowy. Ta lekcja podąża za rzeczywistą ścieżką projektu – najpierw szkielet, potem obsługa błędów, następnie asynchroniczność, udostępnienie przez HTTP, a na końcu pomiary.

Podstawowy wzorzec

Wszystko zaczyna się od tego dziesięcioliniowego szkieletu, który dostosujesz do każdego projektu. Robi on dwie rzeczy jednocześnie: wyświetla tokeny w miarę ich przybywania i akumuluję je do zwrócenia przez funkcję.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

def stream_chat(messages: list, model: str = "mistral-large-latest") -> str:
    """Wysyła żądanie strumieniowe i wyświetla tokeny w czasie rzeczywistym."""
    stream = client.chat.stream(
        model=model,
        messages=messages
    )

    full_text = ""
    for chunk in stream:
        content = chunk.data.choices[0].delta.content
        if content:
            full_text += content
            print(content, end="", flush=True)

    print()  # Nowa linia
    return full_text

Ta wersja działa dla lokalnego skryptu. Ma jednak fatalną wadę w środowisku produkcyjnym: wypisuje dane do terminala, więc nie może robić nic innego poza pracą w terminalu.

Kompleksowa obsługa błędów

Błędy sieciowe, przekroczenia czasu oczekiwania i limity szybkości (rate limits) nie są hipotetyczne – to pewniki przy rzeczywistym ruchu. Poniższy klient rozwiązuje oba problemy. Automatycznie ponawia żądania przy błędach 429, stosując wykładnicze opóźnienie (exponential backoff), i nie wypisuje już niczego bezpośrednio: zamiast tego emituje typowane zdarzenia poprzez yield, pozostawiając wywołującemu decyzję, co z nimi zrobić – wyświetlić je, przesłać przez WebSocket lub zapisać w bazie danych.

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import os
import time

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

def stream_with_retry(
    messages: list,
    model: str = "mistral-large-latest",
    max_retries: int = 3,
    max_tokens: int = 2000
) -> dict:
    """Strumieniowanie z automatycznym ponawianiem i metrykami."""
    for attempt in range(max_retries):
        try:
            stream = client.chat.stream(
                model=model,
                messages=messages,
                max_tokens=max_tokens
            )

            full_text = ""
            finish_reason = None
            chunk_count = 0

            for chunk in stream:
                delta = chunk.data.choices[0].delta
                if delta.content:
                    full_text += delta.content
                    chunk_count += 1
                    yield {"type": "token", "content": delta.content}

                if chunk.data.choices[0].finish_reason:
                    finish_reason = chunk.data.choices[0].finish_reason

            yield {
                "type": "done",
                "full_text": full_text,
                "finish_reason": finish_reason,
                "chunks": chunk_count
            }
            return

        except SDKError as e:
            if e.status_code == 429 and attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Wykładnicze opóźnienie
                yield {"type": "retry", "wait": wait_time, "attempt": attempt + 1}
                time.sleep(wait_time)
            else:
                yield {"type": "error", "message": str(e), "status": e.status_code}
                return

        except Exception as e:
            yield {"type": "error", "message": str(e), "status": None}
            return

Wykładnicze opóźnienie 2 ** attempt czeka odpowiednio 1 sekundę, potem 2, następnie 4. Ta progresja nie jest ozdobnikiem: gdyby wszyscy Twoi klienci ponawiali próby w tym samym stałym rytmie, uderzaliby w API zsynchronizowanymi falami, przedłużając właśnie to przeciążenie, z którym walczą. Zauważ też, że tylko błąd 429 uruchamia ponowienie – ponawianie błędu 401 spowodowanego nieprawidłowym kluczem jedynie opóźniłoby diagnozę.

Po stronie wywołującego konsumpcja sprowadza się do prostego odczytu zdarzeń:

messages = [
    {"role": "system", "content": "Jesteś asystentem technicznym."},
    {"role": "user", "content": "Wyjaśnij wzorce projektowe w Pythonie."}
]

for event in stream_with_retry(messages):
    if event["type"] == "token":
        print(event["content"], end="", flush=True)
    elif event["type"] == "retry":
        print(f"\n[Ponowienie {event['attempt']}, oczekiwanie {event['wait']}s...]")
    elif event["type"] == "done":
        print(f"\n\n--- Zakończono ({event['chunks']} fragmentów, {event['finish_reason']})")
    elif event["type"] == "error":
        print(f"\n[Błąd: {event['message']}]")

Strumieniowanie asynchroniczne z asyncio

Klient synchroniczny blokuje swój wątek przez cały czas generowania. Na serwerze webowym, który musi obsłużyć pięćdziesiąt równoczesnych rozmów, oznacza to unieruchomienie pięćdziesięciu wątków tylko po to, by czekać. Klient asynchroniczny znosi to ograniczenie:

from mistralai.client import Mistral
import asyncio
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

async def async_stream_chat(messages: list) -> str:
    """Asynchroniczne strumieniowanie dla aplikacji współbieżnych."""
    stream = await client.chat.stream_async(
        model="mistral-large-latest",
        messages=messages
    )

    full_text = ""
    async for chunk in stream:
        content = chunk.data.choices[0].delta.content
        if content:
            full_text += content
            print(content, end="", flush=True)

    print()
    return full_text

# Uruchomienie
async def main():
    messages = [{"role": "user", "content": "Cześć, przedstaw się."}]
    result = await async_stream_chat(messages)
    print(f"\nRazem: {len(result)} znaków")

asyncio.run(main())

Logika jest identyczna jak w wersji synchronicznej; zmieniają się tylko stream_async, słowo kluczowe await przy wywołaniu oraz async for w pętli.

Integracja z FastAPI

Następnie musisz wydostać ten strumień z procesu Pythona i przesłać go do przeglądarki. FastAPI radzi sobie z tym dzięki StreamingResponse, pod warunkiem, że sformatujesz każdy fragment zgodnie z formatem SSE omówionym w poprzedniej lekcji:

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from mistralai.client import Mistral
import os
import json

app = FastAPI()
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

async def generate_stream(prompt: str):
    """Generator SSE dla FastAPI."""
    stream = await client.chat.stream_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )

    async for chunk in stream:
        content = chunk.data.choices[0].delta.content
        if content:
            data = json.dumps({"content": content})
            yield f"data: {data}\n\n"

    yield "data: [DONE]\n\n"

@app.get("/chat/stream")
async def chat_stream(prompt: str):
    return StreamingResponse(
        generate_stream(prompt),
        media_type="text/event-stream"
    )

Dwa szczegóły decydują o tym, czy ten endpoint działa poprawnie. Podwójny znak nowej linii \n\n kończący każde yield to właśnie to, co oddziela zdarzenia w protokole SSE: bez niego przeglądarka czekałaby w nieskończoność na zdarzenie, które uważa za niedokończone. Natomiast media_type="text/event-stream" pozwala klientowi JavaScript konsumować odpowiedź za pomocą EventSource, a nie standardowego fetch.

Pomiar wydajności

Gdy strumieniowanie jest już wdrożone, będziesz chciał wiedzieć, jak sobie radzi. Dwie metryki wystarczą, by kierować optymalizacją:

import time

start = time.perf_counter()
first_token_time = None
token_count = 0

stream = client.chat.stream(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Napisz akapit o Paryżu."}]
)

for chunk in stream:
    if chunk.data.choices[0].delta.content:
        if first_token_time is None:
            first_token_time = time.perf_counter() - start
        token_count += 1

total_time = time.perf_counter() - start

print(f"Czas do pierwszego tokena (TTFT): {first_token_time:.3f}s")
print(f"Wygenerowane tokeny: {token_count}")
print(f"Czas całkowity: {total_time:.3f}s")
print(f"Tokeny na sekundę: {token_count / total_time:.1f}")

TTFT (Time to First Token) – czas między wysłaniem żądania a wyświetleniem pierwszego znaku – to najważniejsza metryka dla doświadczenia użytkownika. Ma ona pierwszeństwo przed czasem całkowitym: generowanie trwające piętnaście sekund, którego pierwsze słowo pojawia się w trzy dziesiąte sekundy, będzie wydawać się szybkie, podczas gdy generowanie pięciosekundowe dostarczone w jednym bloku wyda się wolne. Mierz to na swoich rzeczywistych promptach, łącznie z wiadomością systemową – dwustronicowa wiadomość systemowa wydłuża TTFT, zanim jeszcze zostanie wygenerowany pierwszy token.

Kluczowe wnioski

  • Używaj wzorca generatora (yield) do propagowania tokenów strumieniowych
  • Wdróż wykładnicze opóźnienie dla błędów 429 (limit szybkości)
  • Preferuj stream_async w współbieżnych aplikacjach webowych
  • Mierz TTFT i liczbę tokenów na sekundę, aby optymalizować wydajność
  • W FastAPI kombinacja StreamingResponse + text/event-stream propaguje SSE do przeglądarki