如何将 GGUF 模型导入 Ollama？完整操作指南

将 GGUF 模型导入 Ollama 的两种方式

将 GGUF 模型导入 Ollama 有两种方式，具体取决于文件当前的位置。如果模型位于 Hugging Face 仓库中，可以使用 ollama run 命令直接拉取并运行，无需编写 Modelfile。如果 .gguf 文件已经存在于服务器磁盘上，则需要编写一个两行的 Modelfile 并运行 ollama create。

这两种路径的结果相同：模型会被命名并存入本地 Ollama 库，供 ollama run 和 Ollama API 调用。当模型由他人发布时，请使用第一种方式。当您自行量化模型、通过 scp 或 rsync 获取文件，或者机器无法连接 Hugging Face 时，请使用第二种方式。

GGUF 文件是一个包含权重、分词器和模型元数据的二进制文件。这是 llama.cpp 读取的格式，而 Ollama 基于 llama.cpp 构建，这就是几乎所有开源模型都有社区版 GGUF 转换文件的原因。Ollama 无法直接加载包含 .safetensors 权重的文件夹，因此转换步骤是必要的。

以下内容假设 Ollama 已安装且服务正在运行。如果尚未安装，请先参考 在 VPS 上安装 Ollama，完成后再回来。首先运行 ollama list。如果返回的是一个表格（即使是空的）而不是连接错误，说明服务器已启动，本指南的其余部分即可正常执行。

方案一：直接运行 Hugging Face 上的 GGUF 模型（无需 Modelfile）

Ollama 可以直接从 Hugging Face 仓库拉取 GGUF 文件。命令格式为仓库路径加上 hf.co/ 前缀：

ollama run hf.co/{username}/{repository}

hf.co 和 huggingface.co 均可作为域名使用。以下是来自 Hugging Face 文档的实际示例：

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

首次运行时会下载文件，因此下载完成前不会出现聊天提示符。之后模型将存入本地库，启动速度会很快。打开第二个终端窗口并运行 ollama list 查看其存储名称。该名称即完整的 hf.co/... 字符串及其标签，每次输入会很繁琐。建议为其设置一个简短的别名：

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

此方案仅适用于包含 GGUF 文件的仓库。如果仓库仅发布 .safetensors 权重，Ollama 将无法获取任何内容，此时需要执行下文所述的转换步骤。

Ollama 如何选择量化版本？

截至 2026 年 8 月 25 日，Hugging Face 的 Ollama 文档明确规定了默认行为：“默认情况下，如果模型仓库中存在 Q4_K_M 量化方案，则优先使用该方案。如果不存在，我们将自动选择仓库中存在的某个合理量化类型。”因此，如果仓库发布了十种量化版本，系统会默认选择 Q4_K_M；如果仓库中没有 Q4_K_M，Ollama 会代你做出选择。在依赖此机制前请重新阅读该页面，因为默认设置可能会发生变化。

通过添加标签来指定特定的量化版本：

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

量化名称不区分大小写，因此 :iq3_m 和 :IQ3_M 的含义相同。你也可以将确切的文件名作为标签传入，当仓库中的短名称存在歧义时，这是最稳妥的做法。标签必须对应仓库中实际存在的文件，因此在输入前，请先打开“Files and versions”选项卡查看真实的文件名。选择哪种量化版本取决于内存和质量的需求，Q4、Q8 和 FP16 之间的区别 一文对此权衡有详细说明。

路径二：从本地磁盘导入 .gguf 文件

如果文件已在服务器上，你需要一个 Modelfile。它只需一行。创建一个目录，放入 Modelfile，并在其中通过 FROM 指向该文件：

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

将其保存为 Modelfile，然后构建模型：

ollama create my-model

ollama create 默认读取当前目录下名为 Modelfile 的文件。当文件名不同或位于其他位置时，请使用 -f，如 ollama create my-model -f /home/you/models/my-model/Modelfile 所示。运行 ollama create --help 可查看该标志及其默认值。FROM 中的路径可以是绝对路径，也可以是相对于 Modelfile 的路径，因此当两者位于同一目录时，FROM ./my-model-Q4_K_M.gguf 即可生效。使用绝对路径可完全避免路径歧义。

在信任结果前请先进行检查：

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list 现在应包含 my-model。ollama show my-model 会打印 Ollama 从文件元数据中读取的架构、参数量、上下文长度和量化信息。请读取这些值，不要仅凭文件名判断，因为文件名只是人工输入的字符串。如果模型能以正常语言回答你的测试提示词并正常停止，则导入成功。如果失败，请查看下方的模板章节，因为这通常是导致失败的原因。

关于磁盘空间需要注意一点：ollama create 会将 GGUF 文件复制到 Ollama 自身的模型存储区，而不是引用原始文件。在删除原始文件前，权重数据会占用两倍的磁盘空间。确认 ollama run my-model 运行正常后，请删除源文件，或将其存放在不计费的存储位置。Ollama 在磁盘上的模型存储位置 介绍了目录结构及迁移方法。

何时使用 --quantize 以及何时不使用

ollama create 包含一个 --quantize 标志，它仅用于一种情况：源模型为 FP16 或 FP32 格式，即全精度权重。Ollama 的导入文档列出了 q8_0 以及 k-means 变体 q4_K_S 和 q4_K_M 作为目标格式。

ollama create --quantize q4_K_M my-model

不要对已经量化的文件使用该标志。文件名中带有 Q4_K_M 或 Q5_K_S 的 .gguf 已经过此步骤，该标志将无法执行任何操作。量化是从高精度向低精度的单向转换，因此无法从 Q4 转换回 Q8。如果你的源文件是 .safetensors 格式的 Hugging Face 仓库，请先使用 llama.cpp 仓库中的 convert_hf_to_gguf.py 进行转换（这是 Ollama 文档推荐的工具），然后再导入该脚本生成的 GGUF 文件。Ollama 与 llama.cpp 的关系 解释了为何转换脚本属于另一个项目。

为什么导入的 GGUF 模型回复乱码或无法停止？

这是大多数导入教程都会忽略的故障，也是你必然会遇到的问题。其症状看起来像是模型损坏。控制标记以可见文本形式出现在回复中，例如 <|im_start|>assistant 或 <|end|>。模型在回答完问题后，会自行编写一个新的用户提问并继续回答。生成过程会一直持续，直到你按下 Ctrl+C。

模型本身没有问题，是聊天模板（chat template）配置错误。聊天模板是一个包装器，它将你的消息转换为模型训练时所使用的精确标记序列，并包含系统提示词结束和用户对话开始的特定标记。Ollama 会为你选择一个模板：文档称，基于 GGUF 文件内存储的内置 tokenizer.chat_template 元数据，系统会“从常用模板列表中自动选择一个”。当该元数据缺失，或与列表中的任何项都不匹配时，系统会使用一个通用包装器。模型看到的提示词格式与其训练数据完全不同，因此它永远无法识别出它所学到的停止标记（end-of-turn marker）。

打印 Ollama 实际选择的模板：

ollama show --template my-model
ollama show --modelfile my-model

如果输出为空或明显是通用模板，则证实了问题所在。请在 Modelfile 中手动编写模板：

FROM /home/you/models/my-model-Q4_K_M.gguf

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

PARAMETER stop "<|end|>"

使用 ollama create my-model 重新构建，并再次发送相同的测试提示词。stop 参数是你的安全保障：它告诉 Ollama 在出现该字符串时切断生成，即使你仍在调试包装器本身，这也能解决“无法停止”的问题。如果回复仍然持续运行，是因为你指定的标记从未出现，此时 设置 num_predict 上限 可以强制其在达到固定标记数量时停止，无论模板输出什么内容。

该模板必须是 Go 模板，而不是 Jinja 模板。 Hugging Face 文档对此有直接说明，这一点至关重要，因为原始模型仓库中的 tokenizer.chat_template 字段使用的是 Jinja 格式。直接粘贴该内容是无效的。Ollama 的语法包含三个变量：{{ .System }} 代表系统提示词，{{ .Prompt }} 代表用户消息，{{ .Response }} 代表模型回复。请在模型卡片或其 tokenizer_config.json 中查找模型真实的对话轮次标记，然后手动将其重写为 Go 语法。

有一个捷径可以节省大部分工作。许多模型共享通用的提示词格式，因此如果你的库中已有其他模型使用相同的格式，请对该模型运行 ollama show --template 并复制其输出内容。

Hugging Face 仓库中的模板、系统提示词和参数文件

Hugging Face 路径提供的控制方式与仓库中的文件一致，而非 Modelfile 中的指令。如果您拥有该仓库，或者正在发布自己的量化版本，请将这些文件添加到仓库中，这样每个 ollama run hf.co/... 都会自动获取它们。

• 名为 template 的文件用于存放 Go 模板。规则相同：使用 Go 语言，而非 Jinja。
• 名为 system 的文件用于存放系统提示词。
• 名为 params 的文件用于存放采样参数，且必须为 JSON 格式。

一个最小化的 params 文件示例：

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

如果您不是仓库的所有者，则无法添加这些文件。请先拉取一次模型，运行 ollama show --modelfile hf.co/... 导出当前配置，并将输出保存为 Modelfile。其中的 FROM 行指向 Ollama 已下载的 blob，因此您可以编辑 TEMPLATE 和 PARAMETER 行，然后运行 ollama create 构建一个固定的本地副本，无需再次下载。这是修复他人损坏的量化版本时的标准做法。

如何导入私有 GGUF 仓库

私有仓库需要将 Ollama 的 SSH 密钥添加到您的 Hugging Face 账户中。此路径的官方文档方法使用 SSH 密钥而非 API 令牌，因此您现有的令牌无法用于访问私有仓库。

打印公钥。在通过官方脚本安装 Ollama 的 Linux 服务器上，该服务以 ollama 用户身份运行，因此密钥位于该用户的主目录下：

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

如果您以当前用户身份自行启动 ollama serve，则路径应为 ~/.ollama/id_ed25519.pub。复制整行内容，打开您的 Hugging Face 账户设置页面 https://huggingface.co/settings/keys，并将其添加为新的 SSH 密钥。随后，常规命令即可用于您的私有仓库：

ollama run hf.co/{username}/{repository}

如果添加密钥后拉取仍然失败，您可能打印了错误的文件。服务器执行下载操作时会提供其自身的密钥；由 systemd 启动的服务器从不读取您用户目录下的 ~/.ollama，因此您主目录下的密钥并非 Hugging Face 所识别的那个。

该模型能否在您的 VPS 上运行？

决定因素是磁盘上的文件大小加上上下文窗口所需的内存。权重加载到内存中的大小与文件占用空间接近，上下文分配则在此基础上叠加，并随您允许的 token 数量增加。运行 ollama list 查看 Ollama 记录的模型大小，将其与 free -h 在服务器上的数值进行对比，并为操作系统及服务器运行的其他进程预留空间。如果您希望查看针对真实模型的计算示例，在 VPS 上运行 Nemotron 3.5 Lightning 提供了具体的拉取标签、所需内存大小以及纯 CPU 服务器是否能满足性能要求。

上下文是容易被忽略的部分。如果模型在默认窗口下加载，一旦您调高 num_ctx，模型可能会运行失败，因为内存分配会随您设置的窗口大小进行扩展。设置 num_ctx 及其内存开销 提供了详细的计算方法。当总内存需求过大时，通常的解决方法是使用同一模型的更小量化版本，Q4 与 Q8 的对比 涵盖了这种权衡。

运行失败的表现非常明显。在纯 CPU 的 VPS 上，内核的 OOM killer 会终止进程，journalctl -u ollama -n 50 配合 dmesg 可以查看到终止记录。在配备 GPU 的服务器上，ollama ps 会打印出 PROCESSOR 列，告知您加载的模型是进入了 GPU 内存、系统内存，还是分布在两者之间。溢出到系统内存的模型仍然可以响应，但速度较慢。测量每秒 token 数 可以将“较慢”转化为可量化的数值，以便您在不同量化版本之间进行比较。

检查导入结果

在执行任何导入操作后，请按此顺序运行以下四条命令：

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list 用于验证模型是否存在，并显示 Ollama 记录的模型大小。ollama show 用于验证 Ollama 是否已从 GGUF 文件中读取所需的元数据。ollama show --modelfile 用于确认模型实际使用的模板和参数；这是在用户发现输出乱码前，拦截此类故障的关键检查步骤。测试提示词会完整测试整个链路，因为模板损坏的模型即使在处理极短的请求时也会失败。一旦提示词返回结果正常，该模型名称即为您后续调用 Ollama API 时使用的名称，包括 指向您自建服务器的编程助手。若导入失败，请使用 ollama rm my-model 删除并重新构建。该命令仅删除 Ollama 的副本，不会改动您的源文件 .gguf。

FAQ

我可以在不编写 Modelfile 的情况下将 GGUF 导入 Ollama 吗？

可以，如果该文件位于 Hugging Face 仓库中。ollama run hf.co/{username}/{repository} 可以直接拉取并运行它，ollama run hf.co/{username}/{repository}:{quantization} 则用于选择特定的量化版本。只有当 .gguf 已经存在于本地磁盘时，才需要 Modelfile，此时只需包含 FROM /path/to/file.gguf 这一行，后接 ollama create my-model 即可。

如果我不指定量化版本，Ollama 会下载哪种量化格式？

根据 2026 年 8 月 25 日查阅的 Hugging Face 文档，当仓库中存在 Q4_K_M 时会优先使用该版本，否则 Ollama 会选择仓库中存在的某种合理的量化类型。添加如 :Q8_0 这样的标签可以进行控制。使用 ollama show <model> 可以确认实际获取的版本，该命令会从文件元数据而非文件名中读取并打印量化信息。

为什么我导入的模型会重复输出或无法停止生成？

聊天模板与模型不匹配。Ollama 会自动从 GGUF 内部的 tokenizer.chat_template 元数据中选择模板；当该元数据缺失或无法识别时，系统会使用通用包装器，导致模型无法识别其训练时所用的回合结束标记。使用 ollama show --template <model> 打印当前模板，然后在 Modelfile 中添加 TEMPLATE 代码块和 PARAMETER stop 行，并再次运行 ollama create。请将其编写为 Go 模板格式。原始仓库中的 Jinja 模板无法直接使用。

我应该对我下载的 GGUF 使用 --quantize 吗？

不应该。--quantize 用于在 ollama create 期间转换 FP16 或 FP32 源文件，而文件名中已包含如 Q4_K_M 等量化标识的文件已经过转换。量化无法恢复精度，且没有逆向转换路径。仅当你自行将 safetensors 转换为全精度 GGUF 并希望获得更小的版本时，才使用该标志。

如何拉取私有的 GGUF 仓库？

将 Ollama 的 SSH 公钥添加到你的 Hugging Face 账户中。在标准 Linux 安装中通过 sudo cat /usr/share/ollama/.ollama/id_ed25519.pub 打印该公钥，或者在以当前用户身份运行服务器时从 ~/.ollama/id_ed25519.pub 获取，然后将其添加到你账户的 SSH 密钥设置页面。完成此操作后，ollama run hf.co/{username}/{repository} 即可用于你自己的私有仓库以及你所属组织的仓库。