1. 为什么下载开源模型这件事值得单独拎出来讲如果你刚开始接触大模型大概率会遇到这样一个场景在论文或教程里看到一个心仪的模型兴冲冲打开浏览器准备下载结果要么是页面转圈转到怀疑人生要么是命令行里git clone卡在某个进度条上再也不动要么是好不容易下完了发现文件不完整、权重加载报错。折腾半天模型没跑起来心态先崩了。这不是你一个人的问题。开源模型的分发渠道和普通软件包完全不是一回事——一个 7B 参数的模型动辄十几 GB70B 的更是上百 GB文件体积大、分片多、格式杂再加上不同平台的分发策略、存储位置、鉴权方式各不相同下载环节本身就成了一门需要专门掌握的技能。目前主流的开源模型获取渠道主要有三个HuggingFace、ModelScope魔搭以及各模型官方提供的直链或网盘。HuggingFace 是全球最大的模型社区模型数量最多、更新最快但服务器在海外国内直接访问经常不稳定ModelScope 是阿里达摩院推出的国内模型社区访问速度快、中文模型丰富很多国产模型首发就在这里此外还有一些模型会在 GitHub Release 或官方文档里提供直链下载。这篇文章面向的是所有需要把开源模型拉到本地或服务器上跑起来的人——不管你是做推理部署、微调训练还是只想本地跑个对话玩玩。我会把这三个渠道的下载方式、各自的坑、以及我实际用下来最稳的组合方案讲清楚让你少走弯路。2. HuggingFace 下载从网页到命令行的三条路2.1 网页直接下载最简单也最容易翻车的方式打开 HuggingFace 的模型页面切到 Files and versions 标签你会看到模型仓库里的所有文件。对于小模型比如几百 MB 的 embedding 模型直接点文件旁边的下载箭头就能搞定这是最无脑的方式。但问题在于大模型的文件往往是分片的。比如一个 7B 的模型可能被切成model-00001-of-00004.safetensors这样的多个文件每个 3-5 GB。网页下载的痛点很明显不能断点续传浏览器下载中断了就得重来、不能批量下载、速度完全看运气。我试过用浏览器下一个 13B 的模型下了三次都在 80% 左右断掉最后放弃。所以网页下载只适合两种情况文件小于 1GB或者你只是想看看仓库里有哪些文件、确认一下文件结构。2.2 git clone 方式适合熟悉 Git 的人但有个大坑HuggingFace 的每个模型仓库本质上就是一个 Git 仓库所以你可以直接git clone https://huggingface.co/模型作者/模型名这种方式的好处是能拿到完整的仓库结构包括配置文件、tokenizer、README 等。但坑在于模型权重文件是用 Git LFSLarge File Storage管理的如果你本地没装 Git LFSclone 下来的权重文件只是一些几十字节的指针文件根本不是真正的模型。正确姿势是先装 Git LFS# 安装 git-lfs以 Ubuntu 为例 sudo apt-get install git-lfs git lfs install然后再 clone。即便如此git clone 大仓库的体验也不太好——它会把整个历史记录都拉下来而且中断后恢复比较麻烦。对于超过 10GB 的模型我不太推荐这种方式。2.3 huggingface-cli官方命令行工具最推荐的方式HuggingFace 官方提供了一个 Python 命令行工具huggingface_hub里面的huggingface-cli是目前下载模型最靠谱的方式。先安装pip install -U huggingface_hub然后下载整个模型huggingface-cli download 模型作者/模型名 --local-dir ./本地目录如果只想下载特定文件huggingface-cli download 模型作者/模型名 config.json --local-dir ./本地目录这个工具的核心优势是支持断点续传。下载中断了重新执行同样的命令它会自动从断点继续不会重新下载已经完成的文件。对于动辄几十 GB 的模型来说这个特性太重要了。另外它默认会把模型缓存到~/.cache/huggingface/hub目录如果你指定了--local-dir它会用软链接的方式组织文件。如果你希望直接下载实体文件到指定目录而不走缓存可以加上--local-dir-use-symlinks False旧版本参数新版本默认就是直接下载到 local-dir。2.4 国内访问 HuggingFace 的现实问题与应对思路说实话国内直接访问 HuggingFace 的体验很不稳定。有时候能跑满带宽有时候连页面都打不开。这不是 HuggingFace 的问题而是网络链路的客观情况。针对这个情况社区里有一些常见的应对思路。最直接的是使用镜像站点——一些高校和机构提供了 HuggingFace 的镜像服务把模型文件同步到国内服务器上访问速度会快很多。使用方式通常是通过设置环境变量HF_ENDPOINT来切换下载源export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download 模型作者/模型名 --local-dir ./本地目录这个环境变量对huggingface-cli和transformers库都生效设置一次之后后续所有通过 HuggingFace 生态的下载都会走镜像。需要注意的是镜像站点的模型同步可能有延迟刚发布的新模型不一定能立刻在镜像上找到。提示镜像站点的可用性和同步策略会变化使用前建议先确认目标模型是否已经同步。如果镜像上没有还是得回到官方源。3. ModelScope魔搭国内开发者的顺手选择3.1 ModelScope 是什么和 HuggingFace 什么关系ModelScope 是阿里达摩院搞的模型社区定位和 HuggingFace 类似但服务器在国内访问速度快得多。很多国产模型——比如 Qwen 系列、ChatGLM 系列、百川系列——都会在 ModelScope 上首发或同步发布。它和 HuggingFace 的关系不是替代而是互补。同一个模型经常在两个平台都有但 ModelScope 上的版本可能针对国内网络做了优化下载体验好很多。而且 ModelScope 的模型页面通常有更详细的中文说明对国内开发者更友好。3.2 安装 modelscope 库与基础下载命令ModelScope 的下载主要通过modelscope这个 Python 库。安装很简单pip install modelscope下载模型用snapshot_download函数from modelscope import snapshot_download model_dir snapshot_download(qwen/Qwen2.5-7B-Instruct) print(model_dir)默认会下载到~/.cache/modelscope/hub目录返回值就是本地路径。你也可以指定缓存目录model_dir snapshot_download( qwen/Qwen2.5-7B-Instruct, cache_dir./models )如果只想下载特定文件可以用allow_file_pattern参数model_dir snapshot_download( qwen/Qwen2.5-7B-Instruct, allow_file_pattern[*.safetensors, *.json] )3.3 用命令行下载不写代码也能搞定不是所有人都想写 Python 代码。ModelScope 也提供了命令行工具modelscope download --model qwen/Qwen2.5-7B-Instruct --local_dir ./models这个命令和huggingface-cli的用法很像同样支持断点续传。如果你只是想把模型拉到本地用命令行就够了。3.4 ModelScope 下载的实测体验与注意事项我实际用下来ModelScope 的下载速度在国内确实有明显优势。同样的 7B 模型HuggingFace 走镜像可能跑个 5-10 MB/sModelScope 经常能跑到 20-30 MB/s 甚至更高取决于你的带宽。但有几个点需要注意第一模型命名规则不同。HuggingFace 上叫Qwen/Qwen2.5-7B-InstructModelScope 上可能是qwen/Qwen2.5-7B-Instruct大小写和路径都可能不一样。下载前最好先在 ModelScope 网站上搜一下确切的模型 ID。第二文件结构可能有差异。虽然大部分模型在两个平台的文件是一致的但偶尔会有配置文件格式或分片方式的细微差别。如果你是从 HuggingFace 的教程里抄的代码换到 ModelScope 下载的模型上可能需要调整一下加载路径。第三不是所有模型都有。ModelScope 虽然模型数量增长很快但一些纯海外模型比如某些 Llama 的社区微调版本可能只在 HuggingFace 上有。这时候还是得回到 HuggingFace 或镜像。4. 下载策略与工具选型什么场景用什么方案4.1 三个渠道的横向对比我把三个主要渠道的关键维度整理成了一张表方便你快速判断该用哪个维度HuggingFace 官方HuggingFace 镜像ModelScope模型数量最全取决于同步策略国产模型全海外模型部分国内速度不稳定较快快断点续传支持cli支持cli支持鉴权要求部分模型需 token同官方部分模型需登录新模型上架速度最快有延迟国产模型同步快中文文档一般一般完善4.2 我的实际选择逻辑经过一段时间的折腾我形成了一个比较固定的选择逻辑优先看 ModelScope。如果目标模型在 ModelScope 上有直接用 ModelScope 下载省心省力。尤其是 Qwen、ChatGLM、DeepSeek 这些国产模型ModelScope 上的版本通常是最新的下载速度也最快。ModelScope 没有的走 HuggingFace 镜像。设置HF_ENDPOINT环境变量用huggingface-cli下载。大部分主流海外模型在镜像上都能找到。镜像也没有的才考虑官方源。这种情况通常是刚发布的新模型或者比较冷门的社区微调版本。这时候要有心理准备下载可能会比较慢建议挂后台慢慢跑。4.3 大模型下载的存储规划下载大模型之前一定要先规划好存储。一个 7B 的模型FP16 精度大约需要 14-15 GB 的磁盘空间13B 大约 26 GB70B 则要 140 GB 左右。如果你要下载多个模型磁盘很快就满了。我的建议是单独挂一块大容量硬盘或 SSD 专门放模型不要和系统盘混在一起下载前用df -h确认剩余空间至少留出模型体积 1.5 倍的余量因为下载过程中可能有临时文件如果用的是云服务器注意系统盘和数据盘的区分模型尽量放数据盘另外HuggingFace 的缓存机制会在~/.cache/huggingface下保留一份如果你同时用--local-dir指定了目录可能会占用双倍空间。可以用huggingface-cli delete-cache清理不需要的缓存。5. 下载过程中最容易踩的五个坑5.1 坑一磁盘空间不足导致下载中断这个坑我踩过不止一次。下载到一半提示 No space left on device然后整个下载进程挂掉。更麻烦的是有些工具在空间不足时不会自动清理临时文件你得手动找到那些半成品文件删掉。排查方法下载前先df -h看剩余空间下载过程中用du -sh 目标目录监控增长。如果发现空间快满了及时清理其他文件或换目录。5.2 坑二网络中断后不知道从哪继续用git clone下载大模型时网络一断整个 clone 就失败了重新 clone 又会从头开始。这就是我不推荐用 git clone 下大模型的核心原因。解决方案改用huggingface-cli或modelscope download这两个工具都支持断点续传。中断后重新执行同样的命令即可它会自动跳过已完成的文件。5.3 坑三下载的模型文件不完整有时候下载看起来完成了但加载模型时报错提示某个文件缺失或损坏。这通常是因为下载过程中出现了静默错误或者磁盘写入时出了问题。验证方法下载完成后检查关键文件是否齐全。一个标准的模型仓库通常包含config.json、tokenizer.json、tokenizer_config.json、model.safetensors或分片文件、generation_config.json等。如果缺少config.json或权重文件模型肯定加载不了。对于 safetensors 格式可以用safetensors库验证文件完整性from safetensors import safe_open with safe_open(model.safetensors, frameworkpt) as f: print(f.keys())如果能正常打开并列出张量名称说明文件基本完整。5.4 坑四模型需要鉴权但没配置 tokenHuggingFace 上有些模型是 gated 的需要先同意协议并配置 access token 才能下载。如果你直接下载会收到 401 或 403 错误。解决方案在 HuggingFace 网站的个人设置里生成一个 access token然后huggingface-cli login按提示输入 token。或者设置环境变量export HUGGING_FACE_HUB_TOKEN你的tokenModelScope 上部分模型也需要登录用modelscope login命令配置即可。5.5 坑五下载路径包含中文或空格导致报错这个问题比较隐蔽。有些工具在处理包含中文或空格的路径时会出问题尤其是 Windows 环境下。我见过有人把模型下载到 我的模型/新文件夹 这样的路径下结果加载时报编码错误。解决方案模型路径尽量用纯英文、无空格的命名比如/data/models/qwen2.5-7b。这不是强迫症而是能避免很多莫名其妙的报错。6. 下载之后的验证与加载确保模型真的能用6.1 文件完整性检查清单下载完成后别急着跑推理先花两分钟做个基本检查。我通常会用这个清单过一遍config.json是否存在且内容完整能正常解析 JSON权重文件是否齐全分片模型要确认所有分片都在tokenizer相关文件是否齐全文件大小是否和页面标注的一致差太多说明没下完用一条命令快速看目录结构ls -lh ./models/qwen2.5-7b/如果看到model-00001-of-00004.safetensors到model-00004-of-00004.safetensors都在且大小合理基本就没问题。6.2 用 transformers 加载验证最直接的验证方式就是用transformers加载一下from transformers import AutoModelForCausalLM, AutoTokenizer model_path ./models/qwen2.5-7b tokenizer AutoTokenizer.from_pretrained(model_path) model AutoModelForCausalLM.from_pretrained( model_path, device_mapauto, torch_dtypeauto ) inputs tokenizer(你好, return_tensorspt).to(model.device) outputs model.generate(**inputs, max_new_tokens50) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))如果能正常输出说明模型下载完整、加载无误。如果报错根据错误信息定位是哪个文件出了问题。6.3 从 ModelScope 下载的模型如何用 transformers 加载这里有个小细节从 ModelScope 下载的模型目录结构和 HuggingFace 基本一致所以可以直接用transformers加载。但如果你是用snapshot_download下载的返回的路径可能包含一些额外的元数据文件不影响加载。如果遇到transformers版本和模型不兼容的情况比如模型用了新的架构但你的 transformers 太旧升级一下库通常能解决pip install -U transformers7. 一些让下载更顺手的实战技巧7.1 用 aria2 多线程加速下载huggingface-cli和modelscope本身不支持多线程但你可以拿到文件的直链后用aria2来下。以 HuggingFace 为例文件直链格式是https://huggingface.co/模型作者/模型名/resolve/main/文件名然后用 aria2 多线程下载aria2c -x 16 -s 16 -k 1M 文件直链 -o 本地文件名-x 16表示 16 个连接-s 16表示分 16 段下载-k 1M是分片大小。对于大文件多线程能明显提升速度。不过要注意有些镜像站可能不支持多线程会被限速。7.2 只下载需要的文件别整个仓库拉很多模型仓库里除了权重文件还有一堆用不上的东西——比如原始格式的权重.bin和.safetensors可能同时存在、训练日志、示例代码等。如果你只需要推理完全可以只下载 safetensors 格式的权重和配置文件。用huggingface-cli的--include参数huggingface-cli download 模型作者/模型名 \ --include *.safetensors *.json \ --local-dir ./models这样能省下不少空间和下载时间。ModelScope 的allow_file_pattern参数也是同样的思路。7.3 后台下载与进度监控大模型下载动辄几小时不可能一直盯着终端。用nohup或screen让下载在后台跑nohup huggingface-cli download 模型作者/模型名 --local-dir ./models download.log 21 然后定期看日志tail -f download.log或者用screenscreen -S download # 在 screen 里执行下载命令 # CtrlA D 分离screen -r download 恢复这样即使 SSH 断线下载也不会中断。7.4 模型下载后的目录管理下载的模型多了之后目录管理就成了问题。我的做法是按模型系列分目录/data/models/ ├── qwen/ │ ├── qwen2.5-7b/ │ └── qwen2.5-14b/ ├── llama/ │ └── llama-3-8b/ └── chatglm/ └── chatglm4-9b/然后在代码里用一个配置文件或环境变量来指定模型根目录避免硬编码路径。这样迁移或换机器时改一个地方就行。8. 关于下载这件事我踩过几次坑之后的体会说到底模型下载本身不复杂复杂的是网络环境、存储管理和工具链的细节。我刚开始的时候也走过不少弯路——用浏览器下大模型下到崩溃、git clone 完发现权重是空的、磁盘满了导致下载失败还得手动清理。这些坑踩过一遍之后现在基本能做到一次成功。如果让我给一个最简单的建议国内环境优先用 ModelScope海外模型走 HuggingFace 镜像下载工具首选官方 cli下载前先看磁盘空间下载后先验证再加载。这五句话能帮你避开九成以上的问题。另外模型下载只是第一步后面还有推理部署、显存优化、量化压缩一堆事。但把下载这个基础环节做扎实后面的路会顺很多。毕竟模型都拉不下来后面的故事就无从谈起了。