HSAQ.md

# HSAQ — Qué es y cómo funciona

**Hyper Sparse Adaptive Quantization** — documento maestro (v2.0, 2026).

Definición y mecanismo ordenados a partir de la charla del autor en el
**I Congreso IA-LATAM 2026** (presentación oficial + transcripción del video,
sintetizada en el whitepaper de Comunidad IA LATAM).

> 🎬 **Charla en YouTube** (caso de uso práctico con Noctua-C y Antigravity):
> https://www.youtube.com/watch?v=azJURypb3xo
>
> 📄 **Whitepaper oficial del congreso**:
> https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad

---

## 1. ¿Qué es HSAQ?

**HSAQ es un mecanismo de cuantización y poda adaptativa por activaciones.**
Se integra en la arquitectura del modelo y **silencia la información que no le
sirve al modelo para entrenarse**.

- Es un **cuantizador/podador adaptativo** inspirado en la **poda sináptica del
  cerebro humano**: no procesarlo todo, sino *aprender qué cortar*.
- La clave frente a esquemas de cuantización fija (INT8/INT4/GPTQ/AWQ): las
  máscaras de HSAQ son **aprendibles** — el sistema *aprende cuándo cortar y
  cuándo no*.
- **No es cuantización de pesos estática.** Opera sobre **activaciones**, con
  umbral recalculado por lote.

---

## 2. El problema que resuelve

Tres cuellos de botella de los Transformers (motivación de la charla):

1. **Atención intratable** en secuencias largas — el cómputo crece y degrada la
   tarea; las mitigaciones actuales son "un parche, no la solución".
2. **Pesos estáticos** — un Transformer entrenado no modula ni adapta
   dinámicamente su procesamiento.
3. **Desperdicio de memoria en optimizadores** — AdamW usa 2 estados por
   parámetro (8 bytes), agravando el costo del hardware.

Motivación de fondo: **reducir la VRAM necesaria** para que la IA sea accesible
"desde los civiles hasta los gobiernos" — entrenar un modelo de 1.33B con
**10 GB de VRAM en vez de 25**.

---

## 3. ¿Cómo funciona? (tres pilares)

### 3.1 Umbral dinámico por lote

En cada lote se calcula un umbral adaptativo de la activación (kthvalue/mediana)
y se **silencian las activaciones inactivas** por debajo del umbral.

```
1. flat   = |x|.view(B, -1)        # magnitudes por batch
2. n      = flat.size(1)           # total de neuronas
3. k      = n × (1 - sparsity)     # neuronas a mantener
4. umbral = kthvalue(flat, k)      # umbral adaptativo por batch
5. mask   = |x| >= umbral          # máscara binaria {0, 1}
6. return x * mask                 # neuronas irrelevantes → 0
```

### 3.2 Gradiente STE

La actualización de pesos **atraviesa la máscara** en retropropagación
(Straight-Through Estimator): las neuronas activas reciben gradiente, las
inactivas no — el umbral y la poda se vuelven **entrenables** (autorregulados).

### 3.3 Optimización de VRAM

Reemplaza AdamW por **SGD Nesterov con máscaras adaptativas**: 1 estado por
parámetro (4 bytes) en vez de 8.

---

## 4. Resultados reportados (prototipo M.A.T.E.R.I.A. v4, 1.33B, BPE)

| Criterio | AdamW (estándar) | HSAQ + SGD Nesterov | Beneficio |
|---|---|---|---|
| Memoria del optimizador | 8 bytes/parám | 4 bytes/parám | **50% menos** |
| VRAM de entrenamiento | 24.8 GB | 10.07 GB | **−14.7 GB (−59.4%)** |
| Sparsity de activaciones | 0% (densa) | 30% autorregulada | Menos cómputo |
| Convergencia JEPA | N/A | Loss 1.08 → 0.006 | **−99.3%** |

La curva de sparsity se **autorreguló** en torno a un objetivo calibrado (~0.047),
lo que demuestra la estabilidad de la poda adaptativa a esa escala — el beneficio
crece con modelos más grandes.

---

## 5. Aplicación: abliteración selectiva (nuevo, 2026)

Validado con **Qwen3.5-9B**:

1. Se recolecta el vector de refusal por capa: `r = normalize(mean(harmful) − mean(harmless))`.
2. HSAQ enmascara `r` conservando solo el top (1−sparsity) de componentes
   (`sparsity=0.3` → retiene 70% del vector).
3. Los pesos de la capa (`out_proj` + `down_proj`) se ortogonalizan contra el
   vector enmascarado: `W ← W − r̂ ⊗ (r̂ᵀ W)`.

Resultado: el modelo responde a prompts de seguridad ofensiva **sin degradar
tareas harmless**; exportado a **GGUF Q4_K_M** (19.3 GB bf16 → ~5.6 GB).
Modelo: `MethodWhite/Qwen3.5-9B-Abliterated-HSAQ`.

La abliteración clásica borra el vector completo (pierde inteligencia); HSAQ
elimina solo los componentes ruidosos → **menos pérdida de capacidad**.

---

## 6. Ecosistema de la charla

- **M.A.T.E.R.I.A.** — *Multi-Agentic Toroidal Engine for Recursive Intelligent
  Analysis*: motor multiagente con HUB central y ranuras de agentes sobre
  contexto compartido y persistente, arquitectura anidable.
- **HSAQ** — cuantización/poda adaptativa por activaciones (este documento).
- **Noctua-C** — framework de ingeniería inversa (80+ módulos, sandbox) operado
  por un agente de IA; demo en vivo en la charla.

---

## 7. Limitaciones y roadmap

| Limitación | Plan |
|---|---|
| Sparsity objetivo calibrado (no fijo por capa) | Sparsity configurable/aprendida por capa |
| `x * mask` no ahorra FLOPs reales sin kernel sparse | Kernel CUDA sparse |
| `kthvalue` fuera de opset ONNX | Wrapper con `topk` |
| Aplicar HSAQ en runtime dentro de llama.cpp/GGUF | Bloque/máscara en el motor |

Roadmap: primer prototipo 2026 ✓ → modelos comerciales 2027 → gobiernos/empresas
2028 → seguir reduciendo consumo de cómputo 2029.

---

## 8. Evidencia

- Implementación: `hsaq.py` (`nn.Module`, 64 líneas).
- Estándar: `HSAQ_STANDARD.md` (v1.0).
- Paper: `PAPER_CIENTIFICO_MATERIA_V4.md`.
- Scripts: `abliterate_hsaq.py`, `measure_vram.py`.
- Whitepaper congreso: https://comunidadialatam.org/blog/materia-hsaq-ciberseguridad

---

## 9. Créditos

Desarrollado por **Jesús Antonio Zárate Hernández** (MethodWhite, Chile) —
Ingeniero en Ciberseguridad, creador de M.A.T.E.R.I.A. y HSAQ.
Charla: I Congreso IA-LATAM 2026 · [LinkedIn](https://www.linkedin.com/in/methodwhite)

Si te sirve, invítame un café ☕ → **https://buymeacoffee.com/methodwhite**