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 等仅包含张量的文件格式不同——后者也是 Hub 推荐的模型格式——GGUF 同时编码了张量和一组标准化的元数据。

查找 GGUF 文件

您可以通过 GGUF 标签筛选所有包含 GGUF 文件的模型：hf.co/models?library=gguf。此外，您可以使用 ggml-org/gguf-my-repo 工具将您的模型权重转换/量化为 GGUF 权重。

例如，您可以查看 TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF 来了解 GGUF 文件的实际应用。

元数据与张量信息查看器

Hub 提供了一个用于 GGUF 文件的查看器，允许用户查看元数据和张量信息（名称、形状、精度）。该查看器可在模型页面（示例）和文件页面（示例）上使用。

与开源工具配合使用

使用 @huggingface/gguf 解析元数据

我们还创建了一个 JavaScript GGUF 解析器，支持解析远程托管的文件（例如 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);

在此处查找更多信息。

量化类型

类型	source	描述
F64	维基百科	64 位标准 IEEE 754 双精度浮点数。
I64	GH	64 位定宽整数。
F32	维基百科	32 位标准 IEEE 754 单精度浮点数。
I32	GH	32 位定宽整数。
F16	维基百科	16 位标准 IEEE 754 半精度浮点数。
BF16	维基百科	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)`，最终得到 6.5625 位/权重。
Q5_K	GH	5 位量化（`q`）。超级块包含 8 个块，每个块有 32 个权重。权重公式为：`w = q * block_scale(6-bit) + block_min(6-bit)`，最终实现 5.5 bits-per-weight。
Q4_K	GH	4 位量化（`q`）。超级块包含 8 个块，每个块有 32 个权重。权重公式为：`w = q * block_scale(6-bit) + block_min(6-bit)`，最终实现 4.5 位/权重。
Q3_K	GH	3 位量化（`q`）。超级块包含 16 个块，每个块有 16 个权重。权重公式为：`w = q * block_scale(6-bit)`，最终得到 3.4375 位/权重。
Q2_K	GH	2 位量化（`q`）。超级块包含 16 个块，每个块有 16 个权重。权重公式为：`w = q * block_scale(4-bit) + block_min(4-bit)`，最终得到 2.625 位/权重。
IQ4_NL	GH	4 位量化（`q`）。每个超级块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 计算得到。
IQ4_XS	HF	4 位量化（`q`）。每个超级块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 计算得出，最终实现 4.25 位/权重的精度。
IQ3_S	HF	3 位量化（`q`）。每个超级块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 计算得出，最终实现 3.44 位/权重的量化精度。
IQ3_XXS	HF	3 位量化（`q`）。每个超级块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 计算得出，最终实现 3.06 位/权重的量化精度。
IQ2_XXS	HF	2 位量化（`q`）。超块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 获得，最终实现 2.06 位/权重。
IQ2_S	HF	2 位量化（`q`）。超块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 获得，最终实现每个权重 2.5 位。
IQ2_XS	HF	2 位量化（`q`）。超块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 获得，最终实现 2.31 位/权重。
IQ1_S	HF	1 比特量化（`q`）。超块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 获得，最终实现每个权重 1.56 比特。
IQ1_M	GH	1 比特量化（`q`）。超块包含 256 个权重。权重 `w` 通过 `super_block_scale` 和 `importance matrix` 获得，最终实现每个权重 1.75 比特。
TQ1_0	GH	三元量化。
TQ2_0	GH	三元量化。
MXFP4	GH	4 位 Microscaling 块浮点。
旧版类型
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→