BYP's Notes
首页 关于 公开笔记

如何下载单一模型文件（GGUF直链获取与量化选择）

📌 关键要点

大模型本地部署需要的是 GGUF 单文件（一个 .gguf 就是一个完整模型），而非 Ollama 内部的 blobs 分片。下载 GGUF 的核心是直链规律：

一、什么是"单一模型文件"

1.1 GGUF：一个文件一个模型

格式 特点 用途
GGUF（.gguf） 单个文件包含全部权重 + 分词器 + 元数据 Ollama / LM Studio / llama.cpp 本地推理
safetensors（.safetensors） 拆成多个分片文件 PyTorch 训练 / 微调 / 部署
Ollama blobs 导入后按哈希散列存储 Ollama 内部格式，不可直接分发

✅ 要"下载单一模型文件"，目标就是 GGUF。它由 llama.cpp 生态定义，ollama create 可直接导入。

1.2 两类仓库要分清

在 HuggingFace / ModelScope 上，同一个模型往往有两个仓库：

Qwen/Qwen2.5-3B-Instruct          ← 原模型仓库，里面是 safetensors（无 .gguf）
Qwen/Qwen2.5-3B-Instruct-GGUF     ← GGUF 仓库，里面才是 .gguf 单文件 ✅

找下载地址必须进 -GGUF 后缀的仓库。

二、官方 GGUF 仓库命名规律

主流厂商（Qwen、Llama、Gemma、DeepSeek 等）都在 HuggingFace 上维护官方 GGUF 仓库，命名统一为 模型名-GGUF：

模型 官方 GGUF 仓库 直链示例
Qwen2.5 1.5B Qwen/Qwen2.5-1.5B-Instruct-GGUF .../resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf
Qwen2.5 3B Qwen/Qwen2.5-3B-Instruct-GGUF .../resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf
Qwen3.8 27B unsloth/Qwen3.8-27B-GGUF（社区量化） .../resolve/main/<对应量化文件名>.gguf

⚠️ unsloth/ 前缀表示第三方团队（Unsloth）发布的量化版，非 Qwen 官方仓库。第三方量化质量参差，优先选官方仓库；但 Unsloth 的 Dynamic V3 量化获通义千问官方致谢认可，社区口碑好，也可信任。

三、直链拼写规律（核心）

3.1 HuggingFace 直链

https://huggingface.co/<仓库名>/resolve/main/<文件名>

三个要素全在文件页可见：仓库名（页面标题）、resolve/main（固定写法）、文件名（Files 列表里）。示例（1.5B 完整地址）：

https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf

浏览器打开会直接开始下载；命令行 wget / curl 同地址可用。

3.2 ModelScope 直链（国内快）

https://modelscope.cn/models/<仓库名>/resolve/master/<文件名>

注意分支是 master（HuggingFace 是 main）。示例：

https://modelscope.cn/models/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/master/qwen2.5-1.5b-instruct-q4_k_m.gguf

3.3 怎么拿到准确的仓库名和文件名

  1. 进 GGUF 仓库 → 默认文件浏览页
  2. 文件名 = 列表里 .gguf 文件的完整名字（含量化后缀）
  3. 仓库名 = 页面顶部 OrgName/RepoName

四、量化等级怎么选

文件名后半段就是量化等级，影响体积与质量：

量化 1.5B 体积 3B 体积 特点
q2_k ~600MB ~1.2GB 最小，质量损失明显，仅内存极紧时用
q4_k_m ~1.0GB ~2.0GB ✅ 平衡首选，日常够用
q8_0 ~1.6GB ~3.2GB 质量接近原模型，体积约翻倍
fp16 ~3.1GB ~6.2GB 原精度，仅作中间格式，一般不下

选择策略：不确定就选 q4_k_m；内存紧张按 q4_k_m → q2_k 降级；追求质量选 q8_0。

⚠️ 部署前先算内存账：模型驻留内存 ≈ 权重体积 + KV cache。8GB 的香橙派实测两个模型（1.5B+3B）驻留约 3.6GB 已占近半，27B 级模型（q4 约 16GB）8GB 板子跑不动，留待 32GB+ 内存的 PC 或云端。

五、四种下载方式

方式一：浏览器直下（最稳）

把直链粘贴到浏览器地址栏，自动下载。断点续传需浏览器插件，大文件推荐方式二。

方式二：wget 命令行（可断点续传）

# 断点续传：-c；自定义文件名：-O
wget -c -O qwen2.5-3b-instruct-q4_k_m.gguf \
  "https://huggingface.co/Qwen/Qwen2.5-3B-Instruct-GGUF/resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf"

方式三：ModelScope 下载工具（国内最快）

pip install modelscope
# 下载整个仓库（全部量化文件）
modelscope download --model Qwen/Qwen2.5-3B-Instruct-GGUF --local_dir ./qwen-gguf
# 只下载指定单个文件
modelscope download --model Qwen/Qwen2.5-3B-Instruct-GGUF \
  qwen2.5-3b-instruct-q4_k_m.gguf --local_dir ./qwen-gguf

方式四：huggingface-cli（可选）

pip install -U huggingface_hub
huggingface-cli download Qwen/Qwen2.5-3B-Instruct-GGUF \
  qwen2.5-3b-instruct-q4_k_m.gguf --local-dir ./

六、下载后：导入 Ollama

拿到 .gguf 后即可本地导入，完整流程见 如何在端侧安装LLM（以香橙派为例），简要版：

# scp 上传后，板端执行
cd ~/software
printf 'FROM ./qwen2.5-3b-instruct-q4_k_m.gguf\n' > Modelfile
ollama create qwen2.5:3b -f Modelfile
ollama run qwen2.5:3b "你好"   # 验证

导入后 GGUF 已复制进 ~/.ollama/models/blobs，可 rm 原文件释放空间；同名重复导入直接覆盖。

七、常见坑

  1. 进了原模型仓库找不到 .gguf：safetensors 仓库没有 GGUF，必须进 模型名-GGUF 后缀的仓库。
  2. HuggingFace 下载慢 / 超时：换 ModelScope 镜像（国内实测 12MB/s），或笔记本浏览器下载后 scp 上传到板子。
  3. 大文件中断：用 wget -c 断点续传；浏览器下载中断一般只能重来。
  4. 板子内存不够跑大模型：先查模型量化体积 vs 设备内存，8GB 板子别碰 10GB+ 的模型。
  5. 第三方仓库命名不规范（如 unsloth/xxx、拼写奇怪的版本号）：核对模型实际名称，优先官方仓库。

📖 资料来源： - Qwen 官方 HuggingFace 主页 - HuggingFace GGUF 文件直链格式说明 - ModelScope 模型下载文档 - Unsloth 官方主页

相关笔记