Implementacja strumieniowania w Pythonie
Na tej stronie
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_asyncw współbieżnych aplikacjach webowych - Mierz TTFT i liczbę tokenów na sekundę, aby optymalizować wydajność
- W FastAPI kombinacja
StreamingResponse+text/event-streampropaguje SSE do przeglądarki