Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Toteuta suoratoisto Pythonilla

Oppitunti 6 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Prototyypistä tuotantoon
  2. Perusmalli
  3. Kattava virheenkäsittely
  4. Asynkroninen suoratoisto asyncio:lla
  5. Integrointi FastAPIin
  6. Suorituskyvyn mittaaminen
  7. Keskeiset asiat

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-stream välittää SSE:n selaimelle