Upload 6 files

docs/DEPLOYMENT.md

@@ -0,0 +1,313 @@
+# Clasificación de Uso de Suelo de Bogotá - Guía de Despliegue
+
+Esta guía proporciona instrucciones completas para desplegar la aplicación de Clasificación de Uso de Suelo de Bogotá en varias plataformas, con enfoque en el despliegue en Hugging Face Spaces usando aceleración GPU.
+
+## Tabla de Contenidos
+- [Resumen](#resumen)
+- [Despliegue en Hugging Face Spaces](#despliegue-en-hugging-face-spaces)
+- [Desarrollo Local](#desarrollo-local)
+- [Despliegue con Docker](#despliegue-con-docker)
+- [Variables de Entorno](#variables-de-entorno)
+- [Solución de Problemas](#solución-de-problemas)
+
+## Resumen
+
+La aplicación de Clasificación de Uso de Suelo de Bogotá es un servicio web basado en FastAPI que clasifica el uso del suelo en imágenes satelitales de Bogotá utilizando modelos de aprendizaje profundo. La aplicación está diseñada para ejecutarse eficientemente en entornos acelerados por GPU.
+
+## Despliegue en Hugging Face Spaces
+
+### Prerrequisitos
+- Cuenta de Hugging Face con acceso a Spaces
+- Acceso a hardware GPU (recomendado: L40S o similar)
+- Conocimiento básico de Docker y contenedorización
+
+### Paso 1: Crear un Nuevo Space
+
+1. Ve a [Hugging Face Spaces](https://huggingface.co/spaces)
+2. Haz clic en "Create new Space"
+3. Configura tu space:
+   - **Nombre del Space**: `clasificador-uso-suelo-bogota` (o tu nombre preferido)
+   - **Licencia**: MIT
+   - **SDK**: Docker
+   - **Hardware**: **GPU L40S** (48GB VRAM, alto rendimiento para aprendizaje profundo)
+   - **Visibilidad**: Público o Privado (según necesidad)
+
+### Paso 2: Configurar Ajustes del Space
+
+#### Configuración de Hardware
+Selecciona la **GPU L40S** para rendimiento óptimo:
+- **GPU**: NVIDIA L40S
+- **VRAM**: 48GB
+- **Núcleos CUDA**: 18,176
+- **Ancho de Banda de Memoria**: 864 GB/s
+- **Ideal para**: Modelos transformer grandes y tareas de visión por computadora
+
+#### Archivo de Configuración del Space
+Asegúrate de que tu `README.md` (en la raíz del space) contenga:
+
+```yaml
+---
+title: Clasificador Uso de Suelo Bogotá
+emoji: 🏙️
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+hardware: l40s
+---
+```
+
+### Paso 3: Subir Archivos de la Aplicación
+
+Sube los siguientes archivos a tu Hugging Face Space:
+
+```
+├── app.py                 # Aplicación principal FastAPI
+├── classifier.py          # Lógica de clasificación
+├── inference.py           # Pipeline de inferencia
+├── model.py              # Definiciones del modelo
+├── types_io.py           # Definiciones de tipos
+├── requirements.txt      # Dependencias de Python
+├── Dockerfile           # Configuración del contenedor
+└── README.md            # Configuración del space
+```
+
+### Paso 4: Configuración del Dockerfile
+
+La aplicación usa Docker para contenedorización. El Dockerfile debe estar optimizado para uso de GPU:
+
+```dockerfile
+FROM python:3.10-slim
+
+# Instalar dependencias del sistema
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Establecer directorio de trabajo
+WORKDIR /app
+
+# Copiar requisitos e instalar dependencias
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copiar código de la aplicación
+COPY . .
+
+# Exponer puerto
+EXPOSE 7860
+
+# Ejecutar la aplicación
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+### Paso 5: Configuración del Entorno
+
+#### Optimización GPU
+La GPU L40S proporciona excelente rendimiento para esta aplicación:
+- **CUDA**: Detectado automáticamente y utilizado por PyTorch
+- **Memoria**: 48GB VRAM permite procesamiento en lotes grandes
+- **Capacidad de Cómputo**: 8.9 (arquitectura Ampere)
+
+#### Dependencias
+Dependencias clave optimizadas para aceleración GPU:
+```
+torch>=2.7.0          # PyTorch con soporte CUDA
+torchvision>=0.22.0   # Utilidades de visión por computadora
+transformers>=4.52.3   # Transformers de Hugging Face
+accelerate>=1.7.0     # Utilidades de entrenamiento distribuido
+```
+
+### Paso 6: Desplegar y Monitorear
+
+1. **Subir al Space**: Sube todos los archivos a tu Hugging Face Space
+2. **Proceso de Construcción**: El space construirá automáticamente el contenedor Docker
+3. **Asignación de GPU**: La GPU L40S será asignada durante el inicio
+4. **Monitorear Logs**: Revisa los logs del space para cualquier problema de despliegue
+
+#### Tiempo de Inicio Esperado
+- **Construcción del Contenedor**: 5-10 minutos
+- **Carga del Modelo**: 2-3 minutos en L40S
+- **API Lista**: Total ~7-13 minutos
+
+### Paso 7: Uso de la API
+
+Una vez desplegada, tu aplicación estará disponible en:
+```
+https://huggingface.co/spaces/[USUARIO]/[NOMBRE_SPACE]
+```
+
+#### Endpoints de la API
+- `POST /classify`: Endpoint principal de clasificación
+- `GET /health`: Endpoint de verificación de salud
+- `GET /docs`: Documentación interactiva de la API
+
+#### Ejemplo de Uso
+```python
+import requests
+import base64
+
+# Codificar imagen a base64
+with open("imagen_satelital.jpg", "rb") as f:
+    imagen_b64 = base64.b64encode(f.read()).decode()
+
+# Hacer petición a la API
+response = requests.post(
+    "https://huggingface.co/spaces/[USUARIO]/[NOMBRE_SPACE]/classify",
+    json={
+        "images": [
+            {
+                "data": imagen_b64,
+                "format": "base64"
+            }
+        ]
+    }
+)
+
+resultados = response.json()
+print(f"Clasificación: {resultados}")
+```
+
+### Beneficios de Rendimiento GPU
+
+Usar la GPU L40S proporciona ventajas significativas:
+
+#### Métricas de Rendimiento
+- **Velocidad de Inferencia**: ~40-50seg por imagen (vs 40-50min en CPU)
+- **Procesamiento en Lotes**: Puede procesar múltiples imágenes simultáneamente
+- **Memoria**: 48GB permite modelos grandes y tamaños de lote grandes
+- **Rendimiento**: ~60-80 imágenes/hora dependiendo de la complejidad del modelo.
+
+#### Optimización de Costos
+- **Procesamiento Eficiente**: Inferencia más rápida reduce tiempo de cómputo
+- **Operaciones en Lotes**: Procesa múltiples imágenes en paralelo
+- **Auto-escalado**: Hugging Face gestiona la asignación de recursos
+
+## Desarrollo Local
+
+### Configuración
+```bash
+# Clonar repositorio
+git clone <url-repositorio>
+cd bogota_land_use_final
+
+# Instalar dependencias
+pip install -r requirements.txt
+
+# Ejecutar aplicación
+uvicorn app:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Requisitos GPU (Local)
+- GPU NVIDIA con soporte CUDA
+- CUDA 11.8 o posterior
+- cuDNN 8.7 o posterior
+- Al menos 8GB VRAM (16GB+ recomendado)
+
+## Despliegue con Docker
+
+### Construir y Ejecutar
+```bash
+# Construir imagen
+docker build -t bogota-land-use .
+
+# Ejecutar contenedor (soporte GPU)
+docker run --gpus all -p 7860:7860 bogota-land-use
+
+# Ejecutar contenedor (solo CPU)
+docker run -p 7860:7860 bogota-land-use
+```
+
+### Docker Compose
+```yaml
+version: '3.8'
+services:
+  app:
+    build: .
+    ports:
+      - "7860:7860"
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+```
+
+## Variables de Entorno
+
+Configura estas variables de entorno para rendimiento óptimo:
+
+```bash
+# Configuración GPU
+CUDA_VISIBLE_DEVICES=0
+TORCH_CUDA_ARCH_LIST="8.9"  # Arquitectura L40S
+
+# Configuraciones de la Aplicación
+MODEL_CACHE_DIR="/tmp/model_cache"
+MAX_BATCH_SIZE=16
+INFERENCE_TIMEOUT=30
+
+# Ajuste de Rendimiento
+OMP_NUM_THREADS=4
+TORCH_NUM_THREADS=4
+```
+
+## Solución de Problemas
+
+### Problemas Comunes
+
+#### GPU No Detectada
+```bash
+# Verificar disponibilidad de GPU
+python -c "import torch; print(torch.cuda.is_available())"
+python -c "import torch; print(torch.cuda.device_count())"
+```
+
+#### Problemas de Memoria
+- Reducir tamaño de lote en inferencia
+- Habilitar gradient checkpointing
+- Usar entrenamiento de precisión mixta
+
+#### Inferencia Lenta
+- Verificar utilización de GPU
+- Revisar cuantización del modelo
+- Optimizar preprocesamiento de imágenes
+
+### Monitoreo de Rendimiento
+
+#### Monitoreo de GPU
+```bash
+# Monitorear uso de GPU
+nvidia-smi -l 1
+
+# Verificar versión de CUDA
+nvcc --version
+```
+
+#### Logs de la Aplicación
+Revisar logs del Hugging Face Space para:
+- Tiempo de carga del modelo
+- Rendimiento de inferencia
+- Uso de memoria
+- Mensajes de error
+
+### Soporte
+
+Para problemas con:
+- **Hugging Face Spaces**: Consulta [documentación de Hugging Face](https://huggingface.co/docs/hub/spaces)
+- **Configuración GPU**: Verifica instalación y compatibilidad de CUDA
+- **Lógica de la Aplicación**: Revisa logs de la aplicación y mensajes de error
+
+## Recursos Adicionales
+
+- [Documentación de Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
+- [Especificaciones GPU L40S](https://www.nvidia.com/en-us/data-center/l40s/)
+- [Documentación GPU PyTorch](https://pytorch.org/docs/stable/notes/cuda.html)
+- [Documentación FastAPI](https://fastapi.tiangolo.com/)
+
+---
+
+*Última actualización: 13 de julio de 2025*

docs/WORKFLOW.md

@@ -0,0 +1,455 @@
+# Clasificación de Uso de Suelo de Bogotá - Flujo de Código
+
+Este documento explica la arquitectura técnica y el flujo de código de la aplicación de Clasificación de Uso de Suelo de Bogotá, proporcionando una visión detallada de cómo interactúan los diferentes componentes del sistema.
+
+## Tabla de Contenidos
+- [Resumen de Arquitectura](#resumen-de-arquitectura)
+- [Diagrama de Flujo del Sistema](#diagrama-de-flujo-del-sistema)
+- [Componentes Principales](#componentes-principales)
+- [Flujo de Datos Detallado](#flujo-de-datos-detallado)
+- [Modelo de Datos](#modelo-de-datos)
+- [Manejo de Errores](#manejo-de-errores)
+- [Optimizaciones de Rendimiento](#optimizaciones-de-rendimiento)
+- [Patrones de Diseño](#patrones-de-diseño)
+
+## Resumen de Arquitectura
+
+La aplicación sigue una arquitectura de microservicios basada en FastAPI con separación clara de responsabilidades:
+
+- **Capa de API**: Manejo de peticiones HTTP y validación de entrada
+- **Capa de Procesamiento**: Preprocesamiento de imágenes y orquestación
+- **Capa de Inferencia**: Clasificación usando modelos de aprendizaje profundo
+- **Capa de Modelo**: Gestión del modelo de transformers y procesador
+
+## Diagrama de Flujo del Sistema
+
+```mermaid
+graph TD
+    A[Cliente HTTP] -->|POST /classify| B[FastAPI App]
+    B --> C{Validación de Request}
+    C -->|Error| D[HTTP 400 Error]
+    C -->|Válido| E[decode_base64_image]
+    
+    E --> F[save_images_to_disk]
+    F --> G[Inference.classify_building]
+    G --> H[Classifier.get_response]
+    
+    H --> I[get_input_tensor]
+    I --> J[resize_image]
+    J --> K[prepare_messages]
+    
+    K --> L[Model.load_model]
+    L --> M[Model.load_processor]
+    
+    M --> N[generate_model_response]
+    N --> O[processor.apply_chat_template]
+    O --> P[model.generate]
+    P --> Q[processor.batch_decode]
+    
+    Q --> R[Respuesta JSON]
+    R --> S[Cliente HTTP]
+    
+    style B fill:#e1f5fe
+    style H fill:#f3e5f5
+    style L fill:#e8f5e8
+    style N fill:#fff3e0
+```
+
+### Flujo Alternativo de Errores
+
+```mermaid
+graph TD
+    A[Error en cualquier etapa] --> B{Tipo de Error}
+    B -->|Validación| C[HTTP 400 - Bad Request]
+    B -->|Procesamiento| D[HTTP 500 - Internal Error]
+    B -->|Modelo| E[HTTP 500 - Model Error]
+    
+    C --> F[Log de Error]
+    D --> F
+    E --> F
+    F --> G[Respuesta de Error al Cliente]
+```
+
+## Componentes Principales
+
+### 1. app.py - Capa de API (Entrada del Sistema)
+
+**Responsabilidades:**
+- Manejo de peticiones HTTP
+- Validación de entrada
+- Decodificación de imágenes base64
+- Guardado temporal de imágenes
+- Orquestación del flujo principal
+
+**Funciones clave:**
+```python
+def decode_base64_image(base64_str: str) -> Optional[Image.Image]
+def save_images_to_disk(images: List[Image.Image], output_dir: str) -> List[str]
+async def classify(request: ClassificationRequest) -> dict
+```
+
+**Flujo de datos:**
+1. Recibe request con imágenes en base64
+2. Valida formato usando Pydantic
+3. Decodifica cada imagen base64 a PIL.Image
+4. Guarda imágenes temporalmente en disco
+5. Delega clasificación a la capa de inferencia
+6. Retorna respuesta JSON estructurada
+
+### 2. inference.py - Capa de Procesamiento
+
+**Responsabilidades:**
+- Orquestación entre API y clasificador
+- Preprocesamiento de imágenes
+- Conversión de formatos de imagen
+- Logging de operaciones
+
+**Funciones clave:**
+```python
+def _prepare_images(self, images: List[Image.Image]) -> List[Image.Image]
+def classify_building(self, images: List[Image.Image], saved_image_paths: List[str]) -> dict
+```
+
+**Flujo de datos:**
+1. Recibe lista de objetos PIL.Image
+2. Convierte todas las imágenes a formato RGB
+3. Valida integridad de cada imagen
+4. Delega clasificación al componente Classifier
+5. Retorna respuesta estructurada
+
+### 3. classifier.py - Lógica de Clasificación
+
+**Responsabilidades:**
+- Gestión del pipeline de clasificación
+- Redimensionamiento de imágenes
+- Preparación de mensajes para el modelo
+- Generación de respuestas del modelo
+- Aplicación de plantillas de chat
+
+**Funciones clave:**
+```python
+def get_response(self, images: List[Image.Image], saved_image_paths: List[str]) -> dict
+def get_input_tensor(self, images: List[Image.Image]) -> List[Image.Image]
+def generate_model_response(self, images: List[Image.Image], messages: List[dict]) -> str
+def resize_image(image: Image.Image, max_size: int = 224) -> Image.Image
+def prepare_messages(saved_image_paths: List[str]) -> List[dict]
+```
+
+**Prompt del sistema:**
+- Define 20 categorías de uso de suelo específicas para Bogotá
+- Requiere mínimo 3 categorías por clasificación
+- Incluye scores de confianza (0-1)
+- Formato de salida JSON estructurado
+
+### 4. model.py - Gestión del Modelo
+
+**Responsabilidades:**
+- Carga única del modelo y procesador (Singleton)
+- Configuración de parámetros del modelo
+- Gestión de memoria y recursos GPU
+- Abstracción del modelo Kimi-VL-A3B-Thinking
+
+**Funciones clave:**
+```python
+@classmethod
+def load(cls) -> Tuple[AutoModelForCausalLM, AutoProcessor]
+@classmethod 
+def load_model(cls) -> AutoModelForCausalLM
+@classmethod
+def load_processor(cls) -> AutoProcessor
+```
+
+**Configuración del modelo:**
+```python
+MODEL_PATH = "moonshotai/Kimi-VL-A3B-Thinking-2506"
+model_kwargs = {
+    "device_map": "auto",
+    "torch_dtype": "auto", 
+    "trust_remote_code": True
+}
+```
+
+### 5. types_io.py - Definiciones de Tipos
+
+**Responsabilidades:**
+- Validación de datos de entrada y salida
+- Definición de esquemas JSON
+- Enumeración de categorías de clasificación
+- Restricciones de formato y rangos
+
+**Modelos principales:**
+```python
+class ClassificationRequest(BaseModel)  # Entrada de la API
+class ImageData(BaseModel)             # Salida de la clasificación
+class ImageTag(BaseModel)              # Tags individuales
+class TagType(Enum)                   # Categorías de uso de suelo
+```
+
+## Flujo de Datos Detallado
+
+### Fase 1: Recepción y Validación (app.py)
+```
+Cliente → POST /classify → FastAPI → Pydantic Validation
+                                  ↓
+                        ClassificationRequest {
+                            images: List[str]  # base64 strings
+                        }
+```
+
+### Fase 2: Decodificación y Almacenamiento (app.py)
+```
+List[str] → decode_base64_image() → List[PIL.Image]
+                                  ↓
+                        save_images_to_disk() → List[str] # file paths
+```
+
+### Fase 3: Preprocesamiento (inference.py)
+```
+List[PIL.Image] → _prepare_images() → List[PIL.Image] # RGB converted
+                                   ↓
+                         Validación de integridad
+```
+
+### Fase 4: Clasificación (classifier.py)
+```
+List[PIL.Image] → get_input_tensor() → resize_image() → List[PIL.Image] # 224x224
+                                                     ↓
+List[str] # paths → prepare_messages() → List[dict] # chat format
+                                      ↓
+            generate_model_response() → modelo transformer → str # JSON response
+```
+
+### Fase 5: Carga del Modelo (model.py)
+```
+Kimi-VL-A3B-Thinking-2506 → AutoModelForCausalLM.from_pretrained()
+                          ↓
+                    device_map="auto" # GPU allocation
+                          ↓
+                    torch_dtype="auto" # Mixed precision
+```
+
+### Fase 6: Generación de Respuesta
+```
+Imágenes + Prompt → processor.apply_chat_template() → model.generate()
+                                                   ↓
+                  processor.batch_decode() → JSON string → ImageData
+```
+
+## Modelo de Datos
+
+### Estructura de Entrada
+```json
+{
+  "images": [
+    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
+    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB..."
+  ]
+}
+```
+
+### Estructura de Salida
+```json
+{
+  "output": {
+    "classification": [
+      {
+        "category": "Residenciales",
+        "confidence": 0.92
+      },
+      {
+        "category": "Comerciales1", 
+        "confidence": 0.65
+      },
+      {
+        "category": "Moles",
+        "confidence": 0.33
+      }
+    ],
+    "think": "Esta edificación presenta características principalmente residenciales..."
+  }
+}
+```
+
+### Categorías de Clasificación
+
+| Categoría | Descripción | Ejemplo |
+|-----------|-------------|---------|
+| **Residenciales** | Edificios para vivienda | Casas, edificios PH, condominios |
+| **Comerciales1-5** | Diferentes tipos comerciales | Tiendas, oficinas, hoteles, talleres |
+| **Centros_Comerciales** | Complejos comerciales | Centros comerciales, plazas |
+| **Bodegas** | Almacenamiento | Bodegas industriales y comerciales |
+| **Parqueaderos** | Estacionamientos | Edificios de parqueo |
+| **Dotacionales1-5** | Servicios públicos | Escuelas, hospitales, iglesias |
+| **Especiales** | Usos especiales | Áreas militares, cementerios |
+| **Moles** | Grandes edificios | >4 pisos o >10,000 m² |
+| **Rurales** | Construcciones rurales | Galpones, silos, establos |
+| **Mixto1-3** | Usos combinados | Residencial+Comercial |
+
+## Manejo de Errores
+
+### Tipos de Errores y Estrategias
+
+#### 1. Errores de Validación (HTTP 400)
+```python
+# En app.py
+try:
+    images = []
+    for img_str in request.images:
+        img = decode_base64_image(img_str)
+        if img is None:
+            raise ValueError("Invalid base64 image")
+        images.append(img)
+except ValueError as ve:
+    raise HTTPException(status_code=400, detail=str(ve))
+```
+
+#### 2. Errores de Procesamiento (HTTP 500)
+```python
+# En classifier.py
+try:
+    img = self.resize_image(img)
+    processed_images.append(img)
+except Exception as e:
+    logger.error(f"Error processing image at index {idx}: {str(e)}")
+    raise
+```
+
+#### 3. Errores del Modelo (HTTP 500)
+```python
+# En model.py
+try:
+    cls._model = cls.model_class.from_pretrained(
+        cls.MODEL_PATH, **cls.model_kwargs
+    )
+except Exception as e:
+    logger.error(f"Failed to load model: {str(e)}")
+    raise
+```
+
+### Sistema de Logging
+```python
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+)
+```
+
+**Niveles de logging utilizados:**
+- `INFO`: Operaciones principales y flujo normal
+- `DEBUG`: Información detallada para debugging
+- `ERROR`: Errores que requieren atención
+- `WARNING`: Situaciones anómalas pero no críticas
+
+## Optimizaciones de Rendimiento
+
+### 1. Gestión de Memoria
+- **Singleton para modelo**: Carga única en `model.py`
+- **Auto device mapping**: `device_map="auto"` para distribución GPU óptima
+- **Torch dtype automático**: `torch_dtype="auto"` para precisión mixta
+
+### 2. Procesamiento de Imágenes
+- **Redimensionamiento inteligente**: Mantiene aspect ratio, reduce a 224x224
+- **Conversión RGB**: Garantiza compatibilidad del formato
+- **Guardado temporal**: Optimiza memoria usando rutas de archivo
+
+### 3. Batch Processing
+```python
+# En classifier.py
+inputs = self.processor(
+    images=images, 
+    text=text, 
+    return_tensors="pt", 
+    padding=True,        # Padding para batch processing
+    truncation=True      # Truncación para consistencia
+).to(self.model.device)
+```
+
+### 4. Configuración GPU
+```python
+# Parámetros optimizados para L40S
+model_kwargs = {
+    "device_map": "auto",    # Distribución automática en GPU
+    "torch_dtype": "auto",   # Precision mixta FP16/FP32
+    "trust_remote_code": True
+}
+```
+
+## Patrones de Diseño
+
+### 1. Singleton Pattern (model.py)
+```python
+class Model:
+    _model = None
+    _processor = None
+    
+    @classmethod
+    def load(cls):
+        if cls._model is None:
+            # Cargar solo una vez
+            cls._model = cls.model_class.from_pretrained(...)
+```
+
+### 2. Factory Pattern (types_io.py)
+```python
+class ImageData(BaseModel):
+    """Factory para crear respuestas validadas"""
+    classification: List[ImageTag]
+    think: str
+```
+
+### 3. Strategy Pattern (classifier.py)
+```python
+def resize_image(image: Image.Image, max_size: int = 224):
+    """Estrategia configurable de redimensionamiento"""
+    scale = min(max_size / width, max_size / height)
+    # Aplicar estrategia de redimensionamiento
+```
+
+### 4. Dependency Injection (app.py → inference.py → classifier.py)
+```python
+# app.py
+inference = Inference()
+
+# inference.py  
+def __init__(self):
+    self.classifier = classifier  # Inyección de dependencia
+
+# classifier.py
+def __init__(self):
+    self.model = Model.load_model()      # Inyección lazy
+    self.processor = Model.load_processor()
+```
+
+### 5. Pipeline Pattern
+```
+Cliente → API → Inference → Classifier → Model → Respuesta
+```
+
+Cada etapa transforma los datos y los pasa a la siguiente, permitiendo:
+- **Separación de responsabilidades**
+- **Facilidad de testing**
+- **Escalabilidad independiente**
+- **Mantenimiento modular**
+
+## Consideraciones de Escalabilidad
+
+### 1. Arquitectura Horizontal
+- Cada componente puede escalarse independientemente
+- API stateless permite múltiples instancias
+- Modelo singleton optimiza uso de memoria
+
+### 2. Gestión de Recursos
+- Auto device mapping para múltiples GPUs
+- Batch processing para eficiencia
+- Cleanup automático de archivos temporales
+
+### 3. Monitoring y Observabilidad
+- Logging estructurado en cada capa
+- Métricas de tiempo de respuesta
+- Seguimiento de uso de memoria GPU
+
+---
+
+*Documento técnico actualizado: 13 de julio de 2025*
+
+*Para más información sobre el despliegue, consulta [DEPLOYMENT.md](DEPLOYMENT.md)*

test/test_api_local.py

@@ -0,0 +1,71 @@
+import requests
+import base64
+from pathlib import Path
+from PIL import Image
+import io
+
+def resize_image(image: Image.Image, max_size: int = 224) -> Image.Image:
+    """
+    Resize an image while maintaining aspect ratio.
+
+    Args:
+        image: PIL Image object to resize
+        max_size: Maximum dimension (width or height) of the output image
+
+    Returns:
+        PIL Image: Resized image with maintained aspect ratio
+    """
+    # Get current dimensions
+    width, height = image.size
+
+    # Calculate scaling factor to fit within max_size
+    scale = min(max_size / width, max_size / height)
+
+    # Only resize if image is larger than max_size
+    if scale < 1:
+        new_width = int(width * scale)
+        new_height = int(height * scale)
+        image = image.resize(
+            (new_width, new_height),
+            Image.LANCZOS
+        )
+
+    return image
+
+
+# Define your desired size
+TARGET_SIZE = 16
+
+# Define the image paths
+image_paths = [
+    "images/AAA0119DNBSPD01.jpg",
+    "images/AAA0119DNBSPD02.jpg"
+]
+
+# Read and encode images
+images = []
+for path in image_paths:
+    # Open the image
+    img = Image.open(path)
+    
+    # Resize the image (using LANCZOS for high-quality downsampling)
+    img = resize_image(img, max_size=TARGET_SIZE)
+    
+    # Convert to bytes
+    buffered = io.BytesIO()
+    img.save(buffered, format="JPEG")  # You can change format to PNG if needed
+    
+    # Encode to base64
+    base64_image = base64.b64encode(buffered.getvalue()).decode('utf-8')
+    images.append(base64_image)
+
+# Make the request
+print(images[0])
+url = "http://localhost:8000/classify"
+payload = {"images": [images[0]]}
+headers = {"Content-Type": "application/json"}
+
+response = requests.post(url, json=payload, headers=headers)
+print(f"Status Code: {response.status_code}")
+print("Response Text:")
+print(response.text)