Veo 3 est désormais disponible dans l'API Gemini. En savoir plus

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

Gemini avec réflexion

Les modèles de la série Gemini 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.

Avant de commencer

Assurez-vous d'utiliser un modèle de la série 2.5 compatible pour la réflexion. Il peut être utile d'explorer ces modèles dans AI Studio avant de vous plonger dans l'API :

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."
         }
       ]
     }
   ]
 }'
 ```

Budgets de réflexion

Le paramètre thinkingBudget indique au modèle le nombre de jetons de réflexion à utiliser pour générer une réponse. Un nombre de jetons plus élevé permet généralement un raisonnement plus détaillé, ce qui peut être utile pour aborder des tâches plus complexes. Si la latence est plus importante, utilisez un budget inférieur ou désactivez 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 requête.

thinkingBudget n'est compatible qu'avec Gemini 2.5 Flash, 2.5 Pro et 2.5 Flash-Lite. Selon la requête, le modèle peut dépasser ou ne pas atteindre le budget de jetons.

Vous trouverez ci-dessous les détails de configuration de thinkingBudget pour chaque type de modèle.

Modèle	Paramètre par défaut (budget de réflexion non défini)	Plage	Désactiver la réflexion	Activer la pensée dynamique
2.5 Pro	Pensée 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	Pensée 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 pense pas	De `512` à `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
          # Thinking off:
          # "thinkingBudget": 0
          # Turn on dynamic thinking:
          # "thinkingBudget": -1
    }
  }
}'

Résumés des réflexions

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 budgets de réflexion s'appliquent aux pensées brutes du modèle, et non aux résumés de pensées.

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 utilisant la pensée 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)
      }
    }
  }
}

Signatures de pensée

Étant donné que les appels standards de génération de texte et de contenu de l'API Gemini sont sans état, le modèle n'a pas accès au contexte de réflexion des tours précédents lorsqu'il est utilisé pour réfléchir dans des interactions multitours (comme le chat).

Vous pouvez conserver le contexte de la réflexion à l'aide de signatures de réflexion, qui sont des représentations chiffrées du processus de réflexion interne du modèle. Le modèle renvoie des signatures de réflexion dans l'objet de réponse lorsque la réflexion et l'appel de fonction sont activés. Pour que le modèle conserve le contexte sur plusieurs tours de conversation, vous devez lui fournir les signatures de pensée dans les requêtes suivantes.

Vous recevrez des signatures de pensée lorsque :

La réflexion est activée et des pensées sont générées.
La requête inclut des déclarations de fonctions.

Vous trouverez un exemple de réflexion avec des appels de fonction sur la page Appel de fonction.

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 la réponse complète avec toutes les parties au modèle lors des tours suivants.
Ne concaténez pas les parties avec les 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. Les tarifs sont donc basés 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.

Modèles compatibles

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

Bonnes pratiques

Cette section vous donne quelques 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 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 requêtes simples qui ne nécessitent pas de raisonnement complexe, comme la récupération de faits ou la classification, la réflexion n'est pas nécessaire. Voici quelques 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 ou de tâches de codage complexes, 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, souvent en plusieurs étapes internes avant de fournir une réponse. Voici quelques 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.

Réfléchir avec des outils et des fonctionnalités

Les modèles de réflexion 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 et leur réponse finale.

L'outil de recherche permet au modèle d'interroger la recherche Google pour trouver des informations à jour ou des informations qui vont au-delà de ses données d'entraînement. Cela est utile pour les questions sur des événements récents ou des sujets très spécifiques.
L'outil d'exécution de code permet au modèle de générer et d'exécuter du code Python pour effectuer des calculs, manipuler des données ou résoudre des problèmes qui sont mieux traités de manière algorithmique. Le modèle reçoit la sortie du code et peut l'utiliser dans sa réponse.
Avec la sortie structurée, vous pouvez contraindre Gemini à répondre avec JSON. Cela est particulièrement utile pour intégrer la sortie du modèle dans des applications.
L'appel de fonction connecte le modèle de réflexion à des outils et API externes. Il peut ainsi déterminer quand appeler la bonne fonction et quels paramètres fournir.
Le contexte d'URL fournit au modèle des URL comme contexte supplémentaire pour votre requête. Le modèle peut ensuite récupérer le contenu des URL et l'utiliser pour informer et façonner sa réponse.

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

Étape suivante

Pour parcourir des exemples plus détaillés, comme :
- Utiliser des outils avec la réflexion
- Streaming avec réflexion
- Ajuster le budget de réflexion pour différents résultats
Pour en savoir plus, consultez notre livre de recettes sur la pensée.
La couverture de la pensée est désormais disponible dans notre guide de compatibilité avec OpenAI.
Pour en savoir plus sur Gemini 2.5 Pro, Gemini Flash 2.5 et Gemini 2.5 Flash-Lite, consultez la page du modèle.