Sobald du eine Verbindung zu GPT-Live hergestellt hast, kannst du mit Sitzungsereignissen Kontext hinzufügen, Transkripte anzeigen und die Verbindung verwalten. GPT-Live kann gleichzeitig zuhören und sprechen. Erfasse Transkripttext, wiedergegebenes Audio und den Fortschritt von Backend-Aufgaben getrennt. So kann deine Oberfläche anzeigen, was der Assistent gerade sagt und welche Aufgaben noch laufen.
Dieser Leitfaden setzt voraus, dass deine Verbindung bereits session.started gemeldet hat. Wie du die Verbindung aufbaust und Audio streamst, erfährst du unter Verbindungen. Aufgaben im Backend beschreibt der Leitfaden Delegation und Tools.
Sitzung konfigurieren
Wähle beim Erstellen der Sitzung das Modell, die Stimme und den Delegationsmodus. Gib dem Modell Anweisungen für das Gespräch und übergib relevante Teile des bisherigen Verlaufs. GPT-Live verwaltet den Kontext automatisch, während das Gespräch fortschreitet.
Konfigurationsfelder
| Einstellung | Beim Start konfigurieren | Während der Sitzung ändern |
|---|---|---|
| Modell | Gib das erforderliche Feld model an. |
Starte für einen Modellwechsel eine neue Sitzung. |
| Anweisungen | Lege mit instructions fest, wie sich das Modell im Gespräch verhalten soll. Dafür stehen dir bis zu 16.384 Token zur Verfügung. |
Ergänze Anweisungen mit session.instructions.append. |
| Gesprächsverlauf | Übergib in input relevante frühere Textnachrichten. Der Standardwert ist []. |
Ergänze Kontext mit Append-Ereignissen. |
| Stimme | Gib in audio.output.voice eine unterstützte Stimme oder eine autorisierte benutzerdefinierte Stimme an. Der Standardwert ist marin. |
Starte für einen Stimmenwechsel eine neue Sitzung. |
| Delegation | Setze delegation.type auf client oder responses. Lässt du die Delegation weg oder gibst du null an, gilt der Client-Modus. |
Ändere die Responses-Einstellungen innerhalb des bestehenden Modus. |
| Speicherung | Setze store auf true, damit du die Sitzung später forken kannst. Der Standardwert ist false. |
Lege die Einstellung beim Start fest. |
Verfügbare Stimmen
Wähle beim Erstellen der Sitzung eine Stimme aus. Gib in audio.output.voice ihren API-Namen an, zum Beispiel "quartz". GPT-Live bietet diese zusätzlichen Stimmen an:
| Stimme | API-Name | Sprache | Regionale Prägung | Stimmcharakter | Herkunft |
|---|---|---|---|---|---|
| Quartz | quartz |
Englisch | Australien | Weiblich | Generiert |
| Ripple | ripple |
Englisch | Australien | Männlich | Natürlich |
| Vesper | vesper |
Englisch | Großbritannien | Männlich | Natürlich |
| Willow | willow |
Englisch | Irland | Weiblich | Natürlich |
| Stone | stone |
Englisch | Irland | Männlich | Natürlich |
| Gleam | gleam |
Englisch | Nordamerika | Weiblich | Natürlich |
| Meridian | meridian |
Englisch | Nordamerika | Männlich | Natürlich |
| Bossa | bossa |
Portugiesisch | Brasilien | Weiblich | Natürlich |
| Tempo | tempo |
Portugiesisch | Brasilien | Männlich | Natürlich |
| Beacon | beacon |
Englisch | Philippinen | Männlich | Generiert |
| Delta | delta |
Englisch | Süden der USA | Weiblich | Generiert |
| Cinder | cinder |
Englisch | Süden der USA | Männlich | Generiert |
| Nuri | nuri |
Deutsch | – | Weiblich | Natürlich |
| Juni | juni |
Deutsch | – | Weiblich | Natürlich |
| Flitz | flitz |
Deutsch | – | Männlich | Natürlich |
| Brise | brise |
Französisch | – | Weiblich | Natürlich |
| Sillage | sillage |
Französisch | – | Männlich | Natürlich |
| Nira | nira |
Hindi | – | Weiblich | Natürlich |
| Harema | harema |
Japanisch | – | Weiblich | Natürlich |
| Shida | shida |
Japanisch | – | Männlich | Natürlich |
| Noeul | noeul |
Koreanisch | – | Weiblich | Natürlich |
Die regionale Prägung beschreibt die Sprechweise einer Stimme. Teste die Stimme in den Sprachen, die deine Anwendung benötigt, und prüfe die Aussprache. Wie du eine Stimme anhand einer Textbeschreibung oder einer genehmigten Aufnahme erstellst, erfährst du unter Benutzerdefinierte Stimmen.
Bei WebSocket legst du audio.format beim Start fest. Das Format gilt für die Audioeingabe und die Audioausgabe der gesamten Sitzung. Starte eine neue Sitzung, wenn du ein anderes Format verwenden möchtest. WebRTC handelt das Audioformat beim Verbindungsaufbau aus. Lass audio.format deshalb in WebRTC-Anfragen weg. Die unterstützten Formate und Details zum Streaming findest du unter Audioformate für WebSocket.
Laufende Sitzung aktualisieren
Mit session.update kannst du session.delegation.responses ändern, wenn die Sitzung bereits die Responses-Delegation verwendet. Sende nur die Einstellungen, die du ändern möchtest. Alle übrigen behalten ihren Wert. Die Einstellungen und das Vorgehen findest du unter Responses-Delegation konfigurieren.
Lege den Delegationsmodus und die Felder model, instructions, input, audio und store beim Start fest. Verwende session.update nur für die oben beschriebenen Responses-Einstellungen. Andere Konfigurationsfelder weist die API zurück. Erstelle eine neue Sitzung, um den Delegationsmodus zu wechseln. Mit delegation: null wählst du beim Start die Client-Delegation. Die Responses-Standardeinstellungen werden dadurch nicht wiederhergestellt.
Nach einer erfolgreichen Änderung erhältst du session.updated mit der aktualisierten Sitzungskonfiguration. Ordne das Ereignis der gesendeten event_id über client_event_id zu. Behandle abgelehnte Befehle in derselben Ereignisschleife. Verfolge Backend-Aufgaben und Sprachausgabe über ihre jeweiligen Ereignisse.
Gesprächsverlauf und Kontext bereitstellen
Übergib beim Start den bisherigen Gesprächsverlauf, um ein Thema wieder aufzugreifen. Ergänze im weiteren Gespräch relevanten Kontext. Halte vertrauenswürdige Anweisungen deiner Anwendung von Nachrichten der nutzenden Person und sachlichen Ergebnissen getrennt.
Sitzung mit bisherigem Gesprächsverlauf starten
Übergib beim Erstellen der Sitzung frühere Textnachrichten in session.input. Füge zum Beispiel dieses input-Feld in die Konfiguration für die Sitzungserstellung ein:
export const session = {
model: "gpt-live-1",
input: [
{
type: "message",
role: "user",
content: [
{
type: "input_text",
text: "I need help with my recent order.",
},
],
},
{
type: "message",
role: "assistant",
content: [
{
type: "output_text",
text: "What is the order number?",
},
],
},
],
};Die Liste kann bis zu 128 Nachrichten mit insgesamt höchstens 8.192 Token enthalten. Jede Nachricht hat genau einen Textteil und eine der folgenden Rollen: developer, user oder assistant. Nachrichten mit Entwickler- oder Nutzerrolle verwenden input_text. Nachrichten des Assistenten verwenden text oder output_text. Übergib vertrauenswürdige Anweisungen deiner Anwendung in instructions oder in einer Nachricht mit Entwicklerrolle.
Wähle die früheren Textnachrichten aus, die für die nächste Interaktion nötig sind, und übergib sie beim Start. Während der Sitzung kannst du mit den folgenden Kontextereignissen neue Informationen ergänzen. Übermittle Backend-spezifische Inhalte wie Tool-Ergebnisse über den Delegationsablauf.
Wann der Kontext das Modell erreicht
Übergib den Kontext, den das Modell von Anfang an benötigt, in input. Der gesamte Feldinhalt ist beim Sitzungsstart verfügbar.
In einer laufenden Sitzung fügen session.instructions.append, session.thinking.append und session.commentary.append nach und nach Kontext hinzu. Die Bestätigung trifft ein, sobald die Sitzung auf ihrer Zeitachse das geschätzte Ende des hinzugefügten Kontexts erreicht. Die Werte start_ms und end_ms in der Bestätigung geben den ungefähren Zeitraum für diese Ergänzung auf der Zeitachse der Sitzung an.
Diese Zeitangaben beziehen sich ausschließlich auf die Übermittlung des Kontexts. Für die Sprachausgabe und die Wiedergabe gelten andere Zeitpunkte. Das Modell kann antworten, bevor es die gesamte Ergänzung berücksichtigt hat. Hängt eine Aktion von einer neuen Anweisung oder Information ab, prüfe in deiner Anwendung, ob das Modell wie erwartet reagiert.
Wenn die Zeitachse der Sitzung nicht weiterläuft, kann die Bestätigung ausstehen. Ordne Bestätigungen der gesendeten event_id über client_event_id zu und behandle während der Wartezeit weiterhin Fehler. Beim Schließen der Sitzung erhältst du für noch ausstehende Ergänzungen Fehlermeldungen.
Im Gespräch Kontext hinzufügen
Wähle das Ereignis danach aus, wie das Modell die Ergänzung verwenden soll:
session.instructions.append: Ergänze vertrauenswürdige Anweisungen deiner Anwendung, die das Verhalten und die Äußerungen des Modells beeinflussen.session.thinking.append: Ergänze sachliche Informationen, ohne das Modell aufzufordern, sie sofort auszusprechen.session.commentary.append: Übergib Informationen, die das Modell aussprechen soll. Es darf sie umformulieren.
Jedes Ereignis erwartet in content eine einfache Zeichenfolge mit bis zu 500 Token. Außerdem ist delegation_id erforderlich. Verwende null für Kontext, der für die gesamte Sitzung gilt. Sende zum Beispiel das folgende Ereignis, nachdem deine Anwendung die Zustimmung der nutzenden Person geprüft und die Abfrage gestartet hat:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.thinking.append",
event_id: "context_1",
delegation_id: null,
content:
"The user has already accepted the terms. The account lookup is still running.",
});
}Verarbeite session.thinking.appended mit client_event_id: "context_1" oder den zugehörigen Fehler, um diese Ergänzung zu verfolgen. Wann die Bestätigung eintrifft, erfährst du unter Wann der Kontext das Modell erreicht.
Der Assistent kann Informationen wiederholen, die du über eines dieser Ereignisse übermittelt hast. Sende nur Informationen, die für das Gespräch geeignet sind. Bewahre Zugangsdaten und Geheimnisse im Backend auf. Verwende session.instructions.append, um das von deiner Anwendung vorgegebene Verhalten festzulegen. Übergib sachliche Tool-Ergebnisse als Kontext. Setze Berechtigungen im Anwendungscode durch und stelle dort sicher, dass erforderliche Bestätigungen vorliegen.
Wie du GPT-Live mit kurzen Aktualisierungen zu Seitenwechseln, zur aktuellen Auswahl und zu anderen Änderungen der Oberfläche vermittelst, worauf sich eine Person bezieht, erfährst du unter Kontext der Benutzeroberfläche teilen.
Verwende für eine Aktualisierung zu einer bestimmten Backend-Aufgabe die ID der zugehörigen Client-Delegation. Die Delegations-ID bezeichnet die Live-Aufgabe. Antwort-IDs von Responses und IDs von Tool-Aufrufen bezeichnen jeweils andere Objekte. Den Ablauf findest du unter Das passende Ereignis für eine Aktualisierung senden.
Wenn deine Anwendung ein Problem erkennt, sende eine kurze Korrektur über den primären WebSocket der Sitzung oder über einen Sideband-WebSocket. Wie du Prüfungen ausführst, Aktionen steuerst und die Wiedergabe handhabst, erfährst du unter Schutzmaßnahmen für Gespräche anwenden.
Sprache und Transkripte verwalten
Transkriptfragmente
Verarbeite session.input_transcript.delta für Äußerungen der anrufenden Person und session.output_transcript.delta für Äußerungen des Assistenten. Jedes Ereignis enthält ein Textfragment und das zugehörige Zeitintervall auf der Zeitachse der Sitzung:
{
"type": "session.input_transcript.delta",
"event_id": "event_transcript_1",
"delta": "What is",
"start_ms": 1000,
"end_ms": 1200
}
Füge die delta-Fragmente für jede Gesprächsseite genau so aneinander, wie du sie empfängst. Behalte Leerzeichen und Wortwiederholungen bei. Speichere auch die zugehörigen Werte für start_ms und end_ms. Sie geben die Zeit in Millisekunden seit Sitzungsbeginn an. Das Beispiel oben umfasst den Zeitraum von einschließlich 1.000 ms bis ausschließlich 1.200 ms. Die Werte geben den ungefähren Zeitraum eines Fragments an. Exakte Wortgrenzen lassen sich daraus nicht ableiten. Nutze diese Werte anstelle der Empfangszeiten der Pakete, um das Transkript zu ordnen.
Transkriptereignisse treffen für Zeitintervalle ein, in denen Text vorliegt. Die Abstände zwischen den Ereignissen können schwanken. Ein Fragment kann nur einen Teil eines Satzes enthalten. Eine Lücke beim Empfang kann auf eine Netzwerkverzögerung zurückgehen. Transkriptfragmente haben keine Element-ID, und kein Ereignis markiert das Ende eines Gesprächsbeitrags. Deine Anwendung entscheidet daher, wie sie die Fragmente für die Anzeige gruppiert.
Du kannst selbst entscheiden, ob du Transkriptfragmente verarbeitest. Damit kannst du die Oberfläche aktualisieren, Prüfungen ausführen oder Aufgaben schon während des Gesprächs starten. Für einfache Prüfungen bietet sich ein kleines Modell wie gpt-5.6-luna mit geringem Reasoning-Aufwand an. Beispiele und Hinweise zur Verbindung findest du unter Auf Transkriptfragmente reagieren.
Mit Schutzmaßnahmen auf Basis des Transkripts kannst du das Gespräch verfolgen und eingreifen, während noch gesprochen wird. Wenn deine Anwendung Äußerungen des Assistenten vor der Wiedergabe prüfen muss, findest du Hinweise zum Puffern, Freigeben, Unterbrechen und Fortsetzen unter Sprache vor der Wiedergabe prüfen.
Erfasse die Zeitangaben im Transkript getrennt von der Audiowiedergabe. Bei WebSocket enthalten Ereignisse vom Typ session.output_audio.delta keine Zeitangaben. Es gibt auch kein Ereignis, das das Ende der Audioausgabe meldet. WebRTC überträgt Audio über seine Medienspur. Hinweise zur Audioverarbeitung findest du unter Verbindungen.
Untertitel anzeigen
GPT-Live unterstützt Vollduplex. Die anrufende Person und der Assistent können gleichzeitig sprechen. Aktualisiere ihre Untertitel unabhängig voneinander, damit beide Texte weiterwachsen können, wenn sich die Äußerungen überschneiden.
Wenn deine App Sprechblasen verwendet, können die Fragmente „Ich möchte“ und „ meine Buchung ändern“ in derselben Sprechblase der anrufenden Person erscheinen. Sagt der Assistent „Gerne“, während die Person weiterspricht, zeige diese Bestätigung separat an und ergänze weiterhin den Text in der Sprechblase der Person. Bewahre die ursprünglichen Fragmente und Zeitstempel auf, damit du später eintreffenden Text der richtigen Sprechblase zuordnen kannst.
Verwende session.output_transcript.delta für Untertitel zur Sprachausgabe und zeige Backend-Aktualisierungen separat an. Entscheide in der Aufgabenlogik deiner Anwendung, ob sie Tools ausführt oder Aufgaben abbricht. Halte diese Entscheidungen davon getrennt, wie du Text für die Anzeige gruppierst.
Mikrofoneingabe steuern
Sende session.input_audio.mute, um die Eingabe stummzuschalten, ohne die Sitzung zu beenden:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.input_audio.mute",
event_id: "mute_1",
});
}Warte auf session.input_audio.muted mit client_event_id: "mute_1", bevor du den Befehl als angenommen behandelst. Um die Eingabe fortzusetzen, sende session.input_audio.unmute und warte auf session.input_audio.unmuted. Behandle Fehler bei beiden Befehlen.
Bei stummgeschalteter Eingabe läuft die Sitzung weiter. Das Modell kann weiterhin Sprache erzeugen, und delegierte Aufgaben können weiterlaufen. Wenn du auch die lokale Aufnahme oder Wiedergabe stoppen musst, verwende dafür die Mikrofon- und Wiedergabesteuerung deiner Anwendung.
Das Gespräch mit einer Begrüßung eröffnen
Wenn GPT-Live das Gespräch eröffnen soll, erzielst du die besten Ergebnisse, indem du beim Erstellen der Sitzung die Anweisungen zur Begrüßung in einer developer-Nachricht in session.input übergibst. Bei WebSocket fügst du die Nachricht in das Ereignis session.start ein. So stehen die Anweisungen von Anfang an zur Verfügung.
Gib die Sprache und den Inhalt der Begrüßung vor. Weise den Assistenten an, sofort zu beginnen und anschließend zu pausieren und zuzuhören. Verwende die von der Anwendung gewählte Begrüßungssprache, bis die anrufende Person spricht. Für die Nachricht mit Entwicklerrolle kannst du zum Beispiel diesen Text verwenden:
Begrüße die anrufende Person jetzt auf Englisch. Stelle dich als Support-Assistent vor und frage, wie du helfen kannst. Mach dann eine Pause und höre zu.
- Füge die Nachricht zu
session.inputhinzu. Verwenderole: "developer"und einen einzelnen Inhaltsteil vom Typinput_text. Das Nachrichtenformat findest du unter Sitzung mit bisherigem Gesprächsverlauf starten. - Warte auf
session.started. Sende anschließend dieselben Begrüßungsanweisungen wie unten gezeigt einmal übersession.commentary.appendmit einer eindeutigenevent_idunddelegation_id: null. Lass die Audioeingabe aktiv und übertrage auch die Stille, bevor die anrufende Person spricht. Sende bei WebSocket weiterhinsession.input_audio.append. Halte bei WebRTC die Audiospur für die Eingabe aktiv. - Prüfe anhand der Audioausgabe und des Transkripts, ob der Assistent die anrufende Person begrüßt hat. Anweisungen beim Start können die Begrüßung zuverlässiger machen, garantieren aber nicht, dass das Modell spricht.
{
"type": "session.commentary.append",
"event_id": "greeting_1",
"delegation_id": null,
"content": "Greet the caller now in English. Introduce yourself as the support assistant and ask how you can help. Then pause and listen."
}
Das Ereignis session.commentary.appended bestätigt den Empfang der Anfrage. Ob die Begrüßung ausgesprochen oder wiedergegeben wurde, geht daraus nicht hervor. GPT-Live kann die Begrüßung umformulieren, Wörter hinzufügen oder stumm bleiben.
Wenn du eine verlässliche Wiedergabe, einen exakten Wortlaut oder einen bekannten Endzeitpunkt brauchst, spiele eine geprüfte Aufnahme oder einen vorab gerenderten Audioclip über deine Anwendung ab und steuere währenddessen die GPT-Live-Wiedergabe. Teste Begrüßungen in allen unterstützten Sprachen, auch für den Fall, dass die anrufende Person schon während der Begrüßung spricht. Hinweise zum Formulieren von Prompts findest du unter Prompts für Sprachmodelle.
Einen Hinweis vorlesen lassen
Fordere mit session.instructions.append einen bestimmten Wortlaut für einen gesprochenen Hinweis an. Bei session.commentary.append kann das Modell den Text umformulieren. Sende nach session.started zum Beispiel Folgendes:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.instructions.append",
event_id: "disclosure_1",
delegation_id: null,
content:
"Immediately say the following disclosure exactly and in full before responding to the caller: This call may be recorded for quality and training purposes.",
});
}Lass die Audioeingabe aktiv, wie unter Das Gespräch mit einer Begrüßung eröffnen beschrieben. Eine während des Gesprächs gesendete Anweisung kann eine laufende Äußerung unterbrechen.
Prüfe den generierten Hinweis und seine Wiedergabe, bevor du ihn als übermittelt markierst. Die Bestätigung der Anweisung zeigt, dass sie angenommen wurde. Prüfe den Wortlaut anhand der Audioausgabe selbst. Wenn du einen exakten Wortlaut und einen bekannten Endzeitpunkt brauchst, spiele eine geprüfte Aufnahme oder einen vorab gerenderten Audioclip über deine Anwendung ab und steuere währenddessen die GPT-Live-Ausgabe. Weitere Informationen findest du unter Wiedergabe bei Bedarf steuern.
Längere Gespräche verwalten
GPT-Live verwaltet lange Gespräche automatisch und behält deine ursprünglichen Anweisungen vom Sitzungsstart bei.
Das standardmäßige Kontextfenster fasst 128.000 Token. Dazu zählen deine Anweisungen, der Gesprächstext und Audio-Token, die im Transkript nicht erscheinen.
GPT-Live fasst ältere Gesprächsinhalte im Hintergrund zusammen. Sobald das Kontextfenster zu mehr als 90 % ausgelastet ist, startet GPT-Live innerhalb derselben Sitzung eine neue Sprach-Engine als Ersatz. Sie erhält deine ursprünglichen Anweisungen und bis zu 8.192 Token aus dem Gesprächsverlauf. Darin sind die jüngsten Nachrichten und, sofern verfügbar, eine Zusammenfassung älterer Nachrichten enthalten. Das Erstellen einer Zusammenfassung ändert den Kontext der laufenden Engine nicht unmittelbar.
Ältere Gesprächsdetails können zusammengefasst werden oder entfallen. Speichere wichtige Fakten, bestätigte Aktionen und den aktuellen Aufgabenstatus in deiner Anwendung und stelle relevanten Kontext bei Bedarf bereit.
Eine Sitzung speichern und forken
Ein Fork startet eine neue Sitzung auf Basis eines gespeicherten Sprachgesprächs. Damit kannst du mehrere Testläufe mit demselben Referenzgespräch durchführen oder einer Person ermöglichen, ein Gespräch nach dem Ende einer früheren Sitzung fortzusetzen. Jeder Fork erhält eine neue Verbindung und eine neue Sitzungs-ID. Ausgangspunkt sind das ursprüngliche Gespräch und dessen gespeicherte Konfiguration.
Evaluationen mit einem Referenzgespräch durchführen
Angenommen, du möchtest testen, wie dein Agent reagiert, wenn eine anrufende Person eine Bestellung ändern möchte. Zeichne den Gesprächsbeginn einmal auf, bis die Person angegeben hat, um welche Bestellung es geht. Beende die Sitzung und schließe sie vollständig ab, bevor die Person um die Änderung bittet. Für jeden Testlauf kannst du dann dieselbe Referenzsitzung forken und als nächste Audioeingabe dieselbe Äußerung übermitteln: „Actually, can you send it to my office instead?“
Stelle vor jedem Testlauf dieselbe Testbestellung und denselben Anwendungszustand wieder her. Übergib die nächste Eingabe der anrufenden Person und bewerte die neue Antwort sowie die ausgeführten Tool-Aktionen. Du kannst das Szenario wiederholen oder unterstützte Einstellungen des Responses-Backends vergleichen. Miss die Startzeit des Forks getrennt von der Antwortzeit. Hinweise zur Auswahl von Szenarien und zur Messung der Ergebnisse findest du im Leitfaden zur Evaluation von GPT-Live.
Forks übernehmen das GPT-Live-Modell, die Stimme und die ursprünglichen Anweisungen. Wenn du ein anderes Sprachmodell oder einen anderen Start-Prompt vergleichen möchtest, erstelle neue Sitzungen mit der jeweiligen Konfiguration. Die Fork-API verwendet die abgeschlossene Aufnahme der Ausgangssitzung. Beende die Referenzsitzung deshalb genau an der Stelle, an der deine Evaluation beginnen soll.
Ein Gespräch nach Sitzungsende fortsetzen
Eine anrufende Person kann zum Beispiel auflegen und später erneut anrufen oder nach einem Verbindungsabbruch wieder eine Verbindung herstellen. Liegt für die frühere Sitzung eine vollständig gespeicherte Aufnahme vor, kann deine Anwendung die Sitzung über eine neue Verbindung forken und das gespeicherte Gespräch fortsetzen.
Speichere den Aufgabenstatus deiner Anwendung zusammen mit der ID der Ausgangssitzung. Prüfe vor dem Fortsetzen den Status ausstehender Backend-Aufgaben und übergib der neuen Sitzung deren aktuelle Ergebnisse. Wurde beispielsweise bereits eine Bestelländerung übermittelt, prüfe ihr Ergebnis, bevor du eine weitere Änderung versuchst. Verwende die neue Sitzungs-ID für Steuerbefehle und Sideband-Verbindungen und leite nachfolgende Backend-Ergebnisse an die neue Sitzung weiter.
Sitzung für einen Fork vorbereiten
- Aktiviere die Speicherung beim Erstellen der Ausgangssitzung. Setze in der Sitzungskonfiguration
store: true. Standardmäßig gilt für die Speicherungfalse. Die Speicherfunktion muss für dein Projekt freigeschaltet sein, und deine Datenrichtlinie muss die dauerhafte Speicherung erlauben. - Speichere die ID der Ausgangssitzung. Lies sie aus
session.startedoder aus der Antwort auf die WebRTC-Erstellungsanfrage aus und ordne sie dem Gesprächsdatensatz deiner Anwendung zu. - Beende die Ausgangssitzung und schließe sie vollständig ab. Schließe die erforderlichen Backend-Aufgaben ab und folge dann den Schritten unter Nutzung erfassen und Sitzung geordnet schließen. Halte die Verbindung bis
session.closedoffen und behandle Fehler beim Abschluss. Für einen Fork muss die Aufnahme vollständig gespeichert sein. Das Speichern kann den Sitzungsabschluss verlängern. - Starte einen Fork über eine neue Verbindung. Verwende die ID der Ausgangssitzung wie unten für das jeweilige Transportprotokoll beschrieben. Speichere die neue Sitzungs-ID und warte, bis die Sitzung gestartet ist, bevor du das Gespräch fortsetzt. Setze
storefür die neue Sitzung explizit auftrue, wenn du den fortgesetzten Verlauf später forken möchtest, oder auffalse, wenn du diesen Testlauf nicht speichern musst. Lässt du das Feld weg, übernimmt die neue Sitzung die Einstellung der Ausgangssitzung.
Gespeicherte Aufnahmen sind 30 Tage lang verfügbar. Gilt für deine Organisation die Einstellung „Keine Datenaufbewahrung“ (ZDR), behandelt die API store als false und du kannst keine Forks erstellen. Verwende für Evaluationen mit Forks eine Organisation ohne ZDR, in der die Speicherung für dein Projekt aktiviert ist.
Liegt keine vollständig gespeicherte Aufnahme vor, starte eine neue Sitzung mit relevanten gespeicherten Textnachrichten. Die Voraussetzungen für die Speicherung findest du unter Datenkontrollen für GPT-Live.
Setze dieses Feld zum Beispiel in der WebSocket-Konfiguration für session.start oder in der WebRTC-Erstellungsanfrage für die Ausgangssitzung:
{
"store": true
}
Starte den Fork mit dem Transportprotokoll deiner Anwendung:
| Transportprotokoll | Fork starten |
|---|---|
| WebSocket | Stelle eine Verbindung zu wss://api.openai.com/v1/live/sessions/{source_session_id}/fork her. |
| WebRTC | Sende ein neues SDP-Angebot an POST /v1/live/sessions/{source_session_id}/fork. Übernimm transport.sdp aus der Antwort als SDP-Antwort für die neue Peer-Verbindung. |
Ein Fork übernimmt das Modell, die ursprünglichen Anweisungen und die Eingabe der Ausgangssitzung. Beim Start kannst du nur die folgenden Einstellungen überschreiben:
- WebSocket:
store, die Einstellungen für die Responses-Delegation undaudio.formatfür die neue Verbindung. Sende einsession.start-Ereignis mit einemsession-Objekt. Verwende{}, um übernommene Einstellungen beizubehalten, soweit dies unterstützt wird. - WebRTC:
store, die Einstellungen für die Responses-Delegation und die Berechtigungen des Frontend-Clients.
Lege für einen WebSocket-Fork audio.format für die neue Verbindung fest oder verwende das Standardformat PCM16 mit 24 kHz. Der Fork übernimmt weder das Audioformat der Ausgangssitzung noch die Berechtigungen für den Datenkanal des Frontends. WebRTC handelt das Audioformat beim Verbindungsaufbau aus. Lass audio.format deshalb weg. WebRTC behält die Frontend-Berechtigungen bei, sofern du sie nicht überschreibst.
Warte bei WebSocket auf session.started, bevor du weitere Befehle sendest. Bei WebRTC startet die HTTP-Anfrage die Sitzung. Verwende anschließend die ausgehandelte Verbindung, ohne erneut session.start zu senden.
Einen WebSocket-Fork starten
Setze OPENAI_API_KEY. Die Beispiele verwenden die ID der gespeicherten Ausgangssitzung, die deine Anwendung gesichert hat. Sie prüfen, ob die neue Sitzung gestartet ist, und schließen den Fork anschließend. Um das Gespräch fortzusetzen, sende und empfange nach session.started Audiodaten wie unter Verbindungsaufbau mit WebSocket beschrieben. Die Felder und Ereignisse beim Start findest du in der WebSocket-Referenz für Forks.
import OpenAI from "openai";
import { ForksWS } from "openai/resources/live/forks/ws";
async function forkSession(sourceSessionId: string) {
const ws = new ForksWS(new OpenAI(), { session_id: sourceSessionId });
let finalized = false;
let closeRequested = false;
try {
for await (const event of ws) {
if (event.type === "open") {
ws.send({ type: "session.start", session: {} });
} else if (event.type === "error") {
throw event.error;
} else if (event.type === "message") {
if (event.message.type === "session.started") {
console.log("Fork ready:", event.message.session.id);
// This startup example closes the fork after confirming it is ready.
ws.send({ type: "session.close" });
closeRequested = true;
} else if (event.message.type === "session.closed") {
console.log("Final usage:", event.message.usage);
if (!closeRequested) {
throw new Error("Fork ended before startup completed");
}
finalized = true;
break;
}
}
}
if (!finalized) throw new Error("Connection closed before session.closed");
} finally {
ws.close();
}
}Einen WebRTC-Fork starten
Erstelle im Frontend ein neues SDP-Angebot und sende es an dein Backend. Die folgenden Backend-Beispiele verwenden dieses Angebot und die von deiner Anwendung gespeicherte ID der Ausgangssitzung:
import OpenAI from "openai";
async function forkSession(sourceSessionId: string, offerSdp: string) {
const client = new OpenAI();
const fork = await client.live.sessions.fork(sourceSessionId, {
transport: { type: "webrtc", sdp: offerSdp },
});
console.log(JSON.stringify(fork));
}Gib die Antwort an das Frontend zurück, übernimm transport.sdp als SDP-Antwort für die neue Peer-Verbindung und speichere die neue session.id. Bewahre den API-Schlüssel im Backend auf.
Verwende die neue Sitzungs-ID für Sideband-Verbindungen und Sitzungsbefehle. Bevor du eine noch offene Aktion wiederholst, prüfe ihr Ergebnis im Backend und stelle den aktuellen Aufgabenstatus der Anwendung wieder her. Liegt keine vollständig gespeicherte Aufnahme vor, starte eine neue Sitzung mit dem gespeicherten Gesprächsverlauf.
Eine Aufnahme herunterladen
Sobald die Aufnahme vollständig gespeichert ist, kannst du die Audiodaten mit GET /v1/live/sessions/{session_id}/content herunterladen. Die Antwort enthält binäre WAV-Daten in Stereo, mit der Audioeingabe auf dem linken und der Audioausgabe auf dem rechten Kanal. Die Beispiele verwenden die gespeicherte Sitzungs-ID aus deiner Anwendung und schreiben die Antwort als Datenstrom in recording.wav:
import OpenAI from "openai";
import { createWriteStream } from "node:fs";
import { pipeline } from "node:stream/promises";
async function downloadRecording(sessionId: string) {
const client = new OpenAI();
const response = await client.live.sessions.downloadRecording(sessionId);
if (!response.body) throw new Error("Recording response has no body");
await pipeline(response.body, createWriteStream("recording.wav"));
}Inaktive Sitzungen schließen und Gespräche fortsetzen
Wenn zwischen Interaktionen längere Pausen liegen, schließe die Sprachsitzung bei Inaktivität und starte eine neue Sitzung, sobald die Person zurückkehrt. Bewahre den Gesprächskontext und den Aufgabenstatus deiner Anwendung auf, damit die Person fortfahren kann, ohne sich wiederholen zu müssen. Ein Assistent im Auto kann das Gespräch beispielsweise fortsetzen, sobald die Person am Steuer die Sprachfunktion wieder aktiviert. Ein Programmierassistent kann seinen Backend-Worker zwischen Sprachgesprächen weiterlaufen lassen.
- Lege fest, wann die Sitzung geschlossen wird. Lege in deiner Anwendung ein Zeitlimit für Inaktivität fest. Berücksichtige dabei die Audioaktivität, die Wiedergabe von Äußerungen des Assistenten und Interaktionen mit der Anwendung. Plane erwartbare Pausen ein, etwa zum Lesen oder Nachdenken. Schließe die Sitzung erst, wenn die Wiedergabe beendet ist und keine ausstehende Aufgabe die aktuelle Sprachsitzung benötigt. Allein aus Lücken zwischen Transkriptereignissen lässt sich nicht ableiten, dass niemand spricht.
- Speichere den Zustand und schließe die Sitzung geordnet. Speichere die ID der Ausgangssitzung, den Gesprächskontext und den aktuellen Aufgabenstatus. Schließe erforderliche Responses-Aufgaben ab und folge den Schritten unter Nutzung erfassen und Sitzung geordnet schließen. Registriere den Listener für
session.closed, sendesession.closeund warte aufsession.closed, bevor du die Verbindung freigibst. Bei Client-Delegation können von der Anwendung verwaltete Backend-Aufgaben unabhängig weiterlaufen, während die Sprachsitzung geschlossen ist. - Erkenne, wann eine neue Sitzung starten soll. Biete eine Schaltfläche mit der Beschriftung „Gespräch fortsetzen“, eine Push-to-Talk-Funktion oder eine von der Anwendung gesteuerte Aktivierung an. Eine geschlossene Live-Sitzung kann niemandem zuhören. Wenn du die Sitzung per lokaler Spracherkennung automatisch neu startest, lass die Mikrofonaufnahme aktiv und puffere die ersten gesprochenen Worte während des Verbindungsaufbaus. Übertrage die gepufferten Audiodaten, sobald die neue Sitzung bereit ist. So bleiben die ersten Worte erhalten.
- Stelle den Kontext in einer neuen Sitzung wieder her. Wenn du die Ausgangssitzung mit
store: trueerstellt hast, die Speicherung aktiviert und zulässig ist und die Aufnahme erfolgreich abgeschlossen wurde, forke die gespeicherte Sitzung. Andernfalls starte eine neue Sitzung mit dem gespeicherten Textverlauf. Speichere die neue Sitzungs-ID, prüfe den Status ausstehender Backend-Vorgänge und leite nachfolgende Ergebnisse an die neue Sitzung weiter. Halte den Status der Vorgänge in deiner Anwendung fest, damit abgeschlossene Aktionen beim Neustart nicht erneut ausgeführt werden.
Wenn du das Mikrofon stummschaltest, bleibt die Sitzung aktiv. Wäge bei der Wahl des Inaktivitätszeitlimits die eingesparte Sprachdauer gegen die Kosten einer neuen Sitzung und die Wartezeit ab, bis die Sprachfunktion wieder bereit ist. Weitere Informationen findest du unter Kosten für Sprachsitzungen und Gebühren für die WebRTC-Initialisierung.
Fehler behandeln und die Sitzung beenden
Verarbeite Sitzungsereignisse, bis die Sitzung vollständig abgeschlossen ist. Unterscheide zwischen einem abgelehnten Befehl, einem Verbindungsfehler und einer abgeschlossenen Sitzung, damit deine Anwendung angemessen reagieren kann.
Abgelehnte Befehle behandeln
Verarbeite neben Bestätigungen auch error-Ereignisse. Falls vorhanden, gibt error.client_event_id an, welcher gesendete Befehl fehlgeschlagen ist:
{
"type": "error",
"event_id": "event_error",
"error": {
"type": "invalid_request_error",
"code": "immutable_field_update",
"message": "The delegation type cannot change after session startup.",
"param": "session.delegation.type",
"client_event_id": "event_update"
}
}
Implementiere eine allgemeine Fehlerbehandlung für Fehler, deren Code null ist oder bei denen die Client-Ereignis-ID fehlt. Betrifft der Fehler ein unveränderliches Feld, behalte die aktuelle Konfiguration bei oder erstelle eine neue Sitzung mit den gewünschten Einstellungen.
Auf Moderationsereignisse reagieren
Moderation kann sich auf zwei Arten auf die Sitzung auswirken:
- Einige Moderationsereignisse beenden die Sitzung.
- Andere unterbrechen die Audioausgabe des Assistenten für den Rest seiner aktuellen Äußerung und lösen ein
error-Ereignis aus. Die Sitzung läuft weiter.
Verarbeite error-Ereignisse auch während der Audiowiedergabe. Erfasse Unterbrechungen der Audioausgabe getrennt vom Schließen der Sitzung. Markiere eine gesprochene Nachricht erst als übermittelt, nachdem du ihre Wiedergabe geprüft hast. Ergänze die integrierte Moderation durch eigene Schutzmaßnahmen für Gespräche.
Nutzung erfassen und Sitzung geordnet schließen
session.usage.updated meldet die bisherige Gesamtdauer der Sprachnutzung in Sekunden:
{
"type": "session.usage.updated",
"event_id": "event_usage_1",
"usage": { "seconds": 12 },
"context_window": { "usage_ratio": 0.42 }
}
Verwende den jüngsten Wert von usage.seconds als aktuelle Gesamtdauer. Meldet ein Ereignis 12 und das nächste 15 Sekunden, beträgt die Nutzung insgesamt 15 Sekunden. Erfasse den Token-Verbrauch im Backend separat anhand der verschachtelten Responses-Abschlussereignisse. Hinweise zur Erfassung der Nutzung findest du unter Kosten optimieren.
So schließt du die Sitzung geordnet:
- Schließe alle delegierten Responses-Aufgaben ab, die deine Anwendung benötigt. Dazu gehören auch ausstehende Funktionsergebnisse und die Fortsetzung von Antworten.
- Registriere den Listener für
session.closed, bevor dusession.closesendest. - Sende
session.closeund übermittle der Sitzung keine neuen Aufgaben mehr. Halte die WebSocket- oder WebRTC-Verbindung, den Datenkanal und alle verbundenen Sideband-Empfänger aktiv, bis die ausstehenden Sitzungsereignisse verarbeitet sind. - Lies die endgültigen Werte für
usage.secondsundreasonsowie den letzten Sitzungszustand aussession.closedaus. Bewahre die Nutzungsdaten für delegierte Aufgaben auf, die du bereits überresponse.eventerhalten hast. - Gib nach diesem Ereignis die Transportverbindungen und Audiogeräte frei. Schlägt der Abschluss fehl oder überschreitet er das von deiner Anwendung festgelegte Zeitlimit, melde den Abschluss als unvollständig und gib die Ressourcen frei.
Mit session.close werden Responses-Anfragen in der Warteschlange abgebrochen und weitere Befehle abgelehnt. Eine aktive Antwort kann noch abgeschlossen werden. Wartet sie jedoch auf ein Funktionsergebnis, kann sie nach Beginn des Schließvorgangs nicht mehr fortgesetzt werden. Entscheide gesondert, ob deine Anwendung Aufgaben aus der Client-Delegation abschließen oder abbrechen soll.
Prüfe anhand von session.closed, ob die Sitzung vollständig abgeschlossen ist, und lies den endgültigen Konfigurationsstand aus. Halte die Transportverbindung offen, bis dieses Ereignis eintrifft. Schließt sich der Socket vorher, vermerke den Sitzungsabschluss als unbestätigt. Schließt er sich nach einem gültigen session.closed, behalte das bestätigte Ergebnis bei.
Das Feld reason im letzten Ereignis gibt an, warum die Sitzung beendet wurde:
| Grund | Bedeutung |
|---|---|
close_requested |
Deine Anwendung hat session.close gesendet oder den Endpunkt zum Auflegen aufgerufen. |
expired |
Die Sitzung hat ihre maximale Dauer erreicht. |
content |
Ein Sicherheitsfilter hat die Sitzung beendet. |
remote_hangup |
Die Gegenstelle hat die primäre Verbindung geordnet beendet. |
connection_lost |
Die primäre oder eine vorgelagerte Verbindung ist unerwartet abgebrochen. |
Ein session.closed-Ereignis bestätigt den Abschluss auch dann, wenn die Verbindung abgebrochen ist oder die Sitzung aus Sicherheitsgründen beendet wurde. Ohne dieses Ereignis bleibt die endgültige Nutzung unbestätigt. Bei einer gespeicherten Sitzung kann der Abschluss länger dauern, weil die Aufnahme noch gespeichert wird. Berücksichtige diese Zeit beim Festlegen des Zeitlimits für deine Anwendung.
Gespräch nach einem Verbindungsfehler fortsetzen
Ein HTTP-Fehler beim Erstellen der Sitzung bedeutet, dass die Sitzung session.started nicht erreicht hat. Behandle Fehler beim Start getrennt von Fehlern in einer laufenden Sitzung. Bricht eine bestehende Verbindung vor session.closed ab, bewahre die zuletzt gemeldeten Nutzungsdaten auf und markiere die endgültige Nutzung als unbestätigt.
Liegt eine vollständig gespeicherte Aufnahme vor, forke die Sitzung, um das Gespräch in einer neuen Sitzung fortzusetzen. Erstelle andernfalls eine Ersatzsitzung mit den relevanten Teilen des gespeicherten Gesprächsverlaufs. Prüfe vor dem Fortsetzen offene Aktionen im Backend, stelle den aktuellen Aufgabenstatus wieder her und passe die Weiterleitung von Ergebnissen an. So können verspätete Ergebnisse aus der vorherigen Sitzung keine neueren Ergebnisse überschreiben.