Hugging Face's logo

MethodWhite
/
HSAQ

English
Spanish
quantization
sparsity
activation-quantization
adaptive-quantization
pruning
kthvalue
abliteration
research
Model card Files
xet
 Community
HSAQ / HSAQ_STANDARD.md
MethodWhite's picture
MethodWhite
HSAQ: documentación limpia (Qué es/Qué NO es, HSAQ v2 aparte) + implementación + scripts abliteración
dc9acb9 verified
preview code
|
Raw
History Blame Contribute Delete
8.2 kB

HSAQ Standard — HyperSparse Adaptive Quantization

Versión 1.0 — Julio 2026

¿Qué es? ✅

Cuantización y poda adaptativa de activaciones: máscara binaria dinámica por kthvalue (umbral recalculado por lote), máscaras aprendibles, gradiente STE y SGD Nesterov a 4 bytes/parám.

¿Qué NO es? ❌

No es cuantización de pesos. No es INT8, INT4, GPTQ, AWQ ni bitsandbytes. No opera sobre pesos — opera exclusivamente sobre activaciones.

HSAQ v2 — aparte ⚠️

La cuantización de pesos INT8/INT4 del paper de M.A.T.E.R.I.A. V4 es una extensión experimental separada; no forma parte de esta definición core.

1. Definición

HSAQ (HyperSparse Adaptive Quantization) es un mecanismo de cuantización de activaciones mediante sparsity adaptativa dinámica, donde cada capa de la red calcula su propio umbral vía torch.kthvalue en cada forward pass.

La "cuantización" en HSAQ refiere a que las activaciones se reducen a un conjunto discreto de valores {0, valor_original} mediante una máscara binaria. NO es cuantización de pesos. NO es INT8/INT4. NO es bitsandbytes.

2. Principios Fundamentales

  1. Adaptativo: el umbral de sparsity se recalcula en cada batch usando kthvalue
  2. Por capa: cada componente (embedding, transformer, SNN, SSM, JEPA) tiene su propio umbral
  3. Sin calibración: no requiere datasets externos ni pasos post-entrenamiento
  4. Hardware-agnostic: funciona en CPU, GPU y TPU sin modificaciones
  5. Sin estado: no hay buffers persistentes entre batches
  6. Gradiente fluye: las neuronas activas reciben gradiente normalmente (STE nativo)

3. Algoritmo

3.1 Pseudocódigo 

Entrada: x ∈ ℝ^(B×T×D)    # Batch de activaciones
Parámetro: sparsity ∈ [0,1)  # Fracción a enmascarar

1. magnitudes = |x|.view(B, -1)          # Magnitudes por batch
2. n = magnitudes.size(1)                # Total de neuronas
3. k = n × (1 - sparsity)               # Neuronas a mantener
4. umbral = kthvalue(magnitudes, k)      # k-ésimo valor más pequeño
5. mascara = |x| ≥ umbral               # Máscara binaria {0, 1}
6. return x × mascara                   # Neuronas irrelevantes → 0

3.2 Implementación de Referencia 

class HSAQ(nn.Module):
    """HyperSparse Adaptive Quantization"""
    def __init__(self, sparsity: float = 0.3):
        super().__init__()
        self.sparsity = sparsity

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        if self.sparsity <= 0.0:
            return x
        flat = x.abs().view(x.size(0), -1)
        n = flat.size(1)
        k = max(1, min(n - 1, int(n * (1.0 - self.sparsity))))
        thresh = torch.kthvalue(flat, k, dim=1).values
        thresh = thresh.view(-1, *([1] * (x.dim() - 1)))
        return x * (x.abs() >= thresh)

4. Puntos de Aplicación

En M.A.T.E.R.I.A. V4, HSAQ se aplica en 6 puntos del pipeline:

# Componente Entrada Salida Propósito
1 Post-embedding tok_emb(x) → ℝ^(B×T×D) ℝ^(B×T×D) Sparsidad inicial de tokens
2 Post-transformer layer(h_gqa) → ℝ^(B×T×D) ℝ^(B×T×D) Sparsidad por capa atencional
3 Post-SNN snn(h_snn) → ℝ^(B×T×D) ℝ^(B×T×D) Sparsidad de pulsos neuronales
4 Post-SSM ssm(h_ssm) → ℝ^(B×T×D) ℝ^(B×T×D) Sparsidad de estado latente
5 Post-JEPA jepa_enc(fused) → ℝ^(B×T×L) ℝ^(B×T×L) Sparsidad del predictor

Cada punto recalcula kthvalue independientemente → umbral dinámico propio.

5. Parámetros

Parámetro Default Rango Descripción
sparsity 0.3 [0.0, 1.0) Fracción de activaciones a enmascarar

Único parámetro. HSAQ no tiene hiperparámetros adicionales. No weight_bits. No weight_quant_mode. No act_bits.

6. HSAQ como Optimizer

HSAQ reemplaza a AdamW como mecanismo de optimización. La máscara sparse actúa como regularizador adaptativo: las neuronas irrelevantes no reciben gradiente, guiando el aprendizaje.

6.1 Optimizer Externo

Se usa SGD Nesterov como optimizer externo para actualizar pesos:

opt = optim.SGD(
    model.parameters(),
    lr=5e-4,
    momentum=0.9,
    weight_decay=0.01,
    nesterov=True,
)

6.2 Ventajas vs AdamW

Aspecto AdamW HSAQ + SGD Nesterov
Estados de optimizer 2 por parámetro (8 bytes) 1 por parámetro (4 bytes)
Regularización weight_decay Sparsity adaptativa
Memoria extra 8 bytes/param 4 bytes/param
Convergencia Media Comparable con HSAQ

Para 190M parámetros: HSAQ ahorra ~760MB de VRAM solo en estados de optimizer.

7. Pipeline de Entrenamiento 

1. Forward pass
   ├── Token Embedding
   ├── HSAQ (sparsity=0.3, umbral propio)
   │
   ├── Transformer Block 1
   ├── HSAQ (sparsity=0.3, umbral propio)
   │
   ├── Transformer Block 2..N
   ├── HSAQ (sparsity=0.3, umbral propio)
   │
   ├── LIF-SNN
   ├── HSAQ (sparsity=0.3, umbral propio)
   │
   ├── SSM
   ├── HSAQ (sparsity=0.3, umbral propio)
   │
   ├── JEPA Encoder
   ├── HSAQ (sparsity=0.3, umbral propio)
   │
   └── Head → Logits

2. Backward pass
   └── Gradiente fluye solo por activaciones activas

3. Weight update
   └── SGD Nesterov (momentum=0.9, paso único)

8. Comparación con Otras Técnicas

Técnica Reduce Adaptativo Calibración Hardware
HSAQ Activaciones ✅ kthvalue por batch No requiere CPU/GPU/TPU
TurboQuant (Google) Pesos INT8 ❌ Fijo Requiere offline GPU con INT8
AWQ Pesos INT4 ❌ Fijo post-calibración Requiere offline GPU
GPTQ Pesos INT4 ❌ Fijo post-calibración Requiere offline GPU
Pruning Pesos/neuronas ❌ Post-entrenamiento No GPU
DeepSpeed Pesos INT8 ❌ Fijo Requiere offline GPU

8.1 HSAQ vs TurboQuant

HSAQ supera a TurboQuant porque:

  1. No desperdicia recursos: solo las neuronas relevantes se activan
  2. Permite modelos más grandes: con sparsity 30%, un modelo 190M corre como ~133M
  3. Adaptativo: el umbral se ajusta a cada entrada, no es fijo
  4. Zero calibración: no necesita datasets externos
  5. Hardware-agnostic: no requiere INT8, funciona hasta en CPU

9. Integración en M.A.T.E.R.I.A. V4

9.1 Archivos

Archivo Propósito
models/core/hsaq.py Implementación de HSAQ (60 líneas)
models/materia_v4.py Modelo completo con HSAQ por capas
scripts/train_v4_enhanced.py Training script con SGD Nesterov
configs/V4_210M_BPE.yaml Config actual (187M, char-level, HSAQ)

9.2 Config de Entrenamiento 

model:
  dim: 896
  n_layers: 10
  hsaq_sparsity: 0.3

training:
  lr: 5.0e-4
  optimizer: SGD  # HSAQ reemplaza a AdamW
  momentum: 0.9
  nesterov: true
  batch_size: 1
  mixed_precision: bf16

9.3 Cómo Ejecutar 

python scripts/train_v4_enhanced.py \
  --config configs/V4_210M_BPE.yaml \
  --no-synapsis \
  --batch-size 1 \
  --memory-limit 0.85

10. Limitaciones y Trabajo Futuro

Limitación Descripción Plan
Sparsity fija Actualmente 30% fijo para todas las capas Sparsity por capa configurable
Sin sparse kernel real x * mask no ahorra FLOPs reales Implementar kernel CUDA sparse
Sin export ONNX kthvalue no está en opset ONNX Wrapper con topk para export
Sin Synapsis en training Synapsis causa repetición "the the the" Modo Synapsis solo en inferencia

11. Referencias

  1. HSAQ Standard: docs/HSAQ_STANDARD.md
  2. Documentación detallada: docs/HSAQ_DOCUMENTACION_DETALLADA.md
  3. Código fuente: models/core/hsaq.py
  4. Paper científico: docs/PAPER_CIENTIFICO_MATERIA_V4.md

HSAQ Standard v1.0 — M.A.T.E.R.I.A. Research © 2026