Gemini está pensando

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

Cuando usas un modelo de razonamiento, Gemini razona internamente antes de responder. La API de Interactions muestra este razonamiento a través de pasos thought, que son pasos dedicados que aparecen cronológicamente junto con las llamadas a funciones, las entradas del usuario o los resultados del modelo en el array steps.

Cada paso de pensamiento contiene dos campos:

Campo Obligatorio Descripción
signature ✅ Sí Es una representación encriptada del estado de razonamiento interno del modelo. Siempre está presente, incluso cuando el modelo realiza un razonamiento mínimo.
summary ❌ No Es un array de contenido (texto o imágenes) que resume el razonamiento. Puede estar vacío según la configuración de thinking_summaries, si el modelo realizó suficiente razonamiento o el tipo de contenido (por ejemplo, es posible que las latencias de imágenes no tengan resúmenes de texto).

Interacciones con el pensamiento

Iniciar una interacción con un modelo de pensamiento es similar a cualquier otra solicitud de interacción. Especifica uno de los modelos con asistencia para el pensamiento en el campo model:

Python

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)

JavaScript

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

REST

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

Resúmenes de pensamientos

Los resúmenes de pensamiento brindan información sobre el proceso de razonamiento interno del modelo. De forma predeterminada, solo se devuelve el resultado final. Puedes habilitar los resúmenes de pensamientos con thinking_summaries:

Python

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:")
        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()

JavaScript

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:");
        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);
            }
        }
    }
}

REST

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"
    }
  }'

En los siguientes casos, un bloque de pensamiento puede contener solo una firma sin resumen:

  • Solicitudes simples en las que el modelo no razonó lo suficiente para generar un resumen
  • thinking_summaries: "none", donde los resúmenes están inhabilitados de forma explícita
  • Es posible que algunos tipos de contenido de pensamiento, como las imágenes, no tengan resúmenes de texto.

Tu código siempre debe controlar los bloques de pensamiento en los que summary está vacío o ausente.

Transmisión con pensamiento

Usa la transmisión para recibir resúmenes de pensamientos incrementales durante la generación. Los bloques de pensamiento se entregan con eventos enviados por el servidor (SSE) con dos tipos de delta distintos:

Tipo de delta Contiene Cuándo se envió
thought_summary Contenido de resumen de texto o imagen Uno o más deltas con un resumen incremental
thought_signature La firma criptográfica el último delta antes de step.stop

Python

from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought_summary":
            if not thoughts:
                print("Thinking...")
            summary_text = event.delta.content.get('text', '') if hasattr(event.delta, 'content') else getattr(event.delta, 'text', '')
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text

JavaScript

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

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

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

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: prompt,
    generation_config: {
        thinking_summaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.event_type === "step.delta") {
        if (event.delta.type === "thought_summary") {
            if (!thoughts) console.log("Thinking...");
            const text = event.delta.content?.text || "";
            process.stdout.write(`[Thought] ${text}`);
            thoughts += text;
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}

REST

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' \
  --no-buffer \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue. Alice does not live in the red house. Bob does not live in the green house. Carol does not live in the red or green house. Which house does each person live in?",
    "generation_config": {
      "thinking_summaries": "auto"
    },
    "stream": true
  }'

La respuesta de transmisión usa eventos enviados por el servidor (SSE) y se compone de pasos y eventos. Consulta el siguiente ejemplo.

event: interaction.created
data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3-flash-preview"},"event_type":"interaction.created"}

event: step.start
data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"EpoGCpcGAXLI2nx/...","type":"thought_signature"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"v1_xxx","status":"completed","usage":{"total_tokens":530,"total_input_tokens":62,"total_output_tokens":171,"total_thought_tokens":297}},"event_type":"interaction.completed"}

event: done
data: [DONE]

Control del pensamiento

De forma predeterminada, los modelos de Gemini participan en el pensamiento dinámico, ya que ajustan automáticamente la cantidad de esfuerzo de razonamiento según la complejidad de la solicitud. Puedes controlar este comportamiento con el parámetro thinking_level.

Modelo Pensamiento predeterminado Niveles admitidos
gemini-3.1-pro-preview Encendido (alto) baja, media, alta
gemini-3-flash-preview Encendido (alto) mínima, baja, media, alta
gemini-3-pro-preview Encendido (alto) baja, alta
gemini-2.5-pro Activado baja, media, alta
gemini-2.5-flash Activado baja, media, alta
gemini-2.5-flash-lite Desactivado baja, media, alta

Python

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)

JavaScript

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

REST

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"
    }
  }'

Firmas de pensamiento

Las firmas de pensamiento son representaciones encriptadas del razonamiento interno del modelo. Deben mantener la continuidad del razonamiento en las interacciones de varios turnos.

La API de Interactions simplifica el manejo de las firmas de pensamiento mucho más que la API de generateContent.

De forma predeterminada, cuando usas la API de Interactions en modo con estado (configurando store: true y pasando previous_interaction_id en los turnos posteriores), el servidor administra automáticamente el estado de la conversación, incluidos todos los bloques de pensamiento y las firmas. En este modo, no es necesario que hagas nada con respecto a las firmas. Se controlan por completo en el servidor.

Modo sin estado

Si administras el estado de la conversación por tu cuenta (modo sin estado) y pasas el historial completo de entradas y salidas en cada solicitud, haz lo siguiente:

  • DEBES volver a enviar todos los bloques thought exactamente como los recibiste del modelo.
  • NO debes quitar ni modificar los bloques de pensamiento del historial, ya que contienen las firmas necesarias para que el modelo continúe su razonamiento.
  • Cuando cambies de modelo dentro de una sesión, debes volver a enviar los bloques de pensamiento del modelo anterior. El backend administra la compatibilidad.

Precios

Cuando se activa el razonamiento, 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 pensamiento generados en el campo total_thought_tokens.

Python

# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// ...
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

Los modelos de pensamiento generan pensamientos completos para mejorar la calidad de la respuesta final y, luego, generan resúmenes para proporcionar información sobre el proceso de pensamiento. El precio se basa en los tokens de pensamiento completos que el modelo necesita generar, a pesar de que solo el resumen se genera desde la API.

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

Prácticas recomendadas

Sigue estos lineamientos para usar los modelos de pensamiento de manera eficiente.

  • Revisar el razonamiento: Analiza los resúmenes de pensamiento para comprender las fallas y mejorar las instrucciones.
  • Control thinking budget: Solicita al modelo que piense menos para generar respuestas extensas y ahorrar tokens.
  • Tareas simples: Requieren un mínimo de reflexión para recuperar o clasificar hechos (p.ej., "¿Dónde se fundó DeepMind?").
  • Tareas moderadas: Usa el pensamiento predeterminado para comparar conceptos o razonamientos creativos (p.ej., compara autos eléctricos e híbridos).
  • Tareas complejas: Usa el máximo nivel de pensamiento para la programación avanzada, las matemáticas o la planificación de varios pasos (p.ej., resolver problemas matemáticos de AIME).

¿Qué sigue?