Pensamiento de Gemini

Los modelos de las series Gemini 3 y 2.5 usan un "proceso de pensamiento" interno que mejora significativamente sus capacidades de razonamiento y planificación de varios pasos, lo que los hace muy eficaces para tareas complejas, como la programación, las matemáticas avanzadas y el análisis de datos.

En esta guía, se muestra cómo trabajar con las capacidades de pensamiento de Gemini mediante la API de Gemini.

Genera contenido con razonamiento

Iniciar una solicitud con un modelo de razonamiento es similar a cualquier otra solicitud de generación de contenido. La diferencia clave radica en especificar uno de los modelos con compatibilidad de razonamiento en el campo model, como se muestra en el siguiente ejemplo de generación de texto:

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-3.5-flash",
    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-3.5-flash",
    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-3.5-flash"

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

  fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash: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."
         }
       ]
     }
   ]
 }'
 ```

Resúmenes de razonamiento

Los resúmenes de razonamiento son versiones resumidas de los razonamientos sin procesar del modelo y ofrecen información sobre el proceso de razonamiento interno del modelo. Ten en cuenta que los niveles y presupuestos de razonamiento se aplican a los razonamientos sin procesar del modelo y no a los resúmenes de razonamiento.

Para habilitar los resúmenes de razonamiento, configura includeThoughts como true en la configuración de la solicitud. Luego, puedes acceder al resumen iterando a través de los parts del parámetro response y verificando el booleano thought.

A continuación, se muestra un ejemplo que demuestra cómo habilitar y recuperar resúmenes de razonamiento sin transmisión, que muestra un único resumen de razonamiento final con la respuesta:

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-3.5-flash",
  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-3.5-flash",
    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-3.5-flash"
  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)
      }
    }
  }
}

A continuación, se muestra un ejemplo en el que se usa el razonamiento con transmisión, que muestra resúmenes incrementales y continuos durante la generación:

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-3.5-flash",
    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-3.5-flash",
    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-3.5-flash"

  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)
      }
    }
  }
}

Controla el razonamiento

Los modelos de Gemini participan en el razonamiento dinámico de forma predeterminada, y ajustan automáticamente la cantidad de esfuerzo de razonamiento según la complejidad de la solicitud del usuario. Sin embargo, si tienes restricciones de latencia específicas o necesitas que el modelo participe en un razonamiento más profundo de lo habitual, puedes usar parámetros de forma opcional para controlar el comportamiento de razonamiento.

Niveles de razonamiento (Gemini 3)

El parámetro thinkingLevel, recomendado para los modelos de Gemini 3 y versiones posteriores, te permite controlar el comportamiento de razonamiento.

En la siguiente tabla, se detallan los parámetros de configuración de thinkingLevel para cada tipo de modelo:

Nivel de razonamiento Gemini 3.5 Flash Gemini 3.1 Pro Gemini 3.1 Flash-Lite Imagen de Gemini 3.1 Flash-Lite Gemini 3 Flash Descripción
minimal Admitido No admitido Admitido (predeterminado) Admitido (predeterminado) Admitido Coincide con el parámetro de configuración "sin razonamiento" para la mayoría de las consultas. Ten en cuenta que minimal no garantiza que el razonamiento esté desactivado. El modelo puede razonar de forma muy mínima para tareas complejas.
low Admitido Admitido Admitido No se permite Admitido Minimiza la latencia y el costo.
medium Admitido (predeterminado) Admitido Admitido No admitido Admitido Razonamiento equilibrado para la mayoría de las tareas.
high Admitido (dinámico) Admitido (predeterminado, dinámico) Admitido (dinámico) Admitido (dinámico) Admitido (predeterminado, dinámico) Maximiza la profundidad del razonamiento. Es posible que el modelo tarde mucho más en alcanzar un primer token de salida (sin razonamiento), pero el resultado se razonará con más cuidado.

En el siguiente ejemplo, se muestra cómo establecer el nivel de razonamiento.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    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, ThinkingLevel } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingLevel: 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.5-flash"
  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.5-flash: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"
    }
  }
}'

No puedes inhabilitar el razonamiento para Gemini 3.1 Pro. Gemini 3 Flash y Flash-Lite tampoco admiten el razonamiento completo. Si no especificas un nivel de razonamiento, Gemini usará el nivel de razonamiento predeterminado de los modelos de Gemini 3 (p.ej., "high" para Gemini 3.1 Pro y "medium" para Gemini 3.5 Flash).

Los modelos de la serie Gemini 2.5 no admiten thinkingLevel; usa thinkingBudget en su lugar.

Presupuestos de razonamiento

El parámetro thinkingBudget, que se introdujo con la serie Gemini 2.5, guía al modelo sobre la cantidad específica de tokens de razonamiento que se deben usar para el razonamiento.

A continuación, se muestran los detalles de configuración de thinkingBudget para cada tipo de modelo. Para inhabilitar el razonamiento, configura thinkingBudget como 0. Si configuras el thinkingBudget como -1, se activa el razonamiento dinámico, lo que significa que el modelo ajustará el presupuesto según la complejidad de la solicitud.

Modelo Parámetro de configuración predeterminado
(No se establece el presupuesto de razonamiento)		 Rango Inhabilitar el razonamiento Activar el razonamiento dinámico
2.5 Pro Razonamiento dinámico De 128 a 32768 N/A: No se puede inhabilitar el razonamiento thinkingBudget = -1 (predeterminado)
2.5 Flash Razonamiento dinámico De 0 a 24576 thinkingBudget = 0 thinkingBudget = -1 (predeterminado)
Versión preliminar de 2.5 Flash Razonamiento dinámico De 0 a 24576 thinkingBudget = 0 thinkingBudget = -1 (predeterminado)
2.5 Flash Lite El modelo no razona De 512 a 24576 thinkingBudget = 0 thinkingBudget = -1
Versión preliminar de 2.5 Flash Lite El modelo no razona De 512 a 24576 thinkingBudget = 0 thinkingBudget = -1
Versión preliminar de Robotics-ER 1.6 Razonamiento dinámico De 0 a 24576 thinkingBudget = 0 thinkingBudget = -1 (predeterminado)
Versión preliminar de audio nativo en vivo de 2.5 Flash (09-2025) Razonamiento dinámico De 0 a 24576 thinkingBudget = 0 thinkingBudget = -1 (predeterminado)

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    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-flash",
    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-flash"
  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-flash: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
    }
  }
}'

Según la instrucción, el modelo podría desbordar o subdesbordar el presupuesto de tokens.

Firmas de razonamiento

La API de Gemini no tiene estado, por lo que el modelo trata cada solicitud a la API de forma independiente y no tiene acceso al contexto de razonamiento de los turnos anteriores en las interacciones de varios turnos.

Para permitir el mantenimiento del contexto de razonamiento en las interacciones de varios turnos, Gemini muestra firmas de razonamiento, que son representaciones encriptadas del proceso de razonamiento interno del modelo.

  • Los modelos de Gemini 2.5 muestran firmas de razonamiento cuando el razonamiento está habilitado y la solicitud incluye llamadas a funciones, específicamente declaraciones de funciones.
  • Los modelos de Gemini 3 pueden mostrar firmas de razonamiento para todos los tipos de partes. Te recomendamos que siempre pases todas las firmas como se recibieron, pero es obligatorio para las firmas de llamadas a funciones. Lee la página Firmas de razonamiento para obtener más información.

Otras limitaciones de uso que se deben tener en cuenta con las llamadas a funciones incluyen las siguientes:

  • Las firmas se muestran desde el modelo dentro de otras partes de la respuesta, por ejemplo, llamadas a funciones o partes de texto. Devuelve toda la respuesta con todas las partes al modelo en los turnos posteriores.
  • No concatenes partes con firmas.
  • No combines una parte con una firma con otra parte sin una firma.

Precios

Cuando el razonamiento está activado, el precio de la respuesta es la suma de los tokens de salida y los tokens de razonamiento. Puedes obtener la cantidad total de tokens de razonamiento generados desde el campo 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

// ...
fmt.Println("Thoughts tokens:", response.UsageMetadata.ThoughtsTokenCount)
fmt.Println("Output tokens:", response.UsageMetadata.CandidatesTokenCount)

Los modelos de razonamiento generan razonamientos completos para mejorar la calidad de la respuesta final y, luego, muestran resúmenes para proporcionar información sobre el proceso de razonamiento. Por lo tanto, el precio se basa en los tokens de razonamiento completos que el modelo necesita generar para crear un resumen, a pesar de que solo se muestra el resumen de la API.

Puedes obtener más información sobre los tokens en la guía Conteo de tokens.

Prácticas recomendadas

En esta sección, se incluye una guía para usar los modelos de razonamiento de manera eficiente. Como siempre, seguir nuestra guía de instrucciones y las prácticas recomendadas te dará los mejores resultados.

Depuración y dirección

  • Revisa el razonamiento: Cuando no obtienes la respuesta esperada de los modelos de razonamiento, puede ser útil analizar cuidadosamente los resúmenes de razonamiento de Gemini. Puedes ver cómo desglosó la tarea y llegó a su conclusión, y usar esa información para corregir los resultados correctos.

  • Proporciona orientación en el razonamiento: Si esperas un resultado particularmente largo, es posible que desees proporcionar orientación en tu instrucción para restringir la cantidad de razonamiento que usa el modelo. Esto te permite reservar más de la salida de tokens para tu respuesta.

Complejidad de la tarea

  • Tareas fáciles (el razonamiento podría estar desactivado): Para solicitudes directas en las que no se requiere un razonamiento complejo, como la recuperación o clasificación de hechos, no se requiere razonamiento. Los siguientes son algunos ejemplos:
    • "¿Dónde se fundó DeepMind?"
    • "¿Este correo electrónico solicita una reunión o solo proporciona información?"
  • Tareas medianas (predeterminadas/algunos razonamientos): Muchas solicitudes comunes se benefician de un grado de procesamiento paso a paso o de una comprensión más profunda. Gemini puede usar de forma flexible la capacidad de razonamiento para tareas como las siguientes:
    • Analogizar la fotosíntesis y el crecimiento
    • Comparar y contrastar autos eléctricos y autos híbridos
  • Tareas difíciles (capacidad máxima de razonamiento): Para desafíos realmente complejos, como resolver problemas matemáticos complejos o tareas de programación, te recomendamos que establezcas un presupuesto de razonamiento alto. Estos tipos de tareas requieren que el modelo active sus capacidades completas de razonamiento y planificación, que a menudo implican muchos pasos internos antes de proporcionar una respuesta. Los siguientes son algunos ejemplos:
    • Resuelve el problema 1 en AIME 2025: Encuentra la suma de todas las bases enteras b > 9 para las que 17b es un divisor de 97b.
    • Escribe código de Python para una aplicación web que visualice datos del mercado de valores en tiempo real, incluida la autenticación de usuarios. Haz que sea lo más eficiente posible.

Modelos, herramientas y capacidades compatibles

Las funciones de razonamiento son compatibles con todos los modelos de las series 3 y 2.5. Puedes encontrar todas las capacidades del modelo en la página de descripción general del modelo.

Los modelos de razonamiento funcionan con todas las herramientas y capacidades de Gemini. Esto permite que los modelos interactúen con sistemas externos, ejecuten código o accedan a información en tiempo real, y que incorporen los resultados en su razonamiento y respuesta final.

Puedes probar ejemplos de uso de herramientas con modelos de razonamiento en el [recetario de razonamiento][Colab].

Próximos pasos

  • La cobertura de razonamiento está disponible en nuestra guía de compatibilidad con OpenAI.

[Colab]: https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_thinking.ipynb