Streaming: Vastausten vastaanottaminen reaaliajassa
Tällä sivulla
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=Truesaadaksesi reaaliaikaisen kokemuksen - Suodata tapahtumat kentän
event.typeperusteella käsitelläksesi jokaisen datatyypin oikein response.output_text.deltasisältää tekstifragmentitresponse.completedsignaloi lopun ja sisältää käyttömäärät- Käytä
AsyncOpenAI:ta streamaukseen asynkronisissa sovelluksissa - Käsittele virheet aina, myös streaming-tilassa