Optimoitu suoratoisto
Tällä sivulla
Mitä suoratoisto todella muuttaa
Suoratoisto ei tee mallista nopeampaa: se tekee odotuksesta siedettävän. Jos vastauksen tuottaminen kestää viisi sekuntia, käyttäjä ilman suoratoistoa tuijottaa tyhjää ruutua viisi sekuntia ennen kuin saa tekstilohkon kerralla. Suoratoistolla hän näkee ensimmäiset sanat muutaman sadan millisekunnin kuluttua ja voi lukea tekstiä mallin kirjoittaessa sitä. Kokonaiskesto on sama, mutta kokemus on täysin erilainen. Siksi suoratoiston pois jättäminen tuotannossa on lähes aina suunnitteluvirhe, ei tietoinen valinta.
Virran on kuitenkin kuljettava koko ketjusi läpi. Jos API tuottaa virran oikein, mutta sovelluspalvelimesi kerää sen tai käänteinen välityspalvelin (reverse proxy) puskuroi sen, käyttäjä saa vastauksen yhtenä lohkona: olet maksanut suoratoiston monimutkaisuudesta hyötymättä sen eduista. Tämä oppitunti seuraa siksi koko polkua API-kutsusta selaimeseen.
Virran kuluttaminen asiakaspuolella
Responses API:ssa asetus stream=True muuttaa vastauksen tyypitetyksi tapahtumasarjaksi, jota iteroidaan saapumisjärjestyksessä. Jokainen tekstinpätkä saapuu response.output_text.delta-tapahtumassa; virran päättymisestä ilmoittaa response.completed, joka sisältää koko vastausolion. Tämä on hyödyllinen token-kulutuksen hakemiseen.
import openai
client = openai.OpenAI()
def generate_streaming(prompt: str):
"""Suoratoistogenerointi Responses API:lla."""
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)
elif event.type == "response.completed":
print() # Rivinvaihto lopussa
return event.response
Lippu flush=True ei ole kosmeettinen: ilman sitä Python puskuroi tulosteen itse, ja päädyt taas lohkokäyttäytymiseen, jota yritit välttää. Tämä yksityiskohta toistuu ketjun jokaisessa kerroksessa, ja se on suoratoiston suurin haaste.
Mekanismi kattaa myös funktiokutsut. Työkalujen argumentit rakentuvat vähitellen, ja voit näyttää niitä sitä mukaa kun ne generoituvat. Tämä kertoo käyttäjälle, että hakua ollaan muotoilemassa, sen sijaan että hän tuijottaisi jäätyneenä näyttöä mallin valmistellessa kutsua.
tools = [
{
"type": "function",
"name": "search_product",
"description": "Searches for a product in the catalog.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"category": {"type": "string"},
},
"required": ["query"],
},
}
]
def streaming_with_tools(prompt: str):
stream = client.responses.create(
model="gpt-5.6-terra",
input=prompt,
tools=tools,
stream=True,
)
for event in stream:
match event.type:
case "response.output_text.delta":
print(event.delta, end="", flush=True)
case "response.function_call_arguments.delta":
# Generoitavat funktion argumentit
print(f"[arg: {event.delta}]", end="")
case "response.function_call_arguments.done":
print(f"\n[Funktiokutsu valmis]")
Virran välittäminen selaimeen
Frontendisi ei keskustele suoraan OpenAI API:n kanssa, vaan palvelimesi kanssa. Palvelimesi on siksi välitettävä virta eteenpäin. Server-Sent Events (SSE) on tähän luontevin muoto: HTTP-vastaus, joka pysyy auki ja jossa jokainen data:-rivi kuljettaa JSON-pätkän. Seuraava esimerkki välittää tekstin saapuessaan ja lähettää lopuksi viestin, joka sisältää token-määrät. Näin voit laskuttaa tai lokittaa ilman erillistä kutsua.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import openai
import json
app = FastAPI()
client = openai.OpenAI()
@app.post("/api/chat")
async def chat_streaming(request: dict):
prompt = request["message"]
async def generate():
stream = client.responses.create(
model="gpt-5.6-terra",
input=prompt,
stream=True,
)
for event in stream:
if event.type == "response.output_text.delta":
data = json.dumps({"text": event.delta})
yield f"data: {data}\n\n"
elif event.type == "response.completed":
usage = event.response.usage
data = json.dumps({
"end": True,
"input_tokens": usage.input_tokens,
"output_tokens": usage.output_tokens,
})
yield f"data: {data}\n\n"
return StreamingResponse(
generate(),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"X-Accel-Buffering": "no", # Tärkeä nginx:lle
},
)
Sitten on käänteinen välityspalvelin, yleinen syyllinen, kun “suoratoisto ei toimi tuotannossa vaikka paikallisesti toimi”. Oletuksena nginx kerää backend-vastauksen ennen lähettämistä. Alla oleva konfiguraatio poistaa tämän käytön vain tietyltä reitiltä.
location /api/chat {
proxy_pass http://127.0.0.1:8000;
proxy_buffering off;
proxy_cache off;
proxy_set_header Connection "";
chunked_transfer_encoding on;
}
Yhteyden ylläpito ajan myötä
Useita kymmeniä sekunteja auki oleva virta on alttiimpi kuin lyhyt kutsu: verkkokatkos tai kiintiön ylitys pysäyttää generoinnin kesken lauseen. Uudelleenyritysstrategiasi on erotettava nämä kaksi tapausta, sillä ne vaativat erilaisia lähestymistapoja. Yhteysvirhe kannattaa yrittää uudelleen eksponentiaalisella viiveellä (exponential backoff), jotta verkko ehtii palautua ilman API:n kuormittamista. Kiintiön ylitys puolestaan vaatii kiinteän odotusajan, koska nopeusrajoitusikkuna nollautuu säännöllisin väliajoin.
import openai
def resilient_streaming(prompt: str, max_attempts: int = 3):
"""Suoratoisto virheenkäsittelyllä ja uudelleenyrityksellä."""
for attempt in range(max_attempts):
try:
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
yield event.delta
return # Onnistui, poistu
except openai.APIConnectionError:
if attempt < max_attempts - 1:
import time
time.sleep(2 ** attempt) # Eksponentiaalinen viive
else:
raise
except openai.RateLimitError:
import time
time.sleep(5) # Kiinteä odotus nopeusrajoitukselle
Yksi viimeinen hienosäätö parantaa lukukokemusta. Jokaisen tokenin lähettäminen tuottaa nykivää tekstiä, erityisesti jos käyttöliittymäsi käyttää animaatiota tai tulos menee puheeksi muuntamiseen (text-to-speech). Kertyminen lauseen loppuun asti antaa rytmin, joka on lähempänä ihmisen lukemista, ensimmäisen pätkän pienellä lisäviiveellä.
def streaming_by_sentence(prompt: str):
"""Kerryttää ja tuottaa kokonaisia lauseita."""
buffer = ""
stream = client.responses.create(
model="gpt-5.6-terra",
input=prompt,
stream=True,
)
for event in stream:
if event.type == "response.output_text.delta":
buffer += event.delta
# Etsi lauseen loppu
for separator in [".\n", "!\n", "?\n", ". ", "! ", "? "]:
if separator in buffer:
parts = buffer.split(separator, 1)
yield parts[0] + separator.rstrip()
buffer = parts[1] if len(parts) > 1 else ""
if buffer.strip():
yield buffer.strip()
Huomaa lopun if buffer.strip(): ilman sitä vastaus, joka ei pääty vahvaan välimerkkiin, menettäisi viimeiset sanansa. Tällainen huolimattomuus jää huomaamatta testauksessa ja ilmenee tuotannossa vastauksissa, jotka on typistetty max_output_tokens-asetuksella.
Keskeiset asiat
- Käytä aina suoratoistoa tuotannossa vähentääksesi koettua viivettä
- Määritä nginx asetuksella
proxy_buffering offSSE:tä varten - Käsittele virheet uudelleenyrityksillä ja eksponentiaalisella viiveellä
- Kertymä lauseittain luonnollisempaa näyttöä varten