# GGUF

Hugging Face Hub はすべてのファイル形式をサポートしていますが、[GGUF 形式](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md)には組み込みの機能が用意されています。GGUF はモデルの高速な読み込みと保存に最適化されたバイナリ形式であり、推論用途において非常に効率的です。GGUF は GGML およびその他のエグゼキュータでの使用を目的として設計されています。GGUF は [@ggerganov](https://huggingface.co/ggerganov) によって開発されました。彼はまた、人気のある C/C++ 製 LLM 推論フレームワークである [llama.cpp](https://github.com/ggerganov/llama.cpp) の開発者でもあります。PyTorch などのフレームワークで最初に開発されたモデルは、これらのエンジンで使用するために GGUF 形式に変換できます。

このグラフからわかるように、[safetensors](https://huggingface.co/docs/safetensors)のようなテンソルのみを格納するファイル形式とは異なり、GGUFはテンソルと標準化されたメタデータセットの両方をエンコードします。なお、Hubの推奨モデル形式でもあります。

## GGUFファイルの検索

GGUFタグでフィルタリングして、GGUFファイルを持つすべてのモデルを閲覧できます: [hf.co/models?library=gguf](https://huggingface.co/models?library=gguf)。また、[ggml-org/gguf-my-repo](https://huggingface.co/spaces/ggml-org/gguf-my-repo)ツールを使用して、モデルの重みをGGUF形式の重みに変換/量子化できます。

例えば、GGUFファイルの実際の使用例を確認するには、[TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF)をご覧ください。

## メタデータとテンソル情報のビューア

HubにはGGUFファイルのビューアがあり、ユーザーはメタデータとテンソルの情報（名前、形状、精度）を確認できます。ビューアはモデルページ（[例](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF?show_tensors=mixtral-8x7b-instruct-v0.1.Q4_0.gguf)）とファイルページ（[例](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF/tree/main?show_tensors=mixtral-8x7b-instruct-v0.1.Q5_K_M.gguf)）で利用できます。

## オープンソースツールでの使用

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

## @huggingface/ggufでメタデータを解析する

リモートでホストされているファイル（Hugging Face Hub など）で動作する JavaScript 製の GGUF パーサーも作成しました。

```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);
```

詳細は[こちら](https://github.com/huggingface/huggingface.js/tree/main/packages/gguf)をご覧ください。

## 量子化の種類

| 型         | ソース | 説明 |
|---------------------------|--------|-------------|
| F64 | [Wikipedia](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | 64ビットの標準的なIEEE 754ダブル精度浮動小数点数。 |
| I64 | [GH](https://github.com/ggerganov/llama.cpp/pull/6062) | 64ビット固定幅整数。 |
| F32  | [Wikipedia](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) | 32ビットの標準的なIEEE 754単精度浮動小数点数。 |
| I32 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | 32ビット固定幅整数。 |
| F16  | [Wikipedia](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) | 16ビットの標準的なIEEE 754ハーフ精度浮動小数点数。 |
| BF16 | [Wikipedia](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) | 32ビットIEEE 754単精度浮動小数点数の16ビット短縮版です。 |
| I16 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | 16ビット固定幅整数。 |
| Q8_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 8ビット量子化（`q`）。各ブロックには256個の重みがあります。中間結果の量子化にのみ使用されます。この量子化タイプでは、すべての2〜6ビットのドット積が実装されています。重みの式: `w = q * block_scale`。 |
| I8 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | 8ビット固定幅整数。 |
| Q6_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 6ビット量子化（`q`）。スーパーブロックは16個のブロックで構成され、各ブロックには16個の重みが含まれます。重みの式は`w = q * block_scale(8-bit)`であり、結果として1重みあたり6.5625ビットとなります。 |
| Q5_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 5ビット量子化（`q`）。スーパーブロックは8つのブロックで構成され、各ブロックには32個の重みがあります。重みの式は`w = q * block_scale(6-bit) + block_min(6-bit)`であり、結果として1重みあたり5.5ビットになります。 |
| Q4_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 4-bit量子化（`q`）。スーパーブロックは8つのブロックで構成され、各ブロックには32個の重みがあります。重みの式は`w = q * block_scale(6-bit) + block_min(6-bit)`であり、結果として1重みあたり4.5ビットになります。 |
| Q3_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 3ビット量子化（`q`）。スーパーブロックは16個のブロックで構成され、各ブロックには16個の重みが含まれます。重みの式は`w = q * block_scale(6-bit)`であり、結果として1重みあたり3.4375ビットとなります。 |
| Q2_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 2ビット量子化（`q`）。スーパーブロックは16個のブロックで構成され、各ブロックには16個の重みが含まれます。重みの計算式は`w = q * block_scale(4-bit) + block_min(4-bit)`であり、結果として1重みあたり2.625ビットとなります。 |
| IQ4_NL | [GH](https://github.com/ggerganov/llama.cpp/pull/5590) | 4-bit量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`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) | 4-bit量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり4.25ビットとなります。 |
| IQ3_S | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 3ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり3.44ビットとなります。 |
| IQ3_XXS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 3ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり3.06ビットとなります。 |
| IQ2_XXS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 2ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり2.06ビットとなります。 |
| IQ2_S | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 2ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり2.5ビットとなります。 |
| IQ2_XS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 2ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり2.31ビットとなります。 |
| IQ1_S | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 1ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1.56 bits-per-weightとなります。 |
| IQ1_M | [GH](https://github.com/ggerganov/llama.cpp/pull/6302) | 1ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1.75ビット/重みとなります。 |
| TQ1_0 | [GH](https://github.com/ggml-org/llama.cpp/pull/8151) | 3値量子化。 |
| TQ2_0 | [GH](https://github.com/ggml-org/llama.cpp/pull/8151) | 3値量子化。 |
| MXFP4 | [GH](https://github.com/ggml-org/llama.cpp/pull/15091) | 4ビット Microscaling Block Floating Point。 |
| **レガシー型** | | |
| Q8_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 8ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale`。レガシーな量子化手法（現在では広く使用されていません）。 |
| Q8_1 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 8ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale + block_minimum`。レガシーな量子化手法（現在では広く使用されていません）。 |
| Q5_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 5ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale`。レガシーな量子化手法（現在では広く使用されていません）。 |
| Q5_1 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 5ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale + block_minimum`。レガシーな量子化手法（現在では広く使用されていません）。 |
| Q4_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 4ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale`。レガシーな量子化手法（現在では広く使用されていません）。 |
| Q4_1 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 4ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale + block_minimum`。レガシーな量子化手法（現在では広く使用されていません）。 |

*上記の表に不正確な点がある場合は、[このファイル](https://github.com/huggingface/huggingface.js/blob/main/packages/gguf/src/quant-descriptions.ts)に対してPRを作成してください。*