hf-mirror 下载模型：实测 9.4MiB/s 魔搭快 2.8 倍

能用，三条路的差距比多数人想的大。同一台机器上直连 huggingface.co 二十五秒超时返零字节，hf-mirror 配官方 CLI 能到 9.4MiB/s，魔搭 CLI 下同一个 610MiB 文件只用 23 秒。8B 模型的 Q4 量化，前者八分钟，后者三分钟。

先跑一条 curl，把慢和不通分开

下载卡住时先别动配置。拿一条带 Range 的请求打三个域名，只看返回码和字节数。

curl -s -L -m 25 -r 0-62914559 -o /dev/null \
  -w "%{http_code} %{size_download} %{time_total}\n" \
  https://huggingface.co/Qwen/Qwen3-0.6B-GGUF/resolve/main/Qwen3-0.6B-Q8_0.gguf

把域名换成 hf-mirror.com 再跑一次，路径一字不改。魔搭的路径不同，后面单独给。

实测结果：huggingface.co 返回 000，25.0 秒，0 字节。hf-mirror 返回 206，62.9MB 用 22.4 秒。魔搭返回 206，62.9MB 用 4.79 秒。返回 000 或者 size_download 是 0，说明通道根本没通，改 DNS、换 hosts、调并发全都没用。返回 206 但耗时很长，才是带宽或者并发的问题。

第一条路：把 HF_ENDPOINT 指到 hf-mirror

hf-mirror 是纯镜像，只换 endpoint，官方命令其余部分一个字不用改。

export HF_ENDPOINT=https://hf-mirror.com
hf download Qwen/Qwen3-0.6B-GGUF Qwen3-0.6B-Q8_0.gguf --local-dir ./model

实测 610MiB 落地用时 64.89 秒，折 9.4MiB/s。这个数字靠并发撑起来，Xet 日志里有一行 Current concurrency = 64。同一时刻用单条 curl 拉同一个镜像只有 2.7MiB/s，差三倍半。所以用 curl 测镜像速度得出镜像很慢的结论，测法本身有问题。

要长期生效就写进 shell 配置。zsh 在 ~/.zshrc 加一行 export HF_ENDPOINT=https://hf-mirror.com，bash 放 ~/.bashrc。Python 里必须在 import huggingface_hub 之前改 os.environ，顺序反了不生效，这种错很难从报错里看出来。另外带不带末尾斜杠都能正常跑，两种写法我都试过，落地路径和耗时一致，不必纠结这个细节。

第二条路：魔搭 CLI，同一个文件 23 秒

python3 -m pip install modelscope
modelscope download --model Qwen/Qwen3-0.6B-GGUF Qwen3-0.6B-Q8_0.gguf --local_dir ./model

实测 23.30 秒，同样的 610MiB，折 26.2MiB/s，比 hf-mirror 路线快 2.8 倍。命令行进度条上的瞬时速率稳定在 32MB/s 上下，尾部收尾掉到 30MB/s 左右。

不加 –local_dir 时落点是 ~/.cache/modelscope/models/Qwen–Qwen3-0.6B-GGUF/snapshots/master/。目录名把斜杠换成双横线，snapshots 下一级是 master 这种分支名，跟 HF 的 snapshots 用提交哈希不一样。写脚本按路径找文件时要留意这层差异，否则硬编码哈希目录会直接找不到。

落盘位置在自己机器上还算好办，模型多起来换盘的时候麻烦，Windows 上尤其容易把系统盘塞满。具体怎么搬目录、哪些子目录是缓存可以丢，我在 Ollama 模型占 C 盘：移到 D 盘实测与四个坑 里逐条记过，思路对任何下载器都通用。

第三条路：不装 SDK，直接打魔搭文件接口

容器或者 CI 里不想多装一个包，用 HTTP 就够，而且支持 Range。

curl -L -C - -o Qwen3-0.6B-Q8_0.gguf \
  "https://www.modelscope.cn/api/v1/models/Qwen/Qwen3-0.6B-GGUF/repo?Revision=master&FilePath=Qwen3-0.6B-Q8_0.gguf"

实测返回 206，62.9MB 用 4.79 秒，12.5MiB/s。单流就比 hf-mirror 的单流快四倍多，不需要任何并发技巧。Revision 默认写 master，写 main 会 404，这一点跟 GitHub 的习惯相反。

命令里的 -C – 是断点续传。魔搭的 HTTP 通道认 Range，中断后重跑会接着下。hf CLI 那条路做不到，下一节给证据。

三条通道实测对比

同一天、同一台机器、同一个文件。60MB 那列是 curl 单流打 Range 0 到 62914559，全文件那列是各自 CLI 拉 610MiB。

表里可以看出两件事。通道通不通的差别是零和一，速度差别是七倍。同一家服务里，测法（单流还是并发）造成的差距比两家之间的差距还大，所以任何镜像速度的结论都得写上并发数。

按实际体积算一遍要等多久

用上表实测速率折算，不含校验和解压。体积按常见量化档估算。

70B 这一档两条路差了四十五分钟，属于能决定你晚上还睡不睡的量级。选量化档位时顺手把这笔账算进来更划算，同一个模型 Q4 和 Q8 的体积差一倍，显存占用也差一倍。显存怎么按参数和上下文估，本地大模型显存怎么算：8B 每 1K 上下文 144MB 里有一版自己算的公式，比看官网标称准。

踩坑一：中断后重跑是从零开始

我下到第 35 秒把进程 kill 掉，回头看目标目录，只有 8.0K，里面一个 .cache 目录，模型文件本身不存在。

真正的进度藏在一个哈希名文件里，形如 3nJsnUdcCmdBOp4dLn_dEgZ50vw=.9465e63a22add5354d9bb4b99e90117043c7124007664907259bd16d043bb031.d0de8e26.incomplete，大小 0 字节。Xet 通道先把分片收在 HF_HOME 的 xet staging 区，最后一次性拼装成文件，所以杀进程不会留下能续的半成品。

验证方法很简单，重跑一次计时：65.29 秒，跟全新下载的 64.89 秒几乎一样。续传没有发生，前面 35 秒白下。判断依据是 .cache/huggingface/download 下那个 .incomplete 的体积，0 字节就说明什么都没落地，别指望重跑能接着来。要真能续，走上面魔搭 HTTP 那条 -C -，或者把大文件拆成多个 Range 请求自己拼。

踩坑二：HF_HUB_ENABLE_HF_TRANSFER 已经不管事

中文教程里几乎每篇都教你 export HF_HUB_ENABLE_HF_TRANSFER=1。在 huggingface_hub 2.4.0 上这一行会刷出一条警告，原文是 The HF_HUB_ENABLE_HF_TRANSFER environment variable is deprecated as hf_transfer is not used anymore. Please use HF_XET_HIGH_PERFORMANCE instead。设了不加速，连 hf_transfer 包都没装也不报错，属于完全静默失效。

同一批教程里的 huggingface-cli 命令在 2.x 也消失了。敲 huggingface-cli download 得到 command not found，命令行只剩一个 hf。升级过的机器上这个错最容易让人以为环境坏了。

老参数也不是全废，–local-dir 还在，–max-workers 还在，默认 8，–include 和 –exclude 也还在。真正被换掉的只有传输层开关。

踩坑三：默认缓存全是软链，复制的都是断链

不加 –local-dir 时，HF 把文件内容放 blobs，snapshots 下面放的是软链。实测一条 README.md 是这样：lrwxr-xr-x，指向 ../../blobs/249fd4077b71e5870ffd09f9627982065925ceef。

把这个目录 scp 或者 cp 到另一台机器，链接指向的 blobs 路径多半不存在，加载时报找不到文件，而且报错里出现的是 snapshots 路径，很容易误判成下载不完整。要带走必须 cp -L、rsync -L 或者 tar -h，三个都是让软链展开成实体文件。

加 –local-dir 反而干净，落地是真文件，只在旁边多一个 .cache/huggingface 放元数据和锁文件。魔搭这边两种模式都给真文件，没有 blobs 这一层，代价是同一模型存两份就真占两份空间。

下完先验，别等加载时才报错

魔搭的文件列表接口带 Sha256，这就是权威值，不用去翻发布页。

curl -s "https://www.modelscope.cn/api/v1/models/Qwen/Qwen3-0.6B-GGUF/repo/files?Revision=master&Root=" \
  | python3 -m json.tool | grep -A2 Q8_0
shasum -a 256 ./model/Qwen3-0.6B-Q8_0.gguf

这台机器上两边都是 9465e63a22add5354d9bb4b99e90117043c7124007664907259bd16d043bb031。顺带一个巧合：hf CLI 那个 .incomplete 文件名里嵌的 64 位十六进制就是同一个 sha256，光看残缺文件名就能反查该下的是哪个文件、该拿什么值去校验。

GGUF 还能看魔数，head -c 4 出来是 GGUF 说明文件头没坏。safetensors 是前 8 字节存头部长度，读成小端整数后如果大于文件总长，必定是截断。这招救过一次 ComfyUI 现场，文件大小看着正常、加载必崩，就是截断，细节写在 ComfyUI 装 FLUX 模型：safetensors 损坏与下拉框空白怎么修。校验这一分钟比重新下 20GB 便宜太多。

文件下好只是第一步。大模型还得看量化格式能不能被你的推理框架吃下去，比如 LongCat-2.5 开源：1.6T 参数 MIT 协议，W4A4 量化怎么跑 里那种 W4A4 权重，下下来不等于跑得起来，格式和框架要对得上。

FAQ

hf-mirror 现在还能用吗？
能。同一天实测 610MiB 文件 64.89 秒下完，全程返回 206。速度波动比较大，单流在 2.7 到 3.4MiB/s 之间晃，配官方 CLI 走并发能到 9.4MiB/s。它的定位就是镜像，别期待它比源站快。

下载慢到底是网络问题还是配置问题？
先打一条 curl Range 请求看返回码。返回 000 且 size_download 是 0，就是通道不通，改任何配置都没用。返回 206 只是慢，说明通道通、带宽或并发不够，换 CLI 或者换源才有效。这一步两分钟能省掉一下午的试错。

魔搭和 hf-mirror 该选哪个？
能找到同名仓库就选魔搭，同文件实测 23.30 秒对 64.89 秒。HF 上独有的仓库、需要申请授权的 gated 模型、要指定某个 commit 的场景，还得走 hf-mirror 配 HF_ENDPOINT。两边都留着，按仓库有没有来决定，不必二选一。