README.md

---
license: apache-2.0
language:
- en
- es
tags:
- quantization
- sparsity
- activation-quantization
- adaptive-quantization
- pruning
- kthvalue
- abliteration
- research
---

# HSAQ — Hyper Sparse Adaptive Quantization

Cuantización y poda **adaptativa por activaciones**, presentada en el
**I Congreso IA-LATAM 2026** por [Jesús Zárate](https://www.linkedin.com/in/methodwhite) (MethodWhite).

> 🎬 **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

## ¿Qué es HSAQ?

Un mecanismo de **cuantización y poda adaptativa por activaciones** que silencia
la información que no le sirve al modelo para entrenarse. Inspirado en la
**poda sináptica del cerebro humano**: no procesarlo todo, sino aprender qué cortar.

A diferencia de la 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.** Opera sobre **activaciones** con umbral
recalculado por lote (`kthvalue`).

## Cómo funciona — tres pilares

1. **Umbral dinámico por lote**: se calcula la mediana/kthvalue de activaciones
   por batch y se silencian las inactivas.
2. **Gradiente STE** (Straight-Through Estimator): la actualización de pesos
   atraviesa la máscara en retropropagación → poda entrenable/autorregulada.
3. **Optimización de VRAM**: SGD Nesterov con máscaras adaptativas, 4 bytes/parám
   en vez de los 8 de AdamW.

```
flat   = |x|.view(B, -1)
k      = n × (1 - sparsity)
umbral = kthvalue(flat, k)        # umbral adaptativo por batch
mask   = |x| >= umbral
return x * mask
```

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

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

## Archivos

| Archivo | Propósito |
|---|---|
| `HSAQ.md` | Definición y mecanismo ordenados (qué es + cómo funciona + charla) |
| `hsaq.py` | Implementación de referencia (`nn.Module`, 64 líneas) |
| `abliterate_hsaq.py` | Abliteración selectiva con HSAQ (Qwen3.5-9B → GGUF) |
| `measure_vram.py` | Mide pico de VRAM (bf16 vs NF4 vs GGUF) |
| `HSAQ_STANDARD.md` | Especificación del estándar (v1.0) |
| `HSAQ_DOCUMENTACION_DETALLADA.md` | Documentación técnica para conferencia |
| `HSAQ_FORMATO.md` | Formato formal del método |

## Aplicación: abliteración selectiva

En vez de borrar el vector de *refusal* completo, HSAQ enmascara sus componentes
ruidosos (`kthvalue`, top 70%) y ortogonaliza los pesos de la capa contra el
vector enmascarado.

```bash
python abliterate_hsaq.py --layers 4 12 20 28 --sparsity 0.3 --device cpu
```

**Modelo resultante:** [MethodWhite/Qwen3.5-9B-Abliterated-HSAQ](https://huggingface.co/MethodWhite/Qwen3.5-9B-Abliterated-HSAQ)

## Ecosistema

- **M.A.T.E.R.I.A.** — motor multiagente toroidal (HUB + agentes sobre contexto compartido).
- **HSAQ** — cuantización/poda adaptativa (este repo).
- **Noctua-C** — framework de ingeniería inversa (80+ módulos) operado por IA.

## Limitaciones

- Sparsity objetivo calibrado; plan de configurable/aprendida por capa.
- `x * mask` no ahorra FLOPs reales sin kernel CUDA sparse.
- `kthvalue` fuera de opset ONNX — plan: wrapper con `topk`.

## Créditos

**Jesús Antonio Zárate Hernández** (MethodWhite, Chile) — Ingeniero en
Ciberseguridad, creador de M.A.T.E.R.I.A. y HSAQ. M.A.T.E.R.I.A. Research © 2026.

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