入门 8 分钟概念

GGUF、safetensors：理解这些格式 模型

您打开 Hugging Face 上的一个模型页面，迎面而来的是大量文件：.safetensors 文件，有时还有 .gguf 文件，以及 Q4_K_M 或 model-00001-of-00004 这样的名称。该下载哪个文件？本指南解析当下真正重要的两种格式——用于本地推理的 GGUF，以及 Hugging Face 生态中使用的 safetensors——并说明为什么 Ollama 和 LM Studio 需要 GGUF、如何正确解读文件名，以及必要时如何在这两种格式之间进行转换。

作者： Samir K.·更新于 2026-09-20·已在 Windows、macOS 和 Linux 上测试

#为何存在这些格式

一个经过训练的大型语言模型（LLM）本质上只是一个包含海量数字的巨大数据包：这些数字被称为权重（weights），即编码模型“所知”的数十亿参数。文件格式只是这些数字在磁盘上的存储方式。需要决定如何存储、如何快速读取，以及哪些附加信息（词汇表、架构、配置）应一并携带。

过去，这些权重以 PyTorch 的 .bin 格式（Python pickle）保存，使用方便，但加载缓慢，尤其存在安全风险：pickle 文件在打开时可以执行任意代码。为解决不同的问题，两种格式逐渐成为主流。safetensors 满足研究人员和平台的需求：提供安全、快速的存储，并保留原始精度。GGUF 则满足本地推理的需求：一个紧凑、经过量化的文件，可直接在消费级 CPU 或 GPU 上运行。

i
格式 ≠ 模型
同一个模型（例如 Qwen 3.5 7B）可以有多种格式。这并不是另一个模型：权重相同，只是存储方式不同。选择 GGUF 而非 safetensors 不会改变模型的智能水平，只会改变运行模型的方式。

#safetensors：Hugging Face的格式

本地 AI 套件

只需 1 小时，即可在您的电脑上拥有专属的免费 ChatGPT — LM Studio、Ollama、Open WebUI、您的文档，无需云端。

  • 在线空间，终身可用
  • PDF + 文件
  • 终身更新
本地 AI 套件 →或 所有套件终身使用权 — 49 € →

safetensors 是 Hugging Face 生态系统的默认格式。它旨在替代 PyTorch 的 pickle 格式，其首要卖点就体现在名称中：安全性。文件只包含数据（权重张量）和一个描述其形状与类型的小型 JSON 文件头。不含任何可执行代码，因此打开恶意文件也不会带来风险。另一个优势是加载更快：内存映射允许直接从磁盘读取权重，无需先将全部权重复制到内存。

设计上即保障安全
无可执行代码，与旧版 .bin/.pt pickle 文件不同。可安全下载 safetensors 文件，无需担心代码执行。
全精度
权重通常以 FP16 或 BF16（16 位）存储，有时甚至采用 FP32。这是训练时使用的精度，也是作为基准的精度。
为后续转换而设计
这是微调、模型融合（merge）、量化或转换为其他格式的起始格式。
常被分割
大型模型会被拆分成多个文件（分片），并附带一个 JSON 索引，因为单个大小达数十 GB 的文件会难以管理。

缺点是：FP16 的 safetensors 文件体积很大。一个 7B 模型约占 14 GB（每个参数 2 字节），一个 70B 模型则约占 140 GB。对于在服务器 GPU 上进行训练和研究，这是合适的选择。要在您自己的设备上运行模型，它通常过于庞大——这正是量化和 GGUF 的价值所在。

→
估算模型文件大小的经验法则
使用 FP16 时，每十亿个参数的模型文件约占 2 GB。7B 模型约为 14 GB，13B 模型约为 26 GB。经过 Q4（GGUF）量化后，每十亿个参数的文件大小降至约 0.6–0.7 GB：7B 模型降至约 4–5 GB。

#GGUF：本地推理的格式

GGUF（GPT 生成统一格式）源自 llama.cpp 项目，这是一个在 CPU 和 GPU 上高效运行大语言模型（LLM）的推理引擎。该格式于 2023 年取代了旧的 GGML 格式。其核心理念是：所有内容都打包进一个文件。权重、分词器词汇表、架构元数据（层数、上下文长度）、聊天模板——全部集成在一个文件中。您下载一个文件，直接运行即可生效。

单个自包含文件
权重、分词器和元数据都在一个 .gguf 文件中。无需凑齐一个配置目录，也无需安装 Python 依赖。
量化
专为存储压缩权重（4、5、6、8 位）而设计。这让大模型也能在消费级硬件上运行。
CPU + GPU + offload
llama.cpp 可以将层分布在 GPU 和系统内存之间。这样可以运行比 VRAM 更大的模型，但会带来一定的速度损耗。
可移植
同一个.gguf文件可在Windows、macOS（Metal）、Linux上运行，支持Ollama、LM Studio、Jan或llama.cpp直接运行。

量化是本主题的核心。它指的是将每个权重存储在少于比特（例如从 16 位降至 4 位），从而将模型大小缩小 3 到 4 倍，且若选择得当，质量损失极小。这使得一个 7B 模型可以仅占用约 5 GB VRAM，而非原来的 14 GB。常见的量化级别包括：Q4_K_M（最佳平衡，推荐默认）、Q5_K_M（质量上提升一级）、Q8_0（几乎无损，但更重）以及 FP16（未量化，为基准）。

i
GGUF并不一定等同于量化
也可以生成 FP16 的 GGUF，不进行量化。但在 99% 的情况下，如果您下载一个 GGUF，它是一个量化版本：这正是该格式大放异彩的用途。

#为什么 Ollama 和 LM Studio 需要 GGUF

Ollama 和 LM Studio 基于 llama.cpp（或同类引擎）构建，而 llama.cpp 原生支持 GGUF。这并非随意的选择：正是这一点让这些工具如此易用。由于 GGUF 已经包含分词器、架构和聊天模板，工具无需猜测。它读取文件、分配内存，然后就能回答您。无需 Python 环境，无需解决依赖问题，也无需编写配置。

当您执行 `ollama pull llama3.2` 时，Ollama 实际上会从其模型分发仓库下载一个 GGUF 文件，并将其存入本地模型存储区。您始终看不到文件本身，但底层确实使用 GGUF 格式。而 LM Studio 会在下载时明确展示可用的 GGUF 文件及其量化版本。

终端
# Ollama récupère un GGUF depuis sa registry et le sert sur localhost:11434
ollama pull llama3.2
ollama run llama3.2

# Vérifier que le daemon répond
curl http://localhost:11434/api/tags
→
在 Ollama 中加载外部 GGUF 模型
您是手动下载的.gguf文件（例如从Hugging Face下载）？Ollama可以通过一个仅包含两行的Modelfile导入：`FROM ./mon-modele.gguf`，然后`ollama create mon-modele -f Modelfile`。LM Studio则会自动检测其模型目录中放置的.gguf文件。

#正确解读文件名

在 Hugging Face 上，GGUF 文件名遵循一套命名规则，了解各部分的含义后就能读懂。以一个典型例子来看：`Qwen2.5-7B-Instruct-Q4_K_M.gguf`。其中每一部分都包含一项信息。

Qwen2.5
模型的系列和版本。
7B
参数数量：70亿。这是确定所需VRAM的首个指标。
Instruct
经过训练、能够遵循指令并进行对话的变体（与原始、未经聊天对齐的 -base 版本相对）。
Q4_K_M
量化：4 位，K_M（中等）变体。默认推荐的质量与大小平衡方案。
.gguf
格式。您知道它可在 Ollama、LM Studio 或 llama.cpp 中运行，无需转换。

量化后缀是最值得解读的部分。数字表示每个权重的比特数；字母 K_S / K_M / K_L 表示不同变体（Small、Medium、Large），它们对敏感层的保护程度有所不同。数字越大，文件越大，保真度也越高。

Q4_K_M
约 4 位，中等。默认选择：在绝大多数情况下，同等大小下质量最佳。
Q5_K_M
约 5 位。质量更高一档，文件也稍大。显存足够时是不错的选择。
Q8_0
8 位。与未量化版本几乎无法区分，但体积是 Q4 的两倍。适合追求原始模型效果的用户或要求较高的任务。
Q2_K / Q3_K
2–3 位。体积非常小，但质量下降明显。仅在内存确实十分紧张时使用。
FP16 / F16
未量化，16位全精度。是参考版本，但体积庞大——这种情况下最好使用safetensors。
!
分片模型的陷阱
过大的GGUF文件有时会被分割：`model-00001-of-00002.gguf`，`model-00002-of-00002.gguf`。必须下载所有片段并保存在同一个文件夹中——引擎会将其重新组合。不要只取一个分割文件，以为自己已经获得了完整模型。

#根据所用工具选择下载版本

实际需要考虑的问题归根结底是：我要使用哪个工具？格式取决于这个问题的答案，而不是反过来。

Ollama、LM Studio、Jan、llama.cpp
→ GGUF。这些工具专为该用途设计。请根据您的显存选择量化方式（默认为Q4_K_M）
vLLM、TGI、Transformers（Python）
→ safetensors。这些服务器引擎加载 Hugging Face 原生格式，通常以 FP16 或其自定义量化方式（AWQ、GPTQ）运行。
微调、合并、自行量化
→ safetensors。这是工作格式：从全精度开始，将模型进行转换。
您还没有确定
→ 如果要在您自己的机器上本地使用，选择量化后的 GGUF 模型。这是最简单、最节省资源的选择。

选择合适的量化方式时，应以您的显存容量为依据。Q4 量化参考：3B 模型约需 2 GB，7B 约需 5 GB，14B 约需 9 GB，32B 约需 19 GB，70B 约需 40 GB。RTX 3060 12 GB 可流畅运行 Q4 量化的 7B 至 14B 模型；RTX 4090 24 GB 可将 32B 作为目标；若要运行 70B，则应选择大显存显卡或配备统一内存的 Mac（M4 Pro 24–48 GB）。

→
如有疑问，使用Q4_K_M
十次中有九次，Q4_K_M 版本就是该选的文件：它在质量与内存占用之间提供最佳平衡，而且能装入大多数消费级 GPU 的显存。只有在显存有余量且有明确的质量需求时，才升级到 Q5_K_M 或 Q8_0。

#将safetensors转换为GGUF

有时，模型发布时只有 safetensors 格式（发布当天经常如此），而您希望在 Ollama 中运行它。这时需要先将其转换为 GGUF 格式，然后视需要进行量化。常用的标准工具是 llama.cpp 提供的脚本 `convert_hf_to_gguf.py`。整个过程分为两步：先转换为全精度 GGUF，再使用 `llama-quantize` 工具进行量化。

  1. 01
    获取llama.cpp及其依赖项
    克隆 llama.cpp 仓库并安装转换脚本所需的 Python 依赖。convert_hf_to_gguf.py 就包含在该仓库中。
  2. 02
    下载safetensors模型
    从Hugging Face获取模型完整文件夹（包括.safetensors权重文件、config.json和分词器文件）。所有文件都必须存在，而不仅仅是权重文件。
  3. 03
    转换为 GGUF FP16 格式
    以模型文件夹为输入运行 convert_hf_to_gguf.py。您将得到一个全精度（16 位）的 .gguf 文件，体积较大，但保真度高。
  4. 04
    量化为 Q4_K_M
    将 GGUF FP16 通过 llama-quantize 转换，选择所需级别（默认为 Q4_K_M）。最终文件大小减少 3 到 4 倍。
  5. 05
    导入到 Ollama
    编写一个指向量化 .gguf 模型的 Modelfile，并使用 ollama create 创建模型。创建后，该模型即可像其他 Ollama 模型一样使用。
终端
# 1. Cloner llama.cpp et installer les dépendances de conversion
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Convertir le dossier safetensors en GGUF pleine précision
python convert_hf_to_gguf.py ./mon-modele-hf --outfile mon-modele-f16.gguf --outtype f16

# 3. Quantifier en Q4_K_M (compromis recommandé)
./llama-quantize mon-modele-f16.gguf mon-modele-Q4_K_M.gguf Q4_K_M
Modelfile + 导入 Ollama
# Créer un Modelfile minimal
printf 'FROM ./mon-modele-Q4_K_M.gguf\n' > Modelfile

# Enregistrer le modèle dans Ollama
ollama create mon-modele -f Modelfile
ollama run mon-modele
!
转换不会提升质量
先转换再量化并不会让模型变得更好——相反，每一步量化都会损失一点精度。如果已有官方 GGUF 版本（通常由社区发布，例如 Hugging Face 上的“GGUF”仓库），请直接下载，而不要自行转换：这样更快，而且通常经过更好的校准。

#其他可能遇到的格式

GGUF 和 safetensors 涵盖了大多数情况，但下载模型时还会遇到其他一些格式名称。了解它们可以避免遇到意料之外的问题。

.bin / .pt（pickle）
旧版 PyTorch 格式。功能可用但不安全（可能执行代码）。正逐步被 safetensors 取代——若存在替代方案，应避免使用。
GPTQ / AWQ
用于 vLLM 和 Transformers 的 GPU 量化版本，以 safetensors 格式存储。在 NVIDIA GPU 上运行速度快，但 Ollama/llama.cpp 无法读取。
MLX
Apple 为其 MLX 框架提供的格式，针对 Apple Silicon 芯片进行了优化。部分 Mac 原生应用使用这种格式，它与 GGUF 不同。
ONNX
一种多框架的交换格式，尤其适用于工业部署和边缘场景。对于大众本地 LLM 使用场景而言较为罕见。
GGML
GGUF 的前身（相同项目）。已过时：若遇到 .ggml 文件，请查找对应的 .gguf 版本。

#常见问题

GGUF 还是 safetensors，哪个更好？
没有哪一种绝对更好：它们适用于不同用途。GGUF 用于在本地运行模型（Ollama、LM Studio），safetensors 用于 Hugging Face 生态、微调和服务器端引擎。哪一种“最好”取决于您使用的工具。
GGUF模型是否比safetensors差？
量化后的GGUF模型相比原始的safetensors FP16会略有精度损失。在Q4_K_M或Q5_K_M情况下，差异极小，日常使用中几乎不可察觉；而在Q2或Q3时，差异则变得明显。
我能否直接在Ollama中使用safetensors？
大多数情况下不直接支持：Ollama 需要 GGUF 格式。必须先使用 llama.cpp 将 safetensors 转换为 GGUF 格式。部分较新版本支持 safetensors 导入，但 GGUF 仍是更可靠的选择。
为什么Hugging Face页面上会有这么多文件？
模型通常被拆分为多个分片（safetensors 或 GGUF），此外还有配置文件和分词器文件。对于 GGUF，您通常只需要所选量化版本的一个文件（如果该版本被拆分，则需要这一系列的全部分片）。

#深入了解

现在您已经了解了这些格式，以下指南可以帮助您进一步探索这一主题。

选择量化方案（Q4、Q5、Q8、FP16）
根据您的显存大小和对质量的需求，详细指导如何选择GGUF文件的量化级别。
Ollama 是什么以及它如何工作
了解用于在本地下载 GGUF 模型并提供模型服务的工具，以及它的基本命令。
理解上下文窗口
另一个影响内存使用的参数是 token 和上下文，需与量化方式的选择相结合。
这份指南对您有帮助吗？

有反馈、发现了错误，或想补充说明？请告诉我们，让这份指南对每个人都更有帮助。