Migra a los modelos de Gemini más recientes

En esta guía, se explica cómo actualizar tu aplicación a la versión más reciente de Gemini. En esta guía, se supone que tu aplicación ya usa una versión anterior de Gemini. Para aprender a comenzar a usar Gemini en Gemini Enterprise Agent Platform, consulta Comienza a usar Gemini Enterprise Agent Platform.

En esta guía, no se explica cómo cambiar tu aplicación del SDK de Vertex AI al SDK de IA generativa de Google actual. Para obtener esa información, consulta nuestra guía de migración del SDK de Vertex AI.

¿Qué cambios debo esperar?

Para actualizar la mayoría de las aplicaciones de IA generativa a la versión más reciente de Gemini, se requieren pocos cambios en el código o las instrucciones. Sin embargo, algunas aplicaciones pueden requerir ajustes de instrucciones. Es difícil predecir estos cambios sin antes probar tus instrucciones con la nueva versión. Se recomienda realizar pruebas exhaustivas antes de migrar por completo. Para obtener sugerencias sobre cómo crear instrucciones eficaces, consulta nuestra guía de estrategia de instrucciones. Usa nuestra lista de tareas para verificar el estado de las instrucciones para encontrar y solucionar problemas relacionados con ellas.

Actualización del informe de recuento de tokens

Es posible que observes un aumento esperado en los recuentos de tokens informados, ya que nuestra infraestructura actualizada ahora captura con precisión todos los componentes de la solicitud, incluidos los metadatos complejos, como los esquemas de respuesta y las llamadas a funciones, que antes el sistema heredado no registraba por completo.

Solo debes realizar cambios importantes en el código para ciertos cambios que interrumpen la compatibilidad o para usar nuevas funciones de Gemini.

¿A qué modelo de Gemini debería migrar?

El modelo de Gemini que uses dependerá de las necesidades de tu aplicación:

Función 2.5 Pro 2.5 Flash 2.5 Flash-Lite 3.1 Pro 3.5 Flash-Lite 3.5 Flash 3.6 Flash 3.7 Flash 3.8 Flash
Etapa de lanzamiento DG DG DG Vista previa DG DG DG DG DG
Modalidades de entrada
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Texto, Imagen, Audio, Video
Modalidades de salida
Texto
Texto
Texto
Texto
Texto
Texto
Texto
Texto
Texto
Ventana de contexto, límite total de tokens 1,048,576 1,048,576 1,048,576 1,048,576 1,048,576 1,048,576 1,048,576 1,048,576 1,048,576
Longitud del contexto de salida 65,536 65,536 65,536 65,536 65,536 65,536 65,536 65,536 65,536
Grounding with Google Search
Llamada a función
Ejecución de código
Almacenamiento en caché de contexto implícito
Almacenamiento en caché de contexto explícito
Inferencia por lotes
API de Gemini Live
Ajuste
Latencia
Fecha de retiro 20 de octubre de 2026 20 de octubre de 2026 20 de octubre de 2026 21 de julio de 2027 o posterior 19 de mayo de 2027 o más adelante 19 de noviembre de 2026 28 de enero de 2027

Antes de comenzar la migración

Antes de comenzar el proceso de migración, debes tener en cuenta lo siguiente:

Aprobaciones de InfoSec, administración y reglamentación

Obtén la aprobación de tus equipos de seguridad de la información (InfoSec), riesgo y cumplimiento con anticipación. Abarca todas las reglas específicas de riesgo y cumplimiento, en especial en industrias reguladas, como la atención médica y las finanzas.

Disponibilidad de ubicación

Los modelos de Google y de socios, y las funciones potenciadas por IA generativa en Gemini Enterprise Agent Platform, están disponibles a través de extremos regionales específicos y un extremo global. Los endpoints globales abarcan todo el mundo y ofrecen una mejor disponibilidad y confiabilidad en comparación con las regiones individuales.

La disponibilidad de los extremos regionales varía según el modelo. Para obtener detalles sobre cada modelo, consulta nuestra guía de ubicaciones.

Diferencias de precios basadas en la modalidad y la asignación de token

Los precios varían según el modelo de Gemini. En nuestra página de precios, se indican los costos de todas las modalidades (texto, código, imágenes, voz, etc.) por modelo.

Compra o cambia pedidos de capacidad de procesamiento aprovisionada

Si es necesario, compra más capacidad de procesamiento aprovisionada o cambia los pedidos de capacidad de procesamiento aprovisionada existentes.

Ajuste supervisado

Los modelos de Gemini más recientes ofrecen una mejor calidad de los resultados. Esto puede significar que tu aplicación ya no necesita un modelo ajustado. Si tu aplicación usa el ajuste supervisado con un modelo de Gemini más antiguo, primero prueba tu aplicación con el modelo más reciente sin ajuste y evalúa los resultados.

Si eliges usar el ajuste supervisado, no podrás transferir tu modelo ajustado existente desde versiones anteriores de Gemini. Debes ejecutar un nuevo trabajo de ajuste para la nueva versión de Gemini.

Cuando ajustes un modelo de Gemini nuevo, comienza con la configuración de ajuste predeterminada. No vuelvas a usar los valores de hiperparámetros de las versiones anteriores de Gemini, ya que el servicio de ajuste está optimizado para las versiones más recientes. Es poco probable que reutilizar la configuración anterior proporcione resultados óptimos.

Pruebas de regresión

Cuando actualices a la versión más reciente de Gemini, necesitarás tres tipos principales de pruebas de regresión:

  1. Pruebas de regresión de código: Son pruebas de regresión desde una perspectiva de ingeniería de software y operaciones de desarrolladores (DevOps). Este tipo de pruebas de regresión siempre es obligatorio.

  2. Pruebas de regresión del rendimiento del modelo: Son pruebas de regresión desde una perspectiva de ciencia de datos o aprendizaje automático. Esto significa garantizar que la nueva versión del modelo de Gemini proporcione resultados que, al menos, mantengan el mismo nivel de calidad que la versión anterior.

    Las pruebas de regresión del rendimiento del modelo son evaluaciones que se realizan cuando cambia un sistema o su modelo subyacente. Estas incluyen las siguientes:

    • Pruebas de rendimiento sin conexión: Son pruebas que confirman la calidad de los resultados del modelo en un entorno de experimentación dedicado en función de varias métricas de calidad de los resultados del modelo.
    • Pruebas de rendimiento del modelo en línea: Pruebas que confirman la calidad de los resultados del modelo en una implementación en línea activa según los comentarios implícitos o explícitos de los usuarios.
  3. Pruebas de carga: Estas pruebas verifican qué tan bien la aplicación controla muchas solicitudes a la vez. Las pruebas de carga son obligatorias para las aplicaciones que usan capacidad de procesamiento aprovisionada.

Cómo migrar a la versión más reciente

En las siguientes secciones, se describen los pasos para migrar a la versión más reciente de Gemini. Para obtener resultados óptimos, completa estos pasos en orden.

1. Documentar los requisitos de evaluación y prueba del modelo

  1. Prepárate para repetir las evaluaciones pertinentes que realizaste cuando creaste tu aplicación por primera vez, además de las evaluaciones que se realizaron desde entonces.
  2. Si tus evaluaciones actuales no abarcan ni miden por completo todas las tareas que realiza tu aplicación, diseña y prepara más evaluaciones. Puedes usar nuestra guía de evaluación y nuestras recetas de evaluación para comenzar.
  3. Si tu aplicación involucra RAG, uso de herramientas, Agentic Workflows complejos o encadenamiento de instrucciones, asegúrate de que tus datos de evaluación existentes permitan evaluar cada componente de forma independiente. Si no es así, recopila ejemplos de entrada y salida para cada componente.
  4. Si tu aplicación es fundamental o forma parte de un sistema en tiempo real más grande orientado al usuario, incluye la evaluación en línea.

2. Realiza actualizaciones de código y ejecuta pruebas

Para actualizar tu código, debes realizar tres cambios principales:

En las siguientes secciones, se analizan estos cambios con más detalle.

Actualiza al SDK de IA generativa de Google

Si tu aplicación de Gemini 1.x usa el SDK de Vertex AI, cambia al SDK de IA generativa de Google. Consulta nuestra guía de migración del SDK de Vertex AI para obtener detalles, incluidos ejemplos de código para realizar llamadas similares con el SDK de IA generativa de Google. Las versiones del SDK de Vertex AI posteriores a junio de 2026 no admitirán Gemini, y las nuevas funciones de Gemini solo estarán disponibles en el SDK de IA generativa de Google.

Te recomendamos que actualices a la versión 2.0.0 o posterior del SDK de google-genai para aprovechar todas las funciones nuevas de Gemini 3.5 Flash y los modelos posteriores.

Si es la primera vez que usas el SDK de IA generativa de Google, consulta el notebook Comienza a usar la IA generativa de Google con el SDK de IA generativa de Google.

Cómo cambiar tus llamadas de Gemini

Actualiza tu código de predicción para usar uno de los modelos de Gemini más recientes. Como mínimo, esto significa cambiar el nombre del extremo del modelo.

Los cambios exactos en el código variarán según cómo hayas compilado tu aplicación, en especial, si usaste el SDK de IA generativa de Google o el SDK de Vertex AI.

Después de realizar cambios en el código, ejecuta pruebas de regresión de código y otras pruebas de software para asegurarte de que el código funcione como se espera. En este paso, se verifica si el código funciona, pero no la calidad de las respuestas del modelo.

Cómo corregir cambios de código que generan errores

  • Recuperación dinámica: Cambia para usar la Fundamentación con la Búsqueda de Google. Esta función requiere el SDK de IA generativa de Google y no es compatible con el SDK de Vertex AI.
  • Filtros de contenido: Ten en cuenta la configuración predeterminada de los filtros de contenido. Cambia tu código si se basa en un valor predeterminado que cambió.
  • Parámetro de muestreo de tokens Top-K: Los modelos posteriores a gemini-1.0-pro-vision no admiten el cambio del parámetro Top-K.
  • Pensar: Gemini 3 Pro y los modelos posteriores usan el parámetro thinking_level en lugar de thinking_budget. Para obtener más información, consulta Cómo controlar el pensamiento del modelo.
  • Firmas de pensamiento: En Gemini 3 Pro y modelos posteriores, si se espera una firma de pensamiento en un turno, pero no se proporciona, el modelo devuelve un error en lugar de una advertencia. Consulta Firmas de razonamiento.
  • Resolución y tokenización de medios: Gemini 3 Pro y los modelos posteriores usan una longitud de secuencia variable para la tokenización de medios en lugar de Pan and Scan, y tienen nuevas resoluciones predeterminadas y costos de tokens para imágenes, PDFs y videos. Consulta Comprensión de imágenes y Comprensión de videos.
  • Metadatos de uso: En el caso de Gemini 3 Pro y modelos posteriores, los recuentos de tokens de PDF en usage_metadata se registran en la modalidad IMAGE en lugar de DOCUMENT.
  • Segmentación de imágenes: Los modelos Gemini 3 Pro y posteriores no admiten la segmentación de imágenes.
  • Respuestas de funciones multimodales: En el caso de Gemini 3 Pro y modelos posteriores, puedes incluir datos de imágenes y PDF en las respuestas de funciones. Consulta Respuestas de funciones multimodales.
  • Procesamiento de PDFs: En el caso de los modelos de Gemini 3 Pro y versiones posteriores, el OCR no se usa de forma predeterminada cuando se procesan PDFs escaneados.

En este paso, enfócate solo en los cambios de código. Es posible que debas realizar otros cambios más adelante, pero espera hasta que comiences la evaluación. Después de las evaluaciones, considera realizar estos ajustes según los resultados de la evaluación:

  • Si cambias de la recuperación dinámica, es posible que debas ajustar las instrucciones del sistema para controlar cuándo se usa la Búsqueda de Google (por ejemplo, "Only generate queries for the Google Search tool if the user asks about sports. Don't generate queries for any other topic."). Sin embargo, espera hasta que realices la evaluación antes de cambiar las instrucciones.
  • Si usaste el parámetro Top-K, ajusta otros parámetros de muestreo de tokens, como Top-P, para obtener resultados similares.

3. Ejecuta evaluaciones sin conexión

Repite las evaluaciones que realizaste cuando desarrollaste y lanzaste tu aplicación por primera vez, las evaluaciones sin conexión que se hayan realizado desde entonces y las evaluaciones adicionales que identificaste en el paso 1. Si aún consideras que la evaluación no abarca por completo el alcance de tu aplicación, realiza más evaluaciones.

Si no tienes una forma automatizada de ejecutar evaluaciones sin conexión, considera usar el servicio de evaluación de IA generativa.

Si tu aplicación usa el ajuste fino, realiza una evaluación sin conexión antes de volver a ajustar el modelo con la versión más reciente de Gemini. Los modelos más recientes ofrecen una mejor calidad de salida, lo que puede significar que tu aplicación ya no necesita un modelo ajustado.

4. Evalúa los resultados de la evaluación y ajusta tus instrucciones y parámetros

Si la evaluación sin conexión muestra que tu aplicación tiene un rendimiento menos eficaz, mejórala hasta que su rendimiento coincida con el del modelo anterior. Para ello, sigue estos pasos:

5. Ejecuta pruebas de carga

Si tu aplicación necesita una capacidad de procesamiento mínima, realiza pruebas de carga para asegurarte de que la versión más reciente de tu aplicación cumpla con tus requisitos de capacidad de procesamiento.

Las pruebas de carga deben realizarse antes de la evaluación en línea, ya que esta implica exponer el modelo al tráfico en vivo. Usa tus herramientas de prueba de carga y tu instrumentación existentes para este paso.

Si tu aplicación ya cumple con las necesidades de capacidad de procesamiento, considera usar la capacidad de procesamiento aprovisionada. Necesitarás capacidad de procesamiento aprovisionada adicional a corto plazo para cubrir las pruebas de carga mientras tu pedido actual de capacidad de procesamiento aprovisionada controla el tráfico de producción.

6. Ejecuta evaluaciones en línea (opcional)

Pasa a la evaluación en línea solo si la evaluación sin conexión muestra una alta calidad de los resultados de Gemini y tu aplicación requiere una evaluación en línea.

La evaluación en línea es un tipo específico de prueba en línea. Intenta usar las herramientas y los métodos existentes de tu organización para la evaluación en línea. Por ejemplo:

  • Si tu organización realiza pruebas A/B con regularidad, haz una para comparar la versión actual de tu aplicación con la versión más reciente de Gemini.
  • Si tu organización usa con regularidad las implementaciones de versiones canary, utilízalas con los modelos más recientes y mide los cambios en el comportamiento de los usuarios.

También puedes realizar evaluaciones en línea agregando nuevas funciones de medición y comentarios a tu aplicación. Las diferentes aplicaciones necesitan diferentes métodos de comentarios. Por ejemplo:

  • Agregar botones de Me gusta y No me gusta junto a los resultados del modelo y comparar las tasas entre un modelo anterior y los modelos de Gemini más recientes.
  • Mostrarles a los usuarios los resultados del modelo anterior y de los modelos más recientes uno al lado del otro, y pedirles que elijan su favorito
  • Hacer un seguimiento de la frecuencia con la que los usuarios anulan o ajustan manualmente los resultados del modelo anterior en comparación con los modelos más recientes

Estos métodos de comentarios a menudo requieren ejecutar la versión más reciente de Gemini junto con la versión existente. A veces, esta implementación paralela se denomina "modo de sombra" o "implementación azul-verde".

Si los resultados de la evaluación en línea difieren mucho de los resultados de la evaluación sin conexión, esta última no captura aspectos clave del entorno en vivo o de la experiencia del usuario. Aplica los resultados de la evaluación en línea para crear una nueva evaluación sin conexión que cubra la brecha y, luego, vuelve al paso 3.

Si usas la capacidad de procesamiento aprovisionada, es posible que debas comprar capacidad de procesamiento aprovisionada adicional a corto plazo para seguir cumpliendo con tus requisitos de capacidad de procesamiento para los usuarios en la evaluación en línea.

7. Implementar en producción

Una vez que la evaluación muestre que el modelo de Gemini más reciente funciona igual o mejor que un modelo anterior, reemplaza la versión existente de la aplicación por la nueva. Sigue los procedimientos estándar de tu organización para el lanzamiento de producción.

Si usas la capacidad de procesamiento aprovisionada, cambia tu pedido de capacidad de procesamiento aprovisionada al modelo de Gemini que elijas. Si implementas tu aplicación de forma incremental, usa la capacidad de procesamiento aprovisionada a corto plazo para satisfacer las necesidades de capacidad de procesamiento de dos modelos de Gemini diferentes.

Actualizaciones de parámetros y prácticas recomendadas en Gemini 3.x

Los siguientes parámetros se aplican a todos los modelos de Gemini 3.x, incluido Gemini 3.5 Flash. Se presentaron con Gemini 3 y se enumeran aquí como recordatorio.

Parámetros de muestreo (obsoletos)

Ya no se recomiendan temperature, top_p ni top_k para todos los modelos de Gemini 3.x. El modelo administra su propio muestreo para obtener resultados óptimos. Quita estos parámetros de todas las solicitudes.

Para maximizar el determinismo, te recomendamos que definas una instrucción del sistema con reglas explícitas para tu caso de uso específico.

thinking_budget (obsoleto)

Ya no se recomienda el parámetro numérico sin procesar thinking_budget en todos los modelos de Gemini 3.x. En su lugar, usa la enumeración de cadenas thinking_level.

Llamada a función: coincidencia estricta de respuestas

La API aún no genera un error, pero las respuestas que no coinciden hacen que el modelo devuelva respuestas vacías con finish_reason: STOP en la mayoría de los casos. Sigue siempre estas convenciones:

  • Incluye id: Cada FunctionResponse debe incluir el id del FunctionCall correspondiente.
  • Coincidencia de name: El name de la respuesta debe coincidir con el name de la llamada.
  • Recuentos de coincidencias: Muestra exactamente un FunctionResponse por cada FunctionCall recibido.

Respuestas de funciones multimodales

Cuando proporciones contenido multimodal (como imágenes) en respuesta a una llamada a función, incluye el contenido dentro de las partes de la respuesta de la función, no fuera de ellas. Esto evita comportamientos inesperados del modelo, como la filtración de pensamientos.

Instrucciones intercaladas con respuesta de la función

Si necesitas proporcionar instrucciones de la plataforma junto con las respuestas de la función, agrégalas al final del texto de la respuesta de la función separadas por dos saltos de línea, en lugar de como partes separadas.

Reducir las llamadas a herramientas innecesarias

Si experimentas un uso excesivo de llamadas a herramientas, haz lo siguiente: 1. Reduce el nivel de razonamiento (medium, low o minimal). 2. Agrega una instrucción del sistema para restringir el uso de la herramienta (p.ej., "You have a limited action budget of <n> tool calls. Use them efficiently.").

Lista de tareas para la migración

Usa las siguientes listas de tareas como referencia rápida cuando migres desde versiones anteriores del modelo:

De la versión preliminar de Gemini 3 Flash

  • Actualiza el nombre del modelo: gemini-3-flash-preview → gemini-3.5-flash.
  • Revisar precios. Gemini 3.5 Flash es más costoso que Gemini 3 Flash Preview.
  • Quita temperature, top_p y top_k de tu configuración.
  • Reemplaza thinking_budget por thinking_level.
  • Prueba tus instrucciones. El esfuerzo predeterminado cambió de high a medium.
  • La preservación de pensamientos ahora está activada de forma predeterminada. El contexto de razonamiento se mantiene entre los turnos.
  • Reduce las llamadas a herramientas innecesarias ajustando el nivel de razonamiento o agregando instrucciones del sistema.
  • Por el momento, el uso de la computadora no es compatible con Gemini 3.5 Flash.
  • Mitiga la sicofancia: Si gemini-3.5-flash comienza a mostrar signos de sicofancia, puedes experimentar con la mitigación de este comportamiento a través de sus instrucciones del sistema agregando lo siguiente: - Keep your responses concise. - Provide a summary of your work when you end your turn. Ground your response in the work you did. Keep your tone professional and avoid overconfident language, bragging, or overclaiming success. - AVOID using superlatives such as "perfectly", "flawlessly", "100% correct", "Summary of Accomplishments" etc. to summarize your work for the user. Be humble. - AVOID over-the-top politeness or complimenting the user excessively. - Format your responses in github-style markdown.

De Gemini 2.5

  • Probar cargas de trabajo de documentos y PDFs Es posible que aumente el consumo de tokens para los archivos PDF.
  • Simplifica las instrucciones. Prueba thinking_level: "medium" o "high" con instrucciones más simples en lugar de instrucciones complejas de cadena de pensamiento.
  • Aprovecha el uso combinado de herramientas (búsqueda, contexto de URL, ejecución de código, funciones).
  • Mover el contenido multimodal dentro de las partes de la respuesta de la función
  • Agrega instrucciones intercaladas al texto de respuesta de la función.

Mejora el rendimiento del modelo

A medida que realices la migración, aplica estas sugerencias para lograr un rendimiento óptimo con el modelo de Gemini que elijas:

  • Para todos los modelos de Gemini 3, los parámetros de muestreo (temperature, top_p y top_k) dejaron de estar disponibles. El modelo administra su propio muestreo para obtener resultados óptimos. Google recomienda quitar estos parámetros de todas las solicitudes.
  • Verifica tus instrucciones del sistema, instrucciones y ejemplos de aprendizaje con algunos ejemplos para detectar incoherencias, contradicciones o instrucciones y ejemplos irrelevantes.
  • Prueba un modelo más potente. Por ejemplo, si evaluaste un modelo Flash-Lite, prueba con un modelo Flash o Pro.
  • Revisa los resultados de la evaluación automatizada para asegurarte de que coincidan con el criterio humano, especialmente los resultados que utilizan un modelo de juez. Asegúrate de que las instrucciones del modelo de juez sean claras, coherentes y precisas.
  • Para mejorar las instrucciones del modelo de juez, prueba las instrucciones con varias personas que trabajen de forma aislada. Si los humanos interpretan las instrucciones de manera diferente y proporcionan juicios distintos, las instrucciones de tu modelo de juez no son claras.
  • Ajusta el modelo.
  • Examina los resultados de la evaluación para detectar patrones que muestren tipos específicos de fallas. Agrupar las fallas por modelo, tipo o categoría proporciona datos de evaluación más específicos, lo que facilita el ajuste de las instrucciones para corregir estos errores.
  • Asegúrate de evaluar los diferentes componentes de la IA generativa de forma independiente.
  • Experimenta con el ajuste de los parámetros de muestreo de tokens.

Obtén ayuda

Si necesitas ayuda, Google Cloud ofrece paquetes de asistencia para satisfacer tus necesidades, como cobertura, asistencia telefónica y acceso a un administrador de asistencia técnica las 24 horas, todos los días. Para obtener más información, consulta Asistencia deGoogle Cloud .

¿Qué sigue?

Guía

Aprende los conceptos básicos para usar el SDK de IA generativa de Google y enviar consultas a los modelos de Gemini con Agent Platform.

Descripción general

Lista de los modelos de Google disponibles en Agent Platform, como Gemini, Gemma y Veo.

Descripción general

Lista de modelos desarrollados por socios de Google disponibles en Agent Platform, como Claude y Mistral

Descripción general

Descripción general de cómo usar modelos abiertos como Gemma, Llama, DeepSeek y muchos más en Agent Platform.

Recurso

Preguntas frecuentes sobre el uso de Gemini con Agent Platform.