system-docs/03_COMPONENTES/servicios/grace.md

GRACE - Servicio de IA Cognitiva

Versión: 5.0 Fecha: 2024-12-24

---

Estado Actual

BLOQUEADO: RunPod no inicia workers.

Aspecto	Valor
Plataforma	RunPod Serverless
Endpoint ID	r00x4g3rrwkbyh
Balance	~$72 USD
Workers activos	0
Estado	Inoperativo

---

Descripción

GRACE es el servicio de extracción de información mediante IA. Procesa contenido multimedia para extraer datos estructurados.

Contenido Raw
(audio, imagen, video, documento)
       │
       ▼
┌─────────────────────────────────────────┐
│              GRACE (GPU)                │
│                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │   ASR   │  │   OCR   │  │   TTS   │ │
│  └─────────┘  └─────────┘  └─────────┘ │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │  Face   │  │Embeddings│ │ Avatar  │ │
│  └─────────┘  └─────────┘  └─────────┘ │
│                                         │
│  + 12 módulos pendientes                │
└─────────────────────────────────────────┘
       │
       ▼
Datos Estructurados
(JSON, vectores, metadatos)

---

Módulos Implementados (6 de 18)

ASR - Automatic Speech Recognition

Campo	Valor
Modelo	Whisper Large v3
Input	Audio (mp3, wav, m4a)
Output	Texto + timestamps
GPU	A10G recomendado

@grace.module("asr")
def process_asr(audio_bytes: bytes) -> dict:
    """Transcribe audio a texto."""
    model = whisper.load_model("large-v3")
    result = model.transcribe(audio_bytes)
    return {
        "text": result["text"],
        "segments": result["segments"],
        "language": result["language"]
    }

OCR - Optical Character Recognition

Campo	Valor
Modelo	EasyOCR + Tesseract
Input	Imagen (jpg, png)
Output	Texto + bounding boxes
GPU	A10G recomendado

@grace.module("ocr")
def process_ocr(image_bytes: bytes) -> dict:
    """Extrae texto de imagen."""
    reader = easyocr.Reader(['es', 'en'])
    result = reader.readtext(image_bytes)
    return {
        "text": " ".join([r[1] for r in result]),
        "boxes": [{"text": r[1], "bbox": r[0], "confidence": r[2]} for r in result]
    }

TTS - Text to Speech

Campo	Valor
Modelo	Coqui TTS
Input	Texto
Output	Audio (wav)
GPU	A10G recomendado

Face - Reconocimiento Facial

Campo	Valor
Modelo	InsightFace
Input	Imagen
Output	Embeddings faciales
GPU	A10G recomendado

Embeddings - Vectores Semánticos

Campo	Valor
Modelo	Sentence Transformers
Input	Texto
Output	Vector 384/768 dims
GPU	A10G recomendado

Avatar - Generación de Avatares

Campo	Valor
Modelo	StyleGAN
Input	Imagen facial
Output	Avatar estilizado
GPU	A10G recomendado

---

Módulos Pendientes (12)

Módulo	Descripción	Prioridad
Document parsing	Extracción de PDFs	Alta
Image classification	Clasificación de imágenes	Media
Object detection	Detección de objetos	Media
Sentiment analysis	Análisis de sentimiento	Media
Named entity recognition	Extracción de entidades	Alta
Translation	Traducción de texto	Media
Summarization	Resumen de texto	Media
Question answering	Respuestas a preguntas	Baja
Code generation	Generación de código	Baja
Audio classification	Clasificación de audio	Baja
Video analysis	Análisis de video	Baja
Multimodal fusion	Fusión multimodal	Baja

---

Código en R2

El código está listo y disponible:

s3://architect/gpu-services/
├── base/
│   └── bootstrap.sh      # Script de inicialización
├── grace/
│   └── code/
│       └── handler.py    # Handler principal
├── penny/
│   └── code/
│       └── handler.py
└── factory/
    └── code/
        └── handler.py

Descargar Código

source /home/orchestrator/orchestrator/.env
export AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$R2_SECRET_KEY"

aws s3 sync s3://architect/gpu-services/grace/ ./grace/ \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

---

Handler RunPod

import runpod

def handler(event):
    """
    Handler principal de GRACE para RunPod Serverless.

    Input:
        {
            "input": {
                "module": "asr|ocr|tts|face|embeddings|avatar",
                "data": "base64 encoded content",
                "options": {}
            }
        }

    Output:
        {
            "output": { ... resultado del módulo ... },
            "error": null
        }
    """
    try:
        module = event["input"]["module"]
        data = base64.b64decode(event["input"]["data"])
        options = event["input"].get("options", {})

        if module == "asr":
            result = process_asr(data, **options)
        elif module == "ocr":
            result = process_ocr(data, **options)
        elif module == "tts":
            result = process_tts(data, **options)
        elif module == "face":
            result = process_face(data, **options)
        elif module == "embeddings":
            result = process_embeddings(data, **options)
        elif module == "avatar":
            result = process_avatar(data, **options)
        else:
            return {"error": f"Módulo desconocido: {module}"}

        return {"output": result, "error": None}

    except Exception as e:
        return {"error": str(e)}

runpod.serverless.start({"handler": handler})

---

Uso desde MASON

import runpod
import base64

runpod.api_key = "..."  # Desde Infisical

def call_grace(module: str, content: bytes, options: dict = None) -> dict:
    """Llama a GRACE para procesar contenido."""

    job = runpod.run(
        endpoint_id="r00x4g3rrwkbyh",
        input={
            "module": module,
            "data": base64.b64encode(content).decode(),
            "options": options or {}
        }
    )

    # Polling hasta completar
    while True:
        status = runpod.status(job["id"])
        if status["status"] == "COMPLETED":
            return status["output"]
        elif status["status"] == "FAILED":
            raise Exception(status.get("error", "Job failed"))
        time.sleep(1)

---

Problema Actual: Workers No Inician

Incidente 2024-12-24

• Síntoma: 0 workers activos a pesar de jobs en cola
• Balance: $72+ (suficiente)
• Configuración: Correcta
• Causa probable: Problema de capacidad RunPod

Intentos de Diagnóstico

1. Verificado endpoint activo en dashboard
2. Verificado balance suficiente
3. Verificado configuración de scaling
4. Jobs quedan en estado "IN_QUEUE" indefinidamente

Log de Errores

No hay logs disponibles - workers nunca inician

---

Alternativas Evaluadas

1. Modal (Recomendado)

import modal

stub = modal.Stub("grace")
image = modal.Image.debian_slim().pip_install("whisper", "easyocr")

@stub.function(gpu="A10G", image=image)
def process_asr(audio_bytes: bytes) -> dict:
    import whisper
    model = whisper.load_model("large-v3")
    result = model.transcribe(audio_bytes)
    return {"text": result["text"]}

Pros:

• Serverless real
• Buen DX (developer experience)
• Python-native
• Cold start rápido

Contras:

• Menos GPUs disponibles que RunPod
• Pricing puede ser mayor

2. Replicate

import replicate

output = replicate.run(
    "openai/whisper:large-v3",
    input={"audio": audio_url}
)

Pros:

• Modelos pre-entrenados
• API simple
• Sin gestión de infraestructura

Contras:

• Menos control
• Más caro a escala
• Dependencia de modelos de terceros

3. Lambda Labs

Pros:

• Hardware dedicado
• GPUs disponibles

Contras:

• Menos flexible
• Reserva manual
• No serverless

4. Self-Hosted

Pros:

• Control total
• Sin dependencias externas
• Costo fijo a largo plazo

Contras:

• CapEx alto
• Mantenimiento
• Requiere expertise

---

Plan de Migración

Fase 1: Evaluación

• Crear cuenta Modal
• Portar módulo ASR a Modal
• Comparar latencia con RunPod (cuando funcione)
• Comparar costos

Fase 2: Migración

• Portar 6 handlers a Modal
• Actualizar endpoints en MASON
• Actualizar documentación
• Testing end-to-end

Fase 3: Producción

• Desplegar en Modal
• Monitorear costos y performance
• Deprecar RunPod endpoints
• Cancelar cuenta RunPod

---

Principio Fundamental

GRACE nunca modifica datos.

GRACE es read-only: extrae información pero no puede modificar el contenido original ni los datos del sistema. Las extracciones se almacenan como metadatos asociados al contenido original.

Contenido Original ────► GRACE ────► Metadatos Extraídos
      (inmutable)                        (nuevos datos)