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

Streaming: Vastausten vastaanottaminen reaaliajassa

Oppitunti 8 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Streaming: Vastausten vastaanottaminen reaaliajassa
  2. Miksi käyttää streamingiä
  3. Tyypitetyt tapahtumat, ei erottelematon virta
  4. Streaming ja funktiokutsut
  5. Asynkroninen tapaus
  6. Virheet streamauksen aikana
  7. Keskeiset asiat

Streaming: Vastausten vastaanottaminen reaaliajassa

Streamingin avulla voit vastaanottaa vastauksen merkki merkiltä sen sijaan, että odottaisit koko generoinnin valmistumista. Tämä ei ole pelkkä käyttöliittymän hienosäätö: se on se tekijä, joka erottaa hitaalta tuntuvan chatbotin nopealta tuntuvasta, vaikka palvelimen suorituskyky olisi täysin sama.

Miksi käyttää streamingiä

Ilman streamingiä käyttäjät joutuvat joskus tuijottamaan tyhjää ruutua kymmenestä kolmeenkymmeneen sekuntiin, ennen kuin koko vastaus ilmestyy kerralla. Streamingiä käytettäessä ensimmäiset sanat näkyvät alle sekunnissa, ja lukeminen alkaa jo generoinnin jatkuessa. Kokonaiskesto on sama, mutta kokemus on erilainen. Sen käyttöönotto vaatii vain yhden parametrin, stream=True, joka muuttaa metodin create() palauttaman arvon tapahtumaiteraattoriksi.

from openai import OpenAI
client = OpenAI()

# ILMAN streamingiä — odota kaikkea
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a paragraph about artificial intelligence."
)
print(response.output_text)  # Näkyy kerralla odotuksen jälkeen

# STREAMINGIN KANSSA — merkki merkiltä
stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a paragraph about artificial intelligence.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()  # Rivinvaihto lopussa

Tyypitetyt tapahtumat, ei erottelematon virta

Virta ei sisällä pelkkää tekstiä. Se ilmoittaa, kun vastaus luodaan, kun jokainen tulosteelementti lisätään, kun fragmentit saapuvat ja kun suoritus päättyy – viimeinen tapahtuma sisältää käyttömäärät. Suodatat tapahtumat kentän event.type perusteella tietääksesi, mitä käsittelet. Tämä rakenne mahdollistaa esimerkiksi latausindikaattorin näyttämisen heti, kun response.created laukeaa, ja merkkien laskemisen lopussa ilman toista API-kutsua.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Hello!",
    stream=True
)

for event in stream:
    match event.type:
        case "response.created":
            print(f"[Response created] ID: {event.response.id}")
        case "response.output_item.added":
            print(f"[New output item]")
        case "response.output_text.delta":
            print(f"[Text] {event.delta}", end="")
        case "response.output_text.done":
            print(f"\n[Text complete]")
        case "response.completed":
            print(f"[Done] Tokens: {event.response.usage.total_tokens}")

# Tuloste:
# [Response created] ID: resp_abc123
# [New output item]
# [Text] Hello[Text] ! [Text] How[Text] can[Text] I...
# [Text complete]
# [Done] Tokens: 25

Todellisessa sovelluksessa haluat lähes aina tehdä kaksi asiaa samanaikaisesti: näyttää fragmentit ja rakentaa koko tekstin uudelleen, jotta voit arkistoida sen tai palauttaa sen kutsujalle. Sääntö on yksinkertainen: kerää tietoja iteroinnin aikana, sillä kun virta on kulutettu, sitä ei voi kelata takaisin.

def stream_and_collect(prompt: str) -> str:
    """Streamaa vastaus samalla keräten sen."""
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True
    )

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

    print()  # Rivinvaihto
    return full_text

result = stream_and_collect("List 3 European capitals.")
print(f"\nCollected text ({len(result)} characters)")

Streaming ja funktiokutsut

Myös funktiokutsut streamataan, ja niillä on omat tapahtumansa: argumentit saapuvat fragmentteina tapahtuman response.function_call_arguments.delta kautta, ja response.function_call_arguments.done ilmoittaa JSON-tiedon olevan valmis. Tällä on tärkeä käytännön seuraus: älä koskaan yritä purkaa (deserialize) argumentteja ennen done-tapahtumaa, tai sinulla on käytössäsi vain typistynyt JSON.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="What time is it in Tokyo?",
    tools=[{
        "type": "function",
        "name": "get_time",
        "description": "Get the time in a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }],
    stream=True
)

for event in stream:
    match event.type:
        case "response.output_text.delta":
            print(event.delta, end="")
        case "response.function_call_arguments.delta":
            print(f"[Args] {event.delta}", end="")
        case "response.function_call_arguments.done":
            print(f"\n[Function call complete]")

# Tuloste:
# [Args] {"city": "Tokyo"}
# [Function call complete]

Asynkroninen tapaus

Heti kun sovelluksesi palvelee useita käyttäjiä samanaikaisesti, siirry käyttämään AsyncOpenAI:ta: synkroninen asiakas estäisi tapahtumasilmukan koko generoinnin ajaksi, mikä saisi muut pyyntösi odottamaan. Syntaksi eroaa vain kahdella avainsanalla: await luonnin yhteydessä ja async for iteroinnin yhteydessä.

from openai import AsyncOpenAI
import asyncio

async_client = AsyncOpenAI()

async def stream_async(prompt: str):
    """Vastauksen asynkroninen streamaus."""
    stream = await async_client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True
    )

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

asyncio.run(stream_async("Tell a short joke."))

Verkkosovelluksissa streaming on hyödytöntä, jos se pysähtyy palvelimellesi: sinun on jatkettava sitä selaimelle asti. FastAPI mahdollistaa tämän StreamingResponse-luokalla, jota syötetään generaattorilla, joka välittää fragmentit niiden saapuessa.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from openai import OpenAI

app = FastAPI()
client = OpenAI()

@app.get("/chat")
async def chat(question: str):
    def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=question,
            stream=True
        )
        for event in stream:
            if event.type == "response.output_text.delta":
                yield event.delta

    return StreamingResponse(generate(), media_type="text/plain")

Virheet streamauksen aikana

Yksi yksityiskohta ansaitsee huomiosi: streamauksessa virhe voi tapahtua sen jälkeen, kun fragmentteja on jo näytetty. Käyttäjä näkee tällöin vastauksen, joka alkaa mutta katkeaa kesken. Siksi kääri itse iterointi try-except-lohkoon, älä pelkkää streamin luontia, jotta voit ilmoittaa keskeytyksestä siististi sen sijaan, että lause jäisi roikkumaan.

from openai import APIError

def stream_with_errors(prompt: str):
    """Streamaus robustilla virheenkäsittelyllä."""
    try:
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt,
            stream=True
        )

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

    except APIError as e:
        print(f"\nAPI error during streaming: {e.message}")
    except Exception as e:
        print(f"\nUnexpected error: {e}")

stream_with_errors("Explain streaming in 2 sentences.")

Keskeiset asiat

  • Ota streaming käyttöön parametrilla stream=True saadaksesi reaaliaikaisen kokemuksen
  • Suodata tapahtumat kentän event.type perusteella käsitelläksesi jokaisen datatyypin oikein
  • response.output_text.delta sisältää tekstifragmentit
  • response.completed signaloi lopun ja sisältää käyttömäärät
  • Käytä AsyncOpenAI:ta streamaukseen asynkronisissa sovelluksissa
  • Käsittele virheet aina, myös streaming-tilassa