Raisonnement de Gemini

Les modèles des séries 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, 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.

Lorsque vous utilisez un modèle de réflexion, Gemini raisonne en interne avant de répondre. L'API Interactions met en évidence ce raisonnement via des étapes thought, des étapes dédiées qui apparaissent de manière chronologique à côté des appels de fonction, des entrées utilisateur ou des sorties de modèle dans le tableau steps.

Chaque étape de réflexion contient deux champs :

Interactions avec la réflexion

Lancer une interaction avec un modèle de réflexion est semblable à toute autre requête d'interaction. Spécifiez l'un des modèles compatibles avec la réflexion dans le model champ :

# This will only work for SDK newer than 2.0.0
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)

// This will only work for SDK newer than 2.0.0
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);

# Specifies the API revision to avoid breaking changes when they become default
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."
  }'

Vous pouvez diffuser en continu des interactions de réflexion pour recevoir des résumés et des signatures de réflexion incrémentiels lors de la génération. Pour obtenir un guide complet couvrant les types d'événements, les types de delta et des exemples de code, consultez le guide sur les interactions de diffusion en continu.

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 :

# This will only work for SDK newer than 2.0.0
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:")
        if step.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()

// This will only work for SDK newer than 2.0.0
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:");
        if (step.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);
            }
        }
    }
}

# Specifies the API revision to avoid breaking changes when they become default
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 contenir uniquement une signature sans résumé dans les cas suivants :

• Requêtes simples, où 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
• Certains types de contenu de réflexion, tels que les images, peuvent ne pas avoir de résumés de texte

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

Contrôler la réflexion

Les modèles Gemini s'engagent dans une réflexion dynamique par défaut, 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.

# This will only work for SDK newer than 2.0.0
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)

// This will only work for SDK newer than 2.0.0
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);

# Specifies the API revision to avoid breaking changes when they become default
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 réflexion

Les signatures de réflexion sont des représentations chiffrées du raisonnement interne du modèle. Elles sont nécessaires pour maintenir la continuité du raisonnement dans les interactions multitours.

L'API Interactions simplifie considérablement la gestion des signatures de réflexion par rapport à l'API generateContent.

Mode avec état (recommandé)

Par défaut, lorsque vous utilisez l'API Interactions en mode avec état (en définissant store: true et en transmettant le previous_interaction_id dans les tours suivants), le serveur gère automatiquement l'état de la conversation, y compris tous les blocs et signatures de réflexion. 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 requises 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.

# This will only work for SDK newer than 2.0.0
# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

// This will only work for SDK newer than 2.0.0
// ...
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

Les modèles de 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 sur le décompte 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 invites.
• Contrôler le budget de réflexion : demandez au modèle de moins réfléchir pour les sorties longues afin d'économiser des jetons.
• Tâches simples : utilisez une réflexion minimale pour la récupération ou la classification de faits (par exemple, « Où DeepMind a-t-il été fondé ? »).
• Tâches modérées : utilisez la réflexion par défaut pour comparer des concepts ou un raisonnement créatif (par exemple, comparer les voitures électriques et hybrides).
• Tâches complexes : utilisez une réflexion maximale pour le codage avancé, les mathématiques ou la planification en plusieurs étapes (par exemple, résoudre des problèmes mathématiques AIME).

Étape suivante

• Génération de texte : réponses textuelles de base
• Appel de fonction : se connecter à des outils
• Guide Gemini 3 : fonctionnalités spécifiques au modèle