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

Streaming SSE

Oppitunti 5 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Vastaukset reaaliajassa Server-Sent Events -protokollalla
  2. Streaming vs. ei-streaming
  3. SSE-protokolla yksityiskohtaisesti
  4. Streamingin käyttöönotto Pythonilla
  5. Chunkin rakenne
  6. Täydellisen vastauksen kokoaminen
  7. Milloin käyttää streamingiä
  8. Keskeiset asiat

Vastaukset reaaliajassa Server-Sent Events -protokollalla

Oletusarvoisesti Chat Completions API odottaa, kunnes malli on generoinut koko vastauksen, ennen kuin se lähettää sen sinulle. Lyhyessä kysymyksessä viivettä ei kukaan huomaa. Tuhat sanan raportissa se tarkoittaa kuitenkin useita sekunteja tyhjää ruutua, jolloin käyttäjä saattaa luulla sovelluksen kaatuneen. Streaming ratkaisee tämän ongelman lähettämällä tokenit sitä mukaa kuin ne generoituvat, mikä luo keskustelukäyttöliittymistä tutun kirjoituskoneefektin.

Käytetty protokolla on Server-Sent Events (SSE), HTTP-standardi, joka mahdollistaa datan jatkuvan lähettämisen palvelimelta asiakkaalle pysyvän yhteyden yli. Tässä ei ole mitään erikoista: ei WebSockets-asennuksia, ei ylimääräisiä riippuvuuksia.

Streaming vs. ei-streaming

Ei-streaming-tilassa, joka on oletusarvo, asiakas lähettää pyynnön ja odottaa koko vastausta:

Client ──── request ────► Server
         (wait 3-10s)
Client ◄── complete response ── Server

Etuna on yksinkertaisuus: vastaus on atomi, yksi JSON-objekti, jota on helppo käsitellä, validoida ja tallentaa. Haittapuoli on yhtä selvä: koettu viive on suuri, koska käyttäjä ei näe mitään koko generointiprosessin aikana.

Streaming-tilassa palvelin lähettää tokenit yksi kerrallaan tai pienissä ryhmissä:

Client ──── request ────► Server
Client ◄── chunk 1 ─────── Server  (after ~200ms)
Client ◄── chunk 2 ─────── Server  (after ~250ms)
Client ◄── chunk 3 ─────── Server  (after ~300ms)
...
Client ◄── [DONE] ──────── Server

Koettu viive laskee dramaattisesti – ensimmäinen merkki ilmestyy muutamassa sadassa millisekunnissa – mikä parantaa käyttäjäkokemusta merkittävästi. Vastineeksi sinun on koostettava viesti asiakaspuolella ja hallittava tilaa, joka ei enää saavu yhtenä lohkona.

SSE-protokolla yksityiskohtaisesti

Näin vastaanottamasi HTTP-virta näyttää käytännössä:

data: {"id":"cmpl-abc","choices":[{"delta":{"content":"Hello"}}],"usage":null}

data: {"id":"cmpl-abc","choices":[{"delta":{"content":" "}}],"usage":null}

data: {"id":"cmpl-abc","choices":[{"delta":{"content":"!"}}],"usage":null}

data: [DONE]

Jokainen rivi alkaa merkkijonolla data: , jota seuraa JSON-objekti, ja tyhjät rivit toimivat erotinmerkkeinä tapahtumien välillä. Huomaa yksityiskohta, joka ansaan kaikki ensimmäisellä toteutuskerralla: tekstikappale sijaitsee kentässä delta, ei kentässä message kuten klassisessa tilassa. Virta päättyy tapahtumaan data: [DONE], joka signaloi lopun eksplisiittisesti. Ilman sitä et pystyisi erottamaan päättynyttä generointia katkenneesta yhteydestä.

Streamingin käyttöönotto Pythonilla

Mistral SDK:n kanssa otat streamingin käyttöön kutsumalla metodia chat.stream() metodin chat.complete() sijaan:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

stream = client.chat.stream(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Explain how an electric motor works."}
    ]
)

for chunk in stream:
    content = chunk.data.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

print()  # Final newline

Argumentti flush=True ansaitsee selityksen, sillä sen unohtaminen on klassinen syy siihen, miksi streaming “ei toimi”. Ilman sitä Python pitää merkit puskurissa ja näyttää ne lohkoina. Tämä kumoaa visuaalisesti kaikki streamingin hyödyt, vaikka chunkit saapuisivatkin oikein.

Chunkin rakenne

Streaming-chunkia ei lueta kuten täydellistä vastausta, ja access-polut eroavat toisistaan:

# Non-streaming: response.choices[0].message.content
# Streaming:     chunk.data.choices[0].delta.content

# The first chunk often contains the role
# chunk.data.choices[0].delta.role == "assistant"

# Subsequent chunks contain text fragments
# chunk.data.choices[0].delta.content == "Hello"

# The last chunk contains finish_reason
# chunk.data.choices[0].finish_reason == "stop"

Ensimmäinen chunk sisältää yleensä roolin ilman tekstiä, seuraavat sisältävät tekstikappaleita ja viimeinen tarjoaa finish_reason-tiedon. Siksi edellisen koodin if content:-tarkistus ei ole tarpeeton varotoimi: None-arvon liittäminen merkkijonoon aiheuttaisi silmukan epäonnistumisen jo ensimmäisellä kierroksella.

Täydellisen vastauksen kokoaminen

Kappaleiden näyttäminen ei riitä, kun tarvitset vastauksen talteen – esimerkiksi lisätäksesi sen keskusteluhistoriaan, lokittaaksesi sen tai tallentaaksesi sen tietokantaan. Sinun on siis kerrytettävä tekstiä rinnakkain sen näyttämisen kanssa:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

stream = client.chat.stream(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "List 5 programming languages."}]
)

full_response = ""
finish_reason = None

for chunk in stream:
    delta = chunk.data.choices[0].delta
    if delta.content:
        full_response += delta.content
        print(delta.content, end="", flush=True)

    if chunk.data.choices[0].finish_reason:
        finish_reason = chunk.data.choices[0].finish_reason

print(f"\n\nFinish reason: {finish_reason}")
print(f"Complete response ({len(full_response)} characters)")

Muuttuja finish_reason napataan samassa silmukassa samasta syystä kuin klassisessakin tilassa: max_tokens-rajoituksen takia typistynyt vastaus näyttää ruudulla täsmälleen samalta kuin täydellinen vastaus, ja vain tämä kenttä kertoo eron.

Milloin käyttää streamingiä

Streaming ei ole aina parempi. Se on suositeltavaa aina, kun ihminen katsoo näyttöä, mutta tarpeeton tai jopa haitallinen, kun kone käsittelee tulostetta.

KäyttötapaSuositus
Interaktiivinen chatbotStreaming (parempi UX)
EräajotEi-streaming (yksinkertaisempi)
Backend-API frontendilleStreaming (SSE selaimelle)
DataputkiEi-streaming (atominen käsittely)
Jäsennelty ekstraktioEi-streaming (luotettavampi JSON-jäsennys)

Viimeinen tapaus on opettavaisin. Jos odotat JSON-muotoista dataa, streaming ei lisää mitään: et voi jäsentää keskeneräistä objektia, ja joudut odottamaan viimeistä kappaletta joka tapauksessa. Yhtä hyvin voit pitää kutsun atomisena ja koodin yksinkertaisena.

Keskeiset asiat

  • Streaming vähentää koettua viivettä lähettämällä tokenit sitä mukaa kuin ne generoituvat
  • SSE-protokolla on yksinkertainen ja robusti HTTP-standardi
  • Käytä streaming-tilassa delta.content arvon message.content sijaan
  • Kerää kappaleet asiakaspuolella täydellisen vastauksen kokoamiseksi
  • Suosi streamingiä käyttöliittymissä ja ei-streamingiä automatisoidussa käsittelyssä