开源模型下载这件事看起来只是点一下下载按钮但真到项目里跑起来你会发现坑比想象中多得多。我自己刚开始接触大模型那会儿以为下载模型就是复制个链接、跑个命令的事结果第一次下Qwen的时候磁盘爆了、第二次下Llama的时候网络断了三次、第三次下Embedding模型的时候下完发现文件不完整加载直接报错。后来折腾久了才慢慢摸清楚HuggingFace、ModelScope、魔搭这几个平台各有各的脾气下载方式、缓存机制、文件结构、断点续传策略都不一样。这篇内容就是把我这些年下载开源模型踩过的坑、总结出来的方法完整地梳理一遍不管你是刚入门的新手还是已经用过几个模型的老手应该都能从中找到一些之前没注意到的细节。1. 先搞清楚这三个平台到底是什么关系很多人第一次看到HuggingFace、ModelScope、魔搭这三个名字的时候会以为它们是三个完全独立的平台各管各的。实际上ModelScope和魔搭是同一个东西——魔搭是ModelScope的中文名就像HuggingFace有时候被叫做抱脸一样只是叫法不同。所以真正需要区分的其实是HuggingFace和ModelScope这两个平台。1.1 HuggingFace的定位和特点HuggingFace是全球最大的开源模型托管平台基本上你能想到的开源模型上面都能找到。它的模型库覆盖了NLP、CV、语音、多模态等几乎所有方向而且更新速度非常快很多模型刚发布几小时内就会有人上传。它的优势在于生态完整transformers、diffusers、datasets这些库都是它家的模型卡片、讨论区、推理API这些配套功能也很成熟。但问题也很明显——服务器在海外国内访问速度不稳定。有时候下载一个几百MB的模型速度能跑到几MB/s有时候直接卡在几百KB/s甚至断连。尤其是大模型动辄几十GB网络一断就得重来非常折磨人。所以国内开发者用HuggingFace基本都要配合镜像站或者用其他方式加速。1.2 ModelScope魔搭的定位和特点ModelScope是阿里达摩院推出的模型开放平台中文名就是魔搭。它的定位和HuggingFace类似但更偏向国内开发者。上面有大量国内团队上传的模型比如通义千问系列、ChatGLM系列、百川系列等也有很多从HuggingFace同步过来的模型。因为服务器在国内下载速度通常很稳定基本能跑满带宽。ModelScope的另一个优势是和阿里云生态结合得比较紧密如果你用PAI平台或者DashScope API可以直接对接。它的SDK设计也参考了HuggingFace的风格用起来不会太陌生。不过模型数量相比HuggingFace还是少一些特别是一些比较小众或者刚发布的研究模型可能上面还没有。1.3 两个平台的核心差异对比对比维度HuggingFaceModelScope魔搭服务器位置海外国内下载速度不稳定需加速稳定通常跑满带宽模型数量极多覆盖全面较多偏国内模型生态工具transformers/diffusers等modelscope库兼容部分HF接口模型更新速度极快较快热门模型会同步使用门槛需要处理网络问题国内直接可用搞清楚这两个平台的关系和差异之后接下来的问题就是具体怎么下载用命令行还是用代码下载到哪里怎么断点续传这些才是真正影响效率的细节。2. HuggingFace模型下载的几种姿势和各自的坑HuggingFace下载模型的方式有好几种从最原始的git clone到官方的huggingface-cli再到Python代码里直接from_pretrained每种方式适用的场景不一样踩的坑也不一样。我下面按推荐程度从高到低来说。2.1 用huggingface-cli下载最推荐的方式huggingface-cli是官方提供的命令行工具安装很简单pip install -U huggingface_hub[cli]装好之后下载一个模型的基本命令是huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen2.5-7b这个命令会把模型下载到当前目录下的qwen2.5-7b文件夹里。相比git clone它的优势在于支持断点续传、可以只下载指定文件、下载速度更稳定。如果你只想下载模型里的某几个文件比如只需要config.json和模型权重可以这样huggingface-cli download Qwen/Qwen2.5-7B-Instruct --include *.json *.safetensors --local-dir ./qwen2.5-7b这里有个细节要注意--include后面的模式匹配是大小写敏感的而且支持通配符。如果你不确定模型里有哪些文件可以先跑一下huggingface-cli download Qwen/Qwen2.5-7B-Instruct --dry-run--dry-run会列出所有会下载的文件但不会真正下载方便你确认。还有一个很实用的参数是--resume-download不过新版本的huggingface-cli默认就支持断点续传了不需要额外加这个参数。如果你下载到一半断了重新跑同样的命令它会自动从断点继续。2.2 用Python代码下载适合集成到脚本里如果你是在Python脚本里下载模型可以用snapshot_downloadfrom huggingface_hub import snapshot_download snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir./qwen2.5-7b, local_dir_use_symlinksFalse, resume_downloadTrue )这里有几个参数值得说一下。local_dir_use_symlinksFalse这个参数在新版本里已经废弃了但如果你用的是老版本建议设成False否则下载下来的文件是符号链接指向缓存目录你移动文件夹的时候会出问题。resume_downloadTrue是开启断点续传不过新版本也默认开启了。如果你只想下载特定文件可以用allow_patterns和ignore_patternssnapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir./qwen2.5-7b, allow_patterns[*.json, *.safetensors], ignore_patterns[*.bin] )这个在只需要部分文件的时候很有用比如你只需要safetensors格式的权重不想下bin格式的就可以用ignore_patterns排除掉。2.3 用git clone下载不推荐但有时候不得不用git clone是最原始的方式git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct这种方式的问题在于第一它会把整个仓库包括历史记录都克隆下来占用空间更大第二断点续传支持不好断了就得重新来第三大文件是通过git lfs管理的有时候lfs会卡住。所以除非你有特殊需求否则不建议用这种方式。2.4 下载过程中的常见坑和解决办法坑一磁盘空间不够。大模型动辄几十GB下载之前一定要先确认磁盘空间。可以用df -h看一下剩余空间。另外要注意HuggingFace默认会把模型缓存到~/.cache/huggingface/hub目录下如果你用--local-dir指定了目录它还是会先在缓存目录下存一份然后再复制过去。所以实际占用空间可能是模型大小的两倍。解决办法是设置环境变量HF_HOME或者HUGGINGFACE_HUB_CACHE把缓存目录指到大盘上。坑二下载到一半断了重新下发现文件不完整。这种情况通常是因为缓存目录里有残留的临时文件。解决办法是找到缓存目录下的blobs文件夹把对应的.incomplete文件删掉然后重新下载。坑三下载速度慢。这个前面说过了国内访问HuggingFace速度不稳定。解决办法是用镜像站具体怎么配置我后面会详细说。坑四权限问题。有些模型是gated的需要先申请访问权限然后在命令行里登录huggingface-cli login输入你的token之后才能下载。如果你没有token可以去HuggingFace的设置页面生成一个。3. ModelScope魔搭下载模型的完整流程ModelScope的下载方式和HuggingFace有些类似但细节上差别不小。它的SDK叫modelscope安装命令是pip install modelscope3.1 用modelscope-cli下载ModelScope也提供了命令行工具不过相比HuggingFace的cli它的功能要简单一些。基本用法是modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./qwen2.5-7b这个命令会把模型下载到指定目录。和HuggingFace不同的是ModelScope默认不会在缓存目录里再存一份而是直接下载到你指定的目录所以不会出现空间翻倍的问题。如果你只想下载特定文件可以用--include参数modelscope download --model Qwen/Qwen2.5-7B-Instruct --include *.json *.safetensors --local_dir ./qwen2.5-7b3.2 用Python代码下载在Python里下载ModelScope的模型可以用snapshot_downloadfrom modelscope import snapshot_download model_dir snapshot_download( Qwen/Qwen2.5-7B-Instruct, cache_dir./qwen2.5-7b )注意这里的参数名是cache_dir而不是local_dir和HuggingFace不一样。另外ModelScope的snapshot_download默认会返回模型在本地的路径方便你后续加载。3.3 ModelScope下载的注意事项第一模型ID的格式。ModelScope的模型ID通常是组织名/模型名的格式比如Qwen/Qwen2.5-7B-Instruct。但有些模型是个人上传的ID可能是用户名/模型名。如果你不确定模型ID可以去ModelScope网站上搜一下复制对应的ID。第二缓存目录。ModelScope默认的缓存目录是~/.cache/modelscope/hub你可以通过设置环境变量MODELSCOPE_CACHE来修改。如果你经常下载大模型建议把这个目录指到大盘上。第三断点续传。ModelScope的下载工具支持断点续传但有时候会出现下载完成后文件校验不通过的情况。如果遇到这种情况可以先把缓存目录下对应的模型文件夹删掉然后重新下载。第四和HuggingFace的兼容性。ModelScope上有很多模型是从HuggingFace同步过来的文件结构基本一致。但有些模型会做一些调整比如把配置文件改名、把权重格式转换等。如果你从ModelScope下载的模型要放到HuggingFace的transformers里加载可能需要手动调整一下文件结构。4. 国内加速下载的几种实用方案国内下载HuggingFace模型慢这是大家都头疼的问题。我试过好几种方案下面说说各自的效果和适用场景。4.1 使用HF镜像站最常用的方案是使用HuggingFace的镜像站。配置方法很简单设置一个环境变量就行export HF_ENDPOINThttps://hf-mirror.com设置完之后再用huggingface-cli或者Python代码下载就会自动走镜像站。这个方案的好处是配置简单不需要额外装什么东西。缺点是镜像站有时候会同步延迟刚发布的模型可能还没有。如果你是在Python代码里用可以在导入huggingface_hub之前设置import os os.environ[HF_ENDPOINT] https://hf-mirror.com from huggingface_hub import snapshot_download snapshot_download(...)注意这个环境变量必须在导入huggingface_hub之前设置否则不生效。4.2 使用ModelScope作为替代源如果你要下载的模型在ModelScope上也有那直接走ModelScope下载是最省事的。很多热门模型比如Qwen系列、ChatGLM系列、Llama系列ModelScope上都有同步。下载速度稳定也不用折腾镜像配置。但要注意ModelScope上的模型版本可能和HuggingFace上的不完全一致。有些模型在ModelScope上会做一些优化比如量化版本、裁剪版本等。下载之前最好看一下模型卡片确认版本是否符合你的需求。4.3 用huggingface-cli的传输加速功能新版本的huggingface-cli支持--hf-transfer参数可以启用传输加速pip install hf_transfer export HF_HUB_ENABLE_HF_TRANSFER1 huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen2.5-7bhf_transfer是用Rust写的一个传输库下载速度比默认的快不少。不过它和镜像站有时候会冲突如果你同时用了镜像站和hf_transfer可能会出现下载失败的情况。建议先试镜像站如果速度还是不行再试hf_transfer。4.4 几种方案的对比方案配置难度下载速度适用场景HF镜像站低中等偏快通用场景模型在镜像站有同步ModelScope替代低快模型在ModelScope上有hf_transfer中快镜像站速度不理想时手动下载高取决于网络小文件或特殊需求5. 下载之后的文件结构解析和加载验证模型下载完了不代表就能直接用。很多时候加载报错问题就出在文件结构上。这一节我说说下载后的目录里都有什么以及怎么验证模型能不能正常加载。5.1 典型的模型目录结构一个标准的HuggingFace模型目录通常长这样qwen2.5-7b/ ├── config.json ├── generation_config.json ├── model.safetensors ├── model.safetensors.index.json ├── tokenizer.json ├── tokenizer_config.json ├── vocab.json ├── merges.txt └── special_tokens_map.json几个关键文件的作用config.json模型的结构配置包括层数、隐藏维度、注意力头数等。加载模型时首先读这个文件。model.safetensors或pytorch_model.bin模型权重。safetensors格式更安全、加载更快推荐优先用这个。model.safetensors.index.json如果模型太大被切分成多个文件这个索引文件会记录每个权重在哪个分片里。tokenizer.json和tokenizer_config.json分词器的配置和词表。generation_config.json生成参数比如默认的max_length、temperature等。5.2 验证模型能否正常加载下载完之后建议先跑一个简单的加载测试from transformers import AutoModelForCausalLM, AutoTokenizer model_path ./qwen2.5-7b tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, trust_remote_codeTrue, device_mapauto ) input_text 你好请介绍一下你自己。 inputs tokenizer(input_text, return_tensorspt) outputs model.generate(**inputs, max_new_tokens100) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))如果这段代码能跑通说明模型下载完整、文件结构正确。如果报错根据错误信息排查OSError: Unable to load weights权重文件不完整或格式不对检查safetensors文件大小是否和模型卡片上标注的一致。KeyError: xxxconfig.json里缺少某个字段可能是下载不完整或者版本不匹配。ImportError: cannot import name xxxtransformers版本太老升级一下。5.3 常见加载报错和解决办法报错一trust_remote_code相关。很多国内模型需要设置trust_remote_codeTrue才能加载因为它们的模型代码不在transformers库里而是随模型一起下载的。如果你不设这个参数会报错说找不到模型类。报错二显存不够。大模型加载需要大量显存如果显存不够可以用device_mapauto让transformers自动分配或者用load_in_8bitTrue、load_in_4bitTrue做量化加载。不过量化加载需要装bitsandbytes库。报错三文件权限问题。如果你是在Linux上下载的模型文件权限可能不对导致加载时报Permission denied。解决办法是chmod -R 755一下模型目录。报错四路径问题。如果你用相对路径加载模型要注意当前工作目录。建议用绝对路径避免因为目录切换导致找不到模型。6. 大模型下载的磁盘管理和缓存清理下载大模型最容易被忽视的问题就是磁盘管理。一个7B的模型safetensors格式大概14GB左右加上缓存目录里的副本实际占用可能接近30GB。如果你同时下好几个模型磁盘很快就满了。6.1 缓存目录的机制HuggingFace的缓存机制是这样的默认情况下模型会先下载到~/.cache/huggingface/hub目录下然后如果你指定了--local-dir它会从缓存目录复制一份过去。所以实际占用是模型大小的两倍。如果你不想占用两份空间可以设置HF_HUB_CACHE环境变量把缓存目录指到和local-dir同一个盘上或者直接用--local-dir配合local_dir_use_symlinksFalse老版本来避免复制。ModelScope的缓存机制简单一些默认直接下载到~/.cache/modelscope/hub如果你指定了cache_dir就直接下载到指定目录不会额外存一份。6.2 清理缓存的正确姿势如果你确定某个模型不再需要了可以清理缓存。HuggingFace提供了命令行工具huggingface-cli delete-cache这个命令会列出所有缓存的模型让你选择删除哪些。不过它删除的是缓存目录里的文件如果你用--local-dir下载的模型还需要手动删除local-dir目录。ModelScope没有类似的清理工具需要手动删除~/.cache/modelscope/hub下对应的文件夹。6.3 磁盘空间规划建议如果你经常下载大模型建议单独挂一块大盘把缓存目录和模型存储目录都指到这块盘上。具体做法是设置环境变量export HF_HOME/data/huggingface export MODELSCOPE_CACHE/data/modelscope然后把这些环境变量写到~/.bashrc或者~/.zshrc里这样每次登录都会自动生效。另外下载之前一定要先确认磁盘空间。可以用df -h看剩余空间用du -sh看某个目录占用了多少。对于大模型建议预留至少模型大小两倍的空间避免下载到一半空间不够。7. 几个实际下载场景的完整操作记录前面说了很多原理和注意事项这一节我用几个实际场景把完整的操作流程串一遍。你可以直接照着做。7.1 场景一从HuggingFace下载Qwen2.5-7B到本地假设你要下载Qwen2.5-7B-Instruct模型存到/data/models/qwen2.5-7b目录下。第一步确认磁盘空间df -h /data确保/data至少有30GB可用空间。第二步设置镜像站和缓存目录export HF_ENDPOINThttps://hf-mirror.com export HF_HOME/data/huggingface_cache第三步安装huggingface-clipip install -U huggingface_hub[cli]第四步下载模型huggingface-cli download Qwen/Qwen2.5-7B-Instruct \ --local-dir /data/models/qwen2.5-7b \ --include *.json *.safetensors *.txt第五步验证下载结果ls -lh /data/models/qwen2.5-7b检查文件是否齐全特别是safetensors文件的大小是否和模型卡片上标注的一致。第六步跑一个加载测试from transformers import AutoModelForCausalLM, AutoTokenizer model_path /data/models/qwen2.5-7b tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained(model_path, trust_remote_codeTrue, device_mapauto) inputs tokenizer(你好, return_tensorspt) outputs model.generate(**inputs, max_new_tokens50) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))7.2 场景二从ModelScope下载模型并加载假设你要从ModelScope下载Qwen2.5-7B-Instruct存到/data/models/qwen2.5-7b-ms。第一步安装modelscopepip install modelscope第二步设置缓存目录export MODELSCOPE_CACHE/data/modelscope_cache第三步下载模型modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /data/models/qwen2.5-7b-ms第四步验证并加载from modelscope import snapshot_download from transformers import AutoModelForCausalLM, AutoTokenizer model_dir snapshot_download(Qwen/Qwen2.5-7B-Instruct, cache_dir/data/models/qwen2.5-7b-ms) tokenizer AutoTokenizer.from_pretrained(model_dir, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained(model_dir, trust_remote_codeTrue, device_mapauto)7.3 场景三只下载模型的部分文件有时候你只需要模型的配置文件或者只需要tokenizer不需要完整的权重。这时候可以用include参数huggingface-cli download Qwen/Qwen2.5-7B-Instruct \ --include config.json tokenizer* *.txt \ --local-dir /data/models/qwen2.5-7b-config这样只会下载配置文件和tokenizer相关的文件不会下载权重节省大量空间和时间。8. 一些容易被忽略但很关键的细节最后这一节我说几个平时容易忽略但实际很关键的细节。这些细节在官方文档里通常不会写但踩过坑之后就会印象深刻。8.1 模型版本和commit hashHuggingFace上的模型是可以有多个版本的每次更新都会生成一个新的commit hash。如果你在代码里直接写模型ID默认下载的是最新版本。但有时候最新版本可能有bug或者和你用的transformers版本不兼容。这时候可以指定commit hashhuggingface-cli download Qwen/Qwen2.5-7B-Instruct --revision abc123def --local-dir ./qwen2.5-7b在Python代码里也可以指定snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, revisionabc123def, local_dir./qwen2.5-7b )这个在复现实验或者生产环境里很重要可以保证每次下载的都是同一个版本。8.2 模型文件的完整性校验下载完成后建议做一次完整性校验。HuggingFace的模型卡片上通常会标注每个文件的大小你可以用ls -lh看一下实际文件大小是否一致。另外safetensors文件可以用safetensors库来校验from safetensors import safe_open with safe_open(./qwen2.5-7b/model.safetensors, frameworkpt) as f: for key in f.keys(): print(key, f.get_slice(key).get_shape())如果文件损坏这一步会报错。8.3 多文件模型的下载顺序有些大模型会被切分成多个safetensors文件比如model-00001-of-00004.safetensors、model-00002-of-00004.safetensors等。下载的时候要确保所有分片都下载完整缺一个都会导致加载失败。huggingface-cli会自动处理这些分片但如果你手动下载一定要注意不要漏掉。8.4 网络代理的配置如果你在公司内网或者有特殊网络环境可能需要配置代理才能访问HuggingFace。配置方法是在环境变量里设置export HTTP_PROXYhttp://your-proxy:port export HTTPS_PROXYhttp://your-proxy:port不过要注意代理配置可能会和镜像站冲突。如果你用了镜像站通常不需要再配代理。8.5 模型下载后的目录权限在Linux系统上下载的模型文件默认权限可能是rw-r--r--如果你用其他用户来加载模型可能会遇到权限问题。解决办法是chmod -R 755 /data/models/qwen2.5-7b chown -R your_user:your_group /data/models/qwen2.5-7b这个在多用户共享的服务器上尤其重要。8.6 关于模型格式的选择HuggingFace上的模型通常提供多种格式pytorch_model.bin、model.safetensors、tf_model.h5等。优先选safetensors格式因为它加载更快、更安全不会执行任意代码。如果只有bin格式也可以用但要注意bin格式是通过pickle序列化的存在一定的安全风险尽量从可信来源下载。8.7 下载速度的优化组合如果你试了镜像站还是慢可以试试组合方案镜像站 hf_transfer。配置方法是export HF_ENDPOINThttps://hf-mirror.com export HF_HUB_ENABLE_HF_TRANSFER1 pip install hf_transfer然后正常用huggingface-cli下载。这个组合我实测下来速度比单用镜像站快不少但偶尔会出现下载失败的情况如果失败了就把HF_HUB_ENABLE_HF_TRANSFER去掉用纯镜像站重试。8.8 关于ModelScope的模型ID映射有些模型在HuggingFace和ModelScope上的ID不一样。比如HuggingFace上的Qwen/Qwen2.5-7B-Instruct在ModelScope上也是Qwen/Qwen2.5-7B-Instruct这个是一致的。但有些模型比如Llama系列在HuggingFace上是meta-llama/Llama-3.1-8B在ModelScope上可能是LLM-Research/Meta-Llama-3.1-8B。下载之前最好去ModelScope网站上确认一下模型ID。8.9 关于下载中断后的恢复如果你下载到一半断了重新跑同样的命令huggingface-cli会自动从断点继续。但有时候会出现缓存文件损坏的情况这时候需要手动清理。具体做法是找到缓存目录下的blobs文件夹删除对应的.incomplete文件然后重新下载。ModelScope的断点续传有时候不太稳定如果反复失败建议删掉整个模型目录重新下载。8.10 关于模型加载时的内存占用下载模型只是第一步加载模型才是真正吃内存的地方。一个7B的模型用fp16加载大概需要14GB显存用int8量化加载大概需要7GB用int4量化大概需要4GB。如果你的显存不够可以考虑用量化加载或者用CPU加载速度会慢很多。具体用哪种方式要根据你的硬件条件和实际需求来定。我在实际使用中最大的体会是下载模型这件事看起来简单但细节特别多。尤其是国内网络环境下HuggingFace和ModelScope各有各的适用场景不能一刀切。我的建议是热门模型优先看ModelScope上有没有有就直接从ModelScope下省心省力如果没有再用HuggingFace配合镜像站下载。下载之前一定要确认磁盘空间下载之后一定要做加载测试这两个步骤能帮你避开大部分坑。另外养成设置缓存目录的习惯把模型和缓存都放到大盘上避免系统盘被撑爆。这些经验都是踩过坑之后总结出来的希望能帮你少走一些弯路。