Transformers documentation
FP8 de granularidade fina
FP8 de granularidade fina
O FP8 de granularidade fina armazena os pesos em FP8 (E4M3) com uma escala para cada bloco 2D de pesos, 128x128 por padrão, e quantiza as ativações para FP8 em tempo de execução com uma escala por token para cada grupo de 128 valores de canais de entrada. É o formato usado por DeepSeek-V3 e por muitos outros checkpoints FP8 no Hub. Use-o para executar checkpoints FP8 ou para quantizar um modelo para FP8 durante o carregamento, em GPUs Ada, Hopper ou Blackwell e em XPUs da Intel.
A tabela abaixo resume o que o Fine-grained FP8 suporta no Transformers.
| Config | FineGrainedFP8Config |
quant_method | fp8, mxfp8 |
| Fluxo de trabalho | Quantize ao carregar, carregar pré-quantizado |
| Bits | 8 |
| Hardware | CUDA (capacidade de computação 8.9+), XPU |
| Salvar | ✅ |
| Ajuste fino | ✅ |
| Compilação automática | ✅ |
Instale os kernels de FP8 de granularidade fina
O Transformers baixa o kernel de matmul FP8 do repositório kernels-community/finegrained-fp8 no Hub. Instale as bibliotecas kernels e Accelerate.
pip install -U "transformers[kernels]" accelerateQuantize um modelo com FP8 de granulação fina
Crie um FineGrainedFP8Config e passe-o para from_pretrained().
from transformers import AutoModelForCausalLM, FineGrainedFP8Config
quantization_config = FineGrainedFP8Config()
model = AutoModelForCausalLM.from_pretrained(
"Qwen/Qwen3-8B",
quantization_config=quantization_config,
device_map="cuda",
)Configure FP8 de granularidade fina
Esses parâmetros de FineGrainedFP8Config alteram a forma como os pesos e as ativações são quantizados.
| Parâmetro | Padrão | Efeito |
|---|---|---|
weight_block_size | (128, 128) | Tamanho do bloco de pesos que compartilha uma única escala. Defina como None para ter uma escala por tensor de pesos. |
activation_scheme | "dynamic" | "dynamic" calcula as escalas de ativação em tempo de execução. "static" usa uma escala de ativação armazenada por camada, lida de um checkpoint pré-quantizado. |
scale_fmt | "float" | Formato de armazenamento das escalas de pesos. "float" armazena escalas em float32. "ue8m0" armazena escalas de potência de dois de 1 byte (torch.float8_e8m0fnu), como nos checkpoints do DeepSeek-V4, e requer PyTorch 2.7 ou posterior. |
expert_dtype | "fp8" | Formato dos pesos da mixture-of-experts. "fp4" carrega os especialistas empacotados em FP4 nos checkpoints do DeepSeek-V4. |
modules_to_convert | None | Tabelas de incorporação para carregar em FP8 de um checkpoint pré-quantizado, correspondidas pelo sufixo do nome do módulo. |
Carregar um checkpoint FP8 pré-quantizado
Os checkpoints quantizados com Fine-grained FP8 carregam sua configuração de quantização, portanto, carregue-os sem um FineGrainedFP8Config.
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B-FP8", device_map="cuda")O FP8 de granularidade fina também carrega checkpoints MXFP8, cuja configuração define quant_method="mxfp8". O MXFP8 armazena pesos FP8 com uma escala de potência de dois, salva como um byte, para cada bloco de 32 pesos.
Use o caminho rápido do DeepGEMM
Em GPUs Hopper (SM90) e Blackwell (SM100), as camadas lineares FP8 usam os kernels do DeepGEMM do kernels-community/deep-gemm quando weight_block_size=(128, 128) e activation_scheme="dynamic". O DeepGEMM é mais rápido que o kernel Triton padrão nos formatos que ele suporta. A instalação do kernels acima o habilita.
O DeepGEMM compila seus kernels com o nvcc do sistema na primeira vez que é executado, portanto, você precisa de um toolkit CUDA completo, não apenas de uma instalação somente de runtime. O Hopper requer CUDA 12.3 ou posterior e o Blackwell requer CUDA 12.9 ou posterior. O Transformers procura o toolkit em CUDA_HOME, depois em CUDA_PATH, depois no diretório do nvcc no seu PATH e, por fim, em /usr/local/cuda. Defina CUDA_HOME para a raiz do toolkit se o Transformers não o encontrar.
Se o DeepGEMM não conseguir carregar ou recusar uma camada, o Transformers registra um aviso e recorre ao kernel Triton. Defina TRANSFORMERS_DISABLE_DEEPGEMM_LINEAR=1 para usar sempre o kernel Triton para as camadas lineares.
No Blackwell, o DeepGEMM apenas lê escalas UE8M0. Camadas lineares com escalas float32 (scale_fmt="float") usam o kernel Triton em vez disso.
Para camadas de mixture-of-experts, o DeepGEMM é opcional. Passe experts_implementation="deepgemm" para from_pretrained(), ou "deepgemm_megamoe" no Blackwell. Consulte o guia Experts backends para todas as opções.
Limitações
- A quantização durante o carregamento requer uma GPU CUDA ou um XPU. Sem um deles, o carregamento gera um
RuntimeError. Um checkpoint pré-quantizado é carregado sem um acelerador, mas o Transformers desquantiza-o para bf16 e registra um aviso. - No CUDA, o cálculo em FP8 requer capacidade de computação 8.9 ou superior, como uma RTX 4090 ou H100. Em uma GPU mais antiga, o Transformers desquantiza o modelo para bf16 e registra um aviso.
- A quantização durante o carregamento não pode fazer offload para a CPU ou o disco. Um
device_mapque inclui"cpu"ou"disk"junto com outros dispositivos gera umValueError. Um checkpoint pré-quantizado pode fazer offload. - O DeepGEMM é desativado quando um processo distribui o modelo em vários dispositivos CUDA, e as camadas FP8 passam a usar o kernel Triton. Selecionar
experts_implementation="deepgemm"nessa configuração gera umRuntimeError. Execute paralelismo de tensor ou de especialista, com um dispositivo por processo, para manter o DeepGEMM. - No Blackwell, o backend de especialistas
"deepgemm"levanta umNotImplementedErrorpara escalas float32. Use um checkpoint comscale_fmt="ue8m0", ou os backends de especialistas"grouped_mm"ou"batched_mm". - Os backends de especialistas
"grouped_mm"e"batched_mm"não suportamactivation_scheme="static"e lançam umNotImplementedError. scale_fmt="ue8m0"requer PyTorch 2.7 ou posterior. Versões anteriores geram umRuntimeError.
Recursos
- artigo DeepSeek-V3 Technical Report
- repositório DeepGEMM