# GGUF

O Hugging Face Hub suporta todos os formatos de arquivo, mas possui recursos integrados para o [formato GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md), 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](https://huggingface.co/ggerganov), que também é o desenvolvedor do [llama.cpp](https://github.com/ggerganov/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](https://huggingface.co/docs/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](https://huggingface.co/models?library=gguf). Além disso, você pode usar a ferramenta [ggml-org/gguf-my-repo](https://huggingface.co/spaces/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](https://huggingface.co/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](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF?show_tensors=mixtral-8x7b-instruct-v0.1.Q4_0.gguf)) e na página de arquivos ([exemplo](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF/tree/main?show_tensors=mixtral-8x7b-instruct-v0.1.Q5_K_M.gguf)).

## Uso com ferramentas de código aberto

* [llama.cpp](./gguf-llamacpp)
* [LM Studio](./lmstudio)
* [GPT4All](./gguf-gpt4all)
* [Ollama](./ollama)

## 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).

```bash
npm install @huggingface/gguf
```

```ts
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](https://github.com/huggingface/huggingface.js/tree/main/packages/gguf).

## Tipos de Quantização

| type         | source | descrição |
|---------------------------|--------|-------------|
| F64 | [Wikipedia](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | Número de ponto flutuante de precisão dupla padrão IEEE 754 de 64 bits. |
| I64 | [GH](https://github.com/ggerganov/llama.cpp/pull/6062) | Número inteiro de largura fixa de 64 bits. |
| F32  | [Wikipedia](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) | Número de ponto flutuante de precisão simples padrão IEEE 754 de 32 bits. |
| I32 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | Número inteiro de largura fixa de 32 bits. |
| F16  | [Wikipedia](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) | Número de ponto flutuante de meia precisão padrão IEEE 754 de 16 bits. |
| BF16 | [Wikipedia](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) | Versão reduzida de 16 bits do número de ponto flutuante de precisão simples IEEE 754 de 32 bits. |
| I16 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | Número inteiro de largura fixa de 16 bits. |
| Q8_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 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](https://github.com/ggerganov/llama.cpp/pull/6045) | Número inteiro de largura fixa de 8 bits. |
| Q6_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 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](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 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](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 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](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 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](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 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](https://github.com/ggerganov/llama.cpp/pull/5590) | Quantização de 4 bits (`q`). Super-blocos com 256 pesos. O peso `w` é obtido usando `super_block_scale` & `importance matrix`. |
| IQ4_XS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 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](https://github.com/ggerganov/llama.cpp/pull/6302) | 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](https://github.com/ggml-org/llama.cpp/pull/8151) | Quantização ternária. |
| TQ2_0 | [GH](https://github.com/ggml-org/llama.cpp/pull/8151) | Quantização ternária. |
| MXFP4 | [GH](https://github.com/ggml-org/llama.cpp/pull/15091) | 4-bit Microscaling Block Floating Point. |
| **Tipos legados** | | |
| Q8_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 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](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 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](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 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](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 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](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 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](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 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](https://github.com/huggingface/huggingface.js/blob/main/packages/gguf/src/quant-descriptions.ts).*