Migración total IA: Gemini → Gemma 4 vía OpenRouter

⚠️ SUPERSEDED · s55 (11-05-2026) por [[decision—20260511—cleanup-openrouter-monoproveedor-google-genai]].

OpenRouter fue retirado del stack AI tras 8 días de PROD estable con google_genai directo a Google AI Studio Paid Tier (s49 → s55). Los archivos core/services/ai_providers/openrouter.py + monitoring/services/ai_providers/openrouter.py referenciados en sources fueron eliminados en s55 (-1266 LOC). En s58 d21 también se cerró el caller restante del workspace (scripts/translate-wiki.mjs + functions/api/wiki/translate.ts). Solo ai-eval/run.ts mantiene OpenRouter por diseño (tool de comparación multi-proveedor).

ADR conservado como referencia histórica del puente OpenRouter (s44 → s55).

Contexto

El 28 de abril de 2026, durante una sesión sobre el plan registrado en la memoria project_gemma4_openrouter (sesión cierre 28-04 previa), Edu validó subjetivamente en /tools/ai-eval que google/gemma-4-26b-a4b-it:free daba respuestas mejores que gemini-2.5-flash en preguntas largas con prosa libre. Esa observación motivó la propuesta de migrar todos los call sites de IA del proyecto (CreaRack-Pro + workspace) a Gemma 4 vía OpenRouter, hasta entonces no integrado.

La Regla 8 de CLAUDE.md exige que cualquier cambio de modelo requiera un ADR que actualice la tabla canónica. Este es ese ADR.

Decisión

Migrar los 11 call sites de IA del proyecto a google/gemma-4-26b-a4b-it (versión paga vía OpenRouter) a partir del 2026-04-28. La versión :free queda prohibida porque Google AI Studio (provider upstream del free tier) devuelve HTTP 429 sin previo aviso incluso con tráfico bajo.

El cambio unifica todo el stack de IA en un único modelo — anteriormente había 3 modelos Gemini distintos (gemini-3.1-flash-lite-preview para Categoría A, gemini-2.5-flash para Categoría B, y la fallback chain del router). La distinción Categoría A / Categoría B desaparece.

Call sites migrados (11 totales)

CreaRack-Pro (8)

Workspace (3)

Excepción permitida

functions/api/tools/ai-eval/run.ts mantiene la integración Gemini para que la herramienta /tools/ai-eval pueda comparar Gemma vs Gemini en futuras evaluaciones. Esta es la única referencia a Gemini permitida fuera del fallback chain.

Evaluación previa

Subjetiva (Edu en /tools/ai-eval, 27-04-2026)

Probando google/gemma-4-26b-a4b-it:free con preguntas largas y respuestas en prosa: respuestas notablemente más completas y mejor estructuradas que gemini-2.5-flash.

Cuantitativa (scripts/eval_ai_models.py matriz 4×3, 28-04-2026)

Test direcionado de latencia (3 runs por config, prompt MIB largo)

Test direccionado de latencia (prompt corto, 300 chars output)

Lectura clave

Latencia de Gemma 4 escala lineal con tokens de salida (~60-80 tokens/s en Cloudflare/Parasail/DeepInfra). Para prompts cortos es competitivo con Gemini Flash-Lite. Para JSON largos, Gemma 4 es 10× más lento. La elección de migrar acepta este trade-off porque:

1. Los sites de output largo son cron / async (no bloquean UI directa).
2. CreaRack está en modo dev compartido (Edu + Dani), sin clientes que sufran el delay.
3. Beneficio en stack unificado y coste pesa más que latencia en sites no-UX.

Coste

Implementación

Patrón Python (CreaRack-Pro)

Provider único en core/services/ai_providers/openrouter.py con dos entry points:

from core.services.ai_providers.openrouter import call_openrouter, acall_openrouter

# Texto + JSON
text = call_openrouter(prompt, response_json=True, max_tokens=2048)

# JSON Schema estricto (forza provider con structured_outputs)
text = call_openrouter(prompt, response_schema={...}, provider_prefs={"only": ["deepinfra"]})

# Visión
text = call_openrouter(prompt, images=[img_bytes], image_mime="image/jpeg")

# Async con conversation history (Tutor)
text = await acall_openrouter(messages_list, system_instruction=SYSTEM_PROMPT)

Routing por defecto: provider.sort = "latency". OpenRouter elige Cloudflare/Parasail/DeepInfra/etc. según latencia upstream observada.

Patrón TypeScript (workspace)

Fetch directo a https://openrouter.ai/api/v1/chat/completions con Authorization: Bearer ${env.OPENROUTER_API_KEY} y provider: { sort: "latency" } en el body. Sin SDK.

Configuración

• CreaRack-Pro: OPENROUTER_API_KEY añadida a compose.yml (servicio web), config/settings/base.py y .env. Defaults AUTOPLAN_PROVIDER=openrouter y EDGE_AI_PROVIDER=openrouter. Hetzner PROD necesita la key en su .env Dokploy antes del próximo redeploy.
• Workspace: OPENROUTER_API_KEY añadida al Env type (functions/types.ts). Cloudflare Pages requiere añadir la key como secret en el panel del dashboard antes del próximo deploy (no automatizable desde CLI sin reauth wrangler — tarea manual de Edu).

Consecuencias

Positivas

• Stack unificado: un único modelo para todo (texto, JSON, visión). Elimina la distinción Categoría A / B.
• −76% / −78% coste por token vs gemini-3.1-flash-lite-preview.
• Independencia de Google AI Studio: routing automático multi-provider (Cloudflare, Parasail, DeepInfra, Google Vertex…). Si un provider falla OpenRouter cambia automáticamente.
• Latencia competitiva en prompts cortos (Tutor, Help Widget breve, Auto-Plan visión).
• Provider OpenRouter reutilizable (call_openrouter/acall_openrouter) — futuras integraciones IA en CreaRack pasan por aquí.

Negativas / Riesgos

• Latencia 10× peor en sites de JSON largo (MIB classification, CNS Insight con muchos chunks). Aceptado por contexto dev-compartido.
• Variante :free no usable (rate-limited upstream sin previo aviso). Se queda fuera de la opción de fallback gratis.
• Dependencia adicional de OpenRouter como aggregator. Si OpenRouter cae completo, los 11 call sites pasan al fallback DeepSeek → Claude (en CreaRack-Pro) o devuelven error 503 (en workspace).

Neutrales

• Los call sites Auto-Plan y CNS mantienen su lógica de visión / JSON intacta — solo cambia el cliente subyacente.
• Las claves Gemini (GEMINI_API_KEY) y los call sites DeepSeek (Auto-Plan fallback explícito) se mantienen sin cambios. La migración es reversible vía toggle .env.

Revisión 2026-05-03 (sesión 48): :free desbloqueado vía BYOK para Auto-Plan

La afirmación original “:free queda prohibida” era válida para el pool compartido OpenRouter — efectivamente devuelve 429 sin previo aviso por saturación cross-tenant. Tras pruebas en s48:

Cambio: :free es viable y preferible para Auto-Plan siempre que el OPENROUTER_API_KEY tenga BYOK conectado a una API key personal de Google AI Studio (https://openrouter.ai/settings/integrations). Con BYOK, las requests :free consumen la cuota personal del usuario (no el pool compartido) y no hay 429 mientras la cuota diaria personal alcance.

Por qué :free es preferible para visión:

• :free rutea siempre a Google AI Studio (único provider). Es el runtime oficial de Google donde se entrenó el modelo.
• El paid (google/gemma-4-26b-a4b-it) rutea a 10 providers third-party (DekaLLM, DeepInfra, Ionstream, Cloudflare, Parasail, etc.). En s48 se confirmó con provider.only y seed=42 fijo que algunos third-party recortan la imagen antes de servirla al modelo (calidad ~45-95%) o tienen cuantizaciones más agresivas. Solo Google AI Studio (:free) y Google Vertex (google-vertex slug del paid) replican el comportamiento del runtime original.

Estado tras s48:

• Auto-Plan: usa google/gemma-4-26b-a4b-it:free con BYOK Edu (commit 96bc4efb en repo CreaRack-Pro). Validado 100% calidad sobre plano test 68 racks. Reproducible con OPENROUTER_SEED=43.
• Resto de call sites de IA (CNS, MIB Assistant, Tutor, Help Widget, traducciones, finops, perf review): siguen en el modelo paid google/gemma-4-26b-a4b-it original. La migración es Auto-Plan-only.

Doc operativo nuevo: [[crearack-tech—backend—auto-plan-ai-tuning]] cubre el setup actual (Dokploy env vars, prompt, footguns, recetario para iterar prompt con seed fijo).

Riesgo BYOK: la cuota diaria de Google AI Studio personal de Edu (~1500 req/día típico free tier) puede saturar si el uso de Auto-Plan crece mucho. Mitigación: si satura, cambiar OPENROUTER_MODEL=google/gemma-4-26b-a4b-it (paid) — pierde calidad pero recupera funcionalidad. O reactivar self-host EPYC pve-epyc-02 cambiando AUTOPLAN_PROVIDER=ollama.

Reversión

Para revertir a Gemini Flash-Lite:

1. CreaRack-Pro: en .env de PROD cambiar AUTOPLAN_PROVIDER=gemini y EDGE_AI_PROVIDER=gemini. Los call sites mantienen su path Gemini intacto. Para ai_fallback revertir un commit.
2. Workspace: revertir el commit (los CF Workers vuelven a usar GOOGLE_AI_API_KEY directo).

Supersedes

Supersedes: [[decision—20260427—gemini-3-1-flash-lite-migration]]

La Regla 8 de CLAUDE.md ha sido actualizada para reflejar esta decisión como la tabla canónica vigente. Las menciones a Categoría A / Categoría B quedan obsoletas.

Véase también

• [[decision—20260427—gemini-3-1-flash-lite-migration]] — ADR previo sobre Gemini Flash-Lite (ahora superseded)
• [[crearack—blueprints—auto-plan-ai]] — Auto-Plan AI, principal call site de visión
• [[crearack—monitoring—cns-sentinel]] — CNS, call site de JSON crítico
• [[feature—ai—eval-ai-models-framework]] — Script de evaluación A/B usado en este ADR