Streaming SSE
Tällä sivulla
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ötapa | Suositus |
|---|---|
| Interaktiivinen chatbot | Streaming (parempi UX) |
| Eräajot | Ei-streaming (yksinkertaisempi) |
| Backend-API frontendille | Streaming (SSE selaimelle) |
| Dataputki | Ei-streaming (atominen käsittely) |
| Jäsennelty ekstraktio | Ei-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.contentarvonmessage.contentsijaan - Kerää kappaleet asiakaspuolella täydellisen vastauksen kokoamiseksi
- Suosi streamingiä käyttöliittymissä ja ei-streamingiä automatisoidussa käsittelyssä