Migración de Gemini 2.5: validar antes del cambio de ruta del 1 de diciembre

1. Dos fechas y dos rutas de sustitución

Las notas de Gemini API del 2 de noviembre de 2026 indican que Gemini 2.5 Pro y 2.5 Flash están obsoletos y ya no se pueden seleccionar en Google AI Studio. El cambio de la API está previsto para el 1 de diciembre: las solicitudes a gemini-2.5-pro se dirigirán a gemini-3.8-flash; las de gemini-2.5-flash, a gemini-3.5-flash-lite. Se aplicarán las tarifas del modelo de destino.

En la revisión del 4 de noviembre, el acceso a estos modelos por API estaba limitado a quienes los habían utilizado activamente antes. El modelo distinto gemini-2.5-flash-lite no está incluido en esta retirada. Que una solicitud al nombre antiguo funcione hoy no demuestra que su comportamiento vaya a mantenerse después de la fecha prevista. El aviso consultado no fija la hora exacta del cambio ni su zona horaria.

Estas indicaciones corresponden a Gemini Developer API y AI Studio. No establecen el mismo calendario para la aplicación de consumo Gemini, los derechos de una suscripción ni todos los despliegues de Vertex AI. Anota la superficie de servicio y la persona responsable del proyecto en cada tarea antes de asignar un sustituto.

Google: notas de Gemini API del 2 de noviembre · Google: obsolescencia, acceso y calendario de rutas

2. Inventaría el contrato antes de cambiar el nombre del modelo

Revisa la configuración, los procesos en segundo plano, los cuadernos, los trabajos por lotes y los alias de tu propia pasarela. Una variable puede decir pro mientras la pasarela o el ejecutor resuelve otro modelo. Registra el modelo configurado y la identidad que exponga la respuesta: un HTTP 200 por sí solo no demuestra que se haya probado la ruta prevista.

Separa la migración del modelo de la migración del endpoint. Google sigue dando soporte a GenerateContent; Interactions es la interfaz recomendada para proyectos nuevos. Cambiar modelo, SDK, endpoint, instrucciones y protocolo de herramientas en una sola entrega dificulta explicar un fallo. Congela primero una referencia reproducible y modifica una dimensión cada vez.

• Registra endpoint, ID del modelo, versión del SDK, versión de las instrucciones, huella del esquema de herramientas y valores predeterminados de cada entrada.
• Identifica quién conserva el estado: historial del SDK, partes guardadas por la aplicación, Interactions almacenadas o reproducción de pasos sin estado.
• Separa las consultas de las acciones que envían mensajes, cambian registros o generan cargos; simula sus efectos durante la reproducción.
• Asigna responsable, criterios de aceptación y datos autorizados. No copies credenciales de clientes ni conversaciones sin anonimizar al repositorio de migración.

Google: estado, configuración por turno y almacenamiento · Google: claves API, proyectos y credenciales

3. Sustituye las suposiciones por una matriz de compatibilidad

Las guías actuales describen cambios en las solicitudes además de la sustitución del modelo. Algunos parámetros de muestreo obsoletos se ignoran en la generación documentada y pueden provocar errores en generaciones posteriores. Eso no significa que todas esas solicitudes fallen ya. Elimínalos de forma deliberada y comprueba el comportamiento que antes dependía de ellos.

La matriz propone una revisión de la aplicación. Una solicitud válida es solo el primer filtro: no acredita resultados equivalentes, el mismo esfuerzo de razonamiento ni un gasto menor. Conserva un caso negativo para cada suposición eliminada, de modo que un cambio futuro en un componente común no la reintroduzca sin aviso.

Google: lista de migración a Gemini 3.8 Flash · Google: cambios de Gemini 3.6 y 3.5 Flash-Lite

4. Fija el esfuerzo de razonamiento y después compáralo

Gemini 3.8 Flash admite low, medium y high; medium es el valor predeterminado y minimal no está admitido. No reutilices sin más una configuración de Flash-Lite. El enrutador debe validar la pareja modelo y nivel en vez de añadir la misma configuración a todos los modelos.

Este cuerpo REST de Interactions es un ejemplo sin ejecutar para un caso sintético de solo lectura. Se enviaría a POST https://generativelanguage.googleapis.com/v1beta/interactions con una clave custodiada en el servidor. Ilustra el formato, no una configuración de producción ni un resultado medido. store=false impide la continuación posterior mediante previous_interaction_id y es incompatible con la ejecución en segundo plano; no promete ausencia universal de retención por parte del proveedor.

Compara low y medium con los mismos casos de aceptación antes de aumentar el esfuerzo. Los límites de salida, el tiempo máximo y el presupuesto de llamadas a herramientas son controles distintos. Una salida demasiado corta puede truncar el entregable y no sustituye a la selección del nivel de razonamiento.

{
  "model": "gemini-3.8-flash",
  "store": false,
  "input": "Caso sintético: enumera los ID repetidos en [7, 3, 7]. No uses herramientas externas.",
  "generation_config": {
    "thinking_level": "low"
  }
}

Google: lista de migración a Gemini 3.8 Flash · Google: estado, configuración por turno y almacenamiento · Google: experimento de coste por tarea del 3 de noviembre

5. Conserva las firmas en un ciclo real de herramientas

Una firma de pensamiento es estado opaco del protocolo. No es una respuesta, una instrucción que ejecutar ni una transcripción legible del razonamiento. En GenerateContent puede adjuntarse a partes del contenido; en Interactions, el estado pertinente aparece en pasos thought y ciertos pasos de herramientas integradas. Reconstruir el historial solo con el texto visible elimina información que el turno siguiente puede necesitar.

En Interactions almacenadas, previous_interaction_id permite que el servidor gestione ese estado. Sin estado, hay que reenviar los pasos thought devueltos sin modificarlos, incluidas las firmas pertinentes de herramientas integradas. Trata las dos representaciones por separado: no inventes un campo de firma universal ni traduzcas, resumas o reconstruyas un valor opaco.

• Reproduce al menos solicitud, llamada del modelo, resultado de herramienta y respuesta final; un saludo de un solo turno no valida continuidad.
• Prueba por separado las respuestas en streaming y sin streaming. Conserva los eventos completos, incluido el delta de firma: recibir texto no demuestra que el turno haya terminado.
• Añade casos con un paso thought perdido, una firma truncada y un serializador que elimina campos desconocidos. Registra el fallo real sin presuponer un mismo código HTTP para todas las API.

Google: razonamiento, firmas y estado en streaming

6. Empareja los resultados y evita efectos duplicados

En Interactions, function_result identifica la llamada correspondiente mediante call_id y el nombre de función. El adaptador debe devolver exactamente un resultado por llamada, también cuando la ejecución falla. No emparejes resultados paralelos solo por su posición: dos llamadas pueden compartir nombre y tener argumentos diferentes.

El emparejamiento correcto no garantiza idempotencia de negocio. Si la escritura tuvo éxito pero se perdió la confirmación de red, repetir el turno entero puede repetir la acción. Mantén una clave de operación de negocio y un registro de efectos independientes; el ID generado por el modelo no basta como identidad transaccional duradera. En la reproducción, sustituye las escrituras por una simulación que registre la intención y rechace duplicados.

En Interactions, tools, system_instruction y generation_config solo se aplican a la interacción actual, aunque el historial se encadene. Reenvía la política y configuración requeridas en cada turno. Conservar la conversación no demuestra que se hayan heredado permisos de herramientas o el nivel de razonamiento anterior.

Google: funciones y emparejamiento de resultados · Google: estado, configuración por turno y almacenamiento

7. Verifica el contrato de salida y cada modalidad

La salida estructurada restringe la forma, no la veracidad de un valor. Valida en el cliente identificadores, fechas, cálculos, enumeraciones y relaciones de negocio. El subconjunto documentado de JSON Schema no fuerza todas sus restricciones; no delegues por completo longitud o unicidad en la decodificación restringida.

Las fichas de ambos destinos enumeran entradas de texto, imagen, vídeo, audio y PDF, con salida de texto. Leer audio no equivale a generar voz, ni leer una imagen a crearla. Un endpoint Live, de síntesis de voz o de generación de imágenes necesita una revisión específica en vez de aplicar estas sustituciones de modelos de texto.

• En documentos, usa una página y una respuesta conocidas; exige valor y ubicación de la evidencia, no solo prosa convincente.
• En gráficos, incluye un eje o una unidad ambiguos y admite una respuesta de incertidumbre en lugar de una cifra inventada.
• En extracción JSON, prueba datos ausentes, ID duplicados y campos extra; comprueba formato y reglas del dominio.
• Si una herramienta devuelve medios, verifica el tipo de contenido y la carga preservados por el adaptador, no solo un nombre de archivo.

Google: salidas estructuradas y límites de esquema · Google: capacidades de Gemini 3.8 Flash · Google: capacidades de Gemini 3.5 Flash-Lite

8. Diseña pruebas capaces de rechazar una respuesta plausible

Usa casos sintéticos o datos desidentificados aprobados, con respuestas fijas de herramientas. Reserva otro conjunto que nadie utilice para ajustar las instrucciones. Documenta el resultado esperado y su importancia. Distingue una respuesta respaldada, un rechazo correcto y una derivación segura: no toda respuesta terminada es una tarea resuelta.

La siguiente matriz es un diseño original de pruebas, no un informe de ejecución. Decide los umbrales antes de ver los resultados. Desglosa por flujo y gravedad para impedir que muchas extracciones sencillas oculten un pago duplicado, una fuga de identificadores o un fallo en una secuencia de herramientas.

Google: razonamiento, firmas y estado en streaming · Google: funciones y emparejamiento de resultados · Google: salidas estructuradas y límites de esquema

9. Incluye los intentos fallidos en el coste del trabajo aceptado

El artículo de ingeniería de Google del 3 de noviembre analiza el coste por tarea resuelta. Su experimento de 50 preguntas, una ejecución por configuración y evaluación limitada es un caso publicado por el proveedor: no es nuestra medición, una clasificación independiente ni una garantía de producción. La idea útil es comparar la tarea completa y no solo el precio del token.

En tu evaluación, suma los cargos reales por modelos, enrutador, reintentos, herramientas externas e infraestructura medida por separado durante el periodo. Divide por las tareas que superen criterios independientes. Si ninguna pasa, informa de ello y del gasto: no dividas por cero ni elimines los intentos fallidos. Evita sumar otra vez los tokens de pensamiento incluidos en el total facturado.

Conserva métricas de entrada, salida, pensamiento y caché como diagnóstico junto al coste conciliado. Compara los periodos tarifarios actuales y futuros anunciados sin considerar perpetua una oferta introductoria. Informa también de distribución de latencia, reintentos, efectos y derivaciones; una factura media baja puede esconder reparación manual frecuente.

coste_por_tarea_aceptada = coste_total_conciliado / tareas_aceptadas

# Registro propuesto por la aplicación; no son campos de Gemini API
case_id, model, endpoint, sdk_version, prompt_digest
thinking_level, state_mode, tool_schema_digest
accepted, failure_category, latency_ms, retry_count
reconciled_cost, rate_date, cache_condition, intended_effects

Google: precios de Gemini Developer API · Google: experimento de coste por tarea del 3 de noviembre

10. Introduce un enrutador solo si mejora una referencia sencilla

Compara primero unas políticas fijas: Flash-Lite para todo el trabajo apto, 3.8 Flash en low y 3.8 Flash en medium. Mantén las exigencias de calidad y el conjunto de pruebas. Solo después evalúa un enrutador entre combinaciones admitidas. De otro modo, parecerá económico simplemente por compararlo con una referencia mal configurada.

El enrutador debería distinguir propiedades observables, como necesitar resultados secuenciales o realizar una escritura, en vez de etiquetas vagas como fácil. Envía el trabajo incierto o de consecuencias graves a una ruta validada o a revisión humana. La longitud de las instrucciones no basta: una breve simulación de estado puede requerir más razonamiento que una extracción larga y directa.

Evalúa contextos con caché caliente y fría por separado y guarda metadatos que expliquen los cambios de modelo. El enrutamiento puede alterar la reutilización del contexto y las condiciones del estado. Prueba cambios a mitad de sesión: una solicitud nueva correcta no acredita continuidad. El modelo siguiente debe admitir como entrada las modalidades ya presentes en la conversación.

• Versiona las reglas, ajústalas con el conjunto de desarrollo y congélalas antes de evaluar el conjunto reservado.
• Incluye el coste del enrutador, las escaladas y el trabajo desperdiciado en la ruta barata en el mismo registro por tarea.
• Limita la escalada y fija una derivación final; dos agentes que se piden reintentar indefinidamente no constituyen recuperación.
• Adopta el enrutador únicamente si conserva la aceptación predefinida y mejora la métrica operativa necesaria. No se presupone ningún porcentaje de ahorro.

Google: estado, configuración por turno y almacenamiento · Google: experimento de coste por tarea del 3 de noviembre

11. Despliega con una alternativa válida después del 1 de diciembre

Empieza por reproducir consultas y después compara en paralelo sin efectos reales. La ruta de sombra no debe duplicar correos, cambios de registros ni cargos. Migra un grupo acotado cuando haya superado sus pruebas específicas y haz observables la ruta y la categoría de fallo.

Tras el cambio anunciado, volver a gemini-2.5-pro o gemini-2.5-flash no restaurará el modelo anterior. Una alternativa real es una configuración actualmente admitida que ya supere los casos necesarios, o una cola humana autorizada. Conserva el adaptador antiguo mientras resulte útil y tenga soporte; conservar código no conserva la disponibilidad del proveedor.

• Define cuándo detenerse por efectos duplicados, evidencia rota, solicitudes inválidas persistentes o exceso de presupuesto.
• Prueba la alternativa con las mismas restricciones de datos y permisos: rescatar una tarea no justifica ampliar el acceso sin aviso.
• Completa el trabajo antes del plazo en vez de apostar por una zona horaria no documentada o una prórroga.

Google: notas de Gemini API del 2 de noviembre · Google: obsolescencia, acceso y calendario de rutas

12. Deja un registro que otro ingeniero pueda reproducir

Registra fecha de revisión de fuentes, rutas afectadas, configuraciones exactas, huellas de casos, criterios, ejemplos fallidos y responsable de la alternativa. Separa lo medido de lo planificado. Para este artículo se consultó la documentación el 4 de noviembre de 2026; cuerpo de solicitud, matrices y flujo son ejemplos sin ejecutar. No se verificaron elegibilidad de cuentas, cuotas, latencia ni ahorro.

Usa el siguiente encargo con un proyecto autorizado. Solicita artefactos concretos y se detiene antes de los efectos reales. Sustituye conversaciones de producción por casos sintéticos salvo aprobación de otra vía de datos. Vuelve a consultar las referencias al implementarlo: los calendarios y campos admitidos pueden cambiar.

Revisa la migración de Gemini 2.5 sin llamar a API de pago ni modificar producción.
1. Inventaría ID, endpoint, SDK, instrucciones y adaptadores.
2. Asigna a cada ruta un destino admitido y un nivel de razonamiento explícitos.
3. Detecta turnos model precargados, parámetros retirados y estado descartado.
4. Propón casos sintéticos de herramientas secuenciales/paralelas, streaming parcial y efectos duplicados.
5. Entrega matriz de aceptación, registro de costes y plan para validar la alternativa.
Distingue lo verificado en código, lo respaldado por documentación oficial fechada, las inferencias y las incógnitas.

Google: notas de Gemini API del 2 de noviembre · Google: lista de migración a Gemini 3.8 Flash · Google: cambios de Gemini 3.6 y 3.5 Flash-Lite · Google: claves API, proyectos y credenciales