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

SSE-streamaus

Oppitunti 10 / 14 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Vastausten vastaanottaminen reaaliajassa
  2. Miten streamaus toimii
  3. Streamaus Pythonilla OpenAI SDK:n kanssa
  4. Streamaus /v1/responses-päätepisteen kanssa
  5. Streamaus cURLilla
  6. Milloin käyttää streamausta
  7. Virheenkäsittely streamauksessa
  8. Keskeiset asiat

Vastausten vastaanottaminen reaaliajassa

Oletusarvoisesti API odottaa, kunnes vastaus on luotu kokonaan, ennen kuin se palauttaa sen. Streamauksen avulla vastaanotat tokenit sitä mukaa, kun niitä generoidaan. Tämä tekniikka lyhentää käyttäjän kokemaa odotusaikaa ja mahdollistaa vastausten näyttämisen vähitellen, aivan kuten Grok-käyttöliittymä tekee.

Miten streamaus toimii

Streamaus käyttää Server-Sent Events (SSE) -protokollaa. Yhden HTTP-vastauksen sijaan palvelin lähettää jatkuvan tapahtumavirran. Jokainen tapahtuma sisältää osan vastauksesta, ja asiakas kokoaa ne yhteen muodostaakseen koko tekstin.

Parametri stream: true ottaa tämän tilan käyttöön missä tahansa generointipäätepisteessä.

Streamaus Pythonilla OpenAI SDK:n kanssa

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

stream = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "user", "content": "Explain the SOLID principles in programming."}
    ],
    stream=True
)

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

print()  # Final line break

Miten koodi toimii

  • stream=True ottaa streamauksen käyttöön
  • Vastaus on chunk-objektien (palasten) iteraattori
  • Jokainen pala sisältää delta-kentän, jossa on uusi sisältö
  • end="" estää rivinvaihdot palasten välissä
  • flush=True pakottaa välittömän näyttämisen

Streamaus /v1/responses-päätepisteen kanssa

stream = client.responses.create(
    model="grok-4.5",
    input="Describe the steps to deploy a web application.",
    stream=True
)

for event in stream:
    if hasattr(event, 'type') and event.type == 'response.output_text.delta':
        print(event.delta, end="", flush=True)

print()

/v1/responses-päätepiste käyttää tyypitettyjä tapahtumia. Tyyppi response.output_text.delta sisältää tekstipalaset.

Streamaus cURLilla

cURL tukee SSE-streamausta natiivisti. Lisää "stream": true pyynnön sisältöön:

curl -N https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Valitsin -N poistaa cURL:n puskuroinnin, jolloin tapahtumat näkyvät heti saapuessaan.

Jokainen SSE-virran rivi alkaa merkkijonolla data:, jota seuraa JSON-objekti. Viimeinen tapahtuma on data: [DONE], joka ilmoittaa generoinnin päättymisestä.

Milloin käyttää streamausta

Päätös tiivistyy yhteen kysymykseen: seuraako ihminen vastauksen saapumista? Jos näin on (keskustelubotti, avustaja, kirjoitustyökalu), streamaus on lähes pakollinen: käyttäjät näkevät tekstin ilmestyvän sana sanalta sen sijaan, että tuijottaisivat jäätyneenä näyttöä. Pitkissä vastauksissa ero “ensimmäinen sana 300 ms:ssä” ja “koko teksti 8 sekunnin kuluttua” muuttaa koko koettua käyttäjäkokemusta.

Jos kukaan ei seuraa, streamaus ei tuo lisäarvoa ja vain monimutkaistaa koodia. Tietokantaa täyttävä eräajo, automatisoitu putki, jonka on jäsentävä koko vastaus ennen toimintaa, tai kutsu, joka palauttaa vain muutaman sanan: kaikissa näissä tapauksissa klassinen kutsu (yksi pyyntö, yksi täydellinen vastaus) on yksinkertaisempi kirjoittaa, testata ja vianetsiä.

Virheenkäsittely streamauksessa

Streamaus-tilassa virheitä voi ilmetä virran keskellä. Koodisi on pystyttävä käsittelemään nämä keskeytykset:

try:
    stream = client.chat.completions.create(
        model="grok-4.5",
        messages=[{"role": "user", "content": "Test"}],
        stream=True
    )
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
except Exception as e:
    print(f"\nError during streaming: {e}")

Keskeiset asiat

  • Lisää stream=True vastaanottaaksesi tokenit niiden generoituessa
  • Käytetty protokolla on SSE (Server-Sent Events)
  • Pythonissa iteroi palasia ja tulosta delta.content
  • cURLilla käytä valitsinta -N puskuroinnin poistamiseksi
  • Säästä streamaus tapauksiin, joissa vähittäinen näyttäminen tuo lisäarvoa