Ollama 导入 Hugging Face 模型实践整理

2026-05-19

Ollama 导入 Hugging Face 模型实践整理

原文参考：Ollama 导入 HuggingFace 模型

本文在原文基础上做了结构化整理、命令校对和补充说明，方便按步骤操作。

目标

把 Hugging Face 上下载的模型导入到 Ollama 中使用。常见路径有两种：

1. 转换为 GGUF 后导入：兼容性更传统，适合 llama.cpp 支持的模型。
2. 直接导入 safetensors 模型目录：新版 Ollama 支持，但依赖模型架构兼容性。

一、从 Hugging Face 下载模型

1. 安装下载工具

pip3 install huggingface_hub

2. 下载模型

以 Qwen3-8B 为例，模型地址：

https://huggingface.co/Qwen/Qwen3-8B

使用旧版 CLI：

huggingface-cli download --repo-id Qwen/Qwen3-8B --local-dir ./Qwen3-8B

参数说明：

• --repo-id：模型 ID，也就是 Hugging Face URL 中去掉 https://huggingface.co/ 后的部分。
• --local-dir：模型保存路径，可自定义。

如果安装新版 huggingface_hub 后没有 huggingface-cli，可以使用新版命令：

hf download Qwen/Qwen3-8B --local-dir ./Qwen3-8B

如果下载速度较慢，可以考虑配置 Hugging Face 镜像源。

二、理解 safetensors 和 GGUF

从 Hugging Face 下载的模型通常是 *.safetensors 格式。这种格式主要用于安全、高效地存储模型权重。

而 Ollama 常见模型格式是 GGUF，它更适合本地大模型推理、量化和部署。

因此导入 Ollama 有两种方式：

• 将 safetensors 转换为 GGUF 后导入。
• 使用新版 Ollama 直接导入 safetensors 模型目录。

三、方式一：转换为 GGUF 后导入

1. 下载 llama.cpp

git clone https://github.com/ggerganov/llama.cpp

2. 安装依赖

cd llama.cpp
python3 -m venv venv
source ./venv/bin/activate
pip3 install -r requirements.txt

3. 转换模型格式

通用命令：

python3 convert_hf_to_gguf.py /path/to/your/huggingface_model --outtype f16 --outfile my_model.gguf

参数说明：

• --outtype：输出精度，例如 f16 或 f32。
• --outfile：输出的 GGUF 文件名。

以 Qwen3-8B 为例，假设模型目录为：

/home/user/Qwen/Qwen3-8B/

转换命令：

python3 convert_hf_to_gguf.py /home/user/Qwen/Qwen3-8B/ --outfile /home/user/Qwen/qwen3-8b.gguf

四、创建 Modelfile

在 qwen3-8b.gguf 所在目录创建 Modelfile，最基础写法：

FROM ./qwen3-8b.gguf

实际使用时，建议参考 Ollama 官方同类模型的 Modelfile，补充 TEMPLATE 和 PARAMETER。

例如可以包含：

FROM ./qwen3-8b.gguf

PARAMETER temperature 0.6
PARAMETER top_k 20
PARAMETER top_p 0.95
PARAMETER repeat_penalty 1

如果模型有特定对话模板，例如 Qwen、Llama、ChatGLM 等，最好复制同系列 Ollama 模型的模板，避免提示词格式不匹配导致效果异常。

五、导入模型到 Ollama

执行：

ollama create qwen3:8b -f ./Modelfile

查看本地模型：

ollama ls

运行模型：

ollama run qwen3:8b

注意：原文示例里创建命令是 qwen3:8b，运行示例出现了 hf-qwen3:8b。实际运行时应使用你 ollama create 时指定的模型名。

六、方式二：直接导入 safetensors 模型

新版 Ollama 可以直接导入部分 Hugging Face 模型目录。

1. 准备模型目录

确保目录中包含必要文件，例如：

• *.safetensors：模型权重文件
• config.json：模型配置
• tokenizer.json：分词器文件
• 其它 tokenizer / generation 配置文件

假设目录为：

./my-model/

2. 创建 Modelfile

FROM ./my-model

其它参数仍然建议参考同类模型配置。

3. 导入模型

ollama create my-model -f ./Modelfile

七、常见问题

1. 模型架构不支持

不是所有 Hugging Face 模型都能导入 Ollama。

无论是通过 llama.cpp 转 GGUF，还是直接导入 safetensors，如果报错提示模型架构不支持，通常说明当前转换工具或 Ollama 暂不支持该架构。

这种情况不要硬折腾，建议换部署方式，例如：

• 使用 vLLM
• 使用 Transformers
• 使用 LM Studio
• 使用 llama.cpp 支持的模型
• 换成 Ollama 官方已有或同架构模型

2. Modelfile 不知道怎么写

Modelfile 类似 Dockerfile，是 Ollama 创建模型的配置文件。

可以查看已有模型的 Modelfile：

ollama show <模型名称> --modelfile

然后基于同系列模型改 FROM、参数和模板。

八、Modelfile 常用指令速查

总结

推荐优先级：

1. 如果 Ollama 官方已有同类模型，优先直接使用官方模型或参考其 Modelfile。
2. 如果 Hugging Face 模型是 llama.cpp 支持的架构，转换 GGUF 后导入更稳。
3. 如果使用新版 Ollama，可以尝试直接导入 safetensors 模型目录。
4. 如果提示架构不支持，及时换部署路线，避免浪费时间。