Toteuta suoratoisto Pythonilla
Tällä sivulla
Prototyypistä tuotantoon
Edellisessä oppitunnissa käsiteltiin SSE-suoratoiston peruskäsitteitä. Vaikeampi osuus on vielä edessä: demon silmukan muuttaminen asiakasohjelmaksi, joka kestää kuormitusta, selviää verkkovirheistä ja syöttää dataa verkkokäyttöliittymälle. Tämä oppitunti seuraa projektin todellista kaarta: ensin runko, sitten virheenkäsittely, sen jälkeen asynkronisuus, HTTP-rajapinnan avaaminen ja lopuksi mittaukset.
Perusmalli
Kaikki alkaa tästä kymmenen rivin rungosta, jota muokkaat jokaisessa projektissa. Se tekee kaksi asiaa yhtä aikaa: näyttää tokenit sitä mukaa kun ne saapuvat ja kerää ne funktion palautusarvoa varten.
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:
"""Lähettää suoratoistopyynnön ja näyttää tokenit reaaliajassa."""
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() # Rivinvaihto
return full_text
Tämä versio toimii paikallisessa skriptissä. Siinä on kuitenkin tuotannossa kohtalokas vika: se tulostaa päätteen näytölle, joten se pystyy hoitamaan vain päätetyötä.
Kattava virheenkäsittely
Verkkovirheet, aikakatkaisut ja nopeusrajoitukset eivät ole hypoteeseja: ne ovat varmuuksia todellisessa liikenteessä. Alla oleva asiakasohjelma ratkaisee molemmat ongelmat. Se yrittää automaattisesti uudelleen 429-virheitä eksponentiaalisella viiveellä, eikä se enää tulosta mitään: se lähettää tyypitettyjä tapahtumia yield-avainsanan avulla, jolloin kutsuja päättää, mitä niille tehdään – näyttääkö ne, lähettääkö ne WebSocketin kautta vai kirjoittaako ne tietokantaan.
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:
"""Suoratoisto automaattisella uudelleenyrityksellä ja mittareilla."""
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 # Eksponentiaalinen viive
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
Eksponentiaalinen viive 2 ** attempt odottaa ensin 1 sekunnin, sitten 2, sitten 4. Tämä eteneminen ei ole koristeellista: jos kaikki asiakkaasi yrittäisivät uudelleen samaan kiinteään tahtiin, ne osuisivat rajapintaan synkronoiduissa purskeissa ja pidentäisivät juuri sitä kyllästymistä, josta ne kärsivät. Huomaa myös, että vain virhe 429 laukaisee uudelleenyrityksen – 401-virheen uudelleenyritys virheellisen avaimen vuoksi vain viivästyttäisi vian diagnosointia.
Kutsujan puolella kulutus muuttuu yksinkertaiseksi tapahtumien lukemiseksi:
messages = [
{"role": "system", "content": "Olet tekninen avustaja."},
{"role": "user", "content": "Selitä suunnittelumallit Pythonissa."}
]
for event in stream_with_retry(messages):
if event["type"] == "token":
print(event["content"], end="", flush=True)
elif event["type"] == "retry":
print(f"\n[Uudelleenyritys {event['attempt']}, odotetaan {event['wait']}s...]")
elif event["type"] == "done":
print(f"\n\n--- Valmis ({event['chunks']} osaa, {event['finish_reason']})")
elif event["type"] == "error":
print(f"\n[Virhe: {event['message']}]")
Asynkroninen suoratoisto asyncio:lla
Synkroninen asiakas estää säikeensä koko generoinnin ajaksi. Web-palvelimella, jonka on käsiteltävä viisikymmentä samanaikaista keskustelua, tämä tarkoittaa viidenkymmenen säikeen lamaannuttamista pelkkää odotusta varten. Asynkroninen asiakas poistaa tämän rajoituksen:
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:
"""Asynkroninen suoratoisto samanaikaisiin sovelluksiin."""
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
# Suoritus
async def main():
messages = [{"role": "user", "content": "Hei, esittele itsesi."}]
result = await async_stream_chat(messages)
print(f"\nYhteensä: {len(result)} merkkiä")
asyncio.run(main())
Logiikka on identtinen synkronisen version kanssa; vain stream_async, kutsun await ja silmukan async for muuttuvat.
Integrointi FastAPIin
Seuraavaksi sinun on saatava tämä suoratoisto Python-prosessistasi selaimeseen. FastAPI hoitaa tämän StreamingResponse-luokalla, edellyttäen että muotoilet jokaisen osan uudelleen edellisellä tunnilla nähtyyn SSE-muotoon:
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-generaattori FastAPIlle."""
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"
)
Kaksi yksityiskohtaa ratkaisevat, toimiiko tämä päätepiste oikein. Kaksoisrivinvaihto \n\n, joka päättää jokaisen yield-lauseen, erottaa tapahtumat SSE-protokollassa: ilman sitä selain odottaa loputtomiin tapahtumaa, jota se pitää keskeneräisenä. Ja media_type="text/event-stream" on se, mikä mahdollistaa JavaScript-asiakkaan kuluttaa vastauksen EventSource:lla tavallisen fetch:n sijaan.
Suorituskyvyn mittaaminen
Kun suoratoisto on paikallaan, haluat tietää, miten se suoriutuu. Kaksi mittaria riittää optimoinnin ohjaamiseen:
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": "Kirjoita kappale Pariisista."}]
)
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"Aika ensimmäiseen tokeniin (TTFT): {first_token_time:.3f}s")
print(f"Generoidut tokenit: {token_count}")
print(f"Kokonaisaika: {total_time:.3f}s")
print(f"Tokenia/sekunti: {token_count / total_time:.1f}")
TTFT (Time to First Token) – aika pyynnön lähettämisestä ensimmäisen merkin näyttämiseen – on tärkein mittari käyttäjäkokemuksen kannalta. Se on etusijalla kokonaisaikaan nähden: viidentoista sekunnin generointi, jonka ensimmäinen sana ilmestyy kolmessakymmenessä sekunnissa, tuntuu nopealta, kun taas viiden sekunnin generointi, joka toimitetaan yhtenä lohkona, tuntuu hitaalta. Mittaa se todellisilla kehotteillasi, järjestelmäviesti mukaan lukien – kahden sivun mittainen järjestelmäviesti pidentää TTFT:a ennen kuin ensimmäistäkään tokenia on edes generoitu.
Keskeiset asiat
- Käytä generaattorimallia (
yield) suoratoistettavien tokenien välittämiseen - Toteuta eksponentiaalinen viive 429-virheille (nopeusrajoitus)
- Suosi
stream_async:ia samanaikaisissa web-sovelluksissa - Mittaa TTFT ja tokenia/sekunti suorituskyvyn optimoimiseksi
- FastAPIssa
StreamingResponse+text/event-streamvälittää SSE:n selaimelle