Gemini 3 est disponible. Consultez le guide du développeur pour commencer à utiliser notre modèle le plus avancé à ce jour.

Cette page a été traduite par l'API Cloud Translation.

Gemini avec réflexion

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

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

Générer du contenu en réfléchissant

L'initiation d'une requête avec un modèle de réflexion est semblable à toute 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 la réflexion dans le champ model, comme illustré dans l'exemple de génération de texte suivant :

Python

from google import genai

client = genai.Client()
prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example."
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=prompt
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example.";

  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: prompt,
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "google.golang.org/genai"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  prompt := "Explain the concept of Occam's Razor and provide a simple, everyday example."
  model := "gemini-2.5-pro"

  resp, _ := client.Models.GenerateContent(ctx, model, genai.Text(prompt), nil)

  fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent" \
 -H "x-goog-api-key: $GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -X POST \
 -d '{
   "contents": [
     {
       "parts": [
         {
           "text": "Explain the concept of Occam\'s Razor and provide a simple, everyday example."
         }
       ]
     }
   ]
 }'
 ```

Résumés des pensées

Les résumés de réflexion sont des versions synthétisées des réflexions brutes du modèle. Ils offrent des informations sur le processus de raisonnement interne du modèle. Notez que les niveaux et budgets de réflexion s'appliquent aux réflexions brutes du modèle, et non aux résumés de réflexion.

Vous pouvez activer les résumés de réflexion en définissant includeThoughts sur true dans la configuration de votre requête. Vous pouvez ensuite accéder au récapitulatif en parcourant les parts du paramètre response et en vérifiant le booléen thought.

Voici un exemple montrant comment activer et récupérer des résumés de réflexion sans streaming, ce qui renvoie un résumé de réflexion final unique avec la réponse :

Python

from google import genai
from google.genai import types

client = genai.Client()
prompt = "What is the sum of the first 50 prime numbers?"
response = client.models.generate_content(
  model="gemini-2.5-pro",
  contents=prompt,
  config=types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
      include_thoughts=True
    )
  )
)

for part in response.candidates[0].content.parts:
  if not part.text:
    continue
  if part.thought:
    print("Thought summary:")
    print(part.text)
    print()
  else:
    print("Answer:")
    print(part.text)
    print()

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: "What is the sum of the first 50 prime numbers?",
    config: {
      thinkingConfig: {
        includeThoughts: true,
      },
    },
  });

  for (const part of response.candidates[0].content.parts) {
    if (!part.text) {
      continue;
    }
    else if (part.thought) {
      console.log("Thoughts summary:");
      console.log(part.text);
    }
    else {
      console.log("Answer:");
      console.log(part.text);
    }
  }
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  contents := genai.Text("What is the sum of the first 50 prime numbers?")
  model := "gemini-2.5-pro"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      IncludeThoughts: true,
    },
  })

  for _, part := range resp.Candidates[0].Content.Parts {
    if part.Text != "" {
      if part.Thought {
        fmt.Println("Thoughts Summary:")
        fmt.Println(part.Text)
      } else {
        fmt.Println("Answer:")
        fmt.Println(part.Text)
      }
    }
  }
}

Voici un exemple d'utilisation de la réflexion avec le streaming, qui renvoie des résumés cumulatifs et incrémentaux pendant la génération :

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
"""

thoughts = ""
answer = ""

for chunk in client.models.generate_content_stream(
    model="gemini-2.5-pro",
    contents=prompt,
    config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
        include_thoughts=True
      )
    )
):
  for part in chunk.candidates[0].content.parts:
    if not part.text:
      continue
    elif part.thought:
      if not thoughts:
        print("Thoughts summary:")
      print(part.text)
      thoughts += part.text
    else:
      if not answer:
        print("Answer:")
      print(part.text)
      answer += part.text

JavaScript

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

const ai = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. The person who lives in the red house owns a cat.
Bob does not live in the green house. Carol owns a dog. The green house is to
the left of the red house. Alice does not own a cat. Who lives in each house,
and what pet do they own?`;

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

async function main() {
  const response = await ai.models.generateContentStream({
    model: "gemini-2.5-pro",
    contents: prompt,
    config: {
      thinkingConfig: {
        includeThoughts: true,
      },
    },
  });

  for await (const chunk of response) {
    for (const part of chunk.candidates[0].content.parts) {
      if (!part.text) {
        continue;
      } else if (part.thought) {
        if (!thoughts) {
          console.log("Thoughts summary:");
        }
        console.log(part.text);
        thoughts = thoughts + part.text;
      } else {
        if (!answer) {
          console.log("Answer:");
        }
        console.log(part.text);
        answer = answer + part.text;
      }
    }
  }
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "google.golang.org/genai"
)

const prompt = `
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
`

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  contents := genai.Text(prompt)
  model := "gemini-2.5-pro"

  resp := client.Models.GenerateContentStream(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      IncludeThoughts: true,
    },
  })

  for chunk := range resp {
    for _, part := range chunk.Candidates[0].Content.Parts {
      if len(part.Text) == 0 {
        continue
      }

      if part.Thought {
        fmt.Printf("Thought: %s\n", part.Text)
      } else {
        fmt.Printf("Answer: %s\n", part.Text)
      }
    }
  }
}

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 demande de l'utilisateur. Toutefois, si vous avez des contraintes de latence spécifiques ou si vous avez besoin que le modèle s'engage dans un raisonnement plus approfondi que d'habitude, vous pouvez éventuellement utiliser des paramètres pour contrôler le comportement de réflexion.

Niveaux de réflexion (Gemini 3 Pro)

Le paramètre thinkingLevel, recommandé pour les modèles Gemini 3 et ultérieurs, vous permet de contrôler le comportement de raisonnement. Vous pouvez définir le niveau de réflexion sur "low" ou "high". Si vous ne spécifiez pas de niveau de réflexion, Gemini utilisera le niveau de réflexion dynamique par défaut du modèle, "high", pour Gemini 3 Pro Preview.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingLevel: "low",
      },
    },
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  thinkingLevelVal := "low"

  contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
  model := "gemini-3-pro-preview"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      ThinkingLevel: &thinkingLevelVal,
    },
  })

fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [
    {
      "parts": [
        {
          "text": "Provide a list of 3 famous physicists and their key contributions"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
          "thinkingLevel": "low"
    }
  }
}'

Vous ne pouvez pas désactiver la réflexion pour Gemini 3 Pro. Les modèles de la série Gemini 2.5 ne sont pas compatibles avec thinkingLevel. Utilisez plutôt thinkingBudget.

Budgets de réflexion

Le paramètre thinkingBudget, introduit avec la série Gemini 2.5, indique au modèle le nombre spécifique de jetons de réflexion à utiliser pour le raisonnement.

Vous trouverez ci-dessous les détails de configuration de thinkingBudget pour chaque type de modèle. Vous pouvez désactiver la réflexion en définissant thinkingBudget sur 0. Si vous définissez thinkingBudget sur -1, vous activez la réflexion dynamique. Cela signifie que le modèle ajustera le budget en fonction de la complexité de la demande.

Modèle	Paramètre par défaut (budget de réflexion non défini)	Plage	Désactiver le raisonnement	Activer la pensée dynamique
2.5 Pro	Réflexion dynamique : le modèle décide quand et combien réfléchir	De `128` à `32768`	N/A : impossible de désactiver la réflexion	`thinkingBudget = -1`
2.5 Flash	Réflexion dynamique : le modèle décide quand et combien réfléchir	De `0` à `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
Aperçu de Gemini 2.5 Flash	Réflexion dynamique : le modèle décide quand et combien réfléchir	De `0` à `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
2.5 Flash Lite	Le modèle ne réfléchit pas	De `512` à `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
Aperçu de Gemini 2.5 Flash-Lite	Le modèle ne réfléchit pas	De `512` à `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
Robotics-ER 1.5 (preview)	Réflexion dynamique : le modèle décide quand et combien réfléchir	De `0` à `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
2.5 Flash Live Native Audio Preview (09-2025)	Réflexion dynamique : le modèle décide quand et combien réfléchir	De `0` à `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=1024)
        # Turn off thinking:
        # thinking_config=types.ThinkingConfig(thinking_budget=0)
        # Turn on dynamic thinking:
        # thinking_config=types.ThinkingConfig(thinking_budget=-1)
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingBudget: 1024,
        // Turn off thinking:
        // thinkingBudget: 0
        // Turn on dynamic thinking:
        // thinkingBudget: -1
      },
    },
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  thinkingBudgetVal := int32(1024)

  contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
  model := "gemini-2.5-pro"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      ThinkingBudget: &thinkingBudgetVal,
      // Turn off thinking:
      // ThinkingBudget: int32(0),
      // Turn on dynamic thinking:
      // ThinkingBudget: int32(-1),
    },
  })

fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [
    {
      "parts": [
        {
          "text": "Provide a list of 3 famous physicists and their key contributions"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
          "thinkingBudget": 1024
    }
  }
}'

Selon la requête, le modèle peut dépasser ou sous-utiliser le budget de jetons.

Signatures de pensée

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

Pour permettre de conserver le contexte de réflexion lors d'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 pensée lorsque la réflexion est activée et que la requête inclut l'appel de fonction, en particulier les déclarations de fonction.
Les modèles Gemini 3 peuvent renvoyer des signatures de pensée pour tous les types de parties. Nous vous recommandons de toujours renvoyer toutes les signatures telles que vous les avez reçues, mais c'est obligatoire pour les signatures d'appel de fonction. Pour en savoir plus, consultez la page Signatures de pensée.

Le SDK Google GenAI gère automatiquement le retour des signatures de pensée pour vous. Vous n'avez besoin de gérer manuellement les signatures de pensée que si vous modifiez l'historique des conversations ou si vous utilisez l'API REST.

Voici d'autres limites d'utilisation à prendre en compte avec l'appel de fonction :

Les signatures sont renvoyées par le modèle dans d'autres parties de la réponse, par exemple les appels de fonction ou les parties de texte. Renvoyez l'intégralité de la réponse 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 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 thoughtsTokenCount.

Python

# ...
print("Thoughts tokens:",response.usage_metadata.thoughts_token_count)
print("Output tokens:",response.usage_metadata.candidates_token_count)

JavaScript

// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);

Go

// ...
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println("Thoughts tokens:", string(usageMetadata.thoughts_token_count))
fmt.Println("Output tokens:", string(usageMetadata.candidates_token_count))

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. Par conséquent, la tarification est basée sur les jetons de pensée complets dont le modèle a besoin pour générer un résumé, même si seul le résumé est généré par l'API.

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

Bonnes pratiques

Cette section inclut des conseils pour utiliser efficacement les modèles à raisonnement. Comme toujours, pour obtenir les meilleurs résultats, suivez nos conseils et bonnes pratiques concernant les requêtes.

Débogage et orientation

Examiner le raisonnement : si les modèles de réflexion ne vous donnent pas la réponse attendue, 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 tiré sa conclusion, et utiliser ces informations pour corriger les résultats.
Fournissez des instructions pour le raisonnement : si vous souhaitez obtenir une sortie particulièrement longue, vous pouvez fournir des instructions dans votre requête 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é de la tâche

Tâches simples (la réflexion peut être désactivée) : pour les demandes simples qui ne nécessitent pas de raisonnement complexe, comme la récupération d'informations ou la classification, la réflexion n'est pas nécessaire. Exemples :
- "Où DeepMind a-t-elle été fondée ?"
- "Cet e-mail demande-t-il une réunion ou fournit-il simplement des informations ?"
Tâches moyennes (par défaut/nécessitant une certaine réflexion) : de nombreuses requêtes courantes bénéficient d'un traitement par étapes ou d'une compréhension plus approfondie. Gemini peut utiliser sa capacité de réflexion de manière flexible pour des tâches telles que :
- Fais une analogie entre la photosynthèse et le fait de grandir.
- Indiquer les points communs et les différences entre les voitures électriques et les voitures hybrides
Tâches difficiles (capacité de réflexion maximale) : pour les défis vraiment complexes, comme la résolution de problèmes mathématiques complexes ou de tâches de codage, nous vous recommandons de définir un budget de réflexion élevé. Ces types de tâches exigent que le modèle utilise pleinement ses capacités de raisonnement et de planification, ce qui implique souvent de nombreuses étapes internes avant de fournir une réponse. Exemples :
- Résolvez le problème 1 de l'AIME 2025 : trouvez la somme de toutes les bases entières b > 9 pour lesquelles 17_b est un diviseur de 97_b.
- Écrire du code Python pour une application Web qui visualise des données boursières en temps réel, y compris l'authentification des utilisateurs Rendez-le aussi efficace que possible.

Modèles, outils et fonctionnalités compatibles

Les fonctionnalités de réflexion sont disponibles sur tous les modèles des séries 3 et 2.5. Vous trouverez toutes les capacités des modèles sur la page Présentation des modèles.

Les modèles Thinking fonctionnent avec tous les outils et 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 et leur réponse finale.

Vous trouverez des exemples d'utilisation d'outils avec des modèles de réflexion dans le cookbook Thinking.

Étape suivante

La couverture de la réflexion est disponible dans notre guide de compatibilité avec OpenAI.