Implementiraj streaming u Pythonu
Na ovoj stranici
Od prototipa do proizvodnje
Prethodna lekcija pokrila je koncepte SSE streaminga. Teži dio tek slijedi: pretvorba demo petlje u klijenta koji izdržava opterećenje, preživljava mrežne pogreške i napaja web sučelje. Ova lekcija prati stvarni tijek projekta—prvo kostur, zatim rukovanje pogreškama, potom asinkronost, izlaganje putem HTTP-a i na kraju mjerenje.
Osnovni obrazac
Sve počinje s ovim kosturom od deset redaka koji ćeš prilagoditi za svaki projekt. On radi dvije stvari odjednom: prikazuje tokene kako stižu i akumulira ih za povratnu vrijednost funkcije.
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:
"""Šalje streaming zahtjev i prikazuje tokene u stvarnom vremenu."""
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() # Novi redak
return full_text
Ova verzija radi za lokalnu skriptu. Ima kobnu manu u proizvodnji: ispisuje u terminal, pa ne može raditi ništa osim terminalskih zadataka.
Sveobuhvatno rukovanje pogreškama
Mrežne pogreške, isteci vremena i ograničenja brzine nisu hipotetski scenariji: oni su sigurni pri stvarnom prometu. Donji klijent rješava oba problema. Automatski ponavlja 429 pogreške s eksponencijalnim kašnjenjem i više ništa ne ispisuje: emitira tipizirane događaje putem yield, prepuštajući pozivatelju da odluči što s njima—prikazati ih, poslati na WebSocket ili zapisati u bazu podataka.
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 s automatskim ponavljanjem i metrikama."""
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 # Eksponencijalno kašnjenje
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
Eksponencijalno kašnjenje 2 ** attempt čeka 1 sekundu, zatim 2, pa 4. Ovaj napredak nije dekorativan: da svi tvoji klijenti pokušavaju ponovno u istom fiksnom ritmu, udarali bi u API u sinkroniziranim naletima i produljili bi upravo ono zasićenje od kojeg pate. Imaj na umu i da samo pogreška 429 pokreće ponavljanje—ponavljanje 401 zbog neispravnog ključa samo bi odgodilo dijagnostiku.
Na strani pozivatelja, potrošnja postaje jednostavno čitanje događaja:
messages = [
{"role": "system", "content": "You are a technical assistant."},
{"role": "user", "content": "Explain design patterns in 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']}, waiting {event['wait']}s...]")
elif event["type"] == "done":
print(f"\n\n--- Done ({event['chunks']} chunks, {event['finish_reason']})")
elif event["type"] == "error":
print(f"\n[Error: {event['message']}]")
Asinkroni streaming s asyncio
Sinkroni klijent blokira svoju nit tijekom cijele generacije. Na web poslužitelju koji mora obraditi pedeset istodobnih razgovora, to znači imobiliziranje pedeset niti samo da bi se čekalo. Asinkroni klijent uklanja to ograničenje:
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:
"""Asinkroni streaming za konkurentne aplikacije."""
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
# Izvršavanje
async def main():
messages = [{"role": "user", "content": "Hello, introduce yourself."}]
result = await async_stream_chat(messages)
print(f"\nTotal: {len(result)} characters")
asyncio.run(main())
Logika je identična sinkronoj verziji; mijenjaju se samo stream_async, await na pozivu i async for u petlji.
Integracija s FastAPIjem
Sljedeće, trebaš izvući ovaj stream iz svog Python procesa i poslati ga u preglednik. FastAPI to rješava s StreamingResponse, pod uvjetom da preoblikuješ svaki fragment u SSE format viđen u prethodnoj lekciji:
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):
"""SSE generator za 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"
)
Dva detalja određuju radi li ova krajnja točka ispravno. Dvostruki novi redak \n\n koji završava svaki yield je ono što odvaja događaje u SSE protokolu: bez njega, preglednik beskonačno čeka događaj koji smatra nedovršenim. A media_type="text/event-stream" je ono što omogućuje JavaScript klijentu da konzumira odgovor s EventSource umjesto sa standardnim fetch.
Mjerenje performansi
Kada je stream postavljen, htjet ćeš znati kako performira. Dvije metrike su dovoljne za vođenje optimizacije:
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": "Write a paragraph about 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"Tokens generated: {token_count}")
print(f"Total time: {total_time:.3f}s")
print(f"Tokens/second: {token_count / total_time:.1f}")
TTFT (Time to First Token)—vrijeme između slanja zahtjeva i prikazivanja prvog znaka—najvažnija je metrika za korisničko iskustvo. Ima prednost nad ukupnim vremenom: generacija od petnaest sekundi čija se prva riječ pojavi u tri desetine sekunde činit će se brzom, dok će se generacija od pet sekundi isporučena u jednom bloku činiti sporom. Izmjeri je na svojim stvarnim upitima, uključujući sistemsku poruku—sistemska poruka od dvije stranice produljuje TTFT prije nego što se prvi token uopće generira.
Ključne točke
- Koristi obrazac generatora (
yield) za propagaciju streaming tokena - Implementiraj eksponencijalno kašnjenje za 429 pogreške (ograničenje brzine)
- Preferiraj
stream_asyncza konkurentne web aplikacije - Mjeri TTFT i tokene u sekundi za optimizaciju performansi
- S FastAPIjem,
StreamingResponse+text/event-streampropagira SSE u preglednik