Volver a la wiki

Auto-Plan AI · Ajustes y Prompt (operativa)

Doc operativo sobre cómo afinar el modelo y prompt de Auto-Plan AI sin perder la calidad lograda. Última actualización: 03-05-2026 tras sesión 48.

⚠️ Nota histórica (2026-07): este runbook documenta el tuning de la sesión 48 (mayo-2026), cuando Auto-Plan salía por OpenRouter (variante :free) con reversión al self-host pve-epyc-02. Ambos caminos están RETIRADOS: OpenRouter se retiró en s55 (11-05-2026) y el servidor pve-epyc-02 se dio de BAJA en s53 (08-05-2026, wipe NIST + cancelación en Hetzner Robot). Hoy Auto-Plan corre sobre gemma-4-26b-a4b-it en Google AI Studio (Paid Tier) llamado directamente con el SDK google-genai — sin OpenRouter ni self-host. La config y el model string son la fuente de verdad en config/settings/base.py (AUTOPLAN_PROVIDER=google_genai). Lee lo de abajo como registro histórico; lo que SÍ sigue vigente y es reutilizable es la metodología de iteración de prompt (seed determinista, baseline, un cambio a la vez), la estructura del prompt ganador y los invariantes de sampling de Gemma 4 (temp 1.0 / top-p 0.95 / top-k 64 + response_mime_type JSON load-bearing).

Estado (histórico, s48 · superado — ver nota arriba)

Ganador productivo (a fecha s48): Auto-Plan PROD usaba OpenRouter con la variante :free del modelo Gemma 4 26B-A4B-it y la API key personal de Edu (BYOK) conectada en OpenRouter Integrations. La variante :free ruteaba internamente a Google AI Studio — runtime oficial de Google sin third-party intermedios. (Camino retirado en s55; hoy la llamada es directa al SDK google-genai, sin OpenRouter.)

MétricaValor confirmadoComparativa
Tiempo plano test 70 racks2:09vs 4:45 self-host EPYC (2.2× más rápido)
Calidad racks100% (68/68)igual al self-host
Walls / Texts / Connections18 / 22 / 67confirmado visualmente
Coste por análisis$0free tier dedicado BYOK Edu
Reproducibilidadbit-a-bit con seed=43clave para iterar prompt sin varianza

Stack (histórico s48 — ya NO vivo; ver nota arriba)

┌────────────────────┐
│ CreaRack Pro web   │
│ blueprints/services│
│   /openrouter_     │
│    driver.py       │
└─────────┬──────────┘
          │ OpenAI SDK
          ▼
┌────────────────────────────────┐
│ openrouter.ai/api/v1           │
│ model: google/gemma-4-26b-     │
│        a4b-it:free             │
│ ↓ (BYOK con key personal Edu)  │
└─────────┬──────────────────────┘
          ▼
┌────────────────────────────┐
│ Google AI Studio           │
│ (runtime oficial Gemma 4)  │
└────────────────────────────┘

Reversión rápida (~30s): cambiar AUTOPLAN_PROVIDER=ollama en Dokploy y redeploy → vuelve al self-host EPYC pve-epyc-02 (LXC 100 llama-server, receta s47g).

Variables de entorno (Dokploy)

VariableValor productivoPara qué
AUTOPLAN_PROVIDERopenrouterDriver activo (alternativa: ollama para self-host)
OPENROUTER_API_KEYsk-or-v1-...Clave OpenRouter de Edu con BYOK conectado a Google AI Studio
OPENROUTER_SEED43Semilla determinista — clave para iterar prompt sin varianza
OPENROUTER_MODEL(vacío)Toma default código google/gemma-4-26b-a4b-it:free
OPENROUTER_PROVIDER_ORDERdekallm/bf16Irrelevante para :free (1 solo provider). Útil si se vuelve al paid
OPENROUTER_MAX_IMAGE_DIMENSION(vacío → 2048)Probado 2048 / 2560 / 3072 con seed fijo: 2048 = sweet spot
OLLAMA_BASE_URL, OLLAMA_MODEL(vivos)Reversión rápida a self-host

Sólo estas envs valen. Las que se probaron y descartaron en s48 porque Google AI Studio las ignora silenciosamente: OPENROUTER_TEMPERATURE (oficial Google es 1.0, hardcoded), OPENROUTER_FREQUENCY_PENALTY (Google las descarta), OPENROUTER_IMAGE_DETAIL y OPENROUTER_JPEG_QUALITY (no aportan, generan glitches en JSON).

Prompt activo

Vive en el repo en dos archivos sincronizados:

Para iterar sobre el prompt en producción sin tocar el repo, la app expone el modal “Config AI” del editor de blueprints. El prompt editado en ese modal sobreescribe el default por blueprint.

Estructura del prompt ganador (s48)

  1. SYSTEM ROLE + GOAL (2 líneas).
  2. CRITICAL METHODOLOGY: PERIPHERAL VISION & ACUITY — fuerza al modelo a escanear bordes y detalles pequeños.
  3. Sección 1 RACKS & NODAL HUBS — el corazón del prompt:
    • 4 criterios disjuntivos para clasificar como NODAL (basta uno):
      • 3+ cables convergen.
      • Aggregation / distribución.
      • Color destacado (orange/red/yellow/highlighted).
      • Label canónico (NODE / NODO / MDF / IDF / MAIN / DIST / CORE).
    • 3 IMPORTANT explícitos: NODAL es funcional (no tamaño), CONTAR cables antes de clasificar, MÚLTIPLES NODALs por plano.
  4. Sección 2 CONNECTIONS (star topology rule).
  5. Sección 3 WALLS / LINES — incluye detect colors, ambas H y V.
  6. Sección 4 TEXTS & SYMBOLS.
  7. OUTPUT FORMAT — JSON puro, sin prosa, sin markdown fences, sin bloques de thinking.

Nota crítica: si en futuras iteraciones se rompe alguno de los 3 IMPORTANT de la sección 1, el modelo recupera el bug del NODAL grande dividido en 2 racks adyacentes y la calidad cae a ~95% con coste de operador alto (≈30 reconexiones manuales por plano para arreglar).

Receta para iterar prompt con seguridad

Aprendido en s48 tras 10+ iteraciones reales en producción:

  1. Fija seed determinista en Dokploy: OPENROUTER_SEED=43 (o cualquier int). Google AI Studio respeta seed y emite outputs bit-a-bit idénticos. Sin seed, lo que parecía “mejora” o “regresión” puede ser pura varianza.
  2. Establece baseline disparando el plano test 1 vez. Anota racks/walls/texts/connections/chars.
  3. Cambia UNA cosa del prompt en el modal “Config AI” (no varias a la vez).
  4. Dispara el mismo plano. Compara contra baseline:
    • Si los números son idénticos → tu cambio no afectó al modelo. Descarta.
    • Si cambian → mejora o regresión real. Confirma visualmente en el editor.
  5. Si la iteración mejora → guarda el prompt en sitio externo (bloc de notas, copia local) antes de seguir tocando.
  6. Si la iteración rompe el prompt ganador → retroceso inmediato a la copia guardada.

⚠ Cambios de prompt sutiles pueden romper la generación entera (modelo se corta a ~25% de chars normales). Si el output baja drásticamente o el JSON viene corrupto, el prompt es la causa — revierte.

Footguns descubiertos en s48

FootgunDetalleMitigación
Free tier compartido satura con 429El pool :free de OpenRouter está compartido entre TODOS los usuariosBYOK con API key personal de Google AI Studio → cuota dedicada
provider.order con casing incorrecto se ignora silenciosamenteSlugs reales son lowercase con quant (dekallm/bf16), no DekaLLMDefault lowercase + log del provider real consumido
Env vars de Dokploy no llegan al container si no están listadas en compose.yml/compose.prod.ymlDokploy guarda en panel UI pero compose es la fuente de verdadAñadir cada env al compose explícitamente en los 3 servicios afectados (web dev, web prod, worker prod)
int("") y float("") explotan al leer envs vacíasDokploy expande ${VAR:-} con cadena vacía cuando la var del host está vacía, no como ausenteos.environ.get(VAR) or default (no os.environ.get(VAR, default))
Google AI Studio ignora frequency_penalty, temperature (excepto valores oficiales), image_detail, jpeg_quality > 95Acepta los parámetros sin error, pero el output es bit-a-bit idéntico — confirmado con seed=43 fijoNo exponer envs que no se respetan; mantener oficiales Gemma 4 (temp 1.0 / top-p 0.95 / top-k 64)
JSON corrupto puntual ($y1" en vez de "y1", unterminated string)Modelo emite glitches con prompts demasiado densos o palancas A+B (detail=high + q100)Cleaner regex aplicado en driver (AutoPlanService._clean_llm_json) + log de contexto ±80 chars en JSONDecodeError antes del re-raise
Subir resolución de imagen >2048 NO mejora calidad en Google AI StudioGoogle hace internal downsampling parcial; con resolución alta el modelo se distrae con detalle no estructuralDejar MAX_IMAGE_DIMENSION=2048
Resolución 3072 + image_detail=high + JPEG q100 EMPEORA arquitecturaModelo “ve” más detalle pero descarta walls/texts que considera no estructuralesDefault = 2048 / detail=auto / q95

Cómo fue el camino al 100%

  1. Mañana: tuning del self-host EPYC pve-epyc-02 agotado a 4:45 / 100%. Speculative decoding bloqueado upstream para multimodal (llama.cpp issue #19712).
  2. Tarde: switch a OpenRouter modelo paid con DekaLLM → 64s pero 45% calidad (provider third-party recorta imagen).
  3. Descubrimiento: variante :free tiene un único provider — Google AI Studio (runtime oficial Google).
  4. Bloqueo: free tier compartido satura → 429.
  5. Solución: BYOK con clave personal Edu de Google AI Studio → cuota dedicada.
  6. Iteración prompt: seed=43 fija reproducibilidad. Edu itera prompt hasta convergir en versión que detecta 68/68 racks con ambos NODALs unificados.

Decisión sobre el server EPYC

Resuelto (s53, 08-05-2026): se optó por apagar definitivamente. El servidor pve-epyc-02 fue dado de baja (wipe NIST + cancelación en Hetzner Robot). Toda la inferencia vive hoy en Google AI Studio (Paid Tier). Lo de abajo era el planteamiento de opciones en s48, antes de decidir.

Opciones que se barajaron en s48 (histórico):

Referencias

Véase también

Subir