Guide du développeur pour Gemini 3.5 Flash

Gemini 3.5 Flash est un modèle puissant, rapide et économique de la famille Gemini 3. Conçu pour offrir des capacités agentiques proches de celles de Pro sans compromettre les performances ni la valeur, le modèle est désormais en disponibilité générale pour les développeurs utilisant l'API Gemini et pour les entreprises utilisant Gemini Enterprise Agent Platform.

Ce document présente les nouveautés de 3.5 Flash, quand l'utiliser, comment migrer vers 3.5 Flash et fournit un guide de démarrage rapide pour utiliser 3.5 Flash.

Comment s'intègre-t-il dans la famille Gemini ?

Le tableau suivant compare certaines des spécifications de 3.5 Flash, 3.1 Pro et 3.1 Flash-Lite :

Gemini 3.5 Flash Gemini 3.1 Pro Gemini 3.1 Flash-Lite
ID du modèle gemini-3.5-flash gemini-3.1-pro-preview gemini-3.1-flash-lite
Étape de lancement GA Aperçu DG
Types d'entrée Texte, image, audio, vidéo Texte, image, audio, vidéo Texte, image, audio, vidéo
Type(s) de sortie Texte Texte Texte
Fenêtre de contexte 1 048 576 1 048 576 1 048 576
Longueur maximale des jetons de sortie 65 536 65 536 65 536
Régions où le service est disponible Monde, multirégional, Amériques, Europe, Asie-Pacifique Monde Mondial, multirégional
Niveaux de raisonnement compatibles MINIMAL, LOW, MEDIUM, HIGH
(par défaut : MEDIUM) 		LOW, MEDIUM, HIGH
(par défaut : HIGH) 		MINIMAL, LOW, MEDIUM, HIGH
(par défaut : MINIMAL)
Utilisation principale Tâches équilibrées, appel d'outils et raisonnement intermédiaire Raisonnement approfondi, tâches très complexes Tâches à volume élevé, sensibles aux coûts et à la latence

Consultez la page du modèle 3.5 Flash pour obtenir la liste complète des fonctionnalités, outils et options de consommation compatibles.

Répartition des cas d'utilisation

La stratégie recommandée pour les workflows agentifs utilise une approche par niveaux pour optimiser la qualité, la vitesse et le coût :

  • Gemini Pro : réservez-le aux tâches cognitives très complexes nécessitant un raisonnement approfondi, comme la planification initiale, la résolution de problèmes complexes, le codage difficile et la prise de décisions critiques.
  • Gemini Flash : utilisez-le comme "cheval de bataille" principal pour les tâches d'exécution, les appels d'outils et les étapes de raisonnement intermédiaires, car il offre le meilleur équilibre entre performances et efficacité.
  • Gemini Flash-Lite : déployez-le pour les tâches de prétraitement et de structure à volume élevé et à faible latence, où la vitesse et le coût sont primordiaux, comme le routage des intentions, l'extraction de données, l'ajout de tags et la classification.

Quelles sont les nouveautés de Gemini 3.5 Flash ?

Gemini 3.5 Flash apporte les modifications et améliorations suivantes à la gamme de modèles Gemini :

  • Performances de pointe constantes : notre modèle Gemini Flash le plus intelligent, optimisé pour les tâches agentiques et de codage à grande échelle.
  • Exécution agentique : déploiement de sous-agents, résolution de problèmes et boucles agentiques rapides à grande échelle.
  • Codage amélioré : cycles de codage itératifs, exploration rapide et prototypage pour tester d'autres chemins et explorer des solutions de manière dynamique.
  • À long horizon : workflows multi-étapes et utilisation d'outils à grande échelle.
  • Préservation des pensées : le modèle conserve automatiquement le raisonnement intermédiaire dans les conversations multitours. Aucune modification de l'API n'est nécessaire.
  • Nouveau niveau de réflexion par défaut : le niveau de réflexion par défaut est passé de HIGH à MEDIUM.
  • Amélioration de la réflexion LOW : le niveau de réflexion faible est désormais considérablement amélioré pour le code et les tâches agentiques qui nécessitent moins d'étapes, offrant une qualité élevée à une latence et un coût inférieurs.

Pour en savoir plus, consultez la section Principaux changements.

Guide de démarrage rapide

Avant de commencer, vous devez vous authentifier auprès d'Agent Platform à l'aide des Identifiants par défaut de l'application (ADC) ou d'une clé API. Pour en savoir plus, consultez Premiers pas avec Gemini Enterprise Agent Platform.

Dans les blocs de code suivants, remplacez PROJECT_ID par l'ID de votre projet.

Installation

Assurez-vous d'utiliser la dernière version du SDK google-genai :

pip install --upgrade google-genai

Requête de base

Python

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)

REST

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?" },
  },
}'

Principales modifications

Cette section décrit plus en détail les modifications suivantes introduites dans Gemini 3.5 Flash :

Nouveau niveau de raisonnement par défaut

Le niveau de réflexion par défaut des modèles Gemini 3 est désormais MEDIUM, au lieu de HIGH dans la version preview de Gemini 3 Flash. Le niveau de réflexion MEDIUM donne de bons résultats pour un large éventail de tâches, tout en étant plus rapide et plus économique.

Voici les niveaux de réflexion acceptés :

  • MINIMAL : correspond au paramètre "no thinking" pour la plupart des requêtes. Le modèle peut réfléchir très peu pour les tâches complexes comme le codage. Minimise la latence pour les applications de chat ou à haut débit.
  • LOW : raisonnement léger pour la plupart des tâches, avec une vitesse élevée et un coût réduit.
  • MEDIUM : (par défaut) paramètre équilibré pour la plupart des tâches nécessitant un raisonnement.
  • HIGH : maximise le raisonnement pour optimiser les performances des tâches. Le modèle peut prendre plus de temps que le paramètre MEDIUM pour générer le premier jeton, mais la sortie sera plus complète.

Par exemple, utilisez HIGH pour les énigmes logiques, les problèmes mathématiques ou les scénarios complexes où le modèle doit raisonner en plusieurs étapes :

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)

Le paramètre thinking_level est facultatif. Si aucune valeur n'est spécifiée, 3.5 Flash utilisera son paramètre par défaut (MEDIUM).

Préservation des pensées

Le modèle conserve automatiquement le raisonnement intermédiaire dans les conversations multitours. Lorsqu'il est présent dans l'historique de la conversation, le contexte de raisonnement est automatiquement reporté, ce qui améliore les performances sur les tâches complexes en plusieurs étapes, comme le débogage itératif et la refactorisation du code. Aucune modification de l'API n'est nécessaire.

Les pensées des tours précédents sont désormais conservées par défaut. Le service n'efface plus l'historique des pensées du contexte de la conversation avant de le transmettre au modèle.

Lorsque vous envoyez l'historique des conversations, soyez cohérent avec les tours précédents : incluez le contexte complet (pensées, appels de fonction, réponses) ou omettez-le entièrement. Un contexte partiel peut dégrader les performances du modèle.

Obsolète : paramètres d'échantillonnage

Les paramètres d'échantillonnage suivants ne sont plus recommandés pour les modèles Gemini 3 :

  • temperature
  • top_p
  • top_k

Le modèle gère son propre échantillonnage pour des résultats optimaux. Supprimez ces paramètres de toutes les requêtes. Pour garantir le déterminisme, définissez une instruction système avec des règles explicites pour votre cas d'utilisation spécifique.

Obsolète : thinking_budget

Le paramètre numérique brut thinking_budget n'est plus compatible avec tous les modèles Gemini 3. Utilisez plutôt l'énumération de chaîne 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")
)

Bonnes pratiques

Cette section décrit les bonnes pratiques suivantes pour utiliser 3.5 Flash :

Utiliser la correspondance stricte des réponses pour les appels de fonction

Dans la plupart des cas, les réponses non concordantes entraînent le renvoi de réponses vides avec finish_reason: STOP. Suivez toujours ces conventions :

  • Inclure id : chaque FunctionResponse doit inclure le id du FunctionCall correspondant.
  • Correspondance name : l'élément name de la réponse doit correspondre à l'élément name de l'appel.
  • Nombre de correspondances : renvoie exactement un FunctionResponse pour chaque FunctionCall reçu.

Le code suivant est un exemple d'appel de fonction correct :

# ✅ 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,
            )
        ]),
    ],
)

Inclure du contenu multimodal dans la réponse de la fonction parts

Fournir des images en dehors de la réponse de la fonction peut entraîner un comportement inattendu du modèle, comme une fuite de pensée, et une qualité inférieure. Suivez la recommandation de l'introduction aux appels de fonction et incluez du contenu multimodal dans les parties de réponse de la fonction que vous envoyez au modèle. Le modèle peut traiter ce contenu multimodal lors de son prochain tour pour produire une réponse plus éclairée.

Exemple :

# ✅ 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,
            )
        ]),
    ],
)

Utiliser des instructions intégrées dans la réponse de la fonction

Fournir des instructions de plate-forme ainsi que des réponses de fonction en tant que parts ultérieurs peut entraîner un comportement inattendu du modèle, tel qu'une fuite de pensée, et une qualité inférieure. Ajoutez-le plutôt à la fin du texte de réponse de la fonction, séparé par deux nouvelles lignes.

Exemple :

# ✅ 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,
            )
        ]),
    ],
)

Réduire les appels d'outils inutiles

Si vous constatez une utilisation excessive des appels d'outils, deux techniques permettent de les réduire :

  1. Réduire le niveau de raisonnement : des niveaux de raisonnement plus élevés encouragent le modèle à utiliser davantage d'outils pour explorer et vérifier. Par conséquent, réduire le niveau peut réduire les appels d'outils.

  2. Ajouter une instruction système : si la surutilisation persiste après l'ajustement du niveau de réflexion, envisagez d'utiliser une requête qui limite l'utilisation des outils. Exemple :

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

Migrer vers 3.6 Flash depuis 3.5 Flash ou 3.1 Pro

Pour migrer vers 3.6 Flash depuis 3.5 Flash ou 3.1 Pro, procédez comme suit :

  1. Mettre à jour l'ID du modèle : remplacez la chaîne du modèle par gemini-3.6-flash dans vos appels d'API.
  2. Adaptez votre code aux nouvelles règles de l'API de la famille Gemini 3 : Gemini 3.6 Flash applique strictement les règles de paramètres et les conventions d'API établies pour la famille Gemini 3 :
    • Supprimer les paramètres temperature, top-K et top-P : supprimez ces paramètres personnalisés de votre charge utile. Bien qu'ils ne génèrent pas d'erreur, le modèle les ignorera complètement. Utilisez plutôt le paramètre thinking_level ou les sorties structurées json_schema pour contrôler le déterminisme des sorties.
    • Supprimez les pénalités de fréquence et de présence : supprimez toutes les configurations personnalisées pour les pénalités de fréquence ou de présence afin d'éviter que vos appels d'API ne génèrent des erreurs d'exécution.
    • Assurez-vous que votre intégration de chat ne tente pas de préremplir le modèle : examinez vos tableaux d'historique des messages pour vous assurer que votre charge utile d'API ne se termine pas par un tour d'utilisateur ou de modèle vide. Si le dernier objet de votre tableau d'historique est un rôle "model" (API GenerateContent) ou un type "model_output" (API Interactions), restructurez la séquence pour éviter de déclencher une erreur de validation stricte.
    • Utilisez thinking_level : supprimez les instances du paramètre thinking_budget obsolète et utilisez thinking_level à la place.
    • Appliquer des conventions d'appel de fonction strictes : FunctionResponse doit correspondre strictement à id, name et au nombre d'exécutions de FunctionCall précédent. Si vous devez ajouter des instructions intégrées, placez-les directement dans le texte de la réponse de la fonction, séparées par deux sauts de ligne (\n\n).
  3. Tenez compte des changements de workflow :
    • Si votre application repose sur des boucles de conversation multitours, testez vos workflows pour vous assurer que la concision de la nouvelle étape du modèle ne déclenche pas de sorties prématurées.
    • Si vous créez des agents d'interface ou de script de base, surveillez les appels execute_code exploratoires inutiles dus au nouveau biais du modèle en faveur de l'inspection programmatique initiale.

Solutions de contournement pour les exigences de texte avant l'outil

Si votre prompt nécessite que le modèle génère du texte structuré (XLM, YAML, JSON, etc.) (par exemple, <UPDATE>...</UPDATE>) immédiatement avant d'effectuer un appel d'outil, l'appel d'outil peut parfois échouer avec une erreur Malformed_Function_Call. Pour résoudre ce problème, vous pouvez utiliser l'une des solutions suivantes :

  • (Recommandé) Demandez au modèle de placer ses notes préalables à l'outil dans un appel de fonction update() dédié plutôt que dans du texte brut. Pour obtenir des instructions d'implémentation détaillées, consultez la section suivante.
  • Demandez au modèle d'écrire des notes sous forme d'en-têtes Markdown (par exemple, # UPDATE, ## PLAN) au lieu de texte structuré.
  • N'exigez pas que le modèle génère du texte avant les appels d'outils.

Solution recommandée : encapsuler les notes de travail dans un appel de fonction dédié

Au lieu de l'instruction d'origine :

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>`.

Utilisez cette instruction mise à jour :

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

Mettez à jour toutes les références à l'ancien format XML <UPDATE> dans la demande du client. Ajoutez ensuite la déclaration de fonction correspondante pour la fonction de mise à jour :

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

Le modèle effectuera deux appels au cours de la même étape : l'appel update() qui remplace le code XML structuré et l'appel de fonction réel qu'il souhaite effectuer.

Autres ressources