开源模型下载全攻略：HuggingFace与ModelScope双平台实操指南

开源模型这几年正在经历一次质变，生态里冒出来的模型一个比一个能打，能力越来越接近商业闭源产品。但很多人卡住的第一关不是模型本身，而是“下载”这步：开源模型下载，现在基本绕不开两个名字——HuggingFace 和 ModelScope（魔搭）。前者是全球最大的模型托管平台，几乎你能叫得上名字的开源模型都会在这里发布权重，后者是国内活跃度最高的模型社区，对中文开发者极其友好。这篇文章我把两条路径的下载姿势都捋一遍，从模型ID怎么找、命令行怎么用、镜像怎么配，到pip install modelscope之后怎么把 Qwen3-8B 这类大模型完整拉到本地，全程给可以直接抄作业的操作。

1. 开源模型下载为什么这么麻烦

1.1 平台割裂：HuggingFace、ModelScope 和魔搭是什么关系

先说一句：ModelScope 就是魔搭，魔搭就是 ModelScope，同一个平台，只是中文名和英文名的区别。很多教程一会儿写 ModelScope 一会儿写魔搭，新手以为这是两个平台，其实指的是同一个。HuggingFace 是海外的老牌模型托管平台，ModelScope 是国内阿里主导的模型社区，两者在功能上高度相似：都有模型卡、文件列表、版本管理、SDK 下载接口。

但实际体验差别很大。HuggingFace 的优势是生态完整，各种推理框架、评估工具、微调脚本默认都认它，连 transformers 库的from_pretrained默认也是从 HuggingFace 拉权重。ModelScope 的优势是网络友好，国内访问速度快、连接可靠，而且对中文模型的收录非常全，Qwen 系列、通义千问衍生模型、很多中文专用模型都会优先在 ModelScope 发布。

这就造成了“平台割裂”的现状：同一个模型在两个平台各有文件仓库，ID 格式可能稍有差异，文件版本也可能不同步。你需要知道去哪边找、怎么下载，才能在不同环境里灵活切换，而不是只会用一个平台。

1.2 不同使用场景怎么选平台

我的建议很直接。如果你在国内服务器、国内网络环境下工作，优先用 ModelScope。下载速度是最关键的，几十个 GB 的模型文件，速度差别直接决定你是等 10 分钟还是等 2 小时，这个体感差距在实际操作里非常明显。如果你的代码依赖 transformers 生态，或者需要和海外团队协作、需要读取 HuggingFace 上独有的文件，那就用 HuggingFace 配合镜像方案。如果你只是想把模型下载到本地再做微调或推理，其实哪个平台都行，选网络最快、ID 最好找的那个即可。

另外提醒一个小常识：很多模型在两个平台都有官方仓库，但文件可能不同步。你在 ModelScope 看到的文件哈希和 HuggingFace 的未必一致，但权重本身可以互用，关键是看模型卡里的版本号。比如 Qwen3 的 Base 和 Instruct 版本，用途完全不同，别下载错了变体。

提示：模型下载之前，先到模型卡里确认你要的是哪个版本。经常有人把 Base（基座模型）下载下来发现不能聊天，其实是要下 Instruct 或 Chat 版本。

2. HuggingFace 的正确打开方式

2.1 模型ID：从网页到命令行的钥匙

HuggingFace 下载的第一步不是复制网页链接，而是取“模型ID”。一个标准模型 ID 的格式是组织名/模型名，比如meta-llama/Llama-3.1-8B-Instruct、Qwen/Qwen2.5-7B-Instruct。你在浏览器打开某个模型的主页，URL 里的路径就是模型 ID。

为什么要用模型 ID，而不是直接点网页的下载按钮？因为网页下载按钮只适合小文件。正经的模型仓库动辄几十个文件、几十个 GB，浏览器下载会非常痛苦，而且断了一次就得从头再来。命令行和 SDK 的方式支持断点续传、并发下载、按文件类型筛选，这才是专业做法。你可以把模型 ID 理解为“仓库的钥匙”，后面所有下载工具都认这把钥匙。

2.2 用 huggingface_hub 下载：snapshot_download 详解

最常用的 Python 方式是 huggingface_hub 的snapshot_download，它能把整个仓库按快照方式拉下来。安装很简单：

pip install huggingface_hub

然后写一小段代码：

from huggingface_hub import snapshot_download snapshot_download( repo_id="Qwen/Qwen2.5-7B-Instruct", local_dir="./Qwen2.5-7B-Instruct", )

关键参数逐个说清楚。local_dir指定下载到哪个目录，不指定的话默认会塞到缓存目录~/.cache/huggingface/hub，对用户来说非常不直观，强烈建议显式指定local_dir，方便直接拿文件去部署。allow_patterns和ignore_patterns用通配符筛选文件，比如只下载.safetensors权重而跳过.bin格式，或者只下载*.json配置。max_workers控制并发线程数，默认 8，网络情况好时可以调到 16 或 32，多文件仓库的下载速度会明显提升。revision可以指定分支或 tag，用于下载某个历史版本。

2.3 命令行下载：huggingface-cli 与 hf

如果你不想写代码，HuggingFace 也提供了命令行工具。新版 huggingface_hub 推荐用hf命令，语法很直观：

hf download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B-Instruct

老版本的huggingface-cli download也还在用，参数大同小异。实测下来，hf download的进度显示更友好，断点续传的支持也更稳，新项目建议直接用hf。

需要登录才能下载的受限模型（比如 Llama 系列部分权重需要申请权限），就得先配置 token。方式是执行：

hf auth login

然后把你在 HuggingFace 网站上申请的 Access Token 粘进去。token 是身份凭证，别乱发群里，泄露了别人可以用你的身份去下载受限模型，还要注意及时在网页后台吊销。

3. 国内访问 HuggingFace 的合规方案

3.1 镜像站挂载法：HF_ENDPOINT 与 hf-mirror.com

先说实话：HuggingFace 的服务器在海外，国内直连经常遇到速度慢、连接中断的问题。对个人开发者来说，最省事的合规方案是使用镜像站点。HuggingFace 社区维护的常用镜像之一是hf-mirror.com，它把原站公开资源同步到国内可访问的节点，你只需要设置一个环境变量：

export HF_ENDPOINT=https://hf-mirror.com

设置之后，huggingface_hub 库的所有下载请求都会自动指向镜像地址，transformers 的from_pretrained也会跟着走镜像。因为你只是换了一个下载源，API 完全不用改，这对代码侵入性几乎为零。

我建议把这一行写进.bashrc或.zshrc里长期生效。如果只是某个脚本想用镜像，可以在脚本开头动态设置：

import os os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

但有一点要记住：镜像站通常只同步公开模型，需要登录权限的受限模型可能下载不了。遇到这种情况，回 ModelScope 找找，或者在原站登录下载。

3.2 直接走 ModelScope：国内环境的最优解

如果你所在的环境连镜像都觉得费劲，或者要下载的是超大模型（70B、百 GB 级别），我强烈建议直接改用 ModelScope。它本身就是国内平台，没有跨海访问的问题，速度优势非常明显，尤其是下载动辄上百 GB 的大模型时，这种差距是决定性的。

而且现代版本的 modelscope 库越来越顺手，接口也在向 huggingface_hub 看齐，很多时候你只需要把from huggingface_hub import snapshot_download换成from modelscope import snapshot_download，其余代码几乎一样。这种双平台并存的习惯我用了很久了：本地和国内服务器用 ModelScope，需要跟海外框架集成时用 HuggingFace 镜像，两边互不耽误。

注意：镜像站配置只影响 huggingface_hub 相关库，不会影响git clone操作。如果你用git clone https://huggingface.co/xxx这种原始方式，环境变量拦不到，需要把 URL 里的域名手动换成镜像域名。

4. ModelScope 魔搭上手：从装库到下载 Qwen 等模型

4.1 pip install modelscope：安装与依赖

ModelScope 的使用门槛和 HuggingFace 类似，第一步装库：

pip install modelscope

安装后不需要额外配置网络环境，直接调用即可。魔搭社区的模型页同样有模型 ID，格式也是组织名/模型名，比如Qwen/Qwen3-8B-Instruct、deepseek-ai/DeepSeek-R1-Distill-Qwen-32B。如果是在国内服务器上操作，这一步比 HuggingFace 省心太多，网络开销基本可以忽略。

顺便说一句，modelscope 库不只负责下载，还支持调用模型做推理、微调，甚至集成了部分数据集下载接口。但本文聚焦下载，其他的以后有机会再展开。新手只需要记住：装库之后，下载能力是自带的基础功能。

4.2 在魔搭找到你要的模型：搜索与模型卡

打开魔搭社区网站，在搜索框输入Qwen3-8B或DeepSeek，会看到一堆模型仓库。进去之后注意看三件事：模型 ID（用于下载）、许可证（商用时要看）、文件列表（确认是否包含你要的权重格式）。

以 Qwen 系列为例，魔搭官方账号发布的模型质量最高，几乎会与技术团队同步更新。比如Qwen/Qwen3-8B和Qwen/Qwen3-8B-Instruct，下载前先确认后缀，因为 Instruct 版才是对齐了对话能力的，Base 版是用来做继续预训练和科学研究的。这个道理在 HuggingFace 和 ModelScope 上通用。

还有一个容易忽略的点：模型卡页面通常会给出“直接下载”和“SDK下载”两种入口提示。直接下载是网页版，适合小文件；SDK 下载就是本章要讲的snapshot_download。大模型务必用 SDK，浏览器下载体验太差。

4.3 snapshot_download 完整示例

下载命令和 HuggingFace 几乎一模一样：

from modelscope import snapshot_download model_dir = snapshot_download( "Qwen/Qwen3-8B-Instruct", local_dir="./Qwen3-8B-Instruct", )

这里有一个细节：snapshot_download返回的model_dir是实际存放文件的目录。如果你没传local_dir，默认会下载到 modelscope 的缓存目录（通常是~/.cache/modelscope/hub），返回值就是那个路径；传入local_dir后，返回值就是local_dir本身。两种方式都能直接用，但显式指定local_dir对后续部署更友好，因为模型路径是确定的，写部署脚本时不容易出错。

魔搭同样支持文件筛选和并发下载：

snapshot_download( "Qwen/Qwen3-8B-Instruct", local_dir="./model", allow_patterns=["*.safetensors", "*.json", "*.txt"], )

这样只会下载.safetensors权重和必要的配置、说明文件，能帮你省下不少磁盘空间。比如有些仓库同时放了.bin和.safetensors两份权重，格式之间是冗余的，只需要一种即可。

4.4 命令行下载：ModelScope 版 CLI

如果你不想写 Python，也可以直接用命令行。modelscope 库装好之后，系统里会多出modelscope命令，下载语法是：

modelscope download --model Qwen/Qwen3-8B-Instruct --local_dir ./Qwen3-8B-Instruct

实测下来，这个命令的进度条、断点续传都比较可靠。我平时在服务器上批量下载多个模型，就是写一个 shell 脚本循环执行modelscope download，每个模型一个目录，比打开网页一个个点下载靠谱得多。脚本示例：

modelscope download --model Qwen/Qwen3-8B-Instruct --local_dir /data/models/Qwen3-8B-Instruct modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /data/models/Qwen2.5-7B-Instruct

再配合nohup挂到后台，就算下载到一半终端断了，重连后重新执行也会自动续传，不会从头再来。

5. 下载管线、缓存与磁盘管理

5.1 缓存结构：为什么重复下载占满磁盘

用默认缓存方式下载时，HuggingFace 和 ModelScope 都会在本地生成一套“按仓库 ID + 版本哈希”组织的目录结构。同一个模型下载不同版本，磁盘上会同时保留多份，这是很多人磁盘爆满的元凶。

HuggingFace 的缓存目录是~/.cache/huggingface/hub，里面每个仓库是一个哈希目录，打开后能看到 blobs 和 snapshots 两层结构。ModelScope 的缓存目录是~/.cache/modelscope/hub，结构类似。如果你抱着“先下下来再说”的心态，又不定期清理，磁盘很快会被撑爆。

我的建议是：凡是需要长期使用的大模型，一律指定local_dir自己管理文件；只有临时测试的小模型，才用默认缓存。模型文件动辄十几 GB，一个 7B 模型大约 15GB，一个 32B 模型大约 65GB，下载前用df -h看一下磁盘余量，别等下载到一半才发现空间不够。

5.2 断点续传与并发参数

大文件下载最怕中途断掉。好消息是 huggingface_hub 和 modelscope 都内置了断点续传，下载中断后重新执行同样的命令，会从断点继续而不是从头再来。但有个前提：不要手动删除缓存目录里的.incomplete文件，那是断点续传的关键。

关于并发，HuggingFace 的snapshot_download里有max_workers参数，默认值是 8。在带宽足够的情况下，把max_workers调到 16 甚至 32，多文件下载速度会有明显提升。ModelScope 的 CLI 也有类似的多线程拉取行为，大仓库下载时整体效果都还不错。

磁盘速度也是一个容易被忽视的因素。很多人下载慢，其实是机械硬盘写不过来，尤其是模型仓库包含大量小文件时，随机写入性能跟不上。建议把下载目录放到固态硬盘上，能省不少时间。如果服务器只有机械盘，可以先把文件下载到内存盘或 SSD 临时目录，再移动到机械盘归档。

6. 常见问题排查实录

6.1 网络超时或速度极慢

遇到下载超时或速度极慢，先别急着重试，按这个顺序排查。第一步，确认是不是直连了海外域名，有没有正确设置HF_ENDPOINT镜像变量，在 Python 里执行import os; print(os.environ.get("HF_ENDPOINT"))就能看到当前值。第二步，检查网络连通性，用curl -I测试目标域名是否可达。第三步，如果确认网络环境不理想，直接切到 ModelScope。

小文件数量多时，网络往返次数会成为瓶颈，调大并发线程数通常能解决大半问题。另外，有些家用宽带的 DNS 解析可能有问题，可以临时换用公共 DNS 再试一次。网络层面的坑千奇百怪，但核心思路就一句话：先确认下载源没问题，再怀疑本地环境。

6.2 下载中断或文件校验失败

下载中断最常见的原因是网络抖动，重新运行命令即可续传。如果某个文件反复下载失败，而且报错提示校验和（hash）不一致，建议先删掉那个文件的缓存记录再重下。huggingface_hub 和 modelscope 在下载时会校验文件大小和哈希，但如果网络波动剧烈或磁盘写入出错，偶尔会留下损坏文件，手动清理是唯一的办法。

注意，校验失败时不要只删.incomplete文件，有时已经显示“完整”的文件其实也是坏的，需要连完成文件一起删除重下。具体操作：找到对应仓库的缓存目录，把报错文件对应的记录清掉，然后重新执行下载命令。

6.3 模型ID写错或仓库不存在

模型 ID 是大小写敏感的，qwen/qwen3-8b和Qwen/Qwen3-8B-Instruct可能完全不通用。模型 ID 写错时，两个库都会抛类似 HTTP 404 的错误，很多人第一反应是怀疑网络，其实大概率只是拼写问题。正确做法是回到网页，从模型卡地址栏直接复制路径，不要手敲。

还有一种情况是你没有该模型的访问权限。HuggingFace 上很多需要申请审核的模型，如果 token 权限不够，也会报 401 或 403 错误。这时候去模型卡页面点击申请，等权限通过后再重新下载即可。

6.4 磁盘空间不足

模型下载前先用du -sh看目标目录当前占用，用df -h看分区剩余空间。7B 模型通常需要 15~30GB 空间，70B 模型需要 130GB 以上。空间不够时，优先考虑只下载需要的文件类型，用allow_patterns只拉.safetensors和配置文件，跳过不必要的.bin或其他格式。

这里有个小技巧：权重格式之间有冗余，同一个模型同时发布.safetensors和.bin时，只需要下载其中一种即可，没必要双份都拿。另外，下载过程中发现磁盘快满了，不要手动硬删文件，先中断任务，清理后再重新执行，断点续传会保留已有内容继续下。

6.5 模型加载时的缓存路径问题

很多人在下载后写代码仍然报找不到模型，原因是你下载到了自定义目录，但from_pretrained默认还是去缓存目录找。解决方法很简单：加载模型时直接传本地路径，比如：

from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained("./Qwen3-8B-Instruct", torch_dtype="auto")

只要目标是本地目录，就不要用模型 ID 去加载，避免它又去联网下载一遍。这个坑踩的人特别多，尤其是刚接触 transformers 的新手。下载和加载是两步，下载完成后路径是你自己控制的，加载时也要明确指向它。

7. 实操心得：我的双平台下载习惯

最后分享几个我在实际操作中沉淀下来的习惯。第一，永远先看模型卡再下载，把版本后缀搞清楚，Instruct/Chat 和 Base 的差距不是一点点，下载错了不仅浪费时间，后面所有实验都跑偏。第二，优先用命令行或 Python 接口，不要用浏览器点下载按钮。大模型文件必须靠断点续传和并发下载，浏览器做不到这一点。第三，国内环境优先 ModelScope，网络问题会少掉一大半；需要跟海外生态对接时再换 HuggingFace 镜像，两条路都通的时候，选网络最快的那条。

另一个我经常用的做法是：把模型下载脚本写成可复用的 shell 函数，比如pull_model()里传入平台参数。这样在换机器、换项目时，只要改一行参数就能决定从哪个平台拉模型。下载这件事本身不复杂，但做好了能省下很多时间，避免在部署阶段反复折腾。

我个人更偏好 ModelScope 一点，不是它比 HuggingFace 好多少，而是“能正常下载、能跑通”对我来说比什么都重要。你也别再纠结哪个平台，先把第一个模型下下来，跑通推理，你就不会觉得这事儿难了。