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

Implementarea streaming-ului în Python

Lecția 6 din 16 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De la prototip la producție
  2. Modelul de bază
  3. Gestionarea cuprinzătoare a erorilor
  4. Streaming asincron cu asyncio
  5. Integrarea cu FastAPI
  6. Măsurarea performanței
  7. Puncte cheie

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_async pentru aplicațiile web concurente
  • Măsurați TTFT și token-uri/secundă pentru a optimiza performanța
  • Cu FastAPI, StreamingResponse + text/event-stream propagă SSE către browser