开源模型这几年正在经历一次质变生态里冒出来的模型一个比一个能打能力越来越接近商业闭源产品。但很多人卡住的第一关不是模型本身而是“下载”这步开源模型下载现在基本绕不开两个名字——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 格式可能稍有差异文件版本也可能不同步。你需要知道去哪边找、怎么下载才能在不同环境里灵活切换而不是只会用一个平台。维度HuggingFaceModelScope魔搭主要用户群体全球开发者国内开发者国内访问速度依赖镜像或网络条件原生快中文模型收录较全很全且更新快transformers 集成默认支持需手动指定本地路径或改下载源适合场景海外协作、生态集成国内部署、中文项目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_idQwen/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_ENDPOINThttps://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_dtypeauto)只要目标是本地目录就不要用模型 ID 去加载避免它又去联网下载一遍。这个坑踩的人特别多尤其是刚接触 transformers 的新手。下载和加载是两步下载完成后路径是你自己控制的加载时也要明确指向它。7. 实操心得我的双平台下载习惯最后分享几个我在实际操作中沉淀下来的习惯。第一永远先看模型卡再下载把版本后缀搞清楚Instruct/Chat 和 Base 的差距不是一点点下载错了不仅浪费时间后面所有实验都跑偏。第二优先用命令行或 Python 接口不要用浏览器点下载按钮。大模型文件必须靠断点续传和并发下载浏览器做不到这一点。第三国内环境优先 ModelScope网络问题会少掉一大半需要跟海外生态对接时再换 HuggingFace 镜像两条路都通的时候选网络最快的那条。另一个我经常用的做法是把模型下载脚本写成可复用的 shell 函数比如pull_model()里传入平台参数。这样在换机器、换项目时只要改一行参数就能决定从哪个平台拉模型。下载这件事本身不复杂但做好了能省下很多时间避免在部署阶段反复折腾。我个人更偏好 ModelScope 一点不是它比 HuggingFace 好多少而是“能正常下载、能跑通”对我来说比什么都重要。你也别再纠结哪个平台先把第一个模型下下来跑通推理你就不会觉得这事儿难了。