Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

GGUF

O Hugging Face Hub suporta todos os formatos de arquivo, mas possui recursos integrados para o formato GGUF, um formato binário otimizado para carregamento e salvamento rápidos de modelos, tornando-o altamente eficiente para fins de inferência. O GGUF foi projetado para uso com GGML e outros executores. O GGUF foi desenvolvido por @ggerganov, que também é o desenvolvedor do llama.cpp, um popular framework de inferência de LLM em C/C++. Modelos inicialmente desenvolvidos em frameworks como PyTorch podem ser convertidos para o formato GGUF para uso com esses motores.

Como podemos ver neste gráfico, diferentemente dos formatos de arquivo apenas de tensores, como safetensors – que também é um formato de modelo recomendado para o Hub – o GGUF codifica tanto os tensores quanto um conjunto padronizado de metadados.

Localizando arquivos GGUF

Você pode navegar por todos os modelos com arquivos GGUF filtrando pela tag GGUF: hf.co/models?library=gguf. Além disso, você pode usar a ferramenta ggml-org/gguf-my-repo para converter/quantizar os pesos do seu modelo em pesos GGUF.

Por exemplo, você pode conferir TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF para ver arquivos GGUF em ação.

Visualizador de metadados e informações de tensores

O Hub possui um visualizador para arquivos GGUF que permite ao usuário verificar metadados e informações dos tensores (nome, forma, precisão). O visualizador está disponível na página do modelo (exemplo) e na página de arquivos (exemplo).

Uso com ferramentas de código aberto

Analisando os metadados com @huggingface/gguf

Também criamos um parser GGUF em javascript que funciona com arquivos hospedados remotamente (por exemplo, no Hugging Face Hub).

npm install @huggingface/gguf

import { gguf } from "@huggingface/gguf";
// remote GGUF file from https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF
const URL_LLAMA = "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/191239b/llama-2-7b-chat.Q2_K.gguf";
const { metadata, tensorInfos } = await gguf(URL_LLAMA);

Encontre mais informações aqui.

Tipos de Quantização

type	source	descrição
F64	Wikipedia	Número de ponto flutuante de precisão dupla padrão IEEE 754 de 64 bits.
I64	GH	Número inteiro de largura fixa de 64 bits.
F32	Wikipedia	Número de ponto flutuante de precisão simples padrão IEEE 754 de 32 bits.
I32	GH	Número inteiro de largura fixa de 32 bits.
F16	Wikipedia	Número de ponto flutuante de meia precisão padrão IEEE 754 de 16 bits.
BF16	Wikipedia	Versão reduzida de 16 bits do número de ponto flutuante de precisão simples IEEE 754 de 32 bits.
I16	GH	Número inteiro de largura fixa de 16 bits.
Q8_K	GH	Quantização de 8 bits (`q`). Cada bloco possui 256 pesos. Usado apenas para quantizar resultados intermediários. Todos os produtos escalares de 2 a 6 bits são implementados para este tipo de quantização. Fórmula do peso: `w = q * block_scale`.
I8	GH	Número inteiro de largura fixa de 8 bits.
Q6_K	GH	Quantização de 6 bits (`q`). Super-blocos com 16 blocos, cada bloco possui 16 pesos. Fórmula do peso: `w = q * block_scale(8-bit)`, resultando em 6,5625 bits por peso.
Q5_K	GH	Quantização de 5 bits (`q`). Super-blocos com 8 blocos, cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale(6-bit) + block_min(6-bit)`, resultando em 5,5 bits por peso.
Q4_K	GH	Quantização de 4 bits (`q`). Super-blocos com 8 blocos, cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale(6-bit) + block_min(6-bit)`, resultando em 4,5 bits por peso.
Q3_K	GH	Quantização de 3 bits (`q`). Super-blocos com 16 blocos, cada bloco possui 16 pesos. Fórmula do peso: `w = q * block_scale(6-bit)`, resultando em 3,4375 bits por peso.
Q2_K	GH	Quantização de 2 bits (`q`). Super-blocos com 16 blocos, cada bloco possui 16 pesos. Fórmula do peso: `w = q * block_scale(4-bit) + block_min(4-bit)`, resultando em 2,625 bits por peso.
IQ4_NL	GH	Quantização de 4 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`.
IQ4_XS	HF	Quantização de 4 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 4,25 bits por peso.
IQ3_S	HF	Quantização de 3 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 3,44 bits por peso.
IQ3_XXS	HF	Quantização de 3 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 3,06 bits por peso.
IQ2_XXS	HF	Quantização de 2 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 2,06 bits por peso.
IQ2_S	HF	Quantização de 2 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 2,5 bits por peso.
IQ2_XS	HF	Quantização de 2 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 2,31 bits por peso.
IQ1_S	HF	Quantização de 1 bit (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 1,56 bits por peso.
IQ1_M	GH	Quantização de 1 bit (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`, resultando em 1,75 bits por peso.
TQ1_0	GH	Quantização ternária.
TQ2_0	GH	Quantização ternária.
MXFP4	GH	4-bit Microscaling Block Floating Point.
Tipos legados
Q8_0	GH	Quantização 8-bit round-to-nearest (`q`). Cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale`. Método de quantização legado (não amplamente utilizado atualmente).
Q8_1	GH	Quantização 8-bit round-to-nearest (`q`). Cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale + block_minimum`. Método de quantização legado (não amplamente utilizado atualmente).
Q5_0	GH	Quantização de 5 bits com arredondamento para o mais próximo (`q`). Cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale`. Método de quantização legado (não amplamente utilizado atualmente).
Q5_1	GH	Quantização de 5 bits com arredondamento para o mais próximo (`q`). Cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale + block_minimum`. Método de quantização legado (não amplamente utilizado atualmente).
Q4_0	GH	Quantização 4-bit round-to-nearest (`q`). Cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale`. Método de quantização legado (não amplamente utilizado atualmente).
Q4_1	GH	Quantização 4-bit round-to-nearest (`q`). Cada bloco possui 32 pesos. Fórmula do peso: `w = q * block_scale + block_minimum`. Método de quantização legado (não amplamente utilizado atualmente).

se houver alguma imprecisão na tabela acima, abra um PR no este arquivo.

Update on GitHub

←Tarefas Uso de GGUF com llama.cpp→