Gemini réfléchit

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

Lorsque vous utilisez un modèle de réflexion, Gemini raisonne en interne avant de répondre. L'API Interactions présente ce raisonnement en thought étapes, qui s'affichent de manière chronologique à côté des appels de fonction, des saisies utilisateur ou des sorties de modèle dans le tableau steps.

Chaque étape de réflexion contient deux champs :

Champ Obligatoire Description
signature ✅ Oui Représentation chiffrée de l'état de raisonnement interne du modèle. Toujours présent, même lorsque le modèle effectue un raisonnement minimal.
summary ❌ Non Tableau de contenu (texte et/ou images) résumant le raisonnement. Cette valeur peut être vide en fonction de la configuration thinking_summaries, du fait que le modèle ait suffisamment raisonné ou du type de contenu (par exemple, les latents d'image peuvent ne pas avoir de résumés textuels).

Interactions avec la réflexion

L'initiation d'une interaction avec un modèle de réflexion est semblable à toute autre demande d'interaction. Spécifiez l'un des modèles avec prise en charge de la réflexion dans le champ model :

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 "Api-Revision: 2026-05-20" \
  -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 des réflexions

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?",
    generation_config: {
        thinking_summaries: "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 "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'

Un bloc de réflexion peut ne contenir qu'une signature sans résumé dans les cas suivants :

  • Requêtes simples pour lesquelles le modèle n'a pas suffisamment raisonné pour générer un résumé
  • thinking_summaries: "none", où les résumés sont explicitement désactivés
  • Il est possible que certains types de contenus de réflexion, tels que les images, ne disposent pas de résumés textuels.

Votre code doit toujours gérer les blocs de réflexion où summary est vide ou absent.

Streaming avec réflexion

Utilisez le streaming pour recevoir des résumés de pensée incrémentaux pendant la génération. Les blocs de réflexion sont fournis à l'aide d'événements envoyés par le serveur (SSE) avec deux types de delta distincts :

Type de delta Contient Quand les données sont envoyées
thought_summary Contenu récapitulatif sous forme de texte ou d'image Un ou plusieurs deltas avec un récapitulatif incrémentiel
thought_signature Signature cryptographique le dernier delta avant step.stop

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
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought_summary":
            if not thoughts:
                print("Thinking...")
            summary_text = event.delta.content.get('text', '') if hasattr(event.delta, 'content') else 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,
    generation_config: {
        thinking_summaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "thought_summary") {
            if (!thoughts) console.log("Thinking...");
            const text = event.delta.content?.text || "";
            process.stdout.write(`[Thought] ${text}`);
            thoughts += 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;
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "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?",
    "generation_config": {
      "thinking_summaries": "auto"
    },
    "stream": true
  }'

La réponse en flux continu utilise des événements envoyés par le serveur (SSE) et se compose d'étapes et d'événements. Consultez l'exemple ci-dessous.

event: interaction.created
data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3-flash-preview"},"event_type":"interaction.created"}

event: step.start
data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"EpoGCpcGAXLI2nx/...","type":"thought_signature"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"v1_xxx","status":"completed","usage":{"total_tokens":530,"total_input_tokens":62,"total_output_tokens":171,"total_thought_tokens":297}},"event_type":"interaction.completed"}

event: done
data: [DONE]

Pensée contrôlante

Les modèles Gemini s'engagent par défaut dans une réflexion dynamique, en ajustant automatiquement l'effort de raisonnement en fonction de la complexité de la requête. Vous pouvez contrôler ce comportement à l'aide du paramètre thinking_level.

Modèle Pensée par défaut Niveaux compatibles
gemini-3.1-pro-preview Activé (élevé) faible, moyenne, élevée
gemini-3-flash-preview Activé (élevé) minimal, faible, moyen, élevé
gemini-3-pro-preview Activé (élevé) faible, élevé
gemini-2.5-pro Activé faible, moyenne, élevée
gemini-2.5-flash Activé faible, moyenne, élevée
gemini-2.5-flash-lite Désactivé faible, moyenne, élevé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",
    generation_config: {
        thinking_level: "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 "Api-Revision: 2026-05-20" \
  -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"
    }
  }'

Signatures de pensée

Les signatures de pensée sont des représentations chiffrées du raisonnement interne du modèle. Ils doivent maintenir la continuité du raisonnement lors des interactions en plusieurs tours.

L'API Interactions simplifie la gestion des signatures de pensée par rapport à l'API generateContent.

Par défaut, lorsque vous utilisez l'API Interactions en mode avec état (en définissant store: true et en transmettant previous_interaction_id lors des tours suivants), le serveur gère automatiquement l'état de la conversation, y compris tous les blocs de réflexion et les signatures. Dans ce mode, vous n'avez rien à faire concernant les signatures. Elles sont entièrement gérées côté serveur.

Mode sans état

Si vous gérez vous-même l'état de la conversation (mode sans état) et que vous transmettez l'historique complet des entrées et des sorties dans chaque requête :

  • Vous DEVEZ toujours renvoyer tous les blocs thought exactement tels qu'ils ont été reçus du modèle.
  • Vous ne devez PAS supprimer ni modifier les blocs de réflexion de l'historique, car ils contiennent les signatures nécessaires pour que le modèle poursuive son raisonnement.
  • Lorsque vous changez de modèle au cours d'une session, vous devez toujours renvoyer les blocs de réflexion du modèle précédent. Le backend gère la compatibilité.

Tarifs

Lorsque la réflexion est activée, 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.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

Les modèles à raisonnement génèrent des pensées complètes pour améliorer la qualité de la réponse finale, puis génèrent des résumés pour donner un aperçu du processus de réflexion. La tarification est basée sur les jetons de pensée complets que le modèle doit générer, même si seule la synthèse est générée par l'API.

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

Bonnes pratiques

Utilisez efficacement les modèles de réflexion en suivant ces consignes.

  • Examiner le raisonnement : analysez les résumés de réflexion pour comprendre les échecs et améliorer les requêtes.
  • Contrôler le budget de réflexion : demandez au modèle de moins réfléchir pour les réponses longues afin d'économiser des jetons.
  • Tâches simples : elles nécessitent une réflexion minimale pour récupérer des faits ou effectuer une classification (par exemple, "Où DeepMind a-t-elle été fondée ?").
  • Tâches de modération : utilisez la pensée par défaut pour comparer des concepts ou le raisonnement créatif (par exemple, "Compare les voitures électriques et hybrides").
  • Tâches complexes : utilisez la capacité de réflexion maximale pour le codage avancé, les mathématiques ou la planification en plusieurs étapes (par exemple, résoudre des problèmes de mathématiques AIME).

Étape suivante