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, ce qui les rend très efficaces pour des 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 série 2.5 compatible pour la réflexion. Vous pouvez explorer ces modèles dans AI Studio avant de vous plonger dans l'API:
- Essayer la version preview de Gemini 2.5 Flash dans AI Studio
- Essayez la version Preview de Gemini 2.5 Pro dans AI Studio
Générer du contenu en réfléchissant
Lancer 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:
from google import genai
client = genai.Client(api_key="GOOGLE_API_KEY")
prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example."
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
contents=prompt
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
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-flash-preview-05-20",
contents: prompt,
});
console.log(response.text);
}
main();
// import packages here
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
log.Fatal(err)
}
defer client.Close()
model := client.GenerativeModel("gemini-2.5-flash-preview-05-20")
resp, err := model.GenerateContent(ctx, genai.Text("Explain the concept of Occam's Razor and provide a simple, everyday example."))
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_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ésumer vos pensées (expérimental)
Les résumés de pensées fournissent des insights sur le processus de raisonnement interne du modèle. Cette fonctionnalité peut être utile pour vérifier l'approche du modèle et tenir les utilisateurs informés pendant les tâches plus longues, en particulier lorsqu'elle est combinée au streaming.
Vous pouvez activer les résumés de pensées en définissant includeThoughts
sur true
dans la configuration de votre requête. Vous pouvez ensuite accéder au récapitulatif en itérant sur le parts
du paramètre response
et en vérifiant le booléen thought
.
Voici un exemple illustrant comment activer et récupérer des résumés de pensées sans streaming, ce qui renvoie un seul résumé de pensée final avec la réponse:
from google import genai
from google.genai import types
client = genai.Client(api_key="GOOGLE_API_KEY")
prompt = "What is the sum of the first 50 prime numbers?"
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
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()
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-05-20",
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();
package main
import (
"context"
"fmt"
"google.golang.org/genai"
"os"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GOOGLE_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
contents := genai.Text("What is the sum of the first 50 prime numbers?")
model := "gemini-2.5-flash-preview-05-20"
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 pensée en streaming, qui renvoie des récapitulatifs incrémentiels et continus pendant la génération:
from google import genai
from google.genai import types
client = genai.Client(api_key="GOOGLE_API_KEY")
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-flash-preview-05-20",
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("Thoughts summary:")
print(part.text)
answer += part.text
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
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-flash-preview-05-20",
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();
Budgets de réflexion
Le paramètre thinkingBudget
vous permet d'indiquer au modèle le nombre de jetons de réflexion qu'il peut 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 s'attaquer à des tâches plus complexes.
Si vous ne définissez pas thinkingBudget
, le modèle ajustera dynamiquement le budget en fonction de la complexité de la requête.
thinkingBudget
doit être un nombre entier compris entre0
et24576
.- Si vous définissez le budget de réflexion sur
0
, la réflexion est désactivée. - En fonction de l'invite, le modèle peut dépasser ou sous-dépasser le budget de jetons.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
contents="Provide a list of 3 famous physicists and their key contributions",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_budget=1024)
),
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-05-20",
contents: "Provide a list of 3 famous physicists and their key contributions",
config: {
thinkingConfig: {
thinkingBudget: 1024,
},
},
});
console.log(response.text);
}
main();
package main
import (
"context"
"fmt"
"google.golang.org/genai"
"os"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GOOGLE_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
thinkingBudgetVal := int32(1024)
contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
model := "gemini-2.5-flash-preview-05-20"
resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
ThinkingConfig: &genai.ThinkingConfig{
ThinkingBudget: &thinkingBudgetVal,
},
})
fmt.Println(resp.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_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
}
}
}'
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
.
# ...
print("Thoughts tokens:",response.usage_metadata.thoughts_token_count)
print("Output tokens:",response.usage_metadata.candidates_token_count)
// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);
// ...
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 de pensée 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 fournir des insights sur le processus de réflexion. Par conséquent, le prix est basé sur les jetons de pensée complets que le modèle doit générer pour créer 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 Compter les jetons.
Modèles compatibles
Vous trouverez toutes les fonctionnalités du modèle sur la page Présentation du modèle.
Modèle | Résumés de la réflexion | Budget de réflexion |
---|---|---|
Gemini 2.5 Flash | ✔️ | ✔️ |
Gemini 2.5 Pro | ✔️ | X |
Bonnes pratiques
Cette section contient des conseils pour utiliser efficacement les modèles de réflexion. Comme toujours, suivez nos conseils et bonnes pratiques concernant les requêtes pour obtenir les meilleurs résultats.
Débogage et orientation
Examiner le raisonnement: lorsque vous n'obtenez pas la réponse attendue des modèles de réflexion, il peut être utile d'analyser attentivement le processus de raisonnement de Gemini. Vous pouvez voir comment il a décomposé la tâche et abouti à sa conclusion, et utiliser ces informations pour corriger les résultats.
Fournir des conseils pour le raisonnement: si vous souhaitez obtenir une sortie particulièrement longue, vous pouvez fournir des conseils 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é des tâches
- Tâches faciles (la réflexion peut être désactivée) : pour les requêtes simples où un raisonnement complexe n'est pas nécessaire, 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-il été fondé ?"
- "Cet e-mail demande-t-il une réunion ou fournit-il simplement des informations ?"
- Tâches moyennes (par défaut/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 de manière flexible la capacité de réflexion pour des tâches telles que :
- Faites une analogie entre la photosynthèse et la croissance.
- Comparez les voitures électriques et les voitures hybrides.
- Tâches difficiles (capacité de réflexion maximale) : pour les défis vraiment complexes, le modèle doit mobiliser toutes ses capacités de raisonnement et de planification, ce qui implique souvent de nombreuses é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 17b est un diviseur de 97b.
- É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 Faites-le aussi efficacement que possible.
Penser avec des outils et des fonctionnalités
Les modèles de réflexion 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 à 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 au-delà de ses données d'entraînement. Cela est utile pour les questions concernant des événements récents ou des sujets très spécifiques.
L'outil d'exécution du 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 gérés par algorithme. 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 du code JSON. Cela est particulièrement utile pour intégrer la sortie du modèle dans les applications.
L'appel de fonction connecte le modèle de réflexion à des outils et des API externes, afin qu'il puisse déterminer quand appeler la bonne fonction et quels paramètres fournir.
Vous pouvez consulter des exemples d'utilisation d'outils avec des modèles de pensée dans le livre de recettes de la pensée.
Étape suivante
Pour découvrir des exemples plus détaillés, par exemple:
- Utiliser des outils avec réflexion
- Streaming avec réflexion
- Ajuster le budget de réflexion pour obtenir différents résultats
Pour en savoir plus, consultez notre livre de recettes de réflexion.
La couverture de la pensée est désormais disponible dans notre guide de compatibilité avec OpenAI.
Pour en savoir plus sur le preview de Gemini 2.5 Pro et la réflexion Gemini Flash 2.5, consultez la page du modèle.