将 Hugging Face 的 GGUF 模型导入 Ollama

#为何从 Hugging Face 导入 GGUF 模型

Ollama 维护着一个实用的模型库（ollama.com/library），但有意限制其收录范围：维护者在其中发布需求最多的模型，并为这些模型选定量化版本。当您需要专业领域的微调模型、刚发布的版本、法语模型或某个特定的量化版本时，就得去 Hugging Face 寻找——它是最大的开放权重模型共享平台。

GGUF 格式（GGML 的后继格式）是 Ollama 原生支持的格式：一个文件中包含量化后的权重、分词器和模型元数据。TheBloke、bartowski 或 unsloth 等贡献者发布了数千个可直接使用的 GGUF 文件，每个模型通常有十种左右的量化版本。掌握导入方法，就能在您的 Ollama 安装环境中使用这一整个生态系统的资源。

近期模型

昨天刚在 Hugging Face 上发布的模型，甚至在出现在 Ollama 官方模型库之前就可以使用。

细分领域的微调模型

专门针对代码、医学、角色扮演或法语的模型，尚无人将它们正式打包发布。

精确选择量化级别

精确选择适合您VRAM的量化级别（Q4_K_M、Q5_K_M、Q8_0…），而非仅使用默认变体。

私有模型

您自己微调的模型或下载的 GGUF 模型，通过 Modelfile 导入本地。

#先决条件

Ollama 已安装

需要较新的版本（0.5+）才能原生支持 hf.co。守护进程默认在 http://localhost:11434 监听。请使用“ollama --version”检查版本。

互联网连接

用于直接从 Hugging Face 下载的直接方法。之后模型 100% 在本地运行。

足够的VRAM或RAM

Q4 量化参考：7B 模型约需 5 GB，14B 约需 9 GB，32B 约需 19 GB，70B 约需 40 GB。没有 GPU 时，内存（RAM）是关键，但速度会更慢。

一个GGUF仓库的名称

例如 bartowski/Qwen3.5-9B-Instruct-GGUF。请在模型的 Hugging Face 页面 URL 中查找该路径。

要查找 GGUF 仓库，Hugging Face 搜索支持按格式筛选。搜索模型名称并加上“GGUF”，或在侧边栏按“GGUF”库筛选。打开“Files and versions”选项卡：您会看到 .gguf 文件列表，每种量化对应一个文件，并标有以 GB 为单位的文件大小——这对后续操作很有帮助。

#直接方法：ollama run hf.co/...

这是将 Hugging Face 的 GGUF 模型导入 Ollama 的最简单方法。自 0.5 版本起，Ollama 可通过单条命令直接从 Hugging Face 仓库拉取 GGUF 模型，无需手动下载文件或编写 Modelfile。语法采用仓库路径，以 hf.co/ 开头。

# Format : ollama run hf.co/{utilisateur}/{depot}
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF

如果不明确指定，Ollama 会选择默认的量化版本（通常是 Q4_K_M，前提是仓库中提供该版本）。要指定某个量化版本，请将其加在冒号后，写法与普通模型标签完全相同。标签名对应 .gguf 文件名的后缀，不区分大小写。

# Choisir explicitement Q5_K_M
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q5_K_M

# Ou une version plus légère pour une petite carte
ollama run hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M

Ollama 会下载文件，将其保存到本地存储中，然后启动对话。此后，模型会在「ollama list」中以完整名称 hf.co/... 显示，并可立即再次启动。如果您觉得完整名称输入起来太长，可以使用「ollama cp」为它设置一个更短的别名。

# Copier vers un alias court
ollama cp hf.co/bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M qwen-fr

# Désormais utilisable simplement
ollama run qwen-fr

#根据VRAM选择合适的量化方式

同一模型会发布多个量化版本：量化是模型质量与内存占用之间的核心权衡。量化越激进（每个权重使用的比特数越少），文件就越小，也就越容易装入配置较低的显卡显存中，但代价是轻微的精度损失。正确的做法是选择显存能够容纳且仍留有余量的最高精度量化版本。

Q4_K_M — 推荐

对于绝大多数用途，这是最佳折中方案。质量损失几乎不可察觉，内存占用更低。如果您犹豫不决，可将其作为默认选择。

Q5_K_M——再上一个档次

占用空间略大，精度略高。如果您的显存还有余量，并且希望在不转为 8 位量化的情况下获得尽可能高的质量，这是一个值得考虑的选择。

Q8_0 — 几乎无损

与未量化模型非常接近，但体积约为 Q4 的两倍。仅适用于连最轻微的质量下降都很重要、且显存充足的情况。

FP16 — 全精度

未量化的模型，体积最大。本地推理很少需要使用它：Q8_0 几乎总能满足需求，而且能将内存占用减半。

要估算某个量化版本能否装入显存，请参考 Hugging Face 上显示的 .gguf 文件大小，并额外预留约 1 至 2 GB 给上下文和系统。以下列出了不同规模模型在 Q4_K_M 量化下的显存需求参考值，以及通常能运行这些模型的 GPU。

3B ≈ 2 GB

各种设备都能运行，即使是入门级显卡或仅用 CPU 也可以。非常适合 RTX 3060 12 GB，还能为上下文留出充足空间。

7B ≈ 5 GB

在 RTX 3060 12 GB 和 RTX 4070 12 GB 上可轻松运行。这是日常使用中用途最广的模型规格。

14B ≈ 9 GB

RTX 4070 12 GB 勉强够用，RTX 4080 16 GB 则比较宽裕。对于推理和编程，这是一个不错的质量档位。

32B ≈ 19 GB

RTX 4090 24 GB，或配备统一内存的 Mac M4 Pro。这是在工作站上也能用得起的高端配置。

70B ≈ 40 GB

需要至少 48 GB：配备大容量统一内存的 Mac Studio，或多 GPU 配置。请改用 Q4，甚至更激进的量化方式。

#Modelfile 方法：FROM fichier.gguf

直接方法的前提是 GGUF 文件位于 Hugging Face 上，并且可以在线访问。但如果您已经手动下载了一个 .gguf 文件、用 llama.cpp 生成了自己的文件，或希望自定义模型（系统提示词、参数），就需要使用 Modelfile。这是一个类似 Dockerfile 的小型文本文件，用于描述如何从本地 GGUF 文件构建 Ollama 模型。

核心指令是FROM，它指向.gguf文件的路径。在GGUF文件同目录下创建一个名为「Modelfile」（无扩展名）的文件，至少包含这一行内容。

FROM ./mon-modele.Q4_K_M.gguf

然后使用「ollama create」命令构建模型，并为其指定您选择的名称。Ollama 会读取 GGUF 文件，将其保存到自己的存储中，并使其像其他模型一样可供使用。

# Construire le modèle depuis le Modelfile du dossier courant
ollama create mon-modele -f ./Modelfile

# Le lancer
ollama run mon-modele

完整的Modelfile可实现更丰富的功能：设置系统提示、调整采样参数，尤其是定义TEMPLATE——即模型所期望的对话格式。正如后续章节所示，大多数质量相关问题都可在此处解决。

FROM ./mon-modele.Q4_K_M.gguf

# System prompt par défaut
SYSTEM """Tu es un assistant francophone concis et précis."""

# Paramètres d'inférence
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER stop "<|im_end|>"

# Template de chat (exemple format ChatML)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

#修复聊天模板错误

这是导入 GGUF 时最常见的陷阱。导入的模型可能胡乱作答：句子一直生成、无法结束，输出中出现奇怪的标记（<|im_end|>、[INST]、<end_of_turn>），回答忽略问题或陷入循环。十次中有九次，并不是模型本身不好——而是聊天模板与模型训练时使用的模板不匹配。

每个模型家族都要求特定的对话格式：ChatML（<|im_start|>）用于 Qwen 和许多微调模型，[INST]...[/INST] 用于 Mistral 和 Llama 2，<start_of_turn> 用于 Gemma，而 Llama 3 使用专门的格式。如果 GGUF 的元数据中包含错误的模板，或者 Ollama 推断出了错误的模板，回答质量就会下降。最常见的症状是：本应停止生成的回合结束标记，却直接出现在回答中。

症状：标记直接显示出来

模型在回答中显示 <|im_end|> 或 <|eot_id|>。缺少相应的 PARAMETER stop 设置，或者模板没有输出正确的结束 token。

症状：无限生成

模型始终不停止生成，还会自行接着生成后续对话轮次。预期的停止token未声明。

症状：回答混乱

模型忽略了系统提示或回答偏离主题。角色格式（system/user/assistant）与训练时的格式不匹配。

修正方法是在 Modelfile 中提供正确的 TEMPLATE 和 PARAMETER stop 设置。应以原始模型在 Hugging Face 上的“model card”为准：查找“prompt format”或“chat template”部分，其中说明了确切格式。对于采用 ChatML 格式的模型（Qwen 及其衍生模型），模板和停止条件大致如下。

FROM ./mon-modele.Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>
"""

PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"

随后使用“ollama create”重建并测试。获取正确模板而无需重写的一个有效技巧是：从 Ollama 中已有的同系列官方模型入手，查看它生成的 Modelfile，然后复用其中的 TEMPLATE 代码块。

# Voir le Modelfile complet d'un modèle officiel de la même famille
ollama show --modelfile qwen3.5:9b

# Copiez-en le bloc TEMPLATE et les PARAMETER stop
# dans votre propre Modelfile, puis reconstruisez
ollama create mon-modele -f ./Modelfile

#故障排除

'Error: pull model manifest'

hf.co路径拼写错误，仓库为私有/受限，或您的Ollama版本过旧。请检查仓库的准确URL，并更新Ollama。

量化标签不存在

如果Ollama提示找不到标签，请在Hugging Face上打开“Files and versions”，并复制.gguf文件的准确后缀（例如Q4_K_M、IQ4_XS）。大小写会被忽略，但名称必须匹配。

模型非常缓慢 / 响应断断续续

由于 VRAM 不足，模型的一部分被转移到系统 RAM 中，并由 CPU 运行。请使用“ollama ps”检查它是在 GPU 还是 CPU 上运行，并选择位宽更低的量化版本或更小的模型。

仓库中仅包含safetensors格式文件

暂无 .gguf 文件可用：请搜索社区转换的「GGUF」版本，或使用 llama.cpp 脚本自行转换模型。

存在标签污染的输出

聊天模板不正确：请参见上一节，通过 Modelfile 提供正确的 TEMPLATE 和 PARAMETER stop 设置。

#深入了解

导入 GGUF 需要掌握 Ollama 生态中的两项基本技能。以下本站指南可作为本指南的延伸：

选择量化方案（Q4、Q5、Q8、FP16）

深入理解质量与内存之间的权衡，以便根据您的显卡选择合适的 GGUF 模型版本

使用 Ollama Modelfile 自定义模型

通过 Modelfile 进一步探索：系统提示、参数、模板以及同一模型的多种变体。

安装 Ollama：Windows、macOS 和 Linux

这份基础安装指南已更新，适合在导入首批 GGUF 之前从零开始安装的用户。