Entwicklerleitfaden für Gemini 3.5 Flash

Gemini 3.5 Flash ist ein schnelles, kostengünstiges und leistungsstarkes Modell der Gemini 3-Familie. Das Modell wurde entwickelt, um agentenähnliche Funktionen auf Pro-Niveau zu bieten, ohne die Leistung oder den Wert zu beeinträchtigen. Es ist jetzt allgemein verfügbar (GA) für Entwickler, die die Gemini API verwenden, und für Unternehmen, die die Gemini Enterprise Agent Platform nutzen.

In diesem Dokument erfahren Sie, was es Neues bei 3.5 Flash gibt, wann Sie es verwenden sollten, wie Sie zu 3.5 Flash migrieren und wie Sie 3.5 Flash verwenden.

Wie passt es in die Gemini-Familie?

In der folgenden Tabelle werden einige der Spezifikationen von 3.5 Flash, 3.1 Pro und 3.1 Flash-Lite verglichen:

Eine vollständige Liste der unterstützten Funktionen, Tools und Verbrauchsoptionen finden Sie auf der Seite Flash-Modell 3.5.

Aufschlüsselung nach Anwendungsfall

Bei der empfohlenen Strategie für agentische Workflows wird ein mehrstufiger Ansatz verwendet, um Qualität, Geschwindigkeit und Kosten zu optimieren:

• Gemini Pro: Für kognitive Aufgaben mit hoher Komplexität reservieren, die tiefes logisches Denken erfordern, z. B. die erste Routenplanung, komplexe Problemlösung, schwierige Programmierung und kritische Entscheidungsfindung.
• Gemini Flash: Verwenden Sie dieses Modell als primäres „Arbeitstier“ für Ausführungsaufgaben, Tool-Aufrufe und Zwischenschritte, da es das beste Verhältnis zwischen Leistung und Effizienz bietet.
• Gemini Flash Lite: Für Vorverarbeitungs- und Strukturaufgaben mit hohem Volumen und geringer Latenz, bei denen Geschwindigkeit und Kosten im Vordergrund stehen, z. B. Intent-Routing, Datenextraktion, Tagging und Klassifizierung.

Was ist neu bei Gemini 3.5 Flash?

Gemini 3.5 Flash bietet die folgenden Änderungen und Verbesserungen für die Gemini-Modellreihe:

• Dauerhafte Spitzenleistung: Unser intelligentestes Flash-Modell, das für agentische und Coding-Aufgaben in großem Umfang optimiert wurde.
• Agentische Ausführung: Bereitstellung von Sub-Agents, Problemlösung und schnelle agentische Schleifen im großen Maßstab.
• Verbessertes Programmieren: Iterative Programmierzyklen, schnelle Exploration und Prototyping zum Testen alternativer Pfade und dynamischen Erkunden von Lösungen.
• Langfristig: Mehrstufige Workflows und Toolnutzung im großen Maßstab.
• Gedankenerhaltung: Das Modell behält Zwischenschritte bei der Argumentation in mehrteiligen Gesprächen automatisch bei. Es sind keine API-Änderungen erforderlich.
• Neuer Standard-Denkaufwand: Der Standard-Denkaufwand wurde von HIGH in MEDIUM geändert.
• Verbessertes LOW-Denken: Die Denkebene „Niedrig“ wurde für Code- und Agentenaufgaben, die weniger Schritte erfordern, deutlich verbessert. Sie bietet eine hohe Qualität bei geringerer Latenz und niedrigeren Kosten.

Weitere Informationen finden Sie im Abschnitt Wichtige Änderungen.

Kurzanleitung

Bevor Sie beginnen, müssen Sie sich mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) oder einem API-Schlüssel bei der Agent Platform authentifizieren. Weitere Informationen finden Sie unter Erste Schritte mit der Gemini Enterprise Agent Platform.

Ersetzen Sie in den folgenden Codeblöcken PROJECT_ID durch Ihre Projekt-ID.

Installation

Achten Sie darauf, dass Sie das aktuelle google-genai SDK verwenden:

pip install --upgrade google-genai

Einfache Anfrage

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Wichtigste Änderungen

In diesem Abschnitt werden die folgenden Änderungen, die in Gemini 3.5 Flash eingeführt wurden, genauer beschrieben:

• Neue Standard-Denkebene (MEDIUM)
• Fortführung der Logikschritte
• Nicht mehr unterstützt: Parameter für die Stichprobenerhebung
• Eingestellt: thinking_budget

Neuer Standard-Denkaufwand

Der Standard-Denkaufwand für Gemini 3-Modelle ist jetzt MEDIUM. In der Vorabversion von Gemini 3 Flash war er noch HIGH. Die Denkebene MEDIUM liefert bei einer Vielzahl von Aufgaben gute Ergebnisse und ist gleichzeitig schneller und kostengünstiger.

Folgende Denkaufwandstufen werden unterstützt:

• MINIMAL: Entspricht für die meisten Anfragen der Einstellung „Kein Denken“. Bei komplexen Aufgaben wie dem Programmieren kann das Modell sehr wenig nachdenken. Minimiert die Latenz für Chat- oder Anwendungen mit hohem Durchsatz.
• LOW: Einfache Schlussfolgerungen für die meisten Aufgaben mit hoher Geschwindigkeit und niedrigeren Kosten.
• MEDIUM: (Standard) Ausgewogene Einstellung für die meisten Aufgaben, die logisches Denken erfordern.
• HIGH: Maximiert die Argumentation, um die Aufgabenleistung zu optimieren. Es kann länger MEDIUM dauern, bis das Modell das erste Token generiert, aber die Ausgabe ist gründlicher.

Verwenden Sie HIGH beispielsweise für Logikrätsel, mathematische Textaufgaben oder knifflige Szenarien, in denen das Modell mehrere Schritte durchdenken muss:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

Der Parameter thinking_level ist optional. Wenn keine Angabe gemacht wird, verwendet 3.5 Flash die Standardeinstellung (MEDIUM).

Fortführung der Logikschritte

Das Modell behält automatisch Zwischenüberlegungen in Mehrfachdialogen bei. Wenn der Begründungskontext im Unterhaltungsverlauf vorhanden ist, wird er automatisch übertragen, was die Leistung bei komplexen mehrstufigen Aufgaben wie iterativem Debugging und Code-Refactoring verbessert. Es sind keine API-Änderungen erforderlich.

Gedanken aus vorherigen Zügen werden jetzt standardmäßig beibehalten. Der Dienst löscht den Denkverlauf nicht mehr aus dem Unterhaltungskontext, bevor er an das Modell übergeben wird.

Wenn Sie den Unterhaltungsverlauf senden, sollten Sie konsistent mit den vorherigen Runden sein: Entweder Sie fügen den vollständigen Kontext (Gedanken, Funktionsaufrufe, Antworten) ein oder Sie lassen ihn ganz weg. Ein unvollständiger Kontext kann die Modellleistung beeinträchtigen.

Verworfen: Parameter für die Stichprobenerhebung

Die folgenden Sampling-Parameter werden für Gemini 3-Modelle nicht mehr empfohlen:

• temperature
• top_p
• top_k

Das Modell führt selbst Stichproben durch, um optimale Ergebnisse zu erzielen. Entfernen Sie diese Parameter aus allen Anfragen. Um die Deterministik zu gewährleisten, definieren Sie eine Systemanweisung mit expliziten Regeln für Ihren spezifischen Anwendungsfall.

Eingestellt: thinking_budget

Der numerische Rohparameter thinking_budget wird für alle Gemini 3-Modelle nicht mehr unterstützt. Verwenden Sie stattdessen das String-Enum thinking_level.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

Best Practices

In diesem Abschnitt werden die folgenden Best Practices für die Verwendung von 3.5 Flash beschrieben:

• Strikter Abgleich von Antworten für Funktionsaufrufe
• Multimodale Inhalte in die Funktionsantwort parts einfügen
• Inline-Anweisungen in der Funktionsantwort verwenden
• Unnötige Tool-Aufrufe reduzieren

Strikten Antwortabgleich für Funktionsaufrufe verwenden

Bei nicht übereinstimmenden Antworten gibt das Modell in den meisten Fällen leere Antworten mit finish_reason: STOP zurück. Halten Sie sich immer an die folgenden Konventionen:

• id einfügen: Jede FunctionResponse muss die id aus der entsprechenden FunctionCall enthalten.
• Übereinstimmung mit name: Die name in der Antwort muss mit der name im Aufruf übereinstimmen.
• Anzahl der Übereinstimmungen: Für jede empfangene FunctionCall wird genau eine FunctionResponse zurückgegeben.

Der folgende Code ist ein Beispiel für einen korrekten Funktionsaufruf:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

Multimodale Inhalte in die Funktionsantwort einfügen parts

Wenn Sie Bilder außerhalb der Funktionsantwort bereitstellen, kann dies zu unerwartetem Modellverhalten wie dem Durchsickern von Gedanken führen und die Qualität beeinträchtigen. Folgen Sie der Empfehlung in Funktionsaufrufe und fügen Sie multimodale Inhalte in die Teile der Funktionsantwort ein, die Sie an das Modell senden. Das Modell kann diese multimodalen Inhalte in seinem nächsten Zug verarbeiten, um eine fundiertere Antwort zu geben.

Beispiel:

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

Inline-Anweisungen in der Funktionsantwort verwenden

Wenn Sie Plattformanweisungen zusammen mit Funktionsantworten als nachfolgende parts angeben, kann dies zu unerwartetem Modellverhalten wie dem Durchsickern von Gedanken und zu einer geringeren Qualität führen. Hängen Sie ihn stattdessen an das Ende des Antworttexts der Funktion an und trennen Sie ihn durch zwei Zeilenumbrüche.

Beispiel:

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

Unnötige Toolaufrufe reduzieren

Wenn es zu einem übermäßigen Gebrauch von Tool-Aufrufen kommt, können Sie das mit zwei Techniken minimieren:

1. Denkaufwand reduzieren: Bei einem höheren Denkaufwand wird das Modell dazu angeregt, mehr Tools zum Untersuchen und Überprüfen zu verwenden. Wenn Sie den Denkaufwand verringern, kann die Anzahl der Tool-Aufrufe reduziert werden.

2. Systemanweisung hinzufügen: Wenn die übermäßige Nutzung nach dem Anpassen der Denkebene weiterhin besteht, sollten Sie einen Prompt verwenden, der die Toolnutzung einschränkt. Beispiel:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

Von 3.5 Flash oder 3.1 Pro zu 3.6 Flash migrieren

So migrieren Sie von 3.5 Flash oder 3.1 Pro zu 3.6 Flash:

1. Modell-ID aktualisieren: Ändern Sie den Modellstring in Ihren API-Aufrufen zu gemini-3.6-flash.
2. Code an die neuen API-Regeln der Gemini 3-Familie anpassen: Gemini 3.6 Flash erzwingt die Parameterregeln und API-Konventionen, die für die Gemini 3-Familie gelten:
   • Temperatur, Top‑K und Top‑P entfernen: Entfernen Sie diese benutzerdefinierten Parameter aus Ihrer Nutzlast. Es wird kein Fehler ausgegeben, aber das Modell ignoriert sie vollständig. Verwenden Sie stattdessen den Parameter thinking_level oder strukturierte Ausgaben vom Typ json_schema, um die Deterministik der Ausgabe zu steuern.
   • Häufigkeits- und Anwesenheitsabschläge entfernen: Entfernen Sie alle benutzerdefinierten Konfigurationen für Häufigkeits- oder Anwesenheitsabschläge, damit bei Ihren API-Aufrufen keine Laufzeitfehler auftreten.
   • Achten Sie darauf, dass bei Ihrer Chatintegration kein Modell-Prefilling versucht wird.: Prüfen Sie Ihre Nachrichtenverlaufs-Arrays, um sicherzustellen, dass Ihre API-Nutzlast nicht mit einem leeren Nutzer- oder Modell-Turn endet. Wenn das letzte Objekt in Ihrem Verlaufsarray die Rolle „model“ (GenerateContent API) oder den Typ „model_output“ (Interactions API) hat, strukturieren Sie die Sequenz so um, dass kein strenger Validierungsfehler ausgelöst wird.
   • thinking_level verwenden: Entfernen Sie Instanzen des verworfenen Parameters thinking_budget und verwenden Sie stattdessen thinking_level.
   • Strikte Konventionen für Funktionsaufrufe erzwingen: Die FunctionResponse muss genau mit der id, der name und der Anzahl der Ausführungen der vorherigen FunctionCall übereinstimmen. Wenn Sie Inline-Anweisungen anhängen müssen, platzieren Sie sie direkt im Antworttext der Funktion, getrennt durch zwei Zeilenumbrüche (\n\n).
3. Workflow-Änderungen berücksichtigen:
   • Wenn Ihre Anwendung auf Konversationsschleifen mit mehreren Durchläufen basiert, testen Sie Ihre Arbeitsabläufe, um sicherzustellen, dass die neue Kürze der Schritte des Modells keine vorzeitigen Beendigungen auslöst.
   • Wenn Sie Agents für das Frontend oder für einfaches Scripting erstellen, sollten Sie auf unnötige explorative execute_code-Aufrufe achten, die durch die neue Ausrichtung des Modells auf die programmatische Vorabprüfung verursacht werden.

Problemumgehungen für Textanforderungen vor der Verwendung des Tools

Wenn in Ihrem Prompt das Modell aufgefordert wird, strukturierten Text (XML, YAML, JSON usw.) (z. B. <UPDATE>...</UPDATE>) unmittelbar vor einem Tool-Aufruf auszugeben, kann der Tool-Aufruf gelegentlich mit einem Malformed_Function_Call-Fehler fehlschlagen. Sie können das Problem mit einer der folgenden Behelfslösungen beheben:

• (Empfohlen) Weisen Sie das Modell an, seine Notizen vor dem Tool in einem dedizierten update()-Funktionsaufruf anstelle von Rohtext zu platzieren. Eine ausführliche Anleitung zur Implementierung finden Sie im nächsten Abschnitt.
• Weisen Sie das Modell an, Notizen als Markdown-Überschriften (z. B. # UPDATE, ## PLAN) anstelle von strukturiertem Text zu schreiben.
• Das Modell muss vor Tool-Aufrufen keinen Text ausgeben.

Empfohlene Lösung: Arbeitsnotizen in einen dedizierten Funktionsaufruf einfügen

Anstelle der ursprünglichen Anleitung:

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

Verwenden Sie diese aktualisierte Anweisung:

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

Aktualisieren Sie alle Verweise auf das alte <UPDATE>-XML-Format in der Kundenanfrage. Fügen Sie dann die entsprechende Funktionsdeklaration für die Update-Funktion hinzu:

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

Das Modell führt im selben Schritt zwei Aufrufe aus: den update()-Aufruf, der das strukturierte XML ersetzt, und den eigentlichen Funktionsaufruf, den es ausführen möchte.

Zusätzliche Ressourcen

• Seite zum Gemini 3.5 Flash-Modell
• Einführungs-Notebook