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

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

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

GGUFファイルの検索

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

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

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

HubにはGGUFファイルのビューアがあり、ユーザーはメタデータとテンソルの情報（名前、形状、精度）を確認できます。ビューアはモデルページ（例）とファイルページ（例）で利用できます。

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

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

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

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

詳細はこちらをご覧ください。

量子化の種類

型	ソース	説明
F64	Wikipedia	64ビットの標準的なIEEE 754ダブル精度浮動小数点数。
I64	GH	64ビット固定幅整数。
F32	Wikipedia	32ビットの標準的なIEEE 754単精度浮動小数点数。
I32	GH	32ビット固定幅整数。
F16	Wikipedia	16ビットの標準的なIEEE 754ハーフ精度浮動小数点数。
BF16	Wikipedia	32ビットIEEE 754単精度浮動小数点数の16ビット短縮版です。
I16	GH	16ビット固定幅整数。
Q8_K	GH	8ビット量子化（`q`）。各ブロックには256個の重みがあります。中間結果の量子化にのみ使用されます。この量子化タイプでは、すべての2〜6ビットのドット積が実装されています。重みの式: `w = q * block_scale`。
I8	GH	8ビット固定幅整数。
Q6_K	GH	6ビット量子化（`q`）。スーパーブロックは16個のブロックで構成され、各ブロックには16個の重みが含まれます。重みの式は`w = q * block_scale(8-bit)`であり、結果として1重みあたり6.5625ビットとなります。
Q5_K	GH	5ビット量子化（`q`）。スーパーブロックは8つのブロックで構成され、各ブロックには32個の重みがあります。重みの式は`w = q * block_scale(6-bit) + block_min(6-bit)`であり、結果として1重みあたり5.5ビットになります。
Q4_K	GH	4-bit量子化（`q`）。スーパーブロックは8つのブロックで構成され、各ブロックには32個の重みがあります。重みの式は`w = q * block_scale(6-bit) + block_min(6-bit)`であり、結果として1重みあたり4.5ビットになります。
Q3_K	GH	3ビット量子化（`q`）。スーパーブロックは16個のブロックで構成され、各ブロックには16個の重みが含まれます。重みの式は`w = q * block_scale(6-bit)`であり、結果として1重みあたり3.4375ビットとなります。
Q2_K	GH	2ビット量子化（`q`）。スーパーブロックは16個のブロックで構成され、各ブロックには16個の重みが含まれます。重みの計算式は`w = q * block_scale(4-bit) + block_min(4-bit)`であり、結果として1重みあたり2.625ビットとなります。
IQ4_NL	GH	4-bit量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得されます。
IQ4_XS	HF	4-bit量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり4.25ビットとなります。
IQ3_S	HF	3ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり3.44ビットとなります。
IQ3_XXS	HF	3ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり3.06ビットとなります。
IQ2_XXS	HF	2ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり2.06ビットとなります。
IQ2_S	HF	2ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり2.5ビットとなります。
IQ2_XS	HF	2ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1重みあたり2.31ビットとなります。
IQ1_S	HF	1ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1.56 bits-per-weightとなります。
IQ1_M	GH	1ビット量子化（`q`）。256個の重みを持つスーパーブロック。重み`w`は`super_block_scale`と`importance matrix`を使用して取得され、1.75ビット/重みとなります。
TQ1_0	GH	3値量子化。
TQ2_0	GH	3値量子化。
MXFP4	GH	4ビット Microscaling Block Floating Point。
レガシー型
Q8_0	GH	8ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale`。レガシーな量子化手法（現在では広く使用されていません）。
Q8_1	GH	8ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale + block_minimum`。レガシーな量子化手法（現在では広く使用されていません）。
Q5_0	GH	5ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale`。レガシーな量子化手法（現在では広く使用されていません）。
Q5_1	GH	5ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale + block_minimum`。レガシーな量子化手法（現在では広く使用されていません）。
Q4_0	GH	4ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale`。レガシーな量子化手法（現在では広く使用されていません）。
Q4_1	GH	4ビットの最近傍丸め量子化（`q`）。各ブロックには32個の重みがあります。重みの式: `w = q * block_scale + block_minimum`。レガシーな量子化手法（現在では広く使用されていません）。

上記の表に不正確な点がある場合は、このファイルに対してPRを作成してください。

Update on GitHub

←タスク llama.cppでのGGUFの使用方法→