4、GGUF 模型下载与管理：从 Hugging Face 下载 GGUF 模型，使用 huggingface-cli 与 wget 技巧

模型有了，量化也懂了，接下来就是最实际的一步——把模型下载到你的树莓派上。

这一步看着简单，但坑不少。我刚开始玩的时候，直接在树莓派上用浏览器下载，结果下了半天，最后提示「存储空间不足」……嗯，那种感觉，就像你排了半天队，轮到你了发现没带钱。

这一章，我就把下载模型的几种方式、各自的适用场景、以及我踩过的坑，一次性讲清楚。

4.1 从哪里下载 GGUF 模型？

目前最主流的 GGUF 模型仓库，就是 Hugging Face。你可以把它理解成「AI 模型的 GitHub」。几乎所有主流模型（Llama、Mistral、Phi、Qwen 等）的 GGUF 版本，都能在上面找到。

我个人习惯在 Hugging Face 上搜索时，直接加个关键词 gguf，比如搜索 mistral gguf，就能精准定位到量化好的版本。

举个例子，TheBloke 这个用户上传了大量 GGUF 模型，他的仓库命名很规范：

• TheBloke/Mistral-7B-Instruct-v0.2-GGUF
• TheBloke/Phi-3-mini-4k-instruct-GGUF
• TheBloke/Llama-2-7B-Chat-GGUF

每个仓库里，通常会有多个量化版本的文件，比如 Q4_K_M.gguf、Q5_K_M.gguf、Q8_0.gguf 等。你根据自己树莓派的内存大小来选就行。

4.2 方法一：使用 huggingface-cli（推荐）

huggingface-cli 是 Hugging Face 官方提供的命令行工具。它最大的好处是：支持断点续传。这在树莓派上太重要了——你想想看，下载一个 4GB 的模型，万一网络断了，从头再来？那不得崩溃。

安装方式很简单：

pip install huggingface-hub

安装完成后，就可以用 huggingface-cli download 命令下载模型了。

基本用法：

huggingface-cli download TheBloke/Mistral-7B-Instruct-v0.2-GGUF \
    mistral-7b-instruct-v0.2.Q4_K_M.gguf \
    --local-dir ./models

这条命令的意思是：从 TheBloke/Mistral-7B-Instruct-v0.2-GGUF 仓库中，下载 mistral-7b-instruct-v0.2.Q4_K_M.gguf 这个文件，保存到当前目录下的 models 文件夹里。

如果你想把整个仓库都下载下来（比如里面有好几个量化版本），可以省略文件名：

huggingface-cli download TheBloke/Mistral-7B-Instruct-v0.2-GGUF \
    --local-dir ./models

不过我不建议这么干。树莓派的存储空间本来就金贵，下载一堆用不上的版本，纯属浪费。

4.3 方法二：使用 wget（轻量级方案）

如果你的树莓派空间紧张，不想装 huggingface-hub 这个包，或者你只是临时下载一个文件，那 wget 就是最好的选择。

不过要注意，wget 不能直接下载 Hugging Face 上的文件，因为 Hugging Face 的文件链接是动态的。你需要先拿到文件的直接下载链接。

怎么拿？很简单：

1. 打开 Hugging Face 上对应的模型仓库页面
2. 点击你要下载的 .gguf 文件
3. 在文件详情页，点击「Download」按钮，复制链接

或者，你也可以直接拼出链接。Hugging Face 的文件链接格式是：

https://huggingface.co/{用户名}/{仓库名}/resolve/main/{文件名}

比如：

https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf

拿到链接后，直接用 wget 下载：

wget -O ./models/mistral-7b-instruct-v0.2.Q4_K_M.gguf \
    https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf

-O 参数指定了保存路径和文件名。如果不加 -O，文件会以原始文件名保存在当前目录。

所以，用 wget 的正确姿势是：

wget -c -O ./models/mistral-7b-instruct-v0.2.Q4_K_M.gguf \
    https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf

4.4 两种方式对比

特性	huggingface-cli	wget
安装依赖	需要安装 huggingface-hub	树莓派系统自带
断点续传	✅ 原生支持	✅ 加 -c 参数
下载整个仓库	✅ 一行命令	❌ 需要逐个文件下载
速度	一般（受限于 Hugging Face 服务器）	一般（受限于 Hugging Face 服务器）
适用场景	长期使用、频繁下载	临时下载、空间紧张

我个人建议：如果你打算长期玩 GGUF 模型，就用 huggingface-cli。它管理模型更方便，而且支持断点续传，省心。如果你只是偶尔下一个模型，或者树莓派空间实在不够，那就用 wget。

4.5 下载后的文件管理

模型下载下来后，怎么管理？我推荐一个简单的目录结构：

~/models/
├── mistral/
│   └── mistral-7b-instruct-v0.2.Q4_K_M.gguf
├── phi/
│   └── phi-3-mini-4k-instruct.Q4_K_M.gguf
└── llama/
    └── llama-2-7b-chat.Q4_K_M.gguf

每个模型单独一个文件夹，文件夹名用模型名。这样当你跑不同模型时，只需要在 llama.cpp 的命令行里改一下路径就行。

另外，我建议你下载完成后，先验证一下文件完整性。Hugging Face 上每个文件旁边通常会有一个 SHA256 校验值。你可以用 sha256sum 命令来验证：

sha256sum ./models/mistral/mistral-7b-instruct-v0.2.Q4_K_M.gguf

把输出的值和 Hugging Face 页面上显示的对比一下。如果一致，说明文件下载完整。如果不一致……嗯，重新下载吧。我曾经因为网络问题，下载了一个损坏的模型，跑起来各种乱码，排查了半天才发现是文件坏了。

4.6 本章知识结构图

下面这张图，帮你理清本章的核心逻辑：

说白了，下载模型就两条路：要么用 huggingface-cli，省心省力；要么用 wget，轻巧灵活。选哪个，取决于你的使用场景和网络环境。

我个人更倾向于 huggingface-cli，尤其是当你需要频繁下载不同模型时，它的断点续传和仓库管理功能能帮你省下不少时间。不过，如果你只是偶尔下一个模型，或者树莓派上空间实在紧张，wget 也完全够用。

嗯，这一章就到这里。模型下载好了，下一章我们就可以真正开始跑模型了。

---