我先把话说在前面开源模型这事圈子里每天都有人问“模型在哪下”“怎么下这么慢”“有没有国内快一点的办法”。如果你这段时间刷到了 Qwen、Llama、DeepSeek、GLM 这些名字想在自己电脑上跑个开源大模型或者小模型那第一步永远卡在下载。HuggingFace 和 ModelScope魔搭是全球被用得最多的两个模型托管平台一个偏国际生态一个偏国内环境很多新手一上来就被弄糊涂到底该用哪个为什么网页一直打不开文件下到一半断掉怎么办还有“pip install modelscope 报 externally-managed-environment”这种报错网上搜了一堆答案没一个讲清楚。这篇文章就把我实际跑过的下载流程、踩过的坑、教训全盘写出来从网页、命令行、Python 代码、镜像站四个角度把下载这件事捋明白适合想在本地部署开源模型的开发者、AI 初学者以及一切被大模型下载折磨过的人。1. 先搞清楚你要面对的两个平台1.1 HuggingFace全球最大的模型社区但不是为国内网络设计的HuggingFace 是开源模型的中心仓库GPT、Llama、Qwen、Stable Diffusion 这些模型几乎都会在 HuggingFace 上发布官方权重。它不光是存模型文件还附带模型卡Model Card、推理代码示例、数据集、Space 在线 Demo甚至能直接在网页上测试模型效果。你可以理解成 GitHub 和模型领域的 PyPI 合体社区氛围浓生态工具全很多框架默认就是从 HuggingFace 拉模型。但问题也很现实这个平台的服务器在海外国内直连的时候下载速度不稳定有时候几 MB 的文件几分钟都拉不下来几 GB 的权重文件更是折磨。而且 HuggingFace 经常有整站或者 API 连接超时的情况不是你代码写得不对是网络环境本身不够顺畅。所以国内开发者面对 HuggingFace 的第一课题不是“怎么下”而是“在现有网络条件下怎么下得快、下得稳”。1.2 ModelScope魔搭阿里开源的本土平台ModelScope 是阿里开源的一个模型托管与推理平台中文名叫“魔搭”目前上面托管了数千个模型尤其是中文优化过的模型比如 Qwen 系列、通义系列以及大量中文社区贡献的微调模型很多会在 ModelScope 上首发。因为服务器在国内下载速度普遍比 HuggingFace 直连快得多网页加载也顺滑不需要额外的网络适配这对国内开发者来说是实打实的方便。ModelScope 的定位是“全流程”不只是下载还包括在线体验、Notebook、训练微调、部署推理等功能。你可能会问那我是不是只用 ModelScope 就够了也不尽然。很多国际社区新出的模型或者一些比较小众的仓库首发还是在 HuggingFaceModelScope 上的同步有一定滞后甚至有些英文模型根本没有转载。所以两个平台其实是互补关系最好的做法是两个都会用按模型和网络情况灵活选择。对比项HuggingFaceModelScope魔搭模型数量与更新速度数量最大更新最快中文模型丰富部分国际模型有同步国内网络下载体验直连不稳定需镜像或加速方案较快较稳定中文资料与社区氛围国际社区英文资料多中文资料多上手友好配套能力Datasets、Spaces、API 生态强在线体验、微调、部署更本地化下载方式网页、git、Python SDK、镜像网页、Python SDK、CLI2. 模型下载前的准备工作2.1 确认模型文件结构哪些文件必须下载很多人下载模型时直接把整个仓库的几百个文件全拉下来结果磁盘爆了还根本用不上。我在本地跑开源模型时总结过一个经验先看清仓库里的文件结构再决定下载范围。一个典型的 HuggingFace 模型仓库至少包含这几类文件config.json模型架构、层数、注意力头数、词汇表大小等配置这是模型能不能正确加载的地基缺了它整个模型都启动不了。model.safetensors或pytorch_model.bin真正的权重文件也是体积最大的部分。safetensors是现代的推荐格式加载更快、更安全。tokenizer.json、tokenizer_config.json、vocab.json分词器相关文件文本模型基本都会用到。generation_config.json生成参数配置比如 temperature、max_length 等默认值。扩展文件如chat_template、README.md、示例脚本等这些对核心运行不是必要的。如果你只想跑一个 7B 参数的模型model.safetensors往往就有 14GB 以上而整个仓库可能有几十个不同版本的文件。我建议用allow_patterns只下载必要的文件不要全仓下拉后面我会给出具体代码。2.2 用 Python 虚拟环境规避 externally-managed-environment热词里有一个很典型的报错pip install modelscope error: externally-managed-environment。这个错误我在新系统的 Ubuntu 和 Debian 环境上都遇到过本质不是 modelscope 的问题而是新版 Python 对系统环境的保护机制。PEP 668 规定从 Python 3.11 开始很多 Linux 发行版会给系统级 Python 标记externally-managed意思是你不能再直接用pip install往系统环境里塞包避免破坏系统自带的 Python 工具链。解决办法有两个一个是创建虚拟环境用python3 -m venv .venv隔离出独立空间在虚拟环境里随便装另一个是给 pip 加--break-system-packages参数但这个操作等于无视系统的保护措施不建议在生产环境使用。我个人的建议是把所有模型下载、推理相关的依赖都装进虚拟环境这样既不会污染系统也能避免很多环境依赖冲突。python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install modelscope huggingface_hub虚拟环境看起来多了一步操作但长期用下来能省很多事。模型下载完要推理时经常还要装torch、transformers、accelerate这些大包如果全塞进系统 Python一旦某个包版本冲突排查成本非常高。虚拟环境相当于给每个项目一个独立的包仓库出问题直接删掉重建干净利落。2.3 工具链准备与网络环境检查下载开源模型之前我建议先确认三样东西git、git-lfs、huggingface_hub或modelscope。git用来拉取仓库信息git-lfs用来拉大文件huggingface_hub是 HuggingFace 官方提供的 Python 工具库后面讲的代码下载方式全靠它。git --version git lfs install pip show huggingface_hub modelscope如果git lfs没有安装下载大文件时会发现仓库里全是几百字节的指针文件而非真实的权重内容这个问题很隐蔽等会儿我会专门讲。网络环境方面国内访问 HuggingFace 时可以先做一次小测试用浏览器打开一个模型页面如果加载慢或者打不开那就不建议硬等直接上镜像站或者换 ModelScope。3. HuggingFace 下载实操四种主流方法3.1 网页直接下载适合小模型和临时取用HuggingFace 每个模型仓库的页面右上角都有一个“下载”图标点开后会弹出文件列表勾选想下载的文件就能直接下载。这种方式最简单适合几十 MB 到几百 MB 的小模型、分词器文件或者配置文件。但网页下载也有明显的坑第一大文件容易断断了浏览器未必支持断点续传经常重新来过第二有些仓库有几十个文件手动一个一个点又累又容易漏第三如果网页本身加载不顺畅下载体验会雪上加霜。所以网页下载只适合“临时拿个小文件”真正要拉整个模型还是得走命令行或者代码。3.2 git clone Git LFS适合整仓同步但要防指针坑如果你熟悉 Git 操作可以像克隆代码仓库一样克隆模型仓库git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct这条命令会把你带入一个巨大的坑如果没装git-lfs克隆下来的仓库里大文件全是指针文本一个几 GB 的模型文件可能只有几百字节。原因是 HuggingFace 用 Git LFS 存放大文件普通 Git 拉不下来真实内容。解决方法是先git lfs install然后再次git lfs pull或者用GIT_LFS_SKIP_SMUDGE1跳过 LFS 下载但之后手动管理。git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct cd Qwen2.5-7B-Instruct git lfs pull如果网络环境一般git clone大仓库时经常会中途卡住要么超时要么 LFS 下载中断。这时候可以先用GIT_LFS_SKIP_SMUDGE1把代码和元数据先拉下来再单独对 LFS 文件做断点继续虽然操作复杂了一点但至少比反复重来强。3.3 huggingface_hub 代码下载可控性最强我个人最常用的是huggingface_hub的snapshot_download因为它有断点续传、本地目录控制、文件过滤、并发下载这些优势比git clone更适合大模型文件。from huggingface_hub import snapshot_download snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir./models/Qwen2.5-7B-Instruct, allow_patterns[*.json, *.safetensors, *.txt, *.model], )几个参数说明一下repo_id模型仓库的唯一标识格式是“用户名/仓库名”。local_dir下载后存放的本地目录不填的话会存到 HuggingFace 的默认缓存目录。allow_patterns只下载匹配规则的文件用*.safetensors匹配所有权重文件用*.json匹配配置文件灵活控制体积。resume_download在老版本里可以显式开启较新的版本默认支持断点续传下载中断后重新执行同一条命令会自动跳过已完成的文件。代码下载最大的好处是可以写进脚本比如做一个批量下载工具把多个模型放进列表循环拉取下载失败后自动重试这在手动操作时完全不敢想。3.4 用社区镜像站加速网络环境下的常见替代方案国内访问 HuggingFace 不稳定很多开发者会配置社区维护的镜像站。最常被提及的是hf-mirror.com它通过设置环境变量HF_ENDPOINT就能让huggingface_hub把请求指向镜像地址代码本身不用做任何修改。export HF_ENDPOINThttps://hf-mirror.com设置之后再用snapshot_download或者transformers的from_pretrained加载模型时流量会走镜像站下载速度和稳定性都有明显改善。这个镜像站是社区公开的合规加速服务不属于任何非常规手段国内开发者把它当成常规网络优化工具在用。需要注意的是镜像站是缓存同步机制某些最新发布的模型可能暂时没有镜像缓存这时候模型页面上会提示“Not cached”那就只能换 HuggingFace 原站或者 ModelScope 碰碰运气。另外环境变量设置是终端会话级的新开一个终端窗口之后要重新 export如果想永久生效可以写进~/.bashrc。4. ModelScope魔搭下载实操4.1 网页端操作模型详情页的“下载模型”按钮ModelScope 的网页体验相比 HuggingFace 对国内用户友好太多加载快界面全中文找模型也方便。进入一个模型详情页页面上能看到模型卡、文件列表和“下载模型”的按钮。网页下载方式适合小文件和 HuggingFace 一样有断点问题所以我更多是用命令行或者 Python SDK。ModelScope 上有不少热门模型比如Qwen/Qwen2.5-7B-Instruct、ZhipuAI/glm-4-9b-chat、deepseek-ai/DeepSeek-R1-Distill-Qwen-7B等模型页会标注参数规模、支持语言、推理示例选型比 HuggingFace 更直观。4.2 modelscope 库安装与 Python SDK 下载ModelScope 的官方 Python 库就是modelscope安装命令很简单pip install modelscope之后用snapshot_download下载模型函数的用法和 huggingface_hub 很像from modelscope import snapshot_download model_dir snapshot_download( model_idQwen/Qwen2.5-7B-Instruct, local_dir./models/Qwen2.5-7B-Instruct, )注意这里的参数名和 HuggingFace 不一样ModelScope 用的是model_idHuggingFace 用的是repo_id。local_dir参数同样可以控制下载位置如果不填默认会存到~/.cache/modelscope/hub目录里面按“用户名/模型名”的目录结构存放。ModelScope 的下载速度在国内网络环境下通常很快我在实际测试中拉一个 7B 模型的权重文件速度比 HuggingFace 直连高出不少而且断线续传的能力也不错。如果你要下载的模型在 ModelScope 上有同步版本优先用它。4.3 modelscope CLI 下载与缓存目录管理除了 Python APIModelScope 还提供了命令行工具。新版 modelscope 支持modelscope download命令可以直接按模型 ID 下载modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/Qwen2.5-7B-Instruct用 CLI 的好处是简单直接适合不想写 Python 脚本的读者而且可以在服务器上配合tmux或screen挂后台下载。缓存目录方面ModelScope 默认会缓存到~/.cache/modelscope/hub下载过的模型如果你用model_id再次加载SDK 会优先检查缓存不会重复下载大文件。这里我想特别提醒ModelScope 的缓存目录和 HuggingFace 的缓存目录不通用。你在 HuggingFace 下载过 Qwen不等于 ModelScope 就能直接复用两个平台的文件组织方式、索引结构都不同。如果磁盘空间紧张建议用local_dir集中存放下载好的模型用一个总的目录统一管理多个模型后续找文件也方便。5. 下载后的常见问题与排查技巧5.1 下载到一半断了怎么办这是所有大文件下载场景中最高频的问题。无论 HuggingFace 还是 ModelScope几 GB 的权重文件下载到一半断线很容易让人崩溃。解决办法的核心是“支持断点续传”。huggingface_hub和modelscope的snapshot_download默认都会对已完成的文件做校验和跳过所以重新执行一遍下载命令就能接着上次的进度继续而不是从零开始。另外如果你用curl或者wget直接拉单个文件记得加上断点续传参数wget -c https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/model.safetensors-c参数就是 continue中断后重新执行会从断点继续。实测中大文件下载最怕的就是中断后忘记续传直接重新下载白白浪费时间。我现在的习惯是所有大模型下载都写进 Python 脚本配合重试机制下载失败自动重新执行snapshot_download彻底告别手动监控。5.2 “文件不完整”或“safetensors 加载失败”怎么排查模型下完了结果加载时报Error no file named pytorch_model.bin或者safetensors文件损坏这种情况通常有几个原因。首先是文件没下全。经常有人用网页方式手动下载少勾了一个分片文件比如model-00001-of-00004.safetensors只下了前三个加载时自然会报错。排查方法很简单打开模型仓库文件列表对照本地文件逐一检查文件名和大小重点看是否有分片编号缺失。其次是磁盘空间不足。大模型仓库动辄十几 GB如果下载目录所在磁盘空间不够文件写到一半就停了但下载工具没有报错最后得到一个残缺的权重文件。建议下载前用df -h看一下磁盘剩余空间至少留出模型体积的 1.5 倍余量因为还可能要存临时文件。最后是 LFS 指针文件问题。如果用了git clone且没配置好 Git LFS本地文件可能是指针而非真实权重文件体积很小但内容完全不对。用git lfs pull补拉即可。5.3 显存不够优先考虑量化版模型很多新手下载了一个 7B 模型满心期待跑起来结果程序直接报CUDA out of memory。这不是模型文件有问题而是硬件配置支撑不住。7B 模型对应的是大约 14GB 的 float16 权重要跑推理至少需要 16GB 以上的显存很多人的消费级显卡根本带不动。一个实际可用的方案是下载量化版模型。所谓量化简单类比就是把高精度浮点数压缩成低精度整数模型文件体积变小显存占用量大幅下降推理速度反而可能更快代价是生成质量有一点点损失。现在社区里最常见的量化格式有 GGUF 和 GPTQ其中 GGUF 系列里Q4_K_M、Q5_K_M这类文件是性价比很高的选择。如果你想在低显存设备上跑模型优先找带 GGUF 后缀的文件配合llama.cpp系列的推理工具效果不错。我在实际测试中用 8GB 显存跑 7B 模型的 Q4 量化版速度基本能接受生成质量在大部分场景下和原版差别不大内存换显存的思路尤其适合本地部署。5.4 pip install modelscope 报 externally-managed-environment 的完整修复流程这个报错的高频程度在我收到的反馈里排得上前三。完整报错内容大致是error: externally-managed-environment × This environment is externally managed原因我在前面讲过是 PEP 668 的保护机制。完整的修复流程分三步走。第一步创建虚拟环境python3 -m venv .venv第二步激活虚拟环境source .venv/bin/activate第三步再安装 modelscopepip install modelscope激活后终端提示符前面会出现一个(.venv)前缀此时 pip 已经和系统 Python 隔离不会再触发保护报错。如果你需要跑 PyTorch 推理顺便把相关依赖一起装进去pip install modelscope torch transformers accelerate这里面的torch体积很大CPU 版本和 GPU 版本的安装命令有区别GPU 版需要去 PyTorch 官网选对应 CUDA 版本的安装命令直接pip install torch装的是 CPU 版还是 GPU 版因版本而异这一步经常有人踩坑。如果你实在不想用虚拟环境还有一个临时方案pip install modelscope --break-system-packages这个命令能强制安装到系统环境但我不建议长期这么干因为你装的包多了之后系统 Python 环境会变得混乱遇到依赖冲突想排查会非常痛苦。虚拟环境多花两分钟后面能省两小时。5.5 下载慢不是模型的问题可能是并发和协议的问题最后补充一个很多人忽略的点同一个模型文件用不同工具下载速度差距会非常大。我在实验中对比过几种方式仅就 HuggingFace 直连场景而言git clone的速度通常不如snapshot_download原因之一是snapshot_download会用多线程并发拉取多个文件而git clone的 LFS 拉取往往是逐个进行的。镜像站配合snapshot_download可能是国内环境下速度最稳的组合。ModelScope 方面官方 SDK 的下载优化在近几个版本里做了很多改进如果发现某个版本下载速度不理想先升级到最新版再试pip install -U modelscope huggingface_hub写在最后我个人的习惯是模型在国内有官方同步或者中文优化版本时优先用 ModelScope 下载速度快、省心省事模型需要最新权重或者只有 HuggingFace 有时用huggingface_hub配镜像站下载小模型直接网页拿大模型一律脚本化处理。这几种方式配合起来基本能覆盖 90% 的下载场景。至于下载后怎么加载、怎么做推理、怎么量化那是另一篇长文的话题了但你可以放心的是只要模型文件完整地到了本地后面的一切都有路可走。这篇东西如果对你有用下次朋友再问“模型到底在哪下”直接把链接甩给他就行。