Implementarea streaming-ului în Python
Pe această pagină
De la prototip la producție
Lecția anterioară a acoperit conceptele de streaming SSE. Partea mai dificilă rămâne: transformarea unei bucle demonstrative într-un client care rezistă sub sarcină, supraviețuiește erorilor de rețea și alimentează o interfață web. Această lecție urmează traiectoria reală a unui proiect: mai întâi scheletul, apoi gestionarea erorilor, apoi asincronismul, expunerea HTTP și, în final, măsurarea.
Modelul de bază
Totul începe cu acest schelet de zece linii, pe care îl veți adapta pentru fiecare proiect. Acesta face două lucruri simultan: afișează token-urile pe măsură ce sosesc și le acumulează pentru returnarea funcției.
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:
"""Trimite o cerere de streaming și afișează token-urile în timp real."""
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() # Linie nouă
return full_text
Această versiune funcționează pentru un script local. Are un defect fatal în producție: tipărește în terminal, deci nu poate face nimic altceva decât muncă de terminal.
Gestionarea cuprinzătoare a erorilor
Erorile de rețea, timeout-urile și limitările de rată nu sunt ipotetice: sunt certitudini la scară reală de trafic. Clientul de mai jos rezolvă ambele probleme. Retentează automat erorile 429 cu o strategie de backoff exponențial și nu mai tipărește nimic: emite evenimente tipate prin yield, lăsând apelantul să decidă ce să facă cu ele—să le afișeze, să le push-uiască către un WebSocket sau să le scrie într-o bază de date.
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:
"""Streaming cu retry automat și metrici."""
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 # Backoff exponențial
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
Backoff-ul exponențial 2 ** attempt așteaptă 1 secundă, apoi 2, apoi 4. Această progresie nu este decorativă: dacă toți clienții dumneavoastră ar reîncerca în același ritm fix, ar lovi API-ul în rafale sincronizate și ar prelungi chiar saturația de care suferă. Rețineți, de asemenea, că doar eroarea 429 declanșează o reîncercare—reîncercarea unei erori 401 din cauza unei chei invalide ar doar întârzia diagnosticarea.
Din partea apelantului, consumul devine o simplă citire de evenimente:
messages = [
{"role": "system", "content": "Ești un asistent tehnic."},
{"role": "user", "content": "Explică tiparele de design în Python."}
]
for event in stream_with_retry(messages):
if event["type"] == "token":
print(event["content"], end="", flush=True)
elif event["type"] == "retry":
print(f"\n[Retry {event['attempt']}, așteptare {event['wait']}s...]")
elif event["type"] == "done":
print(f"\n\n--- Terminat ({event['chunks']} chunk-uri, {event['finish_reason']})")
elif event["type"] == "error":
print(f"\n[Eroare: {event['message']}]")
Streaming asincron cu asyncio
Clientul sincron blochează firul său de execuție pe întreaga durată a generării. Pe un server web care trebuie să gestioneze cincizeci de conversații simultane, aceasta înseamnă imobilizarea a cincizeci de fire doar pentru a aștepta. Clientul asincron ridică această constrângere:
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:
"""Streaming asincron pentru aplicații concurente."""
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
# Execuție
async def main():
messages = [{"role": "user", "content": "Salut, prezintă-te."}]
result = await async_stream_chat(messages)
print(f"\nTotal: {len(result)} caractere")
asyncio.run(main())
Logica este identică cu versiunea sincronă; se schimbă doar stream_async, apelul await și bucla async for.
Integrarea cu FastAPI
În continuare, trebuie să scoateți acest stream din procesul dumneavoastră Python și să îl aduceți în browser. FastAPI gestionează acest lucru cu StreamingResponse, cu condiția să reformatați fiecare fragment în formatul SSE văzut în lecția anterioară:
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 pentru 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"
)
Două detalii determină dacă acest endpoint funcționează corect. Dubla linie nouă \n\n care termină fiecare yield este ceea ce separă evenimentele în protocolul SSE: fără ea, browserul așteaptă la infinit un eveniment pe care îl consideră neterminat. Iar media_type="text/event-stream" este ceea ce permite clientului JavaScript să consume răspunsul cu un EventSource în loc de un fetch standard.
Măsurarea performanței
Odată ce stream-ul este pus la punct, veți dori să știți cum se comportă. Două metrici sunt suficiente pentru a conduce optimizarea:
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": "Scrie un paragraf despre Paris."}]
)
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"Time to First Token (TTFT): {first_token_time:.3f}s")
print(f"Token-uri generate: {token_count}")
print(f"Timp total: {total_time:.3f}s")
print(f"Token-uri/secundă: {token_count / total_time:.1f}")
TTFT (Time to First Token)—timpul dintre trimiterea cererii și afișarea primului caracter—este cea mai importantă metrică pentru experiența utilizatorului. Are prioritate față de timpul total: o generare de cincisprezece secunde al cărei prim cuvânt apare în trei zecimi de secundă va părea rapidă, în timp ce o generare de cinci secunde livrată într-un singur bloc va părea lentă. Măsurați-o pe prompturile dumneavoastră reale, inclusiv mesajul de sistem—un mesaj de sistem de două pagini lunghește TTFT înainte ca primul token să fie chiar generat.
Puncte cheie
- Utilizați un model de generator (
yield) pentru a propaga token-urile de streaming - Implementați backoff exponențial pentru erorile 429 (limită de rată)
- Preferați
stream_asyncpentru aplicațiile web concurente - Măsurați TTFT și token-uri/secundă pentru a optimiza performanța
- Cu FastAPI,
StreamingResponse+text/event-streampropagă SSE către browser