Auto-Plan: Referencia Técnica

Auto-Plan: Referencia Técnica

Versión: 2.0.0 Última actualización: 25-01-2026 Estado: Producción - Precisión 100%

1. Descripción General

Auto-Plan es el sistema de digitalización automática de planos de infraestructura de red mediante Inteligencia Artificial. Permite convertir imágenes de planos técnicos (blueprints) en datos estructurados editables en el editor de mapas de CreaRack Pro.

Capacidades

• Detección exhaustiva de racks y equipos de red
• Trazado automático de conexiones/cables entre racks
• Identificación de paredes y límites estructurales
• Extracción de textos y etiquetas
• Reconocimiento de símbolos de red (switches, routers, APs, etc.)

2. Arquitectura del Sistema

┌─────────────────────────────────────────────────────────────────┐
│                        FRONTEND                                  │
│  ┌─────────────┐    ┌──────────────┐    ┌───────────────────┐  │
│  │ MapEditor   │───▶│ AutoPlans    │───▶│ MapInteraction    │  │
│  │ (UI)        │    │ Adapter.js   │    │ (Import Handler)  │  │
│  └─────────────┘    └──────────────┘    └───────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ POST /api/blueprints/autoplan/analyze
┌─────────────────────────────────────────────────────────────────┐
│                        BACKEND (Django)                          │
│  ┌─────────────┐    ┌──────────────┐    ┌───────────────────┐  │
│  │ blueprints/ │───▶│ AutoPlan     │───▶│ Gemini API        │  │
│  │ api.py      │    │ Service.py   │    │ (Google AI)       │  │
│  └─────────────┘    └──────────────┘    └───────────────────┘  │
│                              │                                   │
│                              ▼                                   │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    DATABASE (PostgreSQL)                     ││
│  │  ┌────────┐  ┌─────────────────┐  ┌──────────────────┐     ││
│  │  │ Rack   │  │ BlueprintPlace  │  │ MapAnnotation    │     ││
│  │  │        │  │ ment            │  │ (connections,    │     ││
│  │  │        │  │                 │  │  walls, texts)   │     ││
│  │  └────────┘  └─────────────────┘  └──────────────────┘     ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

3. Configuración del Modelo AI

Modelo Fijo (NO MODIFICAR)

Parámetros de Generación

generation_config = types.GenerateContentConfig(
    temperature=0.1,        # Baja para resultados deterministas
    top_p=0.95,
    top_k=40,
    max_output_tokens=16384,  # Suficiente para planos complejos
    safety_settings=[...]     # BLOCK_NONE para contenido técnico
)

Procesamiento de Imagen

4. Prompt de Análisis

Archivo: prompts/blueprint_analyst.md

Sistema de Coordenadas

Origen (0,0) ──────────────────▶ X (1000)
      │
      │   TOP-LEFT = (0, 0)
      │   TOP-RIGHT = (1000, 0)
      │   BOTTOM-LEFT = (0, 1000)
      │   BOTTOM-RIGHT = (1000, 1000)
      │
      ▼
    Y (1000)

Entidades Detectadas

Tipos de Rack

• RACK: Rack estándar (verde/gris)
• NODAL: Rack principal/distribuidor (naranja)

5. Flujo de Procesamiento

5.1 Análisis de Imagen

# 1. Subir imagen y analizar
AutoPlanService.analyze_blueprint_image(
    api_key=settings.GEMINI_API_KEY,
    file_path="/path/to/blueprint.png",
    prompt=open("prompts/blueprint_analyst.md").read(),
    provider="gemini"  # o "deepseek"
)

# 2. Respuesta JSON estructurada
{
    "analysis": "I count 68 racks and 67 connections...",
    "racks": [...],
    "connections": [...],
    "walls": [...],
    "texts": [...],
    "symbols": [...]
}

5.2 Creación de Entidades

# 3. Crear entidades en BD
AutoPlanService.create_blueprint_entities(
    blueprint=bp,
    ai_data=parsed_response,
    scale_x=img_width / 1000.0,
    scale_y=img_height / 1000.0
)

5.3 Sistema de Conexiones (v2.0)

Antes (v1.x): Usaba parent_rack FK (relación 1:1)

# PROBLEMA: Un rack solo podía tener 1 padre
child.parent_rack = parent  # Ignoraba conexiones adicionales

Ahora (v2.0): Usa MapAnnotation tipo rack_connection (muchos-a-muchos)

# SOLUCIÓN: Soporta múltiples cables por rack
MapAnnotation.objects.create(
    blueprint=blueprint,
    type='rack_connection',
    data=json.dumps({'from': from_rack.id, 'to': to_rack.id})
)

6. Endpoints API

POST /api/blueprints/autoplan/analyze

Analiza una imagen subida y devuelve datos estructurados.

Request:

{
    "blueprint_id": 123,
    "provider": "gemini"
}

Response:

{
    "success": true,
    "data": {
        "racks": [...],
        "connections": [...],
        "walls": [...],
        "texts": [...],
        "symbols": []
    }
}

POST /api/blueprints/autoplan/import

Importa los datos analizados al blueprint.

Request:

{
    "blueprint_id": 123,
    "data": { /* AI response */ }
}

Response:

{
    "success": true,
    "created_racks": 68,
    "created_connections": 67
}

7. Modelos de Datos

MapAnnotation (Conexiones)

class MapAnnotation(models.Model):
    blueprint = models.ForeignKey(Blueprint, on_delete=models.CASCADE)
    type = models.CharField(max_length=50)  # 'rack_connection', 'drawing_line', etc.
    data = models.JSONField()  # {'from': rack_id, 'to': rack_id}

Tipos de Anotación Relevantes

8. Archivos del Sistema

CreaRack_Pro_app_Django/
├── blueprints/
│   ├── api.py                    # Endpoints /autoplan/*
│   ├── services/
│   │   ├── autoplan.py           # AutoPlanService (lógica principal)
│   │   └── blueprints.py         # BlueprintService
│   └── models.py                 # Blueprint, MapAnnotation
├── prompts/
│   └── blueprint_analyst.md      # Prompt para Gemini
├── static/js/blueprints/
│   ├── AutoPlansAdapter.js       # Adaptador frontend
│   ├── MapInteraction.js         # Handlers de import
│   └── helpers/
│       └── AnnotationsRenderer.js # Renderizado de anotaciones
└── config/settings/
    └── dev.py                    # Logging config para debug

9. Logging y Debug

Configuración (dev.py)

LOGGING = {
    "loggers": {
        "blueprints.services.autoplan": {
            "handlers": ["console"],
            "level": "DEBUG",
            "propagate": False,
        },
    },
}

Ver logs en tiempo real

docker compose logs -f web | grep AutoPlan

Ejemplo de salida

[INFO] [AutoPlan] Using Gemini 3 Flash Preview for blueprint analysis
[INFO] [AutoPlan] Original image size: (4096, 3072), mode: RGB
[INFO] [AutoPlan] Processed image: (3072, 2304), format=PNG, size=2456.3KB
[INFO] [AutoPlan] Detection summary: 68 racks, 67 connections, 12 walls, 45 texts, 3 symbols
[INFO] [AutoPlan] Successfully created 67 cable connections.

10. Troubleshooting

Error 503 / Model Overloaded

Causa: Imagen muy grande o servidor Gemini saturado.

Solución: El sistema tiene retry automático (3 intentos con espera incremental).

Conexiones no se guardan

Causa histórica: Usaba parent_rack (1:1).

Solución aplicada (v2.0): Ahora usa MapAnnotation tipo rack_connection.

Líneas mal orientadas

Causa: Coordenadas incorrectas del modelo AI.

Solución aplicada: Prompt mejorado con sistema de coordenadas explícito.

Baja precisión en detección

Checklist:

1. Verificar calidad de imagen (resolución mínima 1024px)
2. Contraste adecuado entre elementos
3. Evitar imágenes con mucho ruido visual

11. Historial de Cambios

12. Directrices de Mantenimiento

NO MODIFICAR sin autorización

• Modelo AI: gemini-3-flash-preview
• SDK: google-genai
• Parámetros de generación optimizados

Cambios permitidos

• Ajustes al prompt para mejorar detección
• Logging adicional para debug
• Manejo de errores adicional

Testing

Antes de cualquier cambio, probar con:

1. Plano simple (< 20 racks)
2. Plano complejo (60+ racks)
3. Plano con múltiples conexiones por rack

Documento mantenido por: Equipo de Desarrollo CreaRack Pro Contacto técnico: Ver CLAUDE.md para directrices del proyecto

⚠ Estado real del sistema (post-sesión 48, 03-05-2026): este documento describe la versión histórica con Gemini. La versión productiva actual usa Gemma 4 26B-A4B-it vía OpenRouter :free con BYOK personal de Edu a Google AI Studio. Para operar el sistema vivo, ver [[crearack-tech—backend—auto-plan-ai-tuning]] (env vars, prompt ganador, footguns, recetario para iterar). Esta página queda como referencia de la arquitectura.

Véase también

• [[crearack-tech—backend—auto-plan-ai-tuning]] — operativa actual (post-s48): env vars, prompt ganador, recetario iteración con seed fijo
• [[crearack-tech—backend—autoplan-performance]] — performance histórica de Auto-Plan
• [[crearack-tech—agents—dev-map-editor]] — agente técnico del Map Editor
• [[concept—blueprints—map-editor]] — concepto del editor de planos Map Editor
• [[entity—blueprints—model—blueprint]] — modelo Blueprint
• [[crearack—blueprints—auto-plan-ai]] — funcionalidad Auto-Plan AI para el usuario
• [[ia-tech—roles—dev-vision]] — agente IA visión/IA
• [[decision—20260428—gemma-4-via-openrouter-migration]] — ADR migración a Gemma 4 + revisión 03-05 sobre BYOK