Auto-Plan: OPENROUTER_MODEL configurable + default Google AI Studio :free (s48)

Auto-Plan: OPENROUTER_MODEL configurable + default Google AI Studio `:free`

Versión: v1.0.65+ · Sesión: s48 · Fecha: 2026-05-03
Commit: 07e447fbaa53017c235d5db37bfcf5a5d8919a26
Autor: @Esquembri

Resumen

Esta feature hace que el modelo LLM usado por Auto-Plan AI a través de OpenRouter sea configurable en runtime mediante la variable de entorno OPENROUTER_MODEL, sin necesidad de redeploy de código. Simultáneamente, cambia el valor por defecto al sufijo :free de Gemma 4 26B-A4B, que rutea exclusivamente al runtime oficial de Google AI Studio ($0 por uso).

Motivación

La primera prueba en producción con OpenRouter (s40 + confirmación s48) usó el modelo paid con DekaLLM como provider. Resultado: ~45% de calidad subjetiva respecto al self-host Ollama (referencia). Investigación s48 reveló la causa probable: los proveedores third-party de OpenRouter (DekaLLM, Vertex, Nextbit…) pueden:

Recortar o redimensionar la imagen antes de enviársela al modelo.
Aplicar configuraciones de inferencia distintas (contexto, sampling, etc.).

OpenRouter expone google/gemma-4-26b-a4b-it en dos variantes:

Variante	Providers disponibles	Coste	Runtime
`google/gemma-4-26b-a4b-it` (paid)	DekaLLM, Vertex, Nextbit… (10+)	De pago	Third-party
`google/gemma-4-26b-a4b-it:free`	Google AI Studio (único)	$0	Oficial Google

La variante :free usa el mismo runtime donde Google entrenó y sirve el modelo — equivalente funcional al self-host con mmproj F32, sin infraestructura propia.

Cambios implementados

`blueprints/services/openrouter_driver.py`

# Antes (hardcoded):
model="google/gemma-4-26b-a4b-it",

# Después (configurable):
model = os.environ.get("OPENROUTER_MODEL", "google/gemma-4-26b-a4b-it:free")
# ...
model=model,

`compose.yml` y `compose.prod.yml`

Añadida la env en los servicios web y worker:

- OPENROUTER_MODEL=${OPENROUTER_MODEL:-}

El valor vacío :- hace que Docker Compose use el default del código cuando la variable no está definida en el entorno host.

Cómo operar (sin tocar código)

Configuración actual recomendada (s48)

En Dokploy → Environment Variables del proyecto:

# Dejar como está — el código ya tiene el default correcto:
# OPENROUTER_MODEL=google/gemma-4-26b-a4b-it:free

# Mantener resolución alta:
OPENROUTER_MAX_IMAGE_DIMENSION=3072

# Para cuando se cambie al paid (provider order irrelevante en :free):
OPENROUTER_PROVIDER_ORDER=dekallm/bf16

Cambiar al modelo paid (si rate limits saturan)

OPENROUTER_MODEL=google/gemma-4-26b-a4b-it

→ Save → Deploy. Sin tocar código.

Probar otro modelo completamente

OPENROUTER_MODEL=qwen/qwen3-vl-72b  # ejemplo

Criterio de éxito

Condición	Resultado
Google AI Studio `:free` da calidad ≥95% subjetiva	✅ Ganador absoluto (gratis + runtime oficial). Cierra investigación de provider.
Calidad <95% o igual a paid DekaLLM	Diagnóstico confirmado → siguiente paso: Gemma 4 26B denso, Qwen3-VL-72B o Claude Haiku.
Rate limits saturan en producción	Cambiar a paid sin redeploy. Evaluar modelo alternativo en paralelo.

Riesgos y mitigaciones

Riesgo	Probabilidad	Mitigación
Rate limits free tier (OpenRouter)	Media (uso productivo intensivo)	`OPENROUTER_MODEL=google/gemma-4-26b-a4b-it` sin redeploy
Google AI Studio degrada calidad respecto a self-host	Baja (mismo runtime)	Comparativa cuantitativa pendiente en s49
`OPENROUTER_PROVIDER_ORDER` ignorado en `:free`	No es riesgo — comportamiento correcto	Documentado; la variable queda para el paid

Contexto de sesiones

s40: primera prueba OpenRouter paid → 45% calidad.
s47g: self-host Ollama con mmproj F32 y flags afinados → ~100% calidad (referencia).
s48: investigación provider → descubrimiento variante :free + Google AI Studio. Esta feature.
s49 (pendiente): prueba PROD con :free y evaluación cuantitativa.

Véase también

[[entity—blueprints—service—openrouter-driver]]