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 der Gemini 2.5 Flash Live API Native Audio zu Gemini 3.8 Live erforderlich sind.

Änderungen bei Funktionsaufrufen

Der native Audio-Server der Gemini 2.5 Flash Live API ermöglicht asynchrone Tool-Aufrufe. 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 im Setup 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.

• Das Verhalten der Option „scheduling=interrupt“ für „FunctionResponse“ wurde geändert:

  FunctionResponse-Planung	Wer spricht?	Gemini 2.5 Flash Live API Native Audio	Gemini 3.8 Live
  unterbrechen	Modell	Verhindert, dass das aktive Modell sofort antwortet. Stattdessen wird die Antwort des Tools wiedergegeben.	Verhindert, dass das aktive Modell sofort antwortet. Stattdessen wird die Antwort des Tools wiedergegeben.
  unterbrechen	Nutzer	Wird sofort unterbrochen; die Antwort des Tools wird über den Nutzer abgespielt.	Wartet, bis der Nutzer fertig ist, bevor die Antwort des Tools wiedergegeben wird.

Redundante Sweeps und Wiederholungen von Funktionsaufrufen vermeiden

Gemini 3.8 Live führt manchmal innerhalb eines einzelnen Turns redundante aufeinanderfolgende Funktionsaufrufe aus, wenn ein Tool keine Ergebnisse zurückgibt. Dazu kann es gehören, dass unterschiedliche Parameter wiederholt werden und der Sweep zwei- bis fünfmal durchgeführt wird, bevor eine Antwort erfolgt. Dieses Verhalten verlängert 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, wenn versucht wird, 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“, „Abfragezeitraum zu kurz“ oder „ungültiges Argument“ unterscheiden. Das Modell versucht, die Anfrage 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 Tool-Antwort muss Informationen zum Fehler oder zu den Ergebnissen enthalten, damit das Gemini 3.8 Live-Modell weiß, wie es weitergehen soll.

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

  Fall	Was das Modell tun soll	Erforderliche Nutzlast-Inhalte
  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, erklärende Nachricht in natürlicher Sprache.
  Ungültiges oder nicht vorhandenes Argument (z. B. „falscher Anbieter“).	Hören Sie auf zu suchen und bitten Sie den Nutzer um Klärung oder Bestätigung.	status: 'invalid_argument', reason_code, retryable: false und valid_options-Liste
  Gültige Abfrage mit einem leeren Fenster. Eine breitere Anfrage ist wirklich hilfreich.	Führen Sie einen angemessenen Wiederholungsversuch durch.	status: 'no_results_in_range', retryable: true und retry_hint

  Im folgenden Beispiel wird eine Nutzlast gezeigt, in der search_appointment aufgerufen wird, aber alle potenziellen Termine nicht verfügbar sind. Der Nutzer möchte einen Anbieter ausprobieren, anstatt die Daten zu bereinigen:

  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"]
  }
  

  Im folgenden Beispiel wird gezeigt, wie vorgegangen wird, wenn check_user_account keine genauen Übereinstimmungen zurückgibt. Das erwartete Ergebnis ist, die Suchanfrage zu ändern oder die Steuerung an den Nutzer zurückzugeben, 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."
  }
  

• Richtlinie für Wiederholungsversuche bei 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."
  

Sitzungsverlauf austauschen

In der nativen Audio-API von Gemini 2.5 Flash Live wird send_client_content verwendet, um das History-Seeding vor dem ersten Turn einzurichten 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 den Verlauf zu initialisieren, legen Sie im Abschnitt HistoryConfig der Einrichtungsmitteilung initial_history_in_client_content=True fest. Nach Erhalt von setup_complete. Sie können send_client_content dann wiederholt aufrufen, um den Verlauf bis zur letzten Nachricht zu erstellen, in der turn_complete=True festgelegt ist.

Unterschiede im Modellverhalten

In der folgenden Tabelle werden die Unterschiede im Modellverhalten für Audio, Multimodell und Ausgabe zwischen der nativen Audio-API von Gemini 2.5 Flash Live und Gemini 3.8 Live beschrieben:

Im folgenden Python-Code wird veranschaulicht, 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 Drittanbieter-Frameworks

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

LiveKit

Das Google-Plug-in „RealtimeModel“ von LiveKit unterstützt Gemini 3.8 Live, aber die folgenden Einstellungen werden im Google-Plug-in von LiveKit nicht unterstützt:

• thinking_level
• enable_affective_dialog
• proactivity

Wir empfehlen, das Google-Plug-in von LiveKit mit besonderer Vorsicht zu verwenden, 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:

• Denkaufwandskonfiguration: Entfernen Sie den Denkaufwand, da er von Gemini 3.8 Live nicht unterstützt wird.

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

Telemetrie zur Tokennutzung auf Wire-Ebene

Jeder Server-Turn gibt einen usage_metadata-Frame zurück. Dies ist bei der Gemini 2.5 Flash Live API Native Audio und Gemini 3.8 Live einheitlich. Die Nutzungsmetadaten sind stärker kategorisiert, z. B. in zwischengespeicherte Tokens, Tokens für die Tool-Nutzung und Tokens in verschiedenen Modalitäten.

Bekannte Modelleinschränkungen und Gegenmaßnahmen

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

Checkliste für die Migration

Die folgende Checkliste für die Clientmigration kann verwendet werden, wenn Sie von der nativen Audio-API Gemini 2.5 Flash Live zu Gemini 3.8 Live migrieren:

• Funktionsaufrufe:

  • Informative Tool-Antworten: Alle Tool-Handler müssen so refaktoriert werden, dass sie explizite Statuscodes, Flags für Wiederholungsversuche und Erklärungen in natürlicher Sprache zurückgeben. Geben Sie niemals ein leeres None oder ein leeres {} zurück.

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

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

  • Änderung beim Planen von Funktionen: Wenn der Nutzer spricht, wird 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.

• Thinking: Hacks für das Denken auf Promptebene entfernen: Um zu verhindern, dass Audioinhalte wegfallen, entfernen Sie alle Prompttexte, die versuchen, schrittweise Denkschemata oder Tokenlimits zu erzwingen.