Raisonnement de Gemini

Les modèles des séries Gemini 3 et 2.5 utilisent un "processus de réflexion" interne qui améliore considérablement leurs capacités de raisonnement et de planification en plusieurs étapes, ce qui les rend très efficaces pour les tâches complexes telles que le codage, les mathématiques avancées et l'analyse de données.

Ce guide vous explique comment utiliser les capacités de raisonnement de Gemini à l'aide de l'API Gemini.

Générer du contenu avec raisonnement

Lancer une requête avec un modèle à raisonnement est semblable à n'importe quelle autre requête de génération de contenu. La principale différence réside dans la spécification de l'un des modèles compatibles avec le raisonnement dans le model champ :

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

Résumés de réflexion

Les résumés de réflexion fournissent des insights sur le processus de raisonnement interne du modèle. Par défaut, seule la sortie finale est renvoyée. Vous pouvez activer les résumés de réflexion avec thinking_summaries :

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the sum of the first 50 prime numbers?",
    generation_config={
        "thinking_summaries": "auto"
    }
)

for step in interaction.steps:
    if step.type == "thought":
        print("Thought summary:")
        for content_block in step.summary:
            if content_block.type == "text":
                print(content_block.text)
        print()
    elif step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print("Answer:")
                print(content_block.text)
                print()

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the sum of the first 50 prime numbers?",
    generationConfig: {
        thinkingSummaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought summary:");
        for (const contentBlock of step.summary) {
            if (contentBlock.type === "text") console.log(contentBlock.text);
        }
    } else if (step.type === "model_output") {
        for (const contentBlock of step.content) {
            if (contentBlock.type === "text") {
                console.log("Answer:");
                console.log(contentBlock.text);
            }
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generationConfig": {
      "thinkingSummaries": "auto"
    }
  }'

Streaming avec raisonnement

Utilisez le streaming pour recevoir des résumés de réflexion incrémentaux pendant la génération. Cela renvoie des résumés incrémentaux à mesure qu'ils sont générés :

Python

from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

thoughts = ""
answer = ""

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought":
            if not thoughts:
                print("Thinking...")
            summary_text = getattr(event.delta, 'text', '')
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

let thoughts = "";
let answer = "";

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: prompt,
    generationConfig: {
        thinkingSummaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.type === "step.delta") {
        if (event.delta.type === "thought") {
            if (!thoughts) console.log("Thinking...");
            process.stdout.write(`[Thought] ${event.delta.text || ""}`);
            thoughts += event.delta.text || "";
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}

Contrôler le raisonnement

Les modèles Gemini s'engagent par défaut dans un raisonnement dynamique, en ajustant automatiquement l'effort de raisonnement en fonction de la complexité de la requête. Toutefois, vous pouvez contrôler ce comportement à l'aide de paramètres de configuration.

Niveaux de réflexion (Gemini 3)

Le paramètre thinking_level, recommandé pour les modèles Gemini 3 et versions ultérieures, vous permet de contrôler le comportement de raisonnement.

Niveau de réflexion Gemini 3.1 Pro Gemini 3 Pro (Obsolète) Gemini 3 Flash Description
minimal Not supported Not supported Compatible Correspond au paramètre "no thinking" (pas de raisonnement) pour la plupart des requêtes. Le modèle peut réfléchir de manière très minimale pour les tâches de codage complexes. Réduit la latence pour les applications de chat ou à haut débit. Notez que minimal ne garantit pas que le raisonnement est désactivé.
low Compatible Compatible Compatible Réduit la latence et les coûts. Idéal pour suivre des instructions, discuter ou utiliser des applications à haut débit.
medium Compatible Not supported Compatible Raisonnement équilibré pour la plupart des tâches.
high Compatible (par défaut, dynamique) Compatible (par défaut, dynamique) Compatible (par défaut, dynamique) Maximise la profondeur du raisonnement. Le modèle peut mettre beaucoup plus de temps à atteindre un premier jeton de sortie (sans raisonnement), mais la sortie sera plus soigneusement raisonnée.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generationConfig: {
        thinkingLevel: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

Vous ne pouvez pas désactiver le raisonnement pour Gemini 3 Pro. Gemini 3 Flash ne prend pas non plus en charge la désactivation complète du raisonnement, mais le paramètre minimal signifie que le modèle ne réfléchira probablement pas (bien qu'il puisse toujours le faire).

Signatures de réflexion

L'API Gemini est sans état. Le modèle traite donc chaque requête d'API indépendamment et n'a pas accès au contexte de réflexion des tours précédents dans les interactions multitours.

Pour permettre de maintenir le contexte de réflexion dans les interactions multitours, Gemini renvoie des signatures de réflexion, qui sont des représentations chiffrées du processus de réflexion interne du modèle.

  • Les modèles Gemini 2.5 renvoient des signatures de réflexion lorsque le raisonnement est activé et que la requête inclut un appel de fonction, en particulier des déclarations de fonction.
  • Les modèles Gemini 3 peuvent renvoyer des signatures de réflexion pour tous les types de parties. Nous vous recommandons de toujours renvoyer toutes les signatures telles qu'elles ont été reçues, mais cela est obligatoire pour les signatures d'appel de fonction. Pour en savoir plus, consultez la page Signatures de réflexion.
  • Les signatures sont renvoyées par le modèle dans d'autres parties de la réponse, par exemple des appels de fonction ou des parties de texte. Renvoyez la réponse complète avec toutes les parties au modèle lors des tours suivants.
  • Ne concaténez pas les parties avec des signatures.
  • Ne fusionnez pas une partie avec une signature avec une autre partie sans signature.

Tarifs

Lorsque le raisonnement est activé, le prix de la réponse correspond à la somme des jetons de sortie et des jetons de réflexion. Vous pouvez obtenir le nombre total de jetons de réflexion générés à partir du champ total_thought_tokens.

Python

# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// ...
console.log(`Thoughts tokens: ${interaction.usage.totalThoughtTokens}`);
console.log(`Output tokens: ${interaction.usage.totalOutputTokens}`);

Les modèles à raisonnement génèrent des réflexions complètes pour améliorer la qualité de la réponse finale, puis génèrent des résumés pour fournir des insights sur le processus de réflexion. La tarification est basée sur les jetons de réflexion complets que le modèle doit générer, même si seul le résumé est généré par l'API.

Pour en savoir plus sur les jetons, consultez le guide Comptage des jetons.

Bonnes pratiques

Cette section fournit des conseils pour utiliser efficacement les modèles à raisonnement.

Déboguer et orienter

  • Examiner le raisonnement : lorsque vous n'obtenez pas la réponse attendue des modèles à raisonnement, il peut être utile d'analyser attentivement les résumés de réflexion de Gemini. Vous pouvez voir comment il a décomposé la tâche et est parvenu à sa conclusion, et utiliser ces informations pour corriger les résultats.

  • Fournir des conseils dans le raisonnement : si vous espérez obtenir une sortie particulièrement longue, vous pouvez fournir des conseils dans votre prompt afin de limiter la quantité de réflexion utilisée par le modèle. Vous réservez ainsi une plus grande partie de la sortie de jeton pour votre réponse.

Complexité des tâches

  • Tâches simples (le raisonnement peut être désactivé) : pour les requêtes simples qui ne nécessitent pas de raisonnement complexe, le raisonnement n'est pas nécessaire. Exemples :
    • "Où a été fondée DeepMind ?"
    • "Cet e-mail demande-t-il une réunion ou fournit-il simplement des informations ?"
  • Tâches moyennes (par défaut/certains raisonnements) : de nombreuses requêtes courantes bénéficient d'un traitement étape par étape ou d'une compréhension plus approfondie. Exemples :
    • Comparer la photosynthèse et la croissance.
    • Comparer les voitures électriques et les voitures hybrides.
  • Tâches difficiles (capacité de raisonnement maximale) : pour les défis vraiment complexes, nous vous recommandons de définir un budget de réflexion élevé. Ces types de tâches nécessitent que le modèle utilise pleinement ses capacités de raisonnement et de planification. Exemples :
    • Résoudre le problème 1 dans AIME 2025 : trouver la somme de toutes les bases entières b > 9...
    • Écrire du code Python pour une application Web qui visualise les données boursières en temps réel, y compris l'authentification des utilisateurs. Rendez-la aussi efficace que possible.

Modèles compatibles

Modèle Raisonnement par défaut Niveaux compatibles
gemini-3.1-pro-preview Activé (élevé) faible, moyen, élevé
gemini-3-flash-preview Activé (élevé) minimal, faible, moyen, élevé
gemini-3-pro-preview Activé (élevé) faible, élevé
gemini-2.5-pro Activé Budget: 128-32768
gemini-2.5-flash Activé Budget: 0-24576
gemini-2.5-flash-lite Désactivé Budget: 0-24576

Les modèles à raisonnement fonctionnent avec tous les outils et toutes les fonctionnalités de Gemini. Cela permet aux modèles d'interagir avec des systèmes externes, d'exécuter du code ou d'accéder à des informations en temps réel, en intégrant les résultats dans leur raisonnement.

Étape suivante