Von der nativen Audio-Live-API von Gemini 2.5 Flash zu Gemini 3.8 Live migrieren

In diesem Dokument werden die Änderungen beschrieben, die bei der Migration von Gemini 2.5 Flash Live API Native Audio zu Gemini 3.8 Live erforderlich sind.

Änderungen bei Funktionsaufrufen

Der Gemini 2.5 Flash Live API Native Audio-Server ermöglicht asynchrone Toolaufrufe. Gemini 3.8 Live unterstützt dagegen asynchrone Funktionsaufrufe mit den folgenden Verhaltensänderungen:

• Gemini 3.8 Live unterstützt das Blockieren von Funktionsaufrufen, wenn in der Funktionsdeklaration behavior=BLOCKING in der Einrichtung deklariert wird. Wenn während der Ausführung des blockierenden Funktionsaufrufs eine neue Eingabe empfangen wird, bricht der Live API-Server den aktuellen Funktionsaufruf ab.

• Die Option scheduling=interrupt für FunctionResponse hat sich geändert:

  FunctionResponse-Planung	Wer spricht	Gemini 2.5 Flash Live API Native Audio	Gemini 3.8 Live
  interrupt	Modell	Beendet die Antwort des aktiven Modells sofort und gibt die Antwort des Tools wieder.	Beendet die Antwort des aktiven Modells sofort und gibt die Antwort des Tools wieder.
  interrupt	Nutzer	Unterbricht sofort und spielt die Antwort des Tools über die des Nutzers ab.	Wartet, bis der Nutzer fertig ist, bevor die Antwort des Tools wiedergegeben wird.

Redundante Sweeps und Wiederholungen von Funktionsaufrufen reduzieren

Gemini 3.8 Live führt manchmal redundante Funktionsaufrufe nacheinander innerhalb einer einzelnen Runde aus, wenn ein Tool keine Ergebnisse zurückgibt. Dazu kann es gehören, verschiedene Parameter zu wiederholen und zwei- bis fünfmal zu prüfen, bevor eine Antwort gegeben wird. Dieses Verhalten erhöht die Zeit bis zum ersten Audio (TTFA) und führt zu ungenauer Fallback-Sprache.

Die redundanten aufeinanderfolgenden Funktionsaufrufe werden durch Gemini 3.8 Live verursacht, das versucht, Anfragen zu beantworten. Wenn ein Tool eine nicht informative oder leere Antwort wie {"results": [], "total_available": 0} oder None zurückgibt, kann das Modell nicht zwischen „dauerhaft erschöpft“, „Abfragefenster zu klein“ oder „ungültiges Argument“ unterscheiden. Das Modell versucht, die Suchanfrage zu erweitern oder zu variieren, um die Ergebnisse zu verbessern, und beginnt mit dem Sweeping.

Wenden Sie die folgenden ergänzenden Praktiken an:

• Informative Funktionsantworten zurückgeben: Jede Toolantwort muss Informationen zum Fehler oder zu den Ergebnissen enthalten, damit das Gemini 3.8 Live-Modell weiß, wie es weiter vorgehen soll.

  In der folgenden Tabelle werden die Fälle, die gewünschte Reaktion des Modells und ein Beispiel für die erforderliche Nutzlast beschrieben, um das Modell zu unterstützen:

  Fall	Was das Modell tun soll	Erforderlicher Payload-Inhalt
  Gültige Abfrage, die keine Ergebnisse zurückgibt. Ein wiederholter Versuch führt zu keinem anderen Ergebnis.	Beenden Sie die Suche, informieren Sie den Nutzer und bieten Sie Alternativen an.	status: 'no_results', retryable: false, und eine klare, verständliche Nachricht in natürlicher Sprache.
  Ungültiges oder nicht vorhandenes Argument (z. B. „falscher Anbieter“).	Beende die Suche und bitte den Nutzer um Klarstellung oder Bestätigung.	status: 'invalid_argument', reason_code, retryable: false und valid_options-Liste
  Gültige Abfrage mit einem leeren Fenster. Eine breitere Abfrage ist hier wirklich hilfreich.	Führen Sie einen angemessenen Wiederholungsversuch durch.	status: 'no_results_in_range', retryable: true und retry_hint

  Das folgende Beispiel zeigt eine Nutzlast, bei der search_appointment aufgerufen wird, aber alle potenziellen Termine nicht verfügbar sind. Der Nutzer möchte einen Anbieter ausprobieren, anstatt die Daten zu durchsuchen:

  def search_appointment(vendor: str, date: Datetime):
  
  # BEFORE (Invites Sweeping):
  {
    "results": [],
    "total_available": 0
  }
  
  # AFTER - Exhausted / Dead End (Stops Sweeping):
  {
    "results": [],
    "status": "no_availability",
    "retryable": false,
    "message": "No appointments are available for this provider for the foreseeable future. Searching other dates will not surface anything; openings only come from cancellations.",
    "suggested_next_step": "offer_waitlist_or_a_different_provider"
  }
  
  # AFTER - Invalid Argument (Prompts User Clarification):
  {
    "results": [],
    "status": "invalid_argument",
    "reason": "no_such_provider",
    "retryable": false,
    "message": "There is no provider named 'Mr. Johnson'. Ask the caller to confirm the name.",
    "valid_options": ["Dr. Johnson", "Dr. Chen"]
  }
  

  Das folgende Beispiel zeigt die Verarbeitung, wenn check_user_account keine genauen Übereinstimmungen zurückgibt. Das erwartete Ergebnis ist, dass die Suchanfrage geändert oder die Kontrolle an den Nutzer zurückgegeben wird, anstatt es noch einmal zu versuchen:

  def check_user_account(user_name: str, phone_suffix: str):...
  
  # Checked user account but not existing
  # BEFORE: insufficient error information
  {
   "found": false,
   "matches": []
  }
  
  # AFTER: providing sufficient information to the LiveAPI to avoid further retries because the retries have been exhausted.
  {
   "status": "EXHAUSTED",
   "retryable": false,
   "search_criteria": {
     "name": "Alex Rivera",
     "phone_suffix": "4921"
   },
   "search_scope": "Checked active orders, archived accounts, and guest checkouts across all regions.",
   "guidance": "Exhaustive search completed with 0 matches. Do NOT retry with parameter substrings or variations. Inform the user that no account was found matching those details, and ask if they have an Order ID or billing email."
  }
  

• Wiederholungsrichtlinie für Systemanweisungen: Ergänzen Sie informative Antworten mit einer expliziten Einschränkung in der Systemanweisung:

  "When a tool returns no results, tell the user the result before calling the
  tool again. If a call fails for a reason fundamental to the arguments (for
  example, the entity does not exist), do not silently retry with variations;
  ask the user to clarify or confirm. You may broaden a query once when a
  result set is simply empty. Do not run repeated searches with different
  parameters on your own initiative. Hard cap: Never issue more than two
  consecutive function calls without saying something back to the user."
  

Austausch des Sitzungsverlaufs

In Gemini 2.5 Flash Live API Native Audio wird send_client_content verwendet, um vor der ersten Runde den Verlauf zu füllen und während der Sitzung zusätzlichen Verlauf hinzuzufügen.

Wenn Sie in Gemini 3.8 Live die Methode send_client_content verwenden möchten, um das Seeding des Verlaufs einzurichten, legen Sie im Abschnitt HistoryConfig der Einrichtungsnachricht initial_history_in_client_content=True fest. Nach Erhalt von setup_complete. Sie können dann send_client_content wiederholt aufrufen, um den Verlauf bis zur letzten Nachricht zu erstellen, in der turn_complete=True festgelegt ist.

Aktualisierungen von Systemanweisungen und Tools während der Sitzung

In der Gemini 2.5 Flash Live API Native Audio aktualisieren Sie die Systemanweisung während einer Sitzung, indem Sie Clientinhalte mit der Rolle system senden.

Rufen Sie in Gemini 3.8 Live stattdessen send_context_update im Google Gen AI SDK auf oder senden Sie eine context_update-Nachricht über WebSockets. Sie kann die Systemanweisung, die Liste der Tools oder beides ersetzen. Weitere Informationen finden Sie unter Systemanweisungen und Tools mit Gemini 3.8 Live aktualisieren.

Unterschiede im Modellverhalten

In der folgenden Tabelle werden die Unterschiede im Modellverhalten für Audio, Multimodalität und Ausgabe zwischen der Gemini 2.5 Flash Live API Native Audio und Gemini 3.8 Live beschrieben:

Der folgende Python-Code zeigt, wie media_resolution und custom_vocabulary festgelegt werden:

# Example: Setting media_resolution for image frames in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,  # or MEDIA_RESOLUTION_LOW or MEDIA_RESOLUTION_MEDIUM
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    # Send image frames with the configured resolution budget
    ...


# Example: Setting custom_vocabulary for domain-specific word biasing in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["Gemini", "MagicWord", "Lagrangian"],
    ),
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    ...

Kompatibilität mit Frameworks von Drittanbietern

In den folgenden Abschnitten wird beschrieben, wie Drittanbieter-Frameworks mit Gemini 3.8 Live funktionieren:

LiveKit

Das RealtimeModel des Google-Plug-ins von LiveKit unterstützt Gemini 3.8 Live, die folgenden Einstellungen werden jedoch im Google-Plug-in von LiveKit nicht unterstützt:

• thinking_level
• enable_affective_dialog
• proactivity

Wir empfehlen, bei der Verwendung des Google-Plug-ins von LiveKit besonders vorsichtig zu sein, da es sorgfältig angepasst werden muss, um mit Gemini 3.8 Live zu funktionieren.

Pipecat

Pipecat unterstützt Gemini 3.8 Live mit den folgenden Änderungen:

• Konfiguration des Denkprozesses: Entferne die Denkstufe, da sie von Gemini 3.8 Live nicht unterstützt wird.

• Pipecat verbindet Agent Platform-Endpunkte über den GeminiLiveLLMService-Connector mit dem GoogleVertexLLMService.

Wire-Level-Telemetrie zur Tokennutzung

Jeder Server-Turn gibt einen usage_metadata-Frame zurück. Dies gilt sowohl für die Gemini 2.5 Flash Live API Native Audio als auch für Gemini 3.8 Live. Die Nutzungsmetadaten sind stärker kategorisiert, z. B. in im Cache gespeicherte Tokens, Tokens für die Toolnutzung, Tokens in verschiedenen Modalitäten usw.

Bekannte Einschränkungen des Modells und Maßnahmen zur Risikominderung

Informationen zu bekannten Einschränkungen und Maßnahmen zur Problembehebung bei der Entwicklung von Anwendungen mit Gemini 3.8 Live finden Sie unter Bekannte Einschränkungen.

Checkliste für die Migration

Im Folgenden finden Sie eine Checkliste für die Clientmigration, die Sie bei der Migration von der Gemini 2.5 Flash Live API Native Audio zu Gemini 3.8 Live verwenden können:

• Funktionsaufrufe:

  • Informative Toolantworten: Refaktorieren Sie alle Tool-Handler, um explizite Statuscodes, wiederholbare Flags und Erklärungen in natürlicher Sprache zurückzugeben. Geben Sie niemals ein leeres None oder ein leeres {} zurück.

  • Richtlinie für Systemanweisungen: Fügen Sie explizite Einschränkungen hinzu, die unbemerkte Tool-Wiederholungen verbieten, eine Nutzerbestätigung bei Argumentfehlern erfordern und die Anzahl aufeinanderfolgender Toolaufrufe begrenzen.

  • Abgleich der Toolaufruf-ID: Achten Sie darauf, dass FunctionResponse bei jeder Toolantwort id=fc.id übergibt.

  • Änderung des Verhaltens bei der Funktionsplanung: Wenn der Nutzer spricht, wird die scheduling=interrupt auf scheduling=when_idle herabgestuft, um eine reibungslosere Nutzererfahrung zu ermöglichen.

• Sitzung: send_client_content einschränken: Verwenden Sie send_client_content, um den anfänglichen Verlauf festzulegen, indem Sie einen sinnvollen HistoryConfig angeben.

• Sitzung: Kontext mit context_update aktualisieren: Ersetzen Sie Aktualisierungen von Systemanweisungen innerhalb einer Sitzung, die die Rolle system verwenden, durch send_context_update-Aufrufe im Google Gen AI SDK oder durch context_update-Nachrichten über WebSockets.

• Thinking: Purge Prompt-Level Thinking Hacks: Um Audioausfälle zu vermeiden, entfernen Sie alle Prompt-Texte, die versuchen, schrittweise Denkschemata oder Tokenlimits zu erzwingen.