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

Funktioihin perustuva reaaliaikainen kutsuminen

Oppitunti 4 / 18 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Funktioihin perustuva reaaliaikainen kutsuminen
  2. Työkalujen määrittely istunnossa
  3. Funktiokutsun kulku
  4. Funktiokäsittelijän toteutus
  5. Integrointi tapahtumasilmukkaan
  6. Keskeiset asiat

Päivitys 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä: tts-1, tts-1-hd ja gpt-4o-mini-tts lakkaavat toimimasta 6. tammikuuta 2027 (suositeltu korvaaja on gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tuetun /v1/audio/speech-päätepistettä: puheentuotto siirtyy Realtime API:hun); gpt-realtime, gpt-4o-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. helmikuuta 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Täysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien.

Funktioihin perustuva reaaliaikainen kutsuminen

Realtime API:n funktiokutsut mahdollistavat sen, että ääniagenttisi voi suorittaa konkreettisia toimia keskustelun aikana: tietokannan kysely, tilauksen tekeminen tai tilan tarkistus. Mekaniikka muistuttaa Responses API:a, mutta se on sovitettu WebSocket-tapahtumavirtaan.

Työkalujen määrittely istunnossa

Määrittelet työkalut kohdassa session.update aivan kuten ohjeet ja äänenkin. Jokainen työkalu on JSON-skeema, joka kuvaa sen parametrit:

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather for a given city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Name of the city"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit"
                }
            },
            "required": ["city"]
        }
    },
    {
        "type": "function",
        "name": "book_appointment",
        "description": "Book an appointment",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
                "time": {"type": "string", "description": "Time in HH:MM format"},
                "service": {"type": "string", "description": "Type of service"}
            },
            "required": ["date", "time", "service"]
        }
    }
]

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "output_modalities": ["audio"],
        "instructions": "You are a voice assistant. Use the available tools.",
        "audio": {"output": {"voice": "marin"}},
        "tools": tools,
        "tool_choice": "auto"
    }
}))

Funktiokutsun kulku

Kun malli päättää kutsua työkalua, tapahtumajärjestys on seuraava:

1

response.function_call_arguments.delta

Funktioargumentit saapuvat suoratoistona osissa.

2

response.function_call_arguments.done

Argumentit ovat valmiit. Voit nyt suorittaa funktion.

3

conversation.item.create (sinä)

Lähetät funktion tuloksen takaisin mallille.

4

response.create (sinä)

Pyydät mallia jatkamaan vastaustaan tuloksen pohjalta.

Funktiokäsittelijän toteutus

Tässä on täydellinen esimerkki funktiokutsujen käsittelystä:

import json

# Rekisteri käytettävissä oleville funktioille
async def get_weather(city: str, unit: str = "celsius") -> dict:
    # Kutsu oikeaa sää-API:a
    return {"city": city, "temperature": 22, "unit": unit, "condition": "sunny"}

async def book_appointment(date: str, time: str, service: str) -> dict:
    # Varauslogiikka
    return {"confirmed": True, "date": date, "time": time, "reference": "RDV-2026-0042"}

FUNCTION_REGISTRY = {
    "get_weather": get_weather,
    "book_appointment": book_appointment,
}

async def handle_function_call(ws, event):
    """Käsittelee funktiokutsun ja palauttaa tuloksen."""
    response = event["response"]

    for output in response.get("output", []):
        if output["type"] != "function_call":
            continue

        func_name = output["name"]
        call_id = output["call_id"]
        arguments = json.loads(output["arguments"])

        print(f"Calling function: {func_name}({arguments})")

        # Suorita funktio
        func = FUNCTION_REGISTRY.get(func_name)
        if func:
            result = await func(**arguments)
        else:
            result = {"error": f"Unknown function: {func_name}"}

        # Lähetä tulos takaisin mallille
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "function_call_output",
                "call_id": call_id,
                "output": json.dumps(result)
            }
        }))

    # Pyydä mallia jatkamaan tuloksen kanssa
    await ws.send(json.dumps({
        "type": "response.create"
    }))

Integrointi tapahtumasilmukkaan

Funktiohandleri integroidaan pääsilmukkaasi:

async def event_loop(ws):
    """Pääasiallinen tapahtumien käsittelysilmukka."""
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "response.done":
            response = event["response"]
            # Tarkista, kutsuiko malli mitään funktioita
            has_function_calls = any(
                o["type"] == "function_call"
                for o in response.get("output", [])
            )
            if has_function_calls:
                await handle_function_call(ws, event)

        elif event_type == "response.output_audio.delta":
            # Toista vastausääni
            audio_bytes = base64.b64decode(event["delta"])
            player.write(audio_bytes)

        elif event_type == "error":
            print(f"Error: {event['error']['message']}")

Useat funktiokutsut

Malli voi päättää kutsua useita funktioita yhden vastauksen aikana. Kenttä output kohteessa response.done voi sisältää useita merkintöjä, joiden tyyppi on function_call. Käsittele ne kaikki ennen kuin kutsut response.create.

Keskeiset asiat

  • Työkalut määritellään kohdassa session.update käyttämällä standardia JSON-skeemaa
  • Argumentit saapuvat suoratoistona kautta response.function_call_arguments.delta
  • Suorituksen jälkeen lähetä tulos takaisin kautta conversation.item.create käyttäen call_id:tä
  • Kutsu response.create, jotta malli voi muotoilla äänivasteensa tuloksen pohjalta
  • Huomioi useat kutsut: malli voi kutsua useita funktioita samanaikaisesti