# Glossário — IA local no M5 Max

Linguagem canônica do curso. Toda lição usa estes termos (e evita os aliases). Definições curtas: o que o termo **é**.

## Hardware & memória

**Parâmetro (peso)**:
Um dos números aprendidos no treino. "Modelo de 284 B" = 284 bilhões de pesos.
_Evitar_: variável, neurônio.

**RAM unificada**:
Memória única compartilhada entre CPU e GPU no Apple Silicon; é a "VRAM" do Mac. No M5 Max = 128 GB.
_Evitar_: VRAM (no contexto Mac), memória de vídeo.

**Largura de banda (banda)**:
Quantos GB/s a memória entrega ao chip. Decide a velocidade de **decode**, não os FLOPs.
_Evitar_: velocidade de memória, throughput de RAM.

**Folga (headroom)**:
Os 10–20% de RAM que você deixa livre acima dos pesos+KV+SO para evitar OOM e fragmentação.
_Evitar_: sobra, espaço livre.

## Modelo & precisão

**Quantização**:
Guardar cada peso em menos bits que o original de treino (16 bits) — menos memória, alguma perda de fidelidade.
_Evitar_: compressão, redução.

**Quant assimétrica**:
Quantizar partes diferentes em precisões diferentes (DS4: experts MoE em 2 bits, atenção/roteamento em Q8). É o que mantém o 2-bit útil.
_Evitar_: quant mista, quant seletiva.

**Tier de precisão**:
O formato de bits por peso: FP16 (16) · FP8 (8) · Q6_K (~6) · Q4_K (~4) · Q2_K (~2).
_Evitar_: nível de quant, formato.

**MoE (Mixture of Experts)**:
Arquitetura onde só um subconjunto dos pesos ("experts") é ativado por token. DeepSeek-V4-Flash: 284 B totais, ~13 B ativos.
_Evitar_: modelo esparso, ensemble.

**Parâmetros ativos vs totais**:
Ativos = os pesos usados por token (custo de banda/velocidade). Totais = todos os pesos (custo de memória).
_Evitar_: tamanho real, params efetivos.

## Execução

**Engine de inferência**:
O software que carrega os pesos e gera tokens (DS4, llama.cpp, MLX, vLLM). Escolhido **por último**, depois de hardware/workload/serviço.
_Evitar_: runtime, framework, backend (isolado).

**Prefill vs decode**:
Prefill = processar o prompt de entrada (paralelo, compute-bound). Decode = gerar token a token (sequencial, banda-bound).
_Evitar_: input/output, encode/decode.

**tok/s (tokens por segundo)**:
A métrica de velocidade. Medir prefill e decode separadamente.
_Evitar_: velocidade, TPS sem qualificar.

**KV cache**:
A memória de trabalho da atenção: guarda chaves/valores dos tokens já vistos para não recalcular. Cresce com o contexto (~0,5 MiB/token em FP16).
_Evitar_: cache de atenção, memória de contexto.

**Janela de contexto**:
Quantos tokens o modelo mantém em memória de uma vez (DeepSeek-V4-Flash: até 1M).
_Evitar_: tamanho de contexto, memória.

## Formatos & ferramentas

**GGUF**:
Formato de arquivo de pesos quantizados (só dados, seguro). Usado por llama.cpp e DS4.
_Evitar_: modelo, checkpoint, .bin.

**MLX**:
Framework de ML da Apple para Apple Silicon (Metal). Roda o Qwen3-VL.
_Evitar_: Metal (o backend), CoreML.

**SSD streaming**:
Manter parte dos pesos/KV no SSD e trazer sob demanda, para rodar modelos maiores que a RAM. No DS4, "KV é cidadão de primeira classe do disco".
_Evitar_: offload, paginação.

**DS4 / DwarfStar**:
O engine C from-scratch do antirez para DeepSeek-V4 (Metal primário no Mac).
_Evitar_: ds4.c isolado, dwarf.