Sobald du über WebRTC oder WebSocket mit der Realtime API verbunden bist, kannst du ein Realtime-Modell wie gpt-realtime-2.1 aufrufen, um Speech-to-Speech-Gespräche zu führen. Dazu musst du Client-Ereignisse senden, um Aktionen auszulösen, und auf Server-Ereignisse lauschen, um auf Aktionen der Realtime API zu reagieren.
Dieser Leitfaden zeigt dir, welche Ereignisse du für die Audio- und Textgenerierung, für Bildeingaben und für Funktionsaufrufe brauchst, in welcher Reihenfolge sie auftreten und wie sich der Zustand einer Realtime-Sitzung zusammensetzt.
Wenn du kein Gespräch mit dem Modell führen möchtest, also keine Antwort erwartest, kannst du die Realtime API im Transkriptionsmodus verwenden.
Speech-to-Speech-Sitzungen mit der Realtime API
Eine Realtime-Sitzung ist eine zustandsbehaftete Interaktion zwischen dem Modell und einem verbundenen Client. Die wichtigsten Bestandteile einer Sitzung sind:
- Das Sitzungsobjekt legt die Parameter für die Interaktion fest, etwa das verwendete Modell, die Stimme für die Audioausgabe und weitere Einstellungen.
- Das Gespräch umfasst die Elemente, die während der aktuellen Sitzung durch Nutzereingaben und Modellausgaben entstehen.
- Antworten bestehen aus Audio- oder Textelementen, die das Modell generiert und die dem Gespräch hinzugefügt werden.
Puffer für Audioeingaben und WebSockets
Wenn du WebRTC verwendest, übernehmen die WebRTC-APIs einen Großteil der Medienverarbeitung, die nötig ist, um Audiodaten an das Modell zu senden und von ihm zu empfangen.
Wenn du Audio über WebSockets überträgst, musst du den Puffer für Audioeingaben selbst befüllen. Sende dazu Base64-kodierte Audiodaten in JSON-Ereignissen an den Server.
Zusammen bilden diese Bestandteile eine Realtime-Sitzung. Mit Client-Ereignissen aktualisierst du den Sitzungszustand. Indem du auf Server-Ereignisse lauschst, kannst du auf Zustandsänderungen innerhalb der Sitzung reagieren.
Ereignisse im Lebenszyklus einer Sitzung
Nachdem du eine Sitzung über WebRTC oder WebSockets gestartet hast, meldet der Server mit dem Ereignis session.created, dass die Sitzung bereit ist. Auf dem Client kannst du die aktuelle Sitzungskonfiguration mit dem Ereignis session.update aktualisieren. Die meisten Sitzungseigenschaften kannst du jederzeit ändern. Eine Ausnahme ist voice, die Stimme für die Audioausgabe. Sie lässt sich nicht mehr ändern, sobald das Modell in der Sitzung einmal mit Audio geantwortet hat. Eine Realtime-Sitzung kann höchstens 60 Minuten dauern.
Das folgende Beispiel zeigt, wie du die Sitzung mit dem Client-Ereignis session.update aktualisierst. Wie du Client-Ereignisse über diese Kanäle sendest, erfährst du in den Leitfäden zu WebRTC und WebSocket.
const event = {
type: "session.update",
session: {
type: "realtime",
model: "gpt-realtime-2.1",
// Lock the output to audio (set to ["text"] if you want text without audio)
output_modalities: ["audio"],
audio: {
input: {
format: {
type: "audio/pcm",
rate: 24000,
},
turn_detection: {
type: "semantic_vad",
},
},
output: {
format: {
type: "audio/pcm",
rate: 24000,
},
voice: "marin",
},
},
// Use a server-stored prompt by ID. Optionally pin a version and pass variables.
prompt: {
id: "pmpt_123", // your stored prompt ID
version: "89", // optional: pin a specific version
variables: {
city: "Paris", // example variable used by your prompt
},
},
// You can still set direct session fields; these override prompt fields if they overlap:
instructions:
"Speak clearly and briefly. Confirm understanding before taking actions.",
},
};
// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));Nach der Aktualisierung sendet der Server das Ereignis session.updated mit dem neuen Sitzungszustand.
| Zugehörige Client-Ereignisse | Zugehörige Server-Ereignisse |
|---|---|
Texteingaben und Textausgaben
Um Text mit einem Realtime-Modell zu generieren, kannst du dem aktuellen Gespräch Texteingaben hinzufügen, das Modell zu einer Antwort auffordern und anhand der Server-Ereignisse verfolgen, wie die Antwort entsteht. Für die Textgenerierung muss die Sitzung so konfiguriert sein, dass sie die Modalität text verwendet. Das ist standardmäßig der Fall.
Erstelle mit dem Client-Ereignis conversation.item.create ein neues Textelement im Gespräch. Das funktioniert ähnlich wie das Senden einer Nutzernachricht (eines Prompts) an Chat Completions über die REST-API.
const event = {
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [
{
type: "input_text",
text: "What Prince album sold the most copies?",
},
],
},
};
// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));Nachdem du die Nutzernachricht zum Gespräch hinzugefügt hast, sende das Ereignis response.create, um eine Antwort des Modells auszulösen. Wähle eine Ausgabemodalität. Mit audio erhältst du Audio samt Transkript, mit text ausschließlich Text. Wenn du nur Text generieren möchtest, kannst du das wie im folgenden Beispiel beim Senden des Client-Ereignisses response.create angeben.
const event = {
type: "response.create",
response: {
output_modalities: ["text"],
},
};
// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));Sobald die Antwort vollständig vorliegt, sendet der Server das Ereignis response.done. Es enthält den gesamten vom Modell generierten Text, wie das folgende Beispiel zeigt.
function handleEvent(message: import("ws").RawData | MessageEvent<string>) {
const data = "data" in message ? message.data : message.toString();
const serverEvent = JSON.parse(data);
if (serverEvent.type === "response.done") {
console.log(serverEvent.response.output[0]);
}
}
// Listen for server messages (WebRTC)
// dataChannel.addEventListener("message", handleEvent);
// Listen for server messages (WebSocket)
ws.on("message", handleEvent);Während das Modell die Antwort generiert, sendet der Server mehrere Ereignisse. Du kannst auf Ereignisse wie response.output_text.delta lauschen, um den Fortschritt in Echtzeit anzuzeigen. In der Spalte Zugehörige Server-Ereignisse findest du alle Ereignisse, die der Server dabei sendet. Sie stehen ungefähr in der Reihenfolge, in der sie auftreten. Daneben findest du die Client-Ereignisse für die Textgenerierung.
| Zugehörige Client-Ereignisse | Zugehörige Server-Ereignisse |
|---|---|
Audioeingaben und Audioausgaben
Mit der Realtime API kannst du direkt mit dem Modell sprechen und gesprochene Antworten erhalten, ohne einen Zwischenschritt für die Sprachsynthese oder die Umwandlung von Sprache in Text. Das ermöglicht kürzere Reaktionszeiten bei Sprachschnittstellen und gibt dem Modell mehr Informationen über den Tonfall und die Betonung der gesprochenen Eingabe.
Stimmen auswählen
Für die Audioausgabe einer Realtime-Sitzung stehen mehrere integrierte Stimmen zur Auswahl. Lege voice beim Erstellen der Sitzung oder in einem Ereignis vom Typ response.create fest, um zu bestimmen, wie das Modell klingt. Derzeit stehen alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin und cedar zur Verfügung. Sobald das Modell in einer Sitzung Audio ausgegeben hat, lässt sich voice für diese Sitzung nicht mehr ändern. Für die beste Qualität empfehlen wir marin oder cedar.
Audio mit WebRTC verarbeiten
Wenn du dich über WebRTC mit der Realtime API verbindest, kommuniziert dein Client über eine Peer-Verbindung mit der API. Die Audioausgabe des Modells erreicht deinen Client als Medienstream der Gegenstelle. Für die Audioeingabe erfasst du den Ton eines Audiogeräts mit getUserMedia und fügst die Audiospuren des Medienstreams der Peer-Verbindung hinzu.
Der Beispielcode aus dem Leitfaden zu WebRTC-Verbindungen zeigt, wie du Audio für die lokale Seite und die Gegenstelle mit Browser-APIs konfigurierst.
// Create a peer connection
const pc = new RTCPeerConnection();
// Set up to play remote audio from the model
const audioEl = document.createElement("audio");
audioEl.autoplay = true;
pc.ontrack = (e) => (audioEl.srcObject = e.streams[0]);
// Add local audio track for microphone input in the browser
const ms = await navigator.mediaDevices.getUserMedia({
audio: true,
});
pc.addTrack(ms.getTracks()[0]);Mit diesem Code kannst du bereits mit der Realtime API interagieren. Weitere Beispiele für unterschiedliche Benutzeroberflächen findest du im Repository WebRTC-Beispiele. Die Beispiele kannst du auch als Live-Demos ausprobieren.
Mit den Browser-APIs für Medienaufnahme und Streaming kannst du unter anderem Mikrofone ein- und ausschalten und das Gerät für die Aufnahme auswählen.
Client- und Server-Ereignisse für Audio in WebRTC
Standardmäßig müssen WebRTC-Clients keine Client-Ereignisse an die Realtime API senden, bevor sie Audioeingaben übertragen. Sobald du der Peer-Verbindung eine lokale Audiospur hinzugefügt hast, können die Personen, die deine Anwendung nutzen, direkt lossprechen.
Während Client und Server über die Peer-Verbindung Audio austauschen, empfängt der WebRTC-Client weiterhin Server-Ereignisse zu den einzelnen Phasen. Dazu gehören folgende Ereignisse:
- Wenn Sprache über die lokale Medienspur übertragen wird, erhältst du vom Server Ereignisse vom Typ
input_audio_buffer.speech_started. - Wenn die lokale Spracheingabe endet, erhältst du das Ereignis
input_audio_buffer.speech_stopped. - Du erhältst Delta-Ereignisse für das entstehende Audiotranskript.
- Du erhältst das Ereignis
response.done, sobald das Modell die Antwort transkribiert und vollständig gesendet hat.
Oft bieten dir die WebRTC-APIs für Medienstreams bereits alle Steuerungsmöglichkeiten, die du brauchst. Gelegentlich musst du für die Audioein- und -ausgabe auf Schnittstellen einer niedrigeren Ebene zugreifen. Im folgenden Abschnitt zu WebSockets findest du weitere Informationen und die Ereignisse, mit denen du die Audioeingabe im Detail steuern kannst.
Audio mit WebSockets verarbeiten
Wenn du Audio über einen WebSocket überträgst, muss dein Client einige zusätzliche Schritte übernehmen, um Medien an den Server zu senden und von ihm zu empfangen. Die folgende Tabelle zeigt, welche Ereignisse du während einer WebSocket-Sitzung zum Senden und Empfangen von Audio brauchst.
Die Ereignisse sind in ihrer üblichen Reihenfolge aufgeführt. Einige können gleichzeitig auftreten, etwa die delta-Ereignisse.
| Phase | Client-Ereignisse | Server-Ereignisse |
|---|---|---|
| Initialisierung der Sitzung | ||
| Audioeingabe durch die sprechende Person | (vollständige Audionachricht senden) (Audio blockweise streamen) (bei deaktivierter VAD verwenden) (bei deaktivierter VAD verwenden) |
|
| Audioausgabe des Servers | (bei deaktivierter VAD verwenden) |
|
Audioeingaben an den Server streamen
Mit dem Client-Ereignis input_audio_buffer.append kannst du Audioeingaben an den Server streamen. Dabei sendest du Base64-kodierte Audio-Bytes blockweise über den Socket an die Realtime API. Jeder Block darf höchstens 15 MB groß sein.
Lege session.audio.input.format in session.update fest. Verwende für PCM {"type": "audio/pcm", "rate": 24000} und sende Mono-Audio mit einer Abtastrate von 24 kHz.
import fs from "fs";
import decodeAudio from "audio-decode";
// Converts Float32Array of audio data to PCM16 ArrayBuffer
function floatTo16BitPCM(float32Array: Float32Array) {
const buffer = new ArrayBuffer(float32Array.length * 2);
const view = new DataView(buffer);
let offset = 0;
for (let i = 0; i < float32Array.length; i++, offset += 2) {
const sample = Math.max(-1, Math.min(1, float32Array[i]));
view.setInt16(
offset,
Math.round(sample * (sample < 0 ? 0x8000 : 0x7fff)),
true
);
}
return buffer;
}
// Converts a Float32Array to base64-encoded PCM16 data
function base64EncodeAudio(float32Array: Float32Array<ArrayBufferLike>) {
const arrayBuffer = floatTo16BitPCM(float32Array);
let binary = "";
let bytes = new Uint8Array(arrayBuffer);
const chunkSize = 0x8000; // 32KB chunk size
for (let i = 0; i < bytes.length; i += chunkSize) {
let chunk = bytes.subarray(i, i + chunkSize);
binary += String.fromCharCode(...chunk);
}
return btoa(binary);
}
// Fills the audio buffer with the contents of three files,
// then asks the model to generate a response.
const files = [
"fixtures/sample1.wav",
"fixtures/sample2.wav",
"fixtures/sample3.wav",
];
// Manual commit and response creation require automatic turn detection off.
ws.send(
JSON.stringify({
type: "session.update",
session: {
type: "realtime",
audio: { input: { turn_detection: null } },
},
})
);
for (const filename of files) {
const audioFile = fs.readFileSync(filename);
const audioBuffer = await decodeAudio(audioFile);
if (
audioBuffer.sampleRate !== 24000 ||
audioBuffer.channelData.length !== 1
) {
throw new Error("Expected 24 kHz mono audio: " + filename);
}
const channelData = audioBuffer.channelData[0];
const base64Chunk = base64EncodeAudio(channelData);
ws.send(
JSON.stringify({
type: "input_audio_buffer.append",
audio: base64Chunk,
})
);
}
ws.send(JSON.stringify({ type: "input_audio_buffer.commit" }));
ws.send(
JSON.stringify({
type: "response.create",
response: { output_modalities: ["audio"] },
})
);Vollständige Audionachrichten senden
Du kannst auch vollständige Audioaufnahmen als Nachrichten zum Gespräch hinzufügen. Verwende das Client-Ereignis conversation.item.create, um Nachrichten mit Inhalten vom Typ input_audio zu erstellen.
const fullAudio = "<a base64-encoded string of audio bytes>";
const event = {
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [
{
type: "input_audio",
audio: fullAudio,
},
],
},
};
// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));Audioausgaben über einen WebSocket verarbeiten
Für die Audiowiedergabe auf einem Client, etwa in einem Webbrowser, empfehlen wir WebRTC anstelle von WebSockets. WebRTC überträgt Medien auch bei schwankenden Netzwerkbedingungen zuverlässiger an die Endgeräte.
Um Audioausgaben in Server-zu-Server-Anwendungen über einen WebSocket zu verarbeiten, musst du auf Ereignisse vom Typ response.output_audio.delta lauschen. Sie enthalten die Audiodaten des Modells in Base64-kodierten Blöcken. Du kannst diese Blöcke zwischenspeichern und in eine Datei schreiben oder sie direkt weiterstreamen, etwa in ein Telefongespräch über Twilio.
Beachte, dass die Ereignisse response.output_audio.done und response.done lediglich Transkripte der Audioinhalte enthalten. Um die Audio-Bytes selbst zu erhalten, musst du auf Ereignisse vom Typ response.output_audio.delta lauschen.
Das Format der ausgegebenen Blöcke kannst du für die gesamte Sitzung oder für einzelne Antworten festlegen.
- Für die Sitzung:
session.audio.output.formatinsession.update - Für eine Antwort:
response.audio.output.formatinresponse.create
function handleEvent(message: { toString: () => string }) {
const serverEvent = JSON.parse(message.toString());
if (serverEvent.type === "response.output_audio.delta") {
const audio = Buffer.from(serverEvent.delta, "base64");
console.log(`Received ${audio.length} audio bytes`);
}
}
// Listen for server messages (WebSocket)
ws.on("message", handleEvent);Bildeingaben
gpt-realtime-2 und gpt-realtime unterstützen auch Bildeingaben. Du kannst ein Bild als Teil des Inhalts an eine Nutzernachricht anhängen. Das Modell kann dann bei seiner Antwort berücksichtigen, was auf dem Bild zu sehen ist.
const base64Image = "<a base64-encoded string of image bytes>";
const event = {
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [
{
type: "input_image",
image_url: `data:image/{format};base64,${base64Image}`,
},
],
},
};
// WebRTC data channel and WebSocket both have .send()
dataChannel.send(JSON.stringify(event));Sprachaktivitätserkennung
In Realtime-Sitzungen ist die Sprachaktivitätserkennung (VAD) standardmäßig aktiviert. Die API erkennt dadurch, wann jemand anfängt oder aufhört zu sprechen, und antwortet automatisch.
Wie du VAD konfigurierst, erfährst du im Leitfaden zur Sprachaktivitätserkennung.
VAD deaktivieren
Um VAD zu deaktivieren, setze turn_detection auf null. Verwende dazu das Client-Ereignis session.update. Das bietet sich an, wenn du die Audioeingabe genau steuern möchtest, etwa bei einer Oberfläche mit Push-to-Talk.
Bei deaktivierter VAD muss der Client einige zusätzliche Ereignisse selbst senden, um Audioantworten auszulösen:
- Sende
input_audio_buffer.commitmanuell, um im Gespräch ein neues Element für die Nutzereingabe zu erstellen. - Sende
response.createmanuell, um eine Audioantwort des Modells auszulösen. - Sende
input_audio_buffer.clear, bevor eine neue Nutzereingabe beginnt.
VAD beibehalten und automatische Antworten deaktivieren
Wenn VAD aktiv bleiben soll, du aber selbst entscheiden möchtest, wann das Modell eine Antwort generiert, setze turn_detection.interrupt_response und turn_detection.create_response auf false. Verwende dazu das Client-Ereignis session.update. Die Sprachaktivitätserkennung funktioniert weiterhin wie gewohnt, ohne automatisch neue Antworten zu erstellen. Clients können Antworten manuell mit dem Ereignis response.create auslösen.
Das kann für die Moderation, die Validierung von Eingaben oder für RAG-Verfahren sinnvoll sein, wenn du für mehr Kontrolle über die Eingaben eine etwas höhere Latenz in Kauf nehmen kannst.
Antworten außerhalb des Standardgesprächs erstellen
Standardmäßig werden alle Antworten einer Sitzung in den Gesprächsverlauf dieser Sitzung aufgenommen (das „Standardgespräch“). Manchmal möchtest du jedoch Antworten außerhalb dieses Gesprächskontexts oder mehrere Antworten gleichzeitig generieren. Du kannst auch genauer festlegen, welche Gesprächselemente das Modell bei einer Antwort berücksichtigt, beispielsweise nur die letzten N Gesprächsbeiträge.
Um eine separate Antwort („Out-of-Band“) zu generieren, die nicht in den Verlauf des Standardgesprächs aufgenommen wird, setze das Feld response.conversation auf die Zeichenfolge none, wenn du die Antwort mit dem Client-Ereignis response.create erstellst.
Bei einer separaten Antwort möchtest du in der Regel erkennen können, welche Server-Ereignisse zu ihr gehören. Gib für die Modellantwort metadata an. Damit kannst du erkennen, welche Antwort für das vom Client gesendete Ereignis generiert wird.
const prompt = `
Analyze the conversation so far. If it is related to support, output
"support". If it is related to sales, output "sales".
`;
const event = {
type: "response.create",
response: {
// Setting to "none" indicates the response is out of band
// and will not be added to the default conversation
conversation: "none",
// Set metadata to help identify responses sent back from the model
metadata: { topic: "classification" },
// Set any other available response fields
output_modalities: ["text"],
instructions: prompt,
},
};
// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));Wenn du nun auf das Server-Ereignis response.done lauschst, kannst du das Ergebnis deiner separaten Antwort erkennen.
function handleEvent(message: import("ws").RawData | MessageEvent<string>) {
const data = "data" in message ? message.data : message.toString();
const serverEvent = JSON.parse(data);
if (
serverEvent.type === "response.done" &&
serverEvent.response.metadata?.topic === "classification"
) {
const { response } = serverEvent;
if (response.status !== "completed" || response.output.length === 0) {
throw new Error(
"Classification response ended with status " + response.status
);
}
console.log(response.output[0]);
}
}
// Listen for server messages (WebRTC)
// dataChannel.addEventListener("message", handleEvent);
// Listen for server messages (WebSocket)
ws.on("message", handleEvent);Eigenen Kontext für Antworten erstellen
Du kannst dem Modell auch einen eigenen Kontext außerhalb des aktuellen Standardgesprächs vorgeben, in dem es seine Antwort generieren soll. Verwende dazu das Array input im Client-Ereignis response.create. Du kannst neue Eingaben angeben oder über ihre IDs auf vorhandene Eingabeelemente im Gespräch verweisen.
const existingItemId = "item_pizza";
ws.send(
JSON.stringify({
type: "conversation.item.create",
item: {
id: existingItemId,
type: "message",
role: "user",
content: [
{ type: "input_text", text: "We are ordering pizza for dinner." },
],
},
})
);
const event = {
type: "response.create",
response: {
conversation: "none",
metadata: { topic: "pizza" },
output_modalities: ["text"],
// Create a custom input array for this request with whatever context
// is appropriate
input: [
// potentially include existing conversation items:
{
type: "item_reference",
id: existingItemId,
},
{
type: "message",
role: "user",
content: [
{
type: "input_text",
text: "Is it okay to put pineapple on pizza?",
},
],
},
],
},
};
// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));Antworten ohne Kontext erstellen
Du kannst auch Antworten in das Standardgespräch einfügen, bei denen das Modell alle anderen Anweisungen und den bisherigen Kontext außer Acht lässt. Setze dazu input auf ein leeres Array.
const prompt = `
Say exactly the following:
I'm a little teapot, short and stout!
This is my handle, this is my spout!
`;
const event = {
type: "response.create",
response: {
// An empty input array removes existing context
input: [],
output_modalities: ["text"],
instructions: prompt,
},
};
// WebRTC data channel and WebSocket both have .send()
ws.send(JSON.stringify(event));Funktionsaufrufe
Realtime-Modelle unterstützen auch Funktionsaufrufe. Damit kannst du eigenen Code ausführen, um die Möglichkeiten des Modells zu erweitern. Der Ablauf sieht so aus:
- Beim Aktualisieren der Sitzung oder Erstellen einer Antwort kannst du eine Liste der Funktionen angeben, die das Modell aufrufen kann.
- Wenn das Modell bei der Verarbeitung einer Eingabe entscheidet, eine Funktion aufzurufen, fügt es dem Gespräch Elemente mit den Argumenten für den Funktionsaufruf hinzu.
- Erkennt der Client Gesprächselemente mit Argumenten für einen Funktionsaufruf, führt er mit diesen Argumenten eigenen Code aus.
- Nach der Ausführung erstellt der Client neue Gesprächselemente mit dem Ergebnis des Funktionsaufrufs und fordert das Modell zu einer Antwort auf.
Als praktisches Beispiel ergänzen wir eine Funktion, mit der das Modell auf Anfrage das Tageshoroskop ausgeben kann. Dabei siehst du, wie die Ereignisobjekte aufgebaut sind, die der Client senden muss, und welche Ereignisse der Server daraufhin sendet.
Aufrufbare Funktionen konfigurieren
Gib zunächst an, welche Funktionen das Modell je nach Nutzereingabe aufrufen kann. Du kannst die verfügbaren Funktionen für die gesamte Sitzung oder für einzelne Antworten konfigurieren.
- Für die Sitzung: Eigenschaft
session.toolsinsession.update - Für eine Antwort: Eigenschaft
response.toolsinresponse.create
Die folgenden Beispieldaten für das Client-Ereignis session.update konfigurieren eine Funktion, die ein Horoskop erstellt. Sie erwartet als einziges Argument das Sternzeichen, für das sie das Horoskop erstellen soll.
{
"type": "session.update",
"session": {
"tools": [
{
"type": "function",
"name": "generate_horoscope",
"description": "Give today's horoscope for an astrological sign.",
"parameters": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The sign for the horoscope.",
"enum": [
"Aries",
"Taurus",
"Gemini",
"Cancer",
"Leo",
"Virgo",
"Libra",
"Scorpio",
"Sagittarius",
"Capricorn",
"Aquarius",
"Pisces"
]
}
},
"required": ["sign"]
}
}
],
"tool_choice": "auto"
}
}
Die description-Felder der Funktion und ihrer Parameter helfen dem Modell zu entscheiden, ob es die Funktion aufrufen soll und welche Daten es für die einzelnen Parameter angeben muss. Geht aus der Eingabe hervor, dass jemand sein Horoskop erfahren möchte, ruft das Modell die Funktion mit dem Parameter sign auf.
Erkennen, wann das Modell eine Funktion aufrufen möchte
Je nach Eingabe kann das Modell entscheiden, eine Funktion aufzurufen, um die bestmögliche Antwort zu generieren. Angenommen, unsere Anwendung fügt mit dem Ereignis conversation.item.create das folgende Gesprächselement hinzu und erstellt anschließend eine Antwort:
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is my horoscope? I am an aquarius."
}
]
}
}
Um die Antwort zu generieren, sendet der Client anschließend das Ereignis response.create:
{
"type": "response.create"
}
Das Modell gibt zunächst die Argumente zurück, die deine Anwendung an die Funktion übergeben soll. Mit dem Server-Ereignis response.function_call_arguments.delta kannst du in Echtzeit verfolgen, wie die Argumente entstehen. Auch response.done enthält alle Daten, die wir für den Funktionsaufruf benötigen.
{
"type": "response.done",
"event_id": "event_AeqLA8iR6FK20L4XZs2P6",
"response": {
"object": "realtime.response",
"id": "resp_AeqL8XwMUOri9OhcQJIu9",
"status": "completed",
"status_details": null,
"output": [
{
"object": "realtime.item",
"id": "item_AeqL8gmRWDn9bIsUM2T35",
"type": "function_call",
"status": "completed",
"name": "generate_horoscope",
"call_id": "call_sHlR7iaFwQ2YQOqm",
"arguments": "{\"sign\":\"Aquarius\"}"
}
]
}
}
An den folgenden Eigenschaften in den JSON-Daten des Servers erkennst du, dass das Modell eine von dir definierte Funktion aufrufen möchte:
| Eigenschaft | Bedeutung für den Funktionsaufruf |
|---|---|
response.output[0].type |
Der Wert function_call zeigt an, dass die Antwort Argumente für den Aufruf einer bestimmten Funktion enthält. |
response.output[0].name |
Name der konfigurierten Funktion, die aufgerufen werden soll, hier generate_horoscope. |
response.output[0].arguments |
Eine JSON-Zeichenfolge mit den Argumenten für die Funktion, in unserem Fall "{\"sign\":\"Aquarius\"}". |
response.output[0].call_id |
Eine vom System generierte ID für diesen Funktionsaufruf. Du brauchst diese ID, um das Ergebnis des Funktionsaufrufs an das Modell zurückzugeben. |
Mit diesen Informationen können wir in unserer Anwendung den Code ausführen, der das Horoskop erstellt. Anschließend geben wir das Ergebnis an das Modell zurück, damit es eine Antwort generieren kann.
Das Ergebnis eines Funktionsaufrufs an das Modell zurückgeben
Sobald deine Anwendung eine Modellantwort mit den Argumenten für einen Funktionsaufruf erhält, kann sie den entsprechenden Code ausführen. Was dieser Code tut, bestimmst du selbst. Er kann zum Beispiel externe APIs aufrufen oder auf Datenbanken zugreifen.
Sobald du das Ergebnis deines Codes an das Modell zurückgeben möchtest, kannst du mit dem Client-Ereignis conversation.item.create ein neues Gesprächselement erstellen, das dieses Ergebnis enthält.
{
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_sHlR7iaFwQ2YQOqm",
"output": "{\"horoscope\": \"You will soon meet a new friend.\"}"
}
}
- Das Gesprächselement hat den Typ
function_call_output. item.call_idist dieselbe ID, die wir zuvor im Ereignisresponse.doneerhalten haben.item.outputist eine JSON-Zeichenfolge mit dem Ergebnis unseres Funktionsaufrufs.
Nachdem wir das Gesprächselement mit dem Ergebnis des Funktionsaufrufs hinzugefügt haben, senden wir vom Client erneut das Ereignis response.create. Dadurch generiert das Modell eine Antwort auf Grundlage der Daten aus dem Funktionsaufruf.
{
"type": "response.create"
}
Fehlerbehandlung
Das Ereignis error sendet der Server immer dann, wenn während der Sitzung auf dem Server ein Fehler auftritt. Manchmal lässt sich der Fehler auf ein Client-Ereignis zurückführen, das deine Anwendung gesendet hat.
Bei HTTP gehört jede Antwort implizit zu einer Anfrage des Clients. Um bei der Realtime API zu erkennen, welches Client-Ereignis einen Fehler auf dem Server ausgelöst hat, musst du dem Ereignis eine event_id mitgeben. Das folgende Beispiel zeigt, wie das funktioniert, wenn der Client versucht, ein Ereignis mit einem nicht unterstützten Typ zu senden.
const event = {
event_id: "my_awesome_event",
type: "scooby.dooby.doo",
};
dataChannel.send(JSON.stringify(event));Auf dieses ungültige Client-Ereignis reagiert der Server mit einem Fehlerereignis wie diesem:
{
"type": "error",
"event_id": "event_error_123",
"error": {
"type": "invalid_request_error",
"code": "invalid_value",
"message": "Invalid value: 'scooby.dooby.doo'.",
"param": "type",
"event_id": "my_awesome_event"
}
}
Antworten unterbrechen und kürzen
In vielen Sprachanwendungen kann die sprechende Person das Modell unterbrechen, während es antwortet. Bei aktivierter VAD erkennt die Realtime API, dass jemand spricht, bricht die laufende Antwort ab und startet eine neue. Damit das Modell das Gespräch natürlich fortsetzen kann, muss es wissen, an welcher Stelle es unterbrochen wurde, etwa wenn jemand fragt: „Was hast du gerade gesagt?“ Dazu kürzt du die letzte Antwort des Modells, indem du den noch nicht abgespielten Teil aus dem Gespräch entfernst.
Bei WebRTC- und SIP-Verbindungen verwaltet der Server einen Puffer für die Audioausgabe. Dadurch weiß er jederzeit, wie viel Audio bereits abgespielt wurde. Unterbricht jemand das Modell, entfernt der Server automatisch den noch nicht abgespielten Teil.
Bei einer WebSocket-Verbindung steuert der Client die Audiowiedergabe. Er muss daher die Wiedergabe stoppen und die Antwort kürzen. Gehe dazu wie folgt vor:
- Stoppe bei
input_audio_buffer.speech_startedsofort die Wiedergabe der Modellantwort und verwirf alle Audiodaten dieses Elements, die noch auf die Wiedergabe warten. Halte fest, wie viele Millisekunden der Audiospur dieses Elements die Person tatsächlich gehört hat. - Sende das Ereignis
conversation.item.truncatemit der ID des unterbrochenen Elements, dem Index des Audioinhalts und der abgespielten Dauer alsaudio_end_ms. Dadurch wird der noch nicht abgespielte Teil aus dem Gespräch entfernt. - Wenn VAD eine laufende Antwort unterbricht, bricht der Server sie ab und sendet
response.done. Darin hatresponse.statusden Wertcancelled. An diesem Ereignis erkennst du, dass die Antwort beendet ist. Warte jedoch nicht darauf, bevor du die Wiedergabe stoppst oder das Ereignis zum Kürzen sendest.
Ein Beispiel:
{
"type": "conversation.item.truncate",
"item_id": "item_1234",
"content_index": 0,
"audio_end_ms": 1500
}
Das Beispiel kürzt das Audio auf eine Wiedergabedauer von 1,5 Sekunden.
Was passiert dabei mit dem Transkript? Dem Realtime-Modell fehlen die Informationen, um Textstellen präzise den entsprechenden Stellen im Audio zuzuordnen. Deshalb schneidet conversation.item.truncate das Audio an der angegebenen Stelle ab und entfernt das Texttranskript für den noch nicht abgespielten Teil. So lässt sich das noch nicht abgespielte Audio entfernen. Ein gekürztes Transkript erhältst du dabei nicht.
Push-to-Talk
Die Realtime API verwendet standardmäßig die Sprachaktivitätserkennung (VAD), sodass Audioeingaben Modellantworten auslösen. Für Push-to-Talk kannst du VAD deaktivieren und in deiner Anwendung steuern, wann Audioeingaben an das Modell gesendet werden. Du kannst beispielsweise Audio aufnehmen, solange jemand die Leertaste gedrückt hält, und beim Loslassen eine Antwort auslösen. Für manche Apps funktioniert das besonders gut. Wer die App nutzt, steuert den Gesprächsablauf selbst. Fehler der Sprachaktivitätserkennung entfallen, und die App reagiert schnell, weil sie nicht auf einen VAD-Timeout warten muss.
Die Implementierung von Push-to-Talk unterscheidet sich bei WebSockets und WebRTC. Bei einer WebSocket-Verbindung zur Realtime API laufen alle Ereignisse in ihrer Sendereihenfolge über denselben Kanal. Eine WebRTC-Verbindung verwendet getrennte Kanäle für Audio und Steuerereignisse.
WebSockets
Bei Push-to-Talk über eine WebSocket-Verbindung muss der Client die Audiowiedergabe stoppen, Unterbrechungen verarbeiten und eine neue Antwort auslösen. Gehe dazu wie folgt vor:
- Deaktiviere VAD, indem du
"turn_detection": nullin einem Ereignis vom Typsession.updateangibst. - Starte beim Drücken der Taste die Audioaufnahme auf dem Client.
- Wenn das Modell gerade eine Antwort generiert, brich sie mit dem Ereignis
response.cancelab. - Wenn gerade eine Audioausgabe des Modells abgespielt wird, stoppe die Wiedergabe sofort. Sende das Ereignis
conversation.item.truncate, um noch nicht abgespieltes Audio aus dem Gespräch zu entfernen.
- Wenn das Modell gerade eine Antwort generiert, brich sie mit dem Ereignis
- Sende beim Loslassen der Taste eine Nachricht vom Typ
input_audio_buffer.appendmit der Aufnahme, um die neuen Audiodaten in den Eingabepuffer zu schreiben. - Sende das Ereignis
input_audio_buffer.commit, um die Audiodaten aus dem Eingabepuffer als Eingabe zu übernehmen und die Eingabetranskription zu starten, sofern sie aktiviert ist. - Löse anschließend mit dem Ereignis
response.createeine Antwort aus.
WebRTC und SIP
Mit WebRTC implementierst du Push-to-Talk ähnlich, musst den Puffer für Audioeingaben aber explizit leeren. Gehe dazu wie folgt vor:
- Deaktiviere VAD, indem du
"turn_detection": nullin einem Ereignis vom Typsession.updateangibst. - Sende beim Drücken der Taste das Ereignis
input_audio_buffer.clear, um vorherige Audioeingaben aus dem Puffer zu entfernen.- Wenn das Modell gerade eine Antwort generiert, brich sie mit dem Ereignis
response.cancelab. - Wenn gerade eine Audioausgabe des Modells abgespielt wird, sende das Ereignis
output_audio_buffer.clear, um das noch nicht abgespielte Audio aus dem Puffer zu entfernen. Dabei wird auch die Antwort im Gespräch entsprechend gekürzt.
- Wenn das Modell gerade eine Antwort generiert, brich sie mit dem Ereignis
- Sende beim Loslassen der Taste das Ereignis
input_audio_buffer.commit, um die Audiodaten aus dem Eingabepuffer als Eingabe zu übernehmen und die Eingabetranskription zu starten, sofern sie aktiviert ist. - Löse anschließend mit dem Ereignis
response.createeine Antwort aus.