开源模型下载这件事看起来只是敲一行命令的事但真到用的时候坑比想象中多得多。我自己刚开始接触大模型那会儿光是搞清楚 HuggingFace 和 ModelScope 的区别就花了大半天更别提下载到一半断连、磁盘被塞满、模型加载报错这些破事。这篇内容就是把我这些年踩过的坑、总结出来的下载策略和实操细节一次性讲清楚不管你是刚入门想跑个 Qwen 试试水还是已经在做微调需要批量拉模型都能直接抄作业。核心围绕三个平台展开HuggingFace、ModelScope 和魔搭把它们的定位、下载方式、加速手段、常见报错和排查思路全部拆开讲。1. 三个平台到底什么关系先搞清楚再动手很多人一上来就问“哪个好用”这个问题本身就问错了。HuggingFace、ModelScope、魔搭不是三选一的关系它们更像是同一个生态里不同定位的仓库。你得先明白每个平台的角色才能决定什么时候用哪个。1.1 HuggingFace全球最大的模型集散地HuggingFace 本质上是一个模型托管平台加社区总部在海外。它的核心价值在于模型覆盖面最广——几乎你能叫得出名字的开源模型第一时间都会传到上面。Llama 系列、Mistral、Qwen、DeepSeek、Stable Diffusion 的各种微调版本HuggingFace 上都能找到。除了模型权重它还托管数据集、提供 Spaces 做在线 Demo、维护 transformers/diffusers/accelerate 这些核心库。它的目录结构很规整一个典型的模型仓库长这样meta-llama/Llama-3.1-8B-Instruct/ ├── config.json ├── generation_config.json ├── model-00001-of-00004.safetensors ├── model-00002-of-00004.safetensors ├── model-00003-of-00004.safetensors ├── model-00004-of-00004.safetensors ├── model.safetensors.index.json ├── tokenizer.json ├── tokenizer_config.json └── special_tokens_map.json大模型权重通常被切成多个 safetensors 分片配合一个 index.json 索引文件。这个设计是为了方便断点续传和并行下载你下载的时候不用管分片逻辑工具会自动处理。HuggingFace 的问题也很明显服务器在海外国内直接访问经常超时或者速度只有几十 KB/s。一个 7B 的模型动辄 14GB 以上按这个速度下到天荒地老。所以国内用户用 HuggingFace核心诉求就是解决下载速度问题。1.2 ModelScope阿里系的本土化方案ModelScope 是阿里达摩院推出的模型开放平台中文名叫“魔搭”。注意ModelScope 和魔搭是同一个东西只是叫法不同热搜里两个词经常一起出现就是这个原因。它的定位是“模型即服务”把模型托管、在线推理、数据集、开发工具链整合在一起。ModelScope 最大的优势是国内网络直连下载速度能跑满带宽。它上面国内团队发布的模型非常全Qwen 系列通义千问、Baichuan、ChatGLM、InternLM 这些国产模型的首发基本都在这里。而且它提供了和 HuggingFace 类似的 API 和 SDK迁移成本很低。一个典型的 ModelScope 模型仓库结构qwen/Qwen2.5-7B-Instruct/ ├── config.json ├── configuration.json ├── model-00001-of-00004.safetensors ├── model-00002-of-00004.safetensors ├── model-00003-of-00004.safetensors ├── model-00004-of-00004.safetensors ├── model.safetensors.index.json ├── tokenizer.json ├── tokenizer_config.json └── vocab.json你会发现结构和 HuggingFace 几乎一样因为 ModelScope 在设计上就兼容了 HuggingFace 的模型格式。这意味着你从 ModelScope 下载的模型很多时候可以直接用 transformers 库加载不需要改代码。1.3 两者的核心差异对比光说定位太虚直接上表格对比这是我在选平台时最看重的几个维度对比维度HuggingFaceModelScope魔搭服务器位置海外国内国内下载速度慢常需加速快直连满速模型覆盖全球最全国产模型全海外模型逐步跟进模型格式原生 safetensors/pytorch兼容 HF 格式认证方式Tokenread 权限即可SDK Token命令行工具huggingface-climodelscope CLIPython SDKhuggingface_hubmodelscope数据集支持非常完善逐步完善社区生态全球最大国内活跃这个表格不是让你二选一而是告诉你海外模型优先看 HuggingFace国产模型优先看 ModelScope。如果 HuggingFace 上有你需要的模型但下载太慢那就想办法加速如果 ModelScope 上正好有同款直接用它省事。提示很多模型在两个平台都有镜像仓库比如 Qwen 系列在 HuggingFace 和 ModelScope 上都能找到。这种情况下优先用 ModelScope省去加速的麻烦。2. 下载工具选型别再用浏览器点下载了搞清楚平台定位之后下一步是选下载工具。我见过太多新手直接用浏览器打开模型页面一个个文件点下载下到一半发现少了个 index.json模型加载直接报错。这种方式在下载小模型时勉强能用但面对几十 GB 的大模型必须用专门的工具。2.1 命令行工具huggingface-cli 和 modelscopeHuggingFace 官方提供了huggingface-cliModelScope 提供了modelscope命令行工具。这两个是下载模型的首选方式支持断点续传、多线程、指定文件下载。安装方式# HuggingFace 命令行工具 pip install -U huggingface_hub[cli] # ModelScope 命令行工具 pip install -U modelscope安装完成后HuggingFace 需要先登录下载公开模型其实不登录也行但登录后能避免一些限流huggingface-cli login # 粘贴你的 Token回车确认ModelScope 同样需要登录才能下载部分模型modelscope login --token YOUR_MODELSCOPE_TOKENToken 在各自平台的个人设置页面生成HuggingFace 的 Token 只需要 read 权限就够了不要图省事给 write 权限万一泄露风险更大。2.2 Python SDK写脚本批量下载更灵活如果你需要批量下载多个模型或者把下载逻辑集成到自己的训练脚本里用 Python SDK 更合适。HuggingFace 的snapshot_downloadfrom huggingface_hub import snapshot_download snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir./models/Qwen2.5-7B-Instruct, local_dir_use_symlinksFalse, resume_downloadTrue, max_workers8 )ModelScope 的snapshot_downloadfrom modelscope import snapshot_download model_dir snapshot_download( qwen/Qwen2.5-7B-Instruct, cache_dir./models, revisionmaster )注意local_dir_use_symlinksFalse这个参数。早期 huggingface_hub 默认用软链接把缓存文件链接到目标目录结果就是你以为下载到了指定目录实际上文件还在~/.cache/huggingface里磁盘占用翻倍。新版本已经默认改为直接复制但如果你用的是老版本这个参数一定要显式设置。2.3 为什么不用 git cloneHuggingFace 和 ModelScope 的模型仓库都支持 git clone但我强烈不建议用这种方式下载大模型。原因有三个第一git 会把整个仓库的提交历史也拉下来模型仓库动辄几十个 commit每个 commit 都包含完整的权重文件版本.git目录可能比模型本身还大。第二git clone 不支持断点续传。下到 90% 断网了重新 clone 得从头再来。第三大文件通过 git-lfs 管理配置起来麻烦而且 lfs 的下载速度往往比专用工具慢。注意如果你只是想要仓库里的 README 或配置文件git clone 没问题。但下载权重文件老老实实用 CLI 或 SDK。2.4 工具选型速查表使用场景推荐工具理由下载单个模型huggingface-cli / modelscope CLI简单直接支持断点续传批量下载多个模型Python SDK可写循环灵活控制集成到训练脚本Python SDK代码内调用无需手动操作只下载部分文件CLI 的 --include 参数避免下载不需要的文件查看模型信息CLI 的 scan-cache / list不下载也能看3. HuggingFace 下载加速的几种实战方案这是整篇内容最核心的部分。HuggingFace 在国内的下载速度问题是所有用大模型的人绕不开的坎。我试过好几种方案有的稳定有的坑下面按推荐程度排序讲。3.1 方案一使用 HF 镜像站最推荐HuggingFace 官方支持通过环境变量切换端点国内有一些公益镜像站提供了完整的模型文件同步。这是目前最省事、最稳定的方案。设置方式很简单在终端里导出环境变量export HF_ENDPOINThttps://hf-mirror.com然后正常用huggingface-cli download或snapshot_download流量就会走镜像站。这个环境变量对 CLI 和 Python SDK 都生效。如果你想让这个设置永久生效把它写进 shell 配置文件# 如果你用 bash echo export HF_ENDPOINThttps://hf-mirror.com ~/.bashrc source ~/.bashrc # 如果你用 zsh echo export HF_ENDPOINThttps://hf-mirror.com ~/.zshrc source ~/.zshrc实测下来镜像站的下载速度能到 10-20MB/s一个 14GB 的 7B 模型大概十几分钟就能下完。而且镜像站会定期同步 HuggingFace 上的模型热门模型基本都有。提示镜像站是公益性质的带宽有限下载时尽量避开高峰期。另外镜像站可能不包含所有模型冷门模型如果镜像站没有会回退到源站速度依然慢。3.2 方案二hfd 脚本一键加速hfd是一个开源的一键加速脚本原理是自动设置镜像端点并启动下载。它的好处是省去了手动配置环境变量的步骤适合不想折腾的人。使用方式# 下载脚本 wget https://raw.githubusercontent.com/hfd/hfd/main/hfd.sh chmod x hfd.sh # 运行下载 ./hfd.sh Qwen/Qwen2.5-7B-Instruct这个脚本内部会设置HF_ENDPOINT并调用huggingface-cli本质上和方案一是一样的只是封装了一层。如果你已经会手动设置环境变量这个脚本不是必需的。3.3 方案三手动指定镜像 多线程参数如果你用 Python SDK 下载除了设置HF_ENDPOINT还可以调整并发数来提升速度import os os.environ[HF_ENDPOINT] https://hf-mirror.com from huggingface_hub import snapshot_download snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir./models/Qwen2.5-7B-Instruct, max_workers8, # 并发下载线程数 resume_downloadTrue, # 断点续传 local_dir_use_symlinksFalse )max_workers默认是 8如果你的带宽够大可以调到 16。但不要调太高镜像站可能限流反而适得其反。我一般设 8 就够用了。3.4 方案四先下小文件再下权重有时候你只想先看看模型能不能跑通不想等几十 GB 下载完。这时候可以用--include参数只下载配置文件和 tokenizerhuggingface-cli download Qwen/Qwen2.5-7B-Instruct \ --include *.json *.txt \ --local-dir ./models/Qwen2.5-7B-Instruct这样几秒钟就能下完你可以先用这些文件检查模型结构、确认 tokenizer 是否正常等确认无误再下载权重文件。3.5 各方案对比与选择建议方案配置难度速度稳定性适用场景HF 镜像站低快高日常下载首选hfd 脚本极低快中不想手动配置SDK 多线程中快高脚本集成只下小文件低极快高调试阶段我个人的习惯是环境变量永久设置镜像站日常用 CLI 下载需要批量处理时写 Python 脚本。这套组合用了两年多基本没出过问题。4. ModelScope 下载实操与 Qwen 模型拉取ModelScope 的下载比 HuggingFace 简单得多因为不需要考虑加速问题。但它的 SDK 用法和 HuggingFace 有些差异这里详细讲一遍。4.1 安装与登录pip install modelscope modelscope login --token YOUR_TOKENToken 在 ModelScope 网站的“个人中心-访问令牌”里生成。如果你只是下载公开模型其实不登录也能下但登录后能访问私有模型而且下载速度更稳定。4.2 用 CLI 下载模型ModelScope 的 CLI 下载命令格式modelscope download --model qwen/Qwen2.5-7B-Instruct --local_dir ./models/Qwen2.5-7B-Instruct注意模型 ID 的格式是组织名/模型名比如qwen/Qwen2.5-7B-Instruct。这个 ID 在模型页面的标题下方就能看到。如果你只想下载特定文件modelscope download --model qwen/Qwen2.5-7B-Instruct \ --include *.json *.safetensors \ --local_dir ./models/Qwen2.5-7B-Instruct4.3 用 Python SDK 下载from modelscope import snapshot_download model_dir snapshot_download( qwen/Qwen2.5-7B-Instruct, cache_dir./models, revisionmaster ) print(f模型下载到: {model_dir})cache_dir指定缓存目录下载完成后模型会放在这个目录下。revision指定版本默认是 master也可以指定具体的 tag 或 commit hash。4.4 下载 Qwen 3.8 的注意事项热搜里出现了“modelscope 安装 qwen 3.8”这里要澄清一下Qwen 的版本号目前是 Qwen2.5 系列没有所谓的“Qwen 3.8”。可能是有人把版本号记混了或者指的是某个特定微调版本。下载 Qwen 模型时认准官方组织qwen下的仓库比如qwen/Qwen2.5-7B-Instructqwen/Qwen2.5-14B-Instructqwen/Qwen2.5-72B-Instruct这些是官方发布的指令微调版本适合对话场景。如果你要的是基座模型去掉-Instruct后缀即可。注意下载前先确认磁盘空间。7B 模型约 15GB14B 约 28GB72B 约 145GB。别下到一半发现磁盘满了那才叫尴尬。4.5 ModelScope 下载的常见参数说明参数作用建议值--model指定模型 ID必填--local_dir本地保存路径建议指定否则在缓存目录--include只下载匹配的文件按需--exclude排除匹配的文件按需--revision指定版本默认 master--cache_dir缓存目录默认 ~/.cache/modelscope5. 下载后的模型怎么加载和验证模型下载完不是终点能正确加载才算成功。这一步经常出问题我整理了几个高频报错和排查方法。5.1 用 transformers 加载下载好的模型不管你从哪个平台下载的模型只要格式是 HuggingFace 兼容的都可以用 transformers 加载from transformers import AutoModelForCausalLM, AutoTokenizer model_path ./models/Qwen2.5-7B-Instruct tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypeauto, device_mapauto, trust_remote_codeTrue ) # 简单测试 inputs tokenizer(你好请介绍一下你自己, return_tensorspt) outputs model.generate(**inputs, max_new_tokens100) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))trust_remote_codeTrue这个参数对于 Qwen 等国产模型是必须的因为它们可能包含自定义的模型代码。但要注意这个参数会执行模型仓库里的 Python 代码所以只对你信任的模型开启。5.2 验证模型完整性的方法下载完成后先检查文件是否齐全。一个完整的模型目录应该包含config.json模型配置tokenizer.json或tokenizer.model分词器model.safetensors.index.json权重索引大模型才有model-*.safetensors权重分片generation_config.json生成配置可选如果缺少 index.json 或某个分片加载时会报错。可以用这个脚本快速检查import os import json model_dir ./models/Qwen2.5-7B-Instruct # 检查必要文件 required [config.json, tokenizer.json] for f in required: path os.path.join(model_dir, f) print(f{f}: {存在 if os.path.exists(path) else 缺失}) # 检查权重分片 index_file os.path.join(model_dir, model.safetensors.index.json) if os.path.exists(index_file): with open(index_file) as f: index json.load(f) shards set(index[weight_map].values()) for shard in shards: path os.path.join(model_dir, shard) size os.path.getsize(path) / (1024**3) if os.path.exists(path) else 0 print(f{shard}: {size:.2f}GB {OK if size 0 else 缺失})5.3 常见加载报错与解决报错信息原因解决方法OSError: Unable to load weights权重文件缺失或损坏重新下载缺失的分片KeyError: qwen2transformers 版本过低升级 transformersRuntimeError: CUDA out of memory显存不足用量化或 device_mapValueError: tokenizer not foundtokenizer 文件缺失补下 tokenizer 相关文件ImportError: cannot import name依赖库版本冲突按模型要求安装依赖5.4 磁盘空间管理技巧大模型很占空间一个 7B 模型 15GB下几个就上百 GB 了。几个管理技巧第一用du -sh定期检查模型目录大小删掉不用的模型。第二HuggingFace 的缓存目录默认在~/.cache/huggingface如果你用local_dir下载记得检查缓存目录是否还有残留避免双倍占用。第三可以用huggingface-cli scan-cache查看缓存占用用huggingface-cli delete-cache清理。# 查看缓存 huggingface-cli scan-cache # 交互式清理 huggingface-cli delete-cache6. 常见问题排查与避坑经验这部分是我这些年踩坑最多的地方每一条都是真金白银换来的经验。6.1 下载中断后怎么续传HuggingFace 和 ModelScope 的 CLI 都支持断点续传。如果下载中断重新执行同样的命令即可工具会检查已下载的文件跳过完整的部分只下缺失的。但有个坑如果你中途改了local_dir续传会失效因为工具找不到之前的下载记录。所以下载大模型时路径一旦确定就不要改。6.2 镜像站没有的模型怎么办镜像站虽然覆盖了大部分热门模型但冷门模型可能没有。这时候有几个选择第一去 ModelScope 看看有没有同款。很多海外模型国内团队会做镜像。第二用镜像站下载部分文件剩下的从源站补。但这种方式比较麻烦不推荐。第三如果模型不大比如 1B 以下直接源站下载也能接受。6.3 Token 权限与安全问题HuggingFace 的 Token 分 read 和 write 两种权限。下载模型只需要 read 权限千万不要用 write 权限的 Token 去下载。万一 Token 泄露别人可以用你的账号上传恶意模型。ModelScope 的 Token 同样建议只给必要权限。Token 不要硬编码在代码里用环境变量管理export HF_TOKENhf_xxxxxxxxxxxx export MODELSCOPE_TOKENms_xxxxxxxxxxxx然后在代码里读取import os hf_token os.environ.get(HF_TOKEN)6.4 模型下载速度突然变慢如果下载速度突然从 20MB/s 掉到几百 KB/s可能是几个原因第一镜像站限流了。等一段时间再试或者换个时间段。第二你的网络本身波动。用ping或curl测试一下到镜像站的延迟。第三并发数太高被限流。把max_workers调低试试。6.5 常见问题速查表问题现象可能原因排查步骤下载速度为 0网络不通或端点错误检查 HF_ENDPOINT 设置下载到一半报错磁盘满或网络中断检查磁盘空间重新下载模型加载报错文件缺失或版本不匹配检查文件完整性升级依赖Token 无效Token 过期或权限不足重新生成 Token缓存占用过大重复下载或软链接清理缓存目录6.6 几个我踩过的坑第一个坑早期用local_dir_use_symlinksTrue默认值结果模型文件全在缓存目录local_dir里只有软链接。后来迁移服务器时只拷贝了local_dir模型全废了。现在一律设False。第二个坑下载 72B 模型时没检查磁盘下到 80% 磁盘满了前功尽弃。现在下载前必用df -h检查空间。第三个坑用 git clone 下载模型.git目录占了 30GB删了之后模型文件也受影响。从此再也不用 git 下模型。第四个坑Token 硬编码在脚本里不小心提交到了公开仓库赶紧去平台撤销重新生成。现在一律用环境变量。7. 批量下载与自动化脚本如果你需要管理多个模型手动一个个下载太累。这里给一个批量下载的脚本模板支持 HuggingFace 和 ModelScope 两个平台。7.1 批量下载脚本import os from huggingface_hub import snapshot_download as hf_download from modelscope import snapshot_download as ms_download # 设置镜像 os.environ[HF_ENDPOINT] https://hf-mirror.com # 模型清单 models [ {platform: hf, id: Qwen/Qwen2.5-7B-Instruct, dir: ./models/Qwen2.5-7B-Instruct}, {platform: ms, id: qwen/Qwen2.5-14B-Instruct, dir: ./models/Qwen2.5-14B-Instruct}, {platform: hf, id: meta-llama/Llama-3.1-8B-Instruct, dir: ./models/Llama-3.1-8B-Instruct}, ] for model in models: print(f开始下载: {model[id]}) try: if model[platform] hf: hf_download( repo_idmodel[id], local_dirmodel[dir], local_dir_use_symlinksFalse, resume_downloadTrue, max_workers8 ) else: ms_download( model[id], cache_dirmodel[dir] ) print(f下载完成: {model[id]}) except Exception as e: print(f下载失败: {model[id]}, 错误: {e})7.2 下载前的磁盘检查在批量下载前先算一下总大小检查磁盘是否够用import shutil def check_disk(required_gb, path./): total, used, free shutil.disk_usage(path) free_gb free / (1024**3) print(f可用空间: {free_gb:.2f}GB, 需要: {required_gb}GB) if free_gb required_gb * 1.2: # 留 20% 余量 print(警告: 磁盘空间不足) return False return True # 7B 模型约 15GB14B 约 28GB check_disk(15 28)7.3 自动化下载的注意事项批量下载时建议加个延迟避免请求过于频繁被限流import time for model in models: # ... 下载逻辑 ... time.sleep(5) # 每个模型之间间隔 5 秒另外批量下载最好在后台运行用nohup或tmux避免终端断开导致下载中断nohup python download_models.py download.log 21 这样即使你关掉终端下载也会继续。用tail -f download.log可以实时查看进度。8. 模型格式转换与跨平台迁移有时候你从 HuggingFace 下载的模型想在 ModelScope 的环境里用或者反过来。虽然两者格式兼容但有些细节需要注意。8.1 格式兼容性说明ModelScope 的模型格式基本兼容 HuggingFace但有两个差异第一ModelScope 的configuration.json是它特有的配置文件HuggingFace 没有。这个文件不影响 transformers 加载可以忽略。第二部分 ModelScope 模型使用了自定义的模型类加载时需要trust_remote_codeTrue。8.2 从 HuggingFace 迁移到 ModelScope如果你想把 HuggingFace 的模型上传到 ModelScope需要第一在 ModelScope 创建模型仓库。第二用modelscope的 upload 功能上传文件。第三补充configuration.json文件可选但建议加。modelscope upload --model your_name/model_name --local_dir ./models/your_model8.3 跨平台加载的注意事项从 ModelScope 下载的模型用 transformers 加载时如果报KeyError或ImportError通常是 transformers 版本问题。ModelScope 上的模型可能依赖特定版本的 transformers建议按模型页面的要求安装。# 查看模型要求的 transformers 版本 cat ./models/Qwen2.5-7B-Instruct/config.json | grep transformers如果 config.json 里有transformers_version: 4.37.0这样的字段说明模型是用这个版本训练的但不代表必须用这个版本加载。一般用更新的版本也能加载只是可能有警告。9. 我的下载工作流总结讲了这么多最后分享一下我现在的标准工作流你可以直接参考。第一步确定模型。先在 HuggingFace 上搜看有没有官方仓库。如果有记下 repo_id。第二步查 ModelScope。用同样的模型名在 ModelScope 搜一下如果有官方镜像优先用 ModelScope 下载省去加速配置。第三步配置环境。如果只能用 HuggingFace设置HF_ENDPOINT镜像站配置 Token 环境变量。第四步检查磁盘。用df -h确认空间足够大模型留 20% 余量。第五步下载。用 CLI 或 Python SDK设置resume_downloadTrue和local_dir_use_symlinksFalse。第六步验证。检查文件完整性用 transformers 加载测试。第七步清理。下载完成后检查缓存目录是否有残留清理不需要的文件。这套流程用了很久基本没出过问题。核心原则就一条能直连就不加速能 CLI 就不手动能验证就不偷懒。最后再分享一个小技巧如果你经常下载模型可以写一个 shell 函数封装常用操作比如hfget() { export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download $1 --local-dir ./models/$(basename $1) --resume-download }然后hfget Qwen/Qwen2.5-7B-Instruct就能一键下载。这种小工具积累多了效率提升非常明显。