Voogedastus: vastuste reaalajas vastuvõtt
Sellel lehel
Voogedastus: vastuste reaalajas vastuvõtt
Voogedastus võimaldab sul saada vastust tokeni haaval, ootamata kogu teksti genereerimise lõppu. See ei ole pelgalt kasutajaliidese iluasi: just see eristab aeglast vestlusrobotit sellisest, mis tundub kiire ja reageerimisvõimeline, isegi kui serveri jõudlus on mõlemal juhul identne.
Miks kasutada voogedastust?
Ilma voogedastuseta peavad kasutajad mõnikord kümnest kuni kolmekümne sekundini vaatama tühja ekraani, enne kui kogu vastus korraga ilmub. Voogedastuse korral ilmuvad esimesed sõnad alla sekundi ja lugemine algab juba siis, kui teksti genereerimine veel käib. Kogukestus on sama, kuid tajutav kiirus erineb oluliselt. Selle lubamiseks piisab ühest parameetrist, stream=True, mis muudab funktsiooni create() tagastusväärtuse sündmuste iteraatoriks.
from openai import OpenAI
client = OpenAI()
# ILMA voogedastuseta – oota kõike
response = client.responses.create(
model="gpt-5.6-terra",
input="Write a paragraph about artificial intelligence."
)
print(response.output_text) # Ilmub korraga pärast ootamist
# KOOS voogedastusega – tokeni haaval
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() # Reavahetus lõpus
Tüübitud sündmused, mitte lihtsalt voolav voog
Voog ei edasta ainult teksti. See teavitab sind, kui vastus on loodud, kui lisatakse iga väljundüksus, kui saabuvad tekstifragmendid ja kui protsess lõpeb – viimane sündmus sisaldab ka kasutusstatistikat. Sa filtreerid põhjal event.type, et teada saada, millist andmetüüpi parajasti käsitled. See struktuur võimaldab sul näiteks kuvada laadimisindikaatorit kohe, kui käivitub response.created, ja lugeda tokeneid lõpus ilma teist API päringut tegemata.
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}")
# Väljund:
# [Response created] ID: resp_abc123
# [New output item]
# [Text] Hello[Text] ! [Text] How[Text] can[Text] I...
# [Text complete]
# [Done] Tokens: 25
Reaalses rakenduses soovid peaaegu alati teha kahte asja korraga: kuvada fragmendid ja taastada täistekst, et saaksid seda arhiveerida või väljakutsujale tagastada. Reegel on lihtne: koguda andmeid itereerimise käigus, sest kui voog on tarbitud, ei saa seda tagasi kerida.
def stream_and_collect(prompt: str) -> str:
"""Voogedasta vastus ja koguda see kokku."""
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() # Reavahetus
return full_text
result = stream_and_collect("List 3 European capitals.")
print(f"\nCollected text ({len(result)} characters)")
Voogedastus ja funktsioonide kutsumine
Ka funktsioonikutsed edastatakse voona, kasutades oma spetsiifilisi sündmusi: argumendid saabuvad fragmentidena läbi response.function_call_arguments.delta ja response.function_call_arguments.done annab märku, et JSON on täielik. Sellel on oluline praktiline tagajärg – ära kunagi püüa argumente deserialiseerida enne done sündmust, vastasel juhul on sul käes vaid poolik 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]")
# Väljund:
# [Args] {"city": "Tokyo"}
# [Function call complete]
Asünkroonne variant
Niipea kui sinu rakendus teenindab samaaegselt mitut kasutajat, lülitu kasutama AsyncOpenAI-d: sünkroonne klient blokeeriks sündmuste tsükli kogu genereerimise ajaks, pannes teised päringud ootama. Süntaks erineb vaid kahe märksõna võrra – await loomisel ja async for itereerimisel.
from openai import AsyncOpenAI
import asyncio
async_client = AsyncOpenAI()
async def stream_async(prompt: str):
"""Vastuse asünkroonne voogedastus."""
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."))
Veebis on voogedastus kasutu, kui see peatub sinu serveris: sa pead selle ulatama brauserini. FastAPI võimaldab seda teha StreamingResponse abil, mida toidab generaator, edastades fragmendid nende saabumisel.
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")
Vead voogedastuse käigus
Üks detail väärib erilist tähelepanu: voogedastuse korral võib viga tekkida pärast seda, kui osad fragmendid on juba kuvatud. Kasutaja näeb siis vastust, mis algab, kuid katkeb järsult. Seetõttu paiguta veakäitlus ümber itereerimise enda, mitte ainult voo loomise, et saaksid katkemise korralikult signaliseerida, jättes lause pooleli.
from openai import APIError
def stream_with_errors(prompt: str):
"""Voogedastus robustse veakäitlusega."""
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.")
Peamised punktid
- Luba voogedastus parameetriga
stream=True, et pakkuda reaalajas kogemust - Filtreeri sündmusi põhjal
event.type, et käsitleda iga andmetüüpi õigesti response.output_text.deltasisaldab tekstifragmenteresponse.completedannab märku lõpust ja sisaldab kasutusstatistikat- Kasuta asünkroonsetes rakendustes voogedastuseks
AsyncOpenAI-d - Käitle alati vigu, isegi voogedastusrežiimis