Funktioihin perustuva reaaliaikainen kutsuminen
Tällä sivulla
Päivitys 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä:
tts-1,tts-1-hdjagpt-4o-mini-ttslakkaavat toimimasta 6. tammikuuta 2027 (suositeltu korvaaja ongpt-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-realtimeja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. 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:
response.function_call_arguments.delta
Funktioargumentit saapuvat suoratoistona osissa.
response.function_call_arguments.done
Argumentit ovat valmiit. Voit nyt suorittaa funktion.
conversation.item.create (sinä)
Lähetät funktion tuloksen takaisin mallille.
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.updatekä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.createkäyttäencall_id:tä - Kutsu
response.create, jotta malli voi muotoilla äänivasteensa tuloksen pohjalta - Huomioi useat kutsut: malli voi kutsua useita funktioita samanaikaisesti