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

Optimoitu suoratoisto

Oppitunti 5 / 20 Päivitetty 28. heinäkuuta 2026 Edistynyt
Tällä sivulla
  1. Mitä suoratoisto todella muuttaa
  2. Virran kuluttaminen asiakaspuolella
  3. Virran välittäminen selaimeen
  4. Yhteyden ylläpito ajan myötä
  5. Keskeiset asiat

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 off SSE:tä varten
  • Käsittele virheet uudelleenyrityksillä ja eksponentiaalisella viiveellä
  • Kertymä lauseittain luonnollisempaa näyttöä varten