HuggingFace与ModelScope模型下载全攻略：从链接到离线部署

开源模型下载这事儿看起来就是“找个链接点一下”真做起来能卡一晚上。HuggingFace上的模型确实全几天不上就能冒出几百个新仓库ModelScope魔搭社区这边速度和对中文开发者的友好程度又是另一回事。我刚开始碰开源模型的时候在HuggingFace页面点了半天下载十几个G的权重断了好几次后来才慢慢把两条平台的下载路子摸熟。这篇把我的下载套路直接摊开讲HuggingFace和魔搭怎么选、网页/命令行/Python三种下载方式怎么写、国内环境怎么加速、pip安装报错怎么解决、下载到一半断了怎么续最后附加一套离线部署的传输方案。想做本地大模型实验、私有化部署、或者只是想把某个模型抓回来跑评测的都能在这篇里找到直接能复制的命令。1. 先搞清楚去哪个平台下HuggingFace 和 ModelScope 怎么选1.1 两个平台的定位和差异HuggingFace简称HF是全球开源模型的集散地transformers、diffusers、datasets这些主流Python库默认都从huggingface.co拉取模型。它的优势是“全”新的、老的、热门的、冷门的、各种量化格式都有生态标准统一一个模型在HF发布之后其他工具链都会默认适配。劣势也明显在国内普通网络环境下直连大量小文件的时候还能忍一旦下载几个GB的大权重文件速度就很随缘断线重连是常事。ModelScope魔搭社区是阿里巴巴开源团队主导的模型社区上面分布着大量国产开源模型不少模型在发布时会把ModelScope作为同步站点甚至是首发平台。国内访问走的是国内基础设施下载速度通常比HF直连快得多。它对中文场景做了很多配套创空间可以直接在线体验模型数据集、训练空间、评测榜单都集成在一起。接口和HF高度相似很多代码从HF切到ModelScope只需要改import来源。两者的选择逻辑其实很简单如果你下的是国产模型、主要在国内环境部署优先ModelScope如果你追的是海外最新模型或者某个模型只在HF发布那就在HF下。后面几节会给出两边具体的命令跑一遍就知道哪个顺手。维度HuggingFaceModelScope魔搭模型丰富度全球最全海外模型更新最快国产模型覆盖好海外模型同步速度超出预期国内访问速度直连速度不稳需要镜像加速快基本满带宽配套生态transformers、datasets、diffusersSDK、创空间、数据集、评测榜单API风格huggingface_hubmodelscope参数几乎对齐适合人群追新模型、做国际化项目国内部署、中文模型、快速下载1.2 挑模型时先看什么选模型不是只看参数量下载前先看4个东西许可证、权重格式、模型卡的评测、社区热度。许可证影响最大有些模型只允许研究、不允许商用你拿去落地迟早要还债。权重格式决定你拿下来能不能用safetensors全平台通用GGUF是给llama.cpp这类推理框架跑的AWQ/GPTQ是给特定加速框架用的格式选错等于白下。如果你想要一个能快速下载、本地能跑起来的小模型我常用的几个入口Qwen/Qwen2.5-0.5B-Instruct入门级笔记本都能扛Qwen/Qwen2.5-7B-Instruct12G显存或量化后也能跑中文能力强BAAI/bge-m3中文embedding模型做检索、RAG用meta-llama/Llama-3.2-1B-Instruct英文场景很能打的小模型microsoft/Phi-3.5-mini-instruct微软家的小参数强者注意meta-llama这类仓库在HF上不是公开下载的需要先进模型页同意协议、拿到授权才能拉。具体是不是“真开源”以官方协议和权重可见性为准。如果你只是想快速体验模型效果而不是要本地部署可以先不下载。ModelScope的创空间有大量在线Demo扣子这类平台也内置了主流开源模型在网页上直接聊几句就能大概判断模型风格合适了再下载也不迟。这一条看似偷懒实际能省很多时间和硬盘。2. HuggingFace 模型下载的几种正经方法2.1 网页直下与 git clone 的正确姿势网页下载最直观。打开模型页面在Files标签里找到所有权重文件点下载图标就能拿到单个文件。但我不太推荐用浏览器下大模型十几个GB的safetensors点下去浏览器一旦休眠或者网络抖动几乎必然断而且没有续传。这个方式适合下小文件或者先看看文件清单。git clone适合一次拿到整个仓库命令很简短git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct这里最容易踩的第一个坑是没装Git LFS。HF的模型仓库用git-lfs管理大文件你没装好就跑clone拉完回来发现safetensors全是几百字节的指针文件跑代码直接报错。Ubuntu装法sudo apt install git-lfsmacOSbrew install git-lfsWindows去git-lfs官网下载安装包。装完先运行git lfs install初始化再clone。第二个坑是断线。git clone一个10多GB的仓库下到一半断掉git本身没有断点续传能力重来很肉疼。虽然git lfs pull能补拉缺失的大文件但整体体验依然糟糕。所以我现在很少用git clone下HF的大仓库除非仓库本身很小、或者明确需要保留git历史记录。2.2 用 huggingface_hub 与 Python 代码下载亲测最稳的是官方SDK。先装pip install huggingface_hub如果看到error: externally-managed-environment的报错解决方法见第4.1节办法是通用的。命令行下载huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/qwen25-7b--local-dir指定一个明明白白的目录下载完模型文件都在里面。旧版本没有这个参数时会下载到默认缓存目录目录结构是一串哈希很难直接用所以能用新版本就用新版本。想精确控制下载内容用include参数huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/qwen25-7b --include *.safetensors *.json *.model *.txt *.py这样可以不要GGUF、ONNX等其他格式节省流量和磁盘。Python脚本里更灵活from huggingface_hub import snapshot_download local_path snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir./models/qwen25-7b, allow_patterns[*.safetensors, *.json, *.model, *.txt, *.py], )allow_patterns是白名单ignore_patterns是黑名单两个可以配合用。比如模型仓库里既有safetensors又有gguf、又有onnx部署推理只要safetensors就把gguf、onnx忽略掉。单文件下载也有对应函数from huggingface_hub import hf_hub_download tokenizer_path hf_hub_download( Qwen/Qwen2.5-7B-Instruct, tokenizer.json, local_dir./models/qwen25-7b, )这个接口适合你只需要个别文件的情况没必要把整个仓库拉下来。2.3 加速hf_transfer 与并发参数默认下载是单线程逐文件拉取大文件真的慢。加速方案是用hf_transfer这个Rust实现的传输模块pip install hf_transfer export HF_HUB_ENABLE_HF_TRANSFER1启用之后下载会走多线程分片大文件速度提升非常明显。我实测下载一个7B模型的safetensors从几MB/s能拉到几十MB/s具体看带宽和网络状况。但要注意两个前提hf_transfer的断点续传支持比较弱官方也建议在稳定的网络环境下使用如果网络本身不稳定半路断了再跑不一定能从断点继续反而比默认模式更折腾。另一个问题是小文件特别多的仓库启用hf_transfer收益不明显分片开销都耗在小文件上。所以我的习惯是大模型、网络稳开hf_transfer模型仓库几十个小json、或者网络飘忽就用默认SDK下载稳最重要。3. 国内访问 HuggingFace 的加速方案镜像站与 HF_ENDPOINT3.1 HF_ENDPOINT 环境变量怎么用这是HF在国内环境下载的核心配置。huggingface_hub以及基于它的transformers、diffusers、datasets在请求模型文件时都会读取环境变量HF_ENDPOINT用它拼接请求的URL。默认值是https://huggingface.co你可以把它改成社区维护的国内镜像站例如https://hf-mirror.com。Linux/macOS临时设置export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/qwen25-7b这一行export之后所有走huggingface_hub的下载请求都会被重定向到镜像站。想永久生效把它写进~/.bashrc或~/.zshrc然后source一下即可。Python代码里设置要放在很靠前的位置import os os.environ[HF_ENDPOINT] https://hf-mirror.com from huggingface_hub import snapshot_download snapshot_download(Qwen/Qwen2.5-7B-Instruct, local_dir./models/qwen25-7b)如果你在代码中间、已经调用了API之后才设置环境变量本次请求可能已经拿到了默认地址导致镜像不生效这是最容易被忽略的坑。Windows用户设置系统环境变量系统属性 → 环境变量 → 新建HF_ENDPOINT值填https://hf-mirror.com然后重开终端。如果你的项目跑在Docker里在docker run时加-e HF_ENDPOINThttps://hf-mirror.com传进去不用改镜像内容。3.2 镜像方案的边界和注意点镜像站在多数情况下很好用但它不是万能的。我自己用下来的边界条件有这么几条第一镜像只对走HF SDK的下载生效。git clone https://huggingface.co/xxx这种裸仓库方式不会自动吃到HF_ENDPOINT。需要手动把地址改成镜像地址git clone https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct同样要先git lfs install。第二镜像同步有延迟。新发布的模型、刚更新的分支可能过几个小时才在镜像里出现。追最新模型的用户可以稍微等一会儿或者在魔搭找同步仓库。第三HF_HOME控制的是缓存目录和HF_ENDPOINT并不冲突可以同时设置export HF_HOME/data/huggingface export HF_ENDPOINThttps://hf-mirror.com前者让缓存落到大数据盘后者让请求走国内镜像。不要总在镜像环境和默认缓存之间来回切换否则下载到一半的临时文件会四处散落不好排查。第四上传模型、推送记录这类写操作一般不走镜像它的定位偏向“读”。正常下载场景完全够用。4. 魔搭 ModelScope 下载全流程4.1 安装与 PEP 668 报错的完整解法魔搭的Python SDK安装很简单pip install modelscope但在较新的Ubuntu、Debian系统上大概率会遇到这个报错error: externally-managed-environment很多人第一次看到以为pip坏了其实不是。这是PEP 668规则在起作用从Python 3.11开始主流Linux发行版会把系统自带的Python标记为“外部管理”禁止pip直接往系统环境里写第三方包避免破坏系统的包管理器依赖。你可以理解成系统Python被挂了个“请勿手动改装”的牌子。最推荐的解法是建虚拟环境python3 -m venv venv source venv/bin/activate pip install modelscope虚拟环境相当于给项目单独开一个Python房间装什么都不会污染系统。如果你的服务器有condaconda create -n ms python3.10 conda activate ms pip install modelscope如果只是临时用、或者不想切换环境还可以直接绕过限制pip install --break-system-packages modelscope这个参数的意思是“我知道这是系统Python我就是要装”。装是能装上但如果后续系统包出问题排查成本会高。所以我的建议是开发机随便生产服务器别这么干。4.2 命令行、Python SDK 与 git clone 三种方式ModelScope下载模型有三条路。第一条是命令行modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/qwen25-7b--local_dir指定下载目录下完就是扁平目录模型直接能用。较老版本可能只认--cache_dir会进入默认缓存结构路径里有一串hash不太直观。建议尽量升级到能识别--local_dir的SDK版本。第二条是Python SDKfrom modelscope import snapshot_download model_dir snapshot_download( Qwen/Qwen2.5-7B-Instruct, cache_dir./models, )返回的model_dir就是模型被下载到的路径之后加载模型时直接把这个路径传给from_pretrained。第三条是git clone地址格式稍有不同git clone https://www.modelscope.cn/Qwen/Qwen2.5-7B-Instruct.git同样先git lfs install。魔搭的国内仓库地址访问稳定走LFS拉大文件速度也不错。如果仓库体积大我仍然建议优先用SDK而不是git因为SDK做过分片和断点续传git断线重来太痛苦。实测下来ModelScope下载国产模型的速度优势很直观。同一个Qwen2.5-7B魔搭通常十几分钟能拉完比HF直连的等待时间短很多。4.3 下载数据集、登录与私有模型ModelScope不止有模型还有数据集下载方式和模型类似modelscope download --dataset modelscope/codeshell-v1-test --local_dir ./dataset遇到需要内测或私有权限的模型先在网页端申请通过再用命令行登录modelscope login输入你的魔搭账户token在个人设置里生成。注意别把HuggingFace的token填进来两套token互不相通。下载私有模型报401或NotAuthorizedError先查这个八成是token不对。5. 下载时经常踩的坑和排查手段5.1 常见问题速查表现象可能原因解决办法pip安装任何Python包都报externally-managed-environmentPEP 668系统保护venv/conda或--break-system-packagesgit clone模型仓库报LFS相关报错未安装Git LFS装git-lfs运行git lfs install后重拉Repository not found模型ID拼错/权限不足检查org和name大小写私有仓库先登录下载到一半连接断开、进度卡死大文件下载无断点续传改用SDK的snapshot_download重跑会自动续模型加载时config/tokenizer缺失只下载了权重文件用完整下载或手动补拉*.json/.model/.txtHF_ENDPOINT设置了但没生效环境变量在SDK导入后才设置Python里放最顶部执行Linux写入~/.bashrc下载的文件sha256对不上传输中断或文件损坏删除对应缓存文件重新拉取HuggingFace直连很慢但镜像也慢文件太大或时间段拥挤换ModelScope或用hf_transfer并发加速5.2 断点续传和下载任务的规划断点续传这个事选对工具比求神拜佛管用。huggingface_hub的snapshot_download自带续传逻辑下载中断后重新执行同一个命令已下载的分片会跳过不用从头再来。ModelScope的SDK同样支持。git clone相比之下没有自动续传断了要么重来、要么用git lfs pull补救所以我不建议把git clone作为大仓库的首选。长任务记得挂后台。SSH连服务器下载几小时终端一断进程就没了前面的进度全部浪费。用tmux开一个会话跑下载或者用nohupnohup huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/qwen25-7b download.log 21 跑完看download.log里的输出就能判断是否成功。磁盘规划也要提前做。一个大模型仓库少说十几个GB70B模型能到150GB以上。下载前先df -h看剩余空间把模型放到挂载了大数据盘的路径而不是默认的用户目录。HF的默认缓存是~/.cache/huggingface可以用HF_HOME重定向ModelScope默认缓存是~/.cache/modelscope下载时用cache_dir或--local_dir直接指定外部盘免得系统盘被撑爆。5.3 模型文件的格式和量化档位怎么看打开一个模型仓库的Files列表看到一堆后缀别慌。safetensors是当前主流的权重格式安全且加载快transformers、vLLM直接支持bin是老式权重格式能用但逐渐被替代。GGUF是llama.cpp和Ollama生态用的量化权重适合CPU推理或低显存机器。AWQ和GPTQ是推理加速量化格式有专门的推理引擎支持。MLX主要给Apple Silicon用。GGUF文件名里的量化档位有规律Q2_K体积最小但效果损失偏大Q4_K_M是综合最常用的选择Q5_K_M质量更好一点Q8_0接近原始精度但体积也大。你如果拿笔记本CPU跑模型优先选Q4_K_M如果显存够大直接用safetensors或Q8_0不用纠结量化。格式/档位适用场景safetensors默认选择带GPU/大内存环境首选GGUF Q4_K_M低显存/CPU推理体积效果均衡GGUF Q5_K_M内存稍宽裕时的高质量量化GGUF Q8_0接近原始精度体积偏大AWQ/GPTQ特定推理框架加速场景搞清这些你就知道哪些文件可以跳过不下载哪些是必须拿到的。6. 离线环境与私有化部署的下载迁移套路6.1 从下载机搬到内网的正确姿势生产环境经常是物理隔离的内网没有外网权限下载只能在一台跳板机或自己的电脑上完成再传输进内网。最靠谱的做法是在下载机上用--local_dir/local_dir把模型整理成干净目录然后用rsync同步rsync -avhP ./models/qwen25-7b user内网机器:/data/models/rsync的-P参数带断点续传和进度显示传输中断后重新执行会继续不会从头再来。不要用scp传大目录scp断了就得重来。如果下载时用的是默认缓存目录~/.cache/huggingface/hub/models--org--name/snapshots/hash/那个多层hash结构很难直接迁移最好还是用--local-dir重新组织一下。到了内网机器上之后加载路径直接指向这个目录from transformers import AutoModelForCausalLM, AutoTokenizer model AutoModelForCausalLM.from_pretrained( /data/models/qwen25-7b, trust_remote_codeTrue, ) tokenizer AutoTokenizer.from_pretrained( /data/models/qwen25-7b, trust_remote_codeTrue, )6.2 加载时容易忽略的细节用本地目录加载模型最容易被忽略的是trust_remote_codeTrue。很多模型仓库里带了自定义代码文件比如configuration_xxx.py、modeling_xxx.py这些是HF代码库里没有的必须允许执行相应代码才能加载。如果你只下载了safetensors和json没有下载这些*.py文件加载时一样会报ModuleNotFoundError。这也是为什么前面强调下载的时候用--include *.py或者干脆全量下载千万别自作聪明只抓权重。另外模型文件里的config.json决定了模型结构参数tokenizer.json、tokenizer_config.json决定了分词方式generation_config.json控制生成参数。这些文件都很小但少一个都可能让加载直接失败。手动下载单个文件时先看模型卡里列出的文件清单把所有的*.json、*.model、*.py、*.txt一起收了再考虑大权重。最后说一个我自己这几年养成的习惯也算给这篇收个尾。我现在每次下载前会先问一句“这个模型在魔搭上有没有”有就直接modelscope download没有再去HF先export HF_ENDPOINThttps://hf-mirror.com再下下完顺手把模型ID、来源平台、许可证写进一个文本文件放在模型目录里。这套流程不花哨但确实帮我少踩了很多坑——尤其是过了几个月再回来看一个带说明文件的模型目录比一堆哈希缓存路径不知道好找多少倍。下载模型不是难事难的是下载完之后还能记得住它是什么、从哪来、能不能商用而这些只需要你每次多花一分钟。希望这篇能帮你把下载这一步彻底理顺。