Transformers documentation

FP8 de granularidade fina

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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.

ConfigFineGrainedFP8Config
quant_methodfp8, mxfp8
Fluxo de trabalhoQuantize ao carregar, carregar pré-quantizado
Bits8
HardwareCUDA (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]" accelerate

Quantize 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âmetroPadrãoEfeito
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_convertNoneTabelas 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_map que inclui "cpu" ou "disk" junto com outros dispositivos gera um ValueError. 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 um RuntimeError. Execute paralelismo de tensor ou de especialista, com um dispositivo por processo, para manter o DeepGEMM.
  • No Blackwell, o backend de especialistas "deepgemm" levanta um NotImplementedError para escalas float32. Use um checkpoint com scale_fmt="ue8m0", ou os backends de especialistas "grouped_mm" ou "batched_mm".
  • Os backends de especialistas "grouped_mm" e "batched_mm" não suportam activation_scheme="static" e lançam um NotImplementedError.
  • scale_fmt="ue8m0" requer PyTorch 2.7 ou posterior. Versões anteriores geram um RuntimeError.

Recursos

Update on GitHub