1. 为什么Huggingface非要靠镜像站才能用先说个场景不知道你有没有遇到过明明代码写得没问题训练脚本里from transformers import AutoModel也导入了结果一跑进度条卡在下载权重那一步半天不动最后直接报ConnectionError。这种情况在午后、晚间尤其频繁说白了就是huggingface.co的服务器离我们太远访问稳定性实在没法保证。我以前也硬扛过一阵反复重试、凌晨爬起来跑脚本都试过。后来被一次关键实验的deadline逼到墙角才开始认真研究镜像站方案。现在基本形成了固定的工作流模型下载、缓存管理、团队协作都围着镜像站转。这篇文章我会把目前主流、可落地的Huggingface镜像站使用方法完整梳理一遍包括环境变量配置、huggingface-cli命令行工具、git大文件下载、ComfyUI等GUI工具的接入以及下载中断、缓存路径、权限报错之类的常见坑。先给结论对绝大多数国内开发者来说hf-mirror.com是目前最省事的Huggingface镜像站方案零改动接入只需要设置一个环境变量就能让transformers、diffusers、datasets这些库自动走镜像下载模型。想用清华大学、阿里云这些开源镜像站的同学我也整理了对应方案。这篇内容适合以下几类人刚入坑AI绘画、大模型微调卡在权重下载这一步跑不下去的新手在公司内网或实验室环境无法科学访问国外资源的工程师需要批量下发模型下载任务不想每台机器都手动折腾的运维朋友用ComfyUI、WebUI等工具但模型经常下载失败的老手不管你属于哪一类这篇文章的目标只有一个让你在5分钟内用镜像站把Huggingface的模型下载速度拉起来并且后续无论是写代码调用还是命令行下载都稳定不慌。2. 镜像站原理与主流方案选型2.1 镜像到底解决了什么问题Huggingface本身就是一个面向深度学习社区的模型托管平台官方域名huggingface.co背后是全球CDN分发但是在国内访问时由于链路长、骨干网拥堵实际体验非常不稳定。镜像站的本质就是别人把Huggingface上的模型文件、数据集、代码仓库同步到国内服务器或稳定的海外节点然后提供一个可直连的下载入口。这个同步不是实时的。huggingface.co上有海量模型镜像站通常采用定时增量同步策略比如每24小时拉取一次更新。所以你会遇到“镜像站上找不到某个刚刚上传的最新模型”的情况这很正常等同步周期过了再来就行。理解这一点很重要很多人配置完镜像后发现某个模型404第一反应是配置错了其实只是同步延迟。2.2 主流方案横向对比我实测过几类入口这里直接按推荐程度整理成表格方案接入方式稳定度适用场景备注hf-mirror.com环境变量高日常模型下载、transformers库调用、ComfyUI目前最推荐覆盖全清华TUNA镜像pip源/部分仓库中Python包安装加速、小众场景不是完整Huggingface镜像GitHub镜像站git clone加速中拉取代码仓库一般不同步LFS大文件阿里云/华为云开源镜像特定软件源中系统软件、pip源与Huggingface关系不大Civitai镜像站独立入口视站点而定AI绘画模型模型格式、组织方式与HF不同先说结论如果是跑深度学习相关的工作hf-mirror.com是首选。它把Huggingface的模型仓库、数据集、空间Spaces都同步了一份而且API路径完全兼容设置环境变量后transformers、diffusers、datasets这些库的底层下载逻辑几乎零改动就能走镜像。至于清华大学、中科大这些开源镜像站它们主要做的是系统软件源、pip源、npm源确实快但不解决Huggingface模型下载的问题。不少人误以为“清华镜像”可以加速Huggingface其实不是一回事这里提醒一下别搞混了。2.3 为什么优先推荐hf-mirror.com我理解很多人会问为什么不直接配置代理或者改hosts改hosts只能解决DNS解析问题如果你的网络环境本身连不上huggingface.co的服务器改hosts一点用没有。而代理方案涉及额外的客户端和账号在公司内网或服务器环境下并不总是可行也不方便团队统一配置。hf-mirror.com走的是HTTP/HTTPS直连不依赖任何特殊工具只要你的服务器能访问国内网络就能用它。基于是我自己长期使用的体验它确实做到了“配置一次长期稳定”的效果这点非常关键。另外hf-mirror.com对Huggingface官方的API结构兼容得非常好。原来你用的是from transformers import AutoTokenizer, AutoModelForCausalLM model AutoModelForCausalLM.from_pretrained(meta-llama/Llama-2-7b-chat-hf)加了环境变量之后代码一行都不用改from_pretrained底层走的下载逻辑会自动拼上镜像地址。对一个团队来说这意味不用改代码只要在启动脚本里统一加上环境变量就能解决所有人的下载问题。3. 环境变量配置让所有Huggingface相关库自动走镜像3.1 核心环境变量看懂这三个就够了Huggingface官方提供了一系列环境变量来控制下载行为但实际要记住的就三个环境变量作用推荐值HF_ENDPOINT镜像服务地址最关键https://hf-mirror.comHF_HOME模型和缓存的根目录/data/huggingface自定义路径HF_HUB_CACHE模型文件的缓存目录默认在HF_HOME/hub下HF_ENDPOINT是核心中的核心。它的作用就是替换Huggingface官方API的Base URL让所有走huggingface_hub库的下载请求自动指向镜像站。HF_HOME和HF_HUB_CACHE则是帮你管理模型文件存哪里的。默认情况下模型缓存放在用户目录下的.cache/huggingface如果你的服务器/home目录空间不大模型动不动几十个G很容易把磁盘塞满。我习惯把缓存目录指到独立的数据盘上比如/data/huggingface方便管理。3.2 Linux/macOS环境变量设置Linux下最简单的做法是写进~/.bashrc或~/.zshrcexport HF_ENDPOINThttps://hf-mirror.com export HF_HOME/data/huggingface然后执行source ~/.bashrc验证一下环境变量是否生效echo $HF_ENDPOINT输出https://hf-mirror.com就说明配置好了。如果你是帮别人或临时给某个进程设置不一定要写进bashrc可以直接在执行命令时用内联方式HF_ENDPOINThttps://hf-mirror.com python train.py这种方式的好处是只对当前命令生效不影响全局环境适合临时测试时使用。3.3 Windows环境变量设置Windows下配置也不复杂分两种方式。第一种图形化设置右键“此电脑” - 属性 - 高级系统设置点击“环境变量”在“系统变量”或“用户变量”中点击“新建”变量名填HF_ENDPOINT变量值填https://hf-mirror.com确定保存重新打开终端第二种PowerShell临时设置$env:HF_ENDPOINT https://hf-mirror.com临时设置只在当前PowerShell窗口有效关掉就没了适合测试。3.4 在Python代码中动态设置有些情况下你不想改系统环境变量比如在Jupyter Notebook里跑实验或者调别人的开源代码时不想动全局配置。那可以在代码最顶部动态设置import os os.environ[HF_ENDPOINT] https://hf-mirror.com from transformers import AutoModelForCausalLM, AutoTokenizer # 这之后调from_pretrained就会走镜像注意一个细节os.environ的设置必须在import transformers或任何huggingface_hub相关操作之前完成否则库已经初始化了改环境变量可能不生效。3.5 验证配置是否生效配置完之后最好先跑一条简单命令验证下载确实走镜像了。用Python验证from huggingface_hub import snapshot_download snapshot_download(repo_idbert-base-uncased, cache_dir/tmp/test_cache)观察输出日志如果下载地址中包含hf-mirror.com说明配置生效。还有一种更直观的验证直接看请求速度。走镜像的话一个几百MB的模型文件基本十几秒就能下完如果还是很慢大概率是环境变量没配好或者镜像地址拼写错了。4. 实操Huggingface模型下载的完整流程4.1 用huggingface-cli下载单个模型环境变量配好后最直接的使用方式就是huggingface-cli命令行工具。先确保huggingface_hub库是新的pip install -U huggingface_hub然后下载模型huggingface-cli download meta-llama/Llama-2-7b-chat-hf --local-dir ./models/llama2-7b-chat几点说明--local-dir指定下载到本地目录注意它会把文件直接放到该目录下而不是以缓存目录结构组织文件如果模型比较大下载过程中会显示进度条如果想断点续传直接重新执行同样命令即可huggingface_hub会自动跳过已下载完成的内容新版huggingface_hub还提供了一个短命令hf download替代huggingface-cli download两者行为一样看个人习惯选择hf download meta-llama/Llama-2-7b-chat-hf --local-dir ./models/llama2-7b-chat4.2 下载指定文件或过滤文件有时候模型仓库里文件很多但你不需要全部下载。比如只需要模型权重bin文件不需要tokenizer配置等。用--include和--exclude可以精确控制huggingface-cli download gpt2 --include *.json --local-dir ./gpt2_json这条命令只下载gpt2仓库里所有json文件比如config.json、tokenizer.json等。多个匹配规则用空格分隔huggingface-cli download meta-llama/Llama-2-7b-chat-hf --include *.json *.model --exclude *.safetensors --local-dir ./llama2-config这招在下载大模型时特别实用。比如你只想用某个模型的tokenizer做文本编码完全没必要把几十个G的权重全拉下来。4.3 用Python代码下载模型除了命令行huggingface_hub库提供的Python API也很常用。完整下载一个仓库from huggingface_hub import snapshot_download snapshot_download(repo_idrunwayml/stable-diffusion-v1-5, local_dir./sd15)下载单个文件from huggingface_hub import hf_hub_download hf_hub_download(repo_idbert-base-uncased, filenameconfig.json, local_dir./bert-base)hf_hub_download适合按需取文件比如在推理服务启动时只下载并加载对应的模型权重不必把所有关联文件都拉下来。4.4 利用aria2或多线程加速如果你觉得默认下载速度还不够可以试试hf_transfer。这是Huggingface官方推出的加速工具基于Rust实现支持分片并发下载实测速度提升非常明显。安装pip install hf_transfer使用时设置环境变量export HF_HUB_ENABLE_HF_TRANSFER1然后再执行下载命令底层就会自动走hf_transfer加速。我实测下来的感受是默认下载速度可能只有几十MB/s的时候开hf_transfer之后能跑满带宽特别是网络条件好的服务器上提升效果很明显。有一点要特别注意hf_transfer不支持断点续传。如果你在下载过程中中断了重新执行同一命令它不会像默认模式那样自动跳过已下载的部分而是可能重新下载所有文件。所以我的建议是网络不稳定的情况下别开hf_transfer网络条件好又想追求极致速度再开。4.5 git clone方式下载如果你需要下载模型的源码仓库或者想直接拉取模型的git仓库包括版本历史可以用git clone。直接clone Huggingface上的仓库git clone https://huggingface.co/gpt2走镜像的话把地址换成hf-mirror.com即可git clone https://hf-mirror.com/gpt2这里有个大坑要提醒大模型仓库通常用Git LFS管理大文件直接clone可能拉不下来权重文件或者速度特别慢。Git LFS需要先安装配置git lfs install git clone https://hf-mirror.com/runwayml/stable-diffusion-v1-5不过说实话对大模型文件我对git clone的使用建议是能不用就不用。原因有两个一是git clone会保留完整的版本历史模型仓库的历史记录往往包含多版本文件非常占空间而且实际没太多价值。二是git lfs大文件下载的并发控制和断点续传体验都不如huggingface-cli。我遇到过多次类似“LFS文件下载到一半卡死重新clone依然卡在同一个文件”的尴尬情况。所以更推荐的做法是用git clone拉取纯代码仓库没有大模型文件的用huggingface-cli拉取模型权重仓库。5. ComfyUI、transformers等场景接入镜像5.1 transformers、diffusers库直接调用环境变量配置好之后transformers和diffusers几乎不需要额外操作就是走镜像。比如调用Stable Diffusion模型加载from diffusers import StableDiffusionPipeline pipe StableDiffusionPipeline.from_pretrained( runwayml/stable-diffusion-v1-5, torch_dtypetorch.float16 )环境变量已经设置的话from_pretrained内部会优先从镜像站下载模型非常省心。5.2 ComfyUI修改为国内镜像ComfyUI是我日常用得最多的AI绘画工具之一它默认也会连接Huggingface下载部分模型比如一些辅助模型、VAE、CLIP等。得益于环境变量机制给ComfyUI配镜像站的方式非常优雅。如果你用的是启动脚本比如run_nvidia_gpu.bat可以在脚本开头加入set HF_ENDPOINThttps://hf-mirror.comLinux或macOS下启动ComfyUI前执行export HF_ENDPOINThttps://hf-mirror.com然后正常启动ComfyUIpython main.py这样一来ComfyUI里所有依赖Huggingface下载模型的功能都会自动走镜像。还有一点ComfyUI本身有模型管理机制比如节点缺失时自动下载模型。你可以到ComfyUI/custom_nodes/目录下找到对应节点的源码看它的模型下载地址是否写死在Huggingface上如果写死了可以改成镜像地址。我建议是优先用环境变量方案因为改源码会污染第三方节点代码下次更新插件很可能覆盖掉你的修改环境变量方案对更新更友好。5.3 WebUIA1111接入镜像Stable Diffusion WebUI的情况不同它主要从Huggingface下载一些辅助模型比如VAE等。同样设置环境变量后大多数下载请求都会走镜像。如果偶尔遇到某个辅助模型下载失败检查一下它是不是走的Huggingface之外的地址比如Civitai或Google Drive那些就需要单独处理了。5.4 局域网内共享模型缓存的进阶思路如果你所在团队有多台机器都跑同样的模型可以共享一个Huggingface缓存目录。比如用NFS挂载或者Samba共享把HF_HOME统一指向共享目录。export HF_HOME/nfs/huggingface这样第一台机器下载完的模型其他机器直接从本地缓存读取不会重复下载几个G的文件。这招在大规模分布式训练集群里尤其好用。我见过不少人把模型重复下载这件事当成“正常操作”其实配置好共享缓存后整个团队的启动速度和磁盘占用都会优化很多。5.5 在Docker容器内使用镜像容器化部署时镜像站配置通常写在Dockerfile里这样每个新容器一启动就能直接用。FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime ENV HF_ENDPOINThttps://hf-mirror.com ENV HF_HOME/workspace/huggingface RUN pip install huggingface_hub transformers diffusers也可以在docker run时通过环境变量临时注入docker run -e HF_ENDPOINThttps://hf-mirror.com -e HF_HOME/workspace/huggingface my_image python train.py这两种方式都可行看你的部署流程简洁程度来选。6. 常见问题与排查技巧实录6.1 设置了环境变量但下载还是走官方地址这是被问得最多的一个问题。检查以下事项是否在Python代码中又把环境变量覆盖了有些库内部会重新设置HF_ENDPOINT如果有以代码里设置的为准环境变量是否真的在子进程中生效了比如你在当前Shell设置了变量但用sudo执行Python代码sudo反过来会清空部分环境变量需要加sudo -E保留环境是否import了旧版huggingface_hub老版本可能不识别HF_ENDPOINT升级一下再试6.2 模型在镜像站上找不到或404镜像站是定时同步的如果是刚上传的新模型镜像上可能还没有。处理办法等几个小时或一个同步周期再看换回官方源下载这一个模型其他模型继续走镜像确认repo_id是否写对比如大小写、命名空间6.3 下载到一半中断重新下载又从头开始默认模式下huggingface_hub是支持断点续传的重新执行命令会跳过已经下载完成的部分。如果你发现它从头开始下载大概率是开了hf_transfer。这个工具为了追求速度确实不保留断点信息所以对网络不稳定的情况不太友好把它关掉就好。unset HF_HUB_ENABLE_HF_TRANSFER然后重新执行下载命令断点续传就恢复正常了。6.4 磁盘空间不足大模型下载到一半发现/分区满了这是家常便饭。我踩过的坑就是默认缓存目录放在home下而home分区通常比较小。解决办法就是提前设置HF_HOME到数据盘export HF_HOME/data/huggingface如果已经下了一半想迁移缓存目录直接移动目录修改环境变量新建软链接即可mv ~/.cache/huggingface /data/huggingface ln -s /data/huggingface ~/.cache/huggingface这里的软链接方案对某些把路径写死在代码里的库来说特别有用哪怕你不改环境变量也能让老路径指向新位置。6.5 动态模型加载失败报证书或SSL错误偶尔会出现SSL证书校验失败的问题特别是某些公司内网有SSL decryption中间代理的情况。可以临时关闭huggingface_hub的SSL校验来排查import os os.environ[CURL_CA_BUNDLE] 或者export HF_HUB_DISABLE_SSL1这只适合本地排查正常使用还是建议开启SSL校验别在生产环境顺手就把证书校验关了。6.6 Git LFS下载卡死或权限问题git clone方式下载大文件如果遇到以下两类问题一是LFS文件一直卡在Filtering content。基本是网络不稳定导致LFS请求挂起。处理办法是调整git LFS并发数git config --global lfs.concurrenttransfers 1这样会降低并发但明显提高稳定性。二是报LFS: Authentication required之类的权限错误。注意如果模型仓库是需要登录才能访问的gated model直接走git匿名clone是过不了权限验证的。但反过来如果你已经用huggingface-cli成功登录过官方账号凭证文件里会存有AccessTokengit LFS也能读到这时候别同时设置HF_ENDPOINT指向镜像否则可能认证时先连镜像站而在认证步骤失败。6.7 下载速度慢的最终排查思路如果你发现镜像速度也不理想按照以下顺序排查确认不是WiFi/移动网络临时波动用curl -I https://hf-mirror.com看延迟尝试关掉hf_transfer有时候并发太高反而被限速检查服务器是否有带宽限制策略换一台地域不同的机器对比测试确认是否开着代理工具代理与镜像同时启用有时会导致走弯路7. 个人实操中的一些体会最后分享几条我实际使用中攒下来的经验。第一环境变量配置这件事越早统一越好。如果你是在团队里建议把HF_ENDPOINT、HF_HOME写进团队的基础镜像和标准启动脚本里别让每个人各自在bashrc里面加不然总有漏配的机器出现各种奇怪问题。第二别过度依赖git clone下载模型。对普通大模型权重文件huggingface-cli的体验明显优于git lfs不管是断点续传还是并发下载都更成熟。git方式留给代码仓库就够了。第三对于需要频繁复用的基础模型比如中文Embedding模型、常用的base模型我建议下载完后单独备份一份到内部文件服务器版本固定后直接内网分发。镜像站再快也不如内网快。第四镜像站的同步有延迟所以当你要复现一些热门论文的最新模型时多留一点时间余量。比如周四周五新发的模型临到周末要复现很可能镜像上还没有做好等一等或者直接从官方源下载的预案。镜像站不是银弹但对国内开发者来说它解决了一个非常实际的问题让模型下载不再成为跑通实验的瓶颈。希望这篇文章里这些实操方法和排坑记录能帮你在配镜像的时候少走弯路。
HuggingFace模型下载加速：镜像站配置、环境变量与踩坑排查全攻略
1. 为什么Huggingface非要靠镜像站才能用先说个场景不知道你有没有遇到过明明代码写得没问题训练脚本里from transformers import AutoModel也导入了结果一跑进度条卡在下载权重那一步半天不动最后直接报ConnectionError。这种情况在午后、晚间尤其频繁说白了就是huggingface.co的服务器离我们太远访问稳定性实在没法保证。我以前也硬扛过一阵反复重试、凌晨爬起来跑脚本都试过。后来被一次关键实验的deadline逼到墙角才开始认真研究镜像站方案。现在基本形成了固定的工作流模型下载、缓存管理、团队协作都围着镜像站转。这篇文章我会把目前主流、可落地的Huggingface镜像站使用方法完整梳理一遍包括环境变量配置、huggingface-cli命令行工具、git大文件下载、ComfyUI等GUI工具的接入以及下载中断、缓存路径、权限报错之类的常见坑。先给结论对绝大多数国内开发者来说hf-mirror.com是目前最省事的Huggingface镜像站方案零改动接入只需要设置一个环境变量就能让transformers、diffusers、datasets这些库自动走镜像下载模型。想用清华大学、阿里云这些开源镜像站的同学我也整理了对应方案。这篇内容适合以下几类人刚入坑AI绘画、大模型微调卡在权重下载这一步跑不下去的新手在公司内网或实验室环境无法科学访问国外资源的工程师需要批量下发模型下载任务不想每台机器都手动折腾的运维朋友用ComfyUI、WebUI等工具但模型经常下载失败的老手不管你属于哪一类这篇文章的目标只有一个让你在5分钟内用镜像站把Huggingface的模型下载速度拉起来并且后续无论是写代码调用还是命令行下载都稳定不慌。2. 镜像站原理与主流方案选型2.1 镜像到底解决了什么问题Huggingface本身就是一个面向深度学习社区的模型托管平台官方域名huggingface.co背后是全球CDN分发但是在国内访问时由于链路长、骨干网拥堵实际体验非常不稳定。镜像站的本质就是别人把Huggingface上的模型文件、数据集、代码仓库同步到国内服务器或稳定的海外节点然后提供一个可直连的下载入口。这个同步不是实时的。huggingface.co上有海量模型镜像站通常采用定时增量同步策略比如每24小时拉取一次更新。所以你会遇到“镜像站上找不到某个刚刚上传的最新模型”的情况这很正常等同步周期过了再来就行。理解这一点很重要很多人配置完镜像后发现某个模型404第一反应是配置错了其实只是同步延迟。2.2 主流方案横向对比我实测过几类入口这里直接按推荐程度整理成表格方案接入方式稳定度适用场景备注hf-mirror.com环境变量高日常模型下载、transformers库调用、ComfyUI目前最推荐覆盖全清华TUNA镜像pip源/部分仓库中Python包安装加速、小众场景不是完整Huggingface镜像GitHub镜像站git clone加速中拉取代码仓库一般不同步LFS大文件阿里云/华为云开源镜像特定软件源中系统软件、pip源与Huggingface关系不大Civitai镜像站独立入口视站点而定AI绘画模型模型格式、组织方式与HF不同先说结论如果是跑深度学习相关的工作hf-mirror.com是首选。它把Huggingface的模型仓库、数据集、空间Spaces都同步了一份而且API路径完全兼容设置环境变量后transformers、diffusers、datasets这些库的底层下载逻辑几乎零改动就能走镜像。至于清华大学、中科大这些开源镜像站它们主要做的是系统软件源、pip源、npm源确实快但不解决Huggingface模型下载的问题。不少人误以为“清华镜像”可以加速Huggingface其实不是一回事这里提醒一下别搞混了。2.3 为什么优先推荐hf-mirror.com我理解很多人会问为什么不直接配置代理或者改hosts改hosts只能解决DNS解析问题如果你的网络环境本身连不上huggingface.co的服务器改hosts一点用没有。而代理方案涉及额外的客户端和账号在公司内网或服务器环境下并不总是可行也不方便团队统一配置。hf-mirror.com走的是HTTP/HTTPS直连不依赖任何特殊工具只要你的服务器能访问国内网络就能用它。基于是我自己长期使用的体验它确实做到了“配置一次长期稳定”的效果这点非常关键。另外hf-mirror.com对Huggingface官方的API结构兼容得非常好。原来你用的是from transformers import AutoTokenizer, AutoModelForCausalLM model AutoModelForCausalLM.from_pretrained(meta-llama/Llama-2-7b-chat-hf)加了环境变量之后代码一行都不用改from_pretrained底层走的下载逻辑会自动拼上镜像地址。对一个团队来说这意味不用改代码只要在启动脚本里统一加上环境变量就能解决所有人的下载问题。3. 环境变量配置让所有Huggingface相关库自动走镜像3.1 核心环境变量看懂这三个就够了Huggingface官方提供了一系列环境变量来控制下载行为但实际要记住的就三个环境变量作用推荐值HF_ENDPOINT镜像服务地址最关键https://hf-mirror.comHF_HOME模型和缓存的根目录/data/huggingface自定义路径HF_HUB_CACHE模型文件的缓存目录默认在HF_HOME/hub下HF_ENDPOINT是核心中的核心。它的作用就是替换Huggingface官方API的Base URL让所有走huggingface_hub库的下载请求自动指向镜像站。HF_HOME和HF_HUB_CACHE则是帮你管理模型文件存哪里的。默认情况下模型缓存放在用户目录下的.cache/huggingface如果你的服务器/home目录空间不大模型动不动几十个G很容易把磁盘塞满。我习惯把缓存目录指到独立的数据盘上比如/data/huggingface方便管理。3.2 Linux/macOS环境变量设置Linux下最简单的做法是写进~/.bashrc或~/.zshrcexport HF_ENDPOINThttps://hf-mirror.com export HF_HOME/data/huggingface然后执行source ~/.bashrc验证一下环境变量是否生效echo $HF_ENDPOINT输出https://hf-mirror.com就说明配置好了。如果你是帮别人或临时给某个进程设置不一定要写进bashrc可以直接在执行命令时用内联方式HF_ENDPOINThttps://hf-mirror.com python train.py这种方式的好处是只对当前命令生效不影响全局环境适合临时测试时使用。3.3 Windows环境变量设置Windows下配置也不复杂分两种方式。第一种图形化设置右键“此电脑” - 属性 - 高级系统设置点击“环境变量”在“系统变量”或“用户变量”中点击“新建”变量名填HF_ENDPOINT变量值填https://hf-mirror.com确定保存重新打开终端第二种PowerShell临时设置$env:HF_ENDPOINT https://hf-mirror.com临时设置只在当前PowerShell窗口有效关掉就没了适合测试。3.4 在Python代码中动态设置有些情况下你不想改系统环境变量比如在Jupyter Notebook里跑实验或者调别人的开源代码时不想动全局配置。那可以在代码最顶部动态设置import os os.environ[HF_ENDPOINT] https://hf-mirror.com from transformers import AutoModelForCausalLM, AutoTokenizer # 这之后调from_pretrained就会走镜像注意一个细节os.environ的设置必须在import transformers或任何huggingface_hub相关操作之前完成否则库已经初始化了改环境变量可能不生效。3.5 验证配置是否生效配置完之后最好先跑一条简单命令验证下载确实走镜像了。用Python验证from huggingface_hub import snapshot_download snapshot_download(repo_idbert-base-uncased, cache_dir/tmp/test_cache)观察输出日志如果下载地址中包含hf-mirror.com说明配置生效。还有一种更直观的验证直接看请求速度。走镜像的话一个几百MB的模型文件基本十几秒就能下完如果还是很慢大概率是环境变量没配好或者镜像地址拼写错了。4. 实操Huggingface模型下载的完整流程4.1 用huggingface-cli下载单个模型环境变量配好后最直接的使用方式就是huggingface-cli命令行工具。先确保huggingface_hub库是新的pip install -U huggingface_hub然后下载模型huggingface-cli download meta-llama/Llama-2-7b-chat-hf --local-dir ./models/llama2-7b-chat几点说明--local-dir指定下载到本地目录注意它会把文件直接放到该目录下而不是以缓存目录结构组织文件如果模型比较大下载过程中会显示进度条如果想断点续传直接重新执行同样命令即可huggingface_hub会自动跳过已下载完成的内容新版huggingface_hub还提供了一个短命令hf download替代huggingface-cli download两者行为一样看个人习惯选择hf download meta-llama/Llama-2-7b-chat-hf --local-dir ./models/llama2-7b-chat4.2 下载指定文件或过滤文件有时候模型仓库里文件很多但你不需要全部下载。比如只需要模型权重bin文件不需要tokenizer配置等。用--include和--exclude可以精确控制huggingface-cli download gpt2 --include *.json --local-dir ./gpt2_json这条命令只下载gpt2仓库里所有json文件比如config.json、tokenizer.json等。多个匹配规则用空格分隔huggingface-cli download meta-llama/Llama-2-7b-chat-hf --include *.json *.model --exclude *.safetensors --local-dir ./llama2-config这招在下载大模型时特别实用。比如你只想用某个模型的tokenizer做文本编码完全没必要把几十个G的权重全拉下来。4.3 用Python代码下载模型除了命令行huggingface_hub库提供的Python API也很常用。完整下载一个仓库from huggingface_hub import snapshot_download snapshot_download(repo_idrunwayml/stable-diffusion-v1-5, local_dir./sd15)下载单个文件from huggingface_hub import hf_hub_download hf_hub_download(repo_idbert-base-uncased, filenameconfig.json, local_dir./bert-base)hf_hub_download适合按需取文件比如在推理服务启动时只下载并加载对应的模型权重不必把所有关联文件都拉下来。4.4 利用aria2或多线程加速如果你觉得默认下载速度还不够可以试试hf_transfer。这是Huggingface官方推出的加速工具基于Rust实现支持分片并发下载实测速度提升非常明显。安装pip install hf_transfer使用时设置环境变量export HF_HUB_ENABLE_HF_TRANSFER1然后再执行下载命令底层就会自动走hf_transfer加速。我实测下来的感受是默认下载速度可能只有几十MB/s的时候开hf_transfer之后能跑满带宽特别是网络条件好的服务器上提升效果很明显。有一点要特别注意hf_transfer不支持断点续传。如果你在下载过程中中断了重新执行同一命令它不会像默认模式那样自动跳过已下载的部分而是可能重新下载所有文件。所以我的建议是网络不稳定的情况下别开hf_transfer网络条件好又想追求极致速度再开。4.5 git clone方式下载如果你需要下载模型的源码仓库或者想直接拉取模型的git仓库包括版本历史可以用git clone。直接clone Huggingface上的仓库git clone https://huggingface.co/gpt2走镜像的话把地址换成hf-mirror.com即可git clone https://hf-mirror.com/gpt2这里有个大坑要提醒大模型仓库通常用Git LFS管理大文件直接clone可能拉不下来权重文件或者速度特别慢。Git LFS需要先安装配置git lfs install git clone https://hf-mirror.com/runwayml/stable-diffusion-v1-5不过说实话对大模型文件我对git clone的使用建议是能不用就不用。原因有两个一是git clone会保留完整的版本历史模型仓库的历史记录往往包含多版本文件非常占空间而且实际没太多价值。二是git lfs大文件下载的并发控制和断点续传体验都不如huggingface-cli。我遇到过多次类似“LFS文件下载到一半卡死重新clone依然卡在同一个文件”的尴尬情况。所以更推荐的做法是用git clone拉取纯代码仓库没有大模型文件的用huggingface-cli拉取模型权重仓库。5. ComfyUI、transformers等场景接入镜像5.1 transformers、diffusers库直接调用环境变量配置好之后transformers和diffusers几乎不需要额外操作就是走镜像。比如调用Stable Diffusion模型加载from diffusers import StableDiffusionPipeline pipe StableDiffusionPipeline.from_pretrained( runwayml/stable-diffusion-v1-5, torch_dtypetorch.float16 )环境变量已经设置的话from_pretrained内部会优先从镜像站下载模型非常省心。5.2 ComfyUI修改为国内镜像ComfyUI是我日常用得最多的AI绘画工具之一它默认也会连接Huggingface下载部分模型比如一些辅助模型、VAE、CLIP等。得益于环境变量机制给ComfyUI配镜像站的方式非常优雅。如果你用的是启动脚本比如run_nvidia_gpu.bat可以在脚本开头加入set HF_ENDPOINThttps://hf-mirror.comLinux或macOS下启动ComfyUI前执行export HF_ENDPOINThttps://hf-mirror.com然后正常启动ComfyUIpython main.py这样一来ComfyUI里所有依赖Huggingface下载模型的功能都会自动走镜像。还有一点ComfyUI本身有模型管理机制比如节点缺失时自动下载模型。你可以到ComfyUI/custom_nodes/目录下找到对应节点的源码看它的模型下载地址是否写死在Huggingface上如果写死了可以改成镜像地址。我建议是优先用环境变量方案因为改源码会污染第三方节点代码下次更新插件很可能覆盖掉你的修改环境变量方案对更新更友好。5.3 WebUIA1111接入镜像Stable Diffusion WebUI的情况不同它主要从Huggingface下载一些辅助模型比如VAE等。同样设置环境变量后大多数下载请求都会走镜像。如果偶尔遇到某个辅助模型下载失败检查一下它是不是走的Huggingface之外的地址比如Civitai或Google Drive那些就需要单独处理了。5.4 局域网内共享模型缓存的进阶思路如果你所在团队有多台机器都跑同样的模型可以共享一个Huggingface缓存目录。比如用NFS挂载或者Samba共享把HF_HOME统一指向共享目录。export HF_HOME/nfs/huggingface这样第一台机器下载完的模型其他机器直接从本地缓存读取不会重复下载几个G的文件。这招在大规模分布式训练集群里尤其好用。我见过不少人把模型重复下载这件事当成“正常操作”其实配置好共享缓存后整个团队的启动速度和磁盘占用都会优化很多。5.5 在Docker容器内使用镜像容器化部署时镜像站配置通常写在Dockerfile里这样每个新容器一启动就能直接用。FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime ENV HF_ENDPOINThttps://hf-mirror.com ENV HF_HOME/workspace/huggingface RUN pip install huggingface_hub transformers diffusers也可以在docker run时通过环境变量临时注入docker run -e HF_ENDPOINThttps://hf-mirror.com -e HF_HOME/workspace/huggingface my_image python train.py这两种方式都可行看你的部署流程简洁程度来选。6. 常见问题与排查技巧实录6.1 设置了环境变量但下载还是走官方地址这是被问得最多的一个问题。检查以下事项是否在Python代码中又把环境变量覆盖了有些库内部会重新设置HF_ENDPOINT如果有以代码里设置的为准环境变量是否真的在子进程中生效了比如你在当前Shell设置了变量但用sudo执行Python代码sudo反过来会清空部分环境变量需要加sudo -E保留环境是否import了旧版huggingface_hub老版本可能不识别HF_ENDPOINT升级一下再试6.2 模型在镜像站上找不到或404镜像站是定时同步的如果是刚上传的新模型镜像上可能还没有。处理办法等几个小时或一个同步周期再看换回官方源下载这一个模型其他模型继续走镜像确认repo_id是否写对比如大小写、命名空间6.3 下载到一半中断重新下载又从头开始默认模式下huggingface_hub是支持断点续传的重新执行命令会跳过已经下载完成的部分。如果你发现它从头开始下载大概率是开了hf_transfer。这个工具为了追求速度确实不保留断点信息所以对网络不稳定的情况不太友好把它关掉就好。unset HF_HUB_ENABLE_HF_TRANSFER然后重新执行下载命令断点续传就恢复正常了。6.4 磁盘空间不足大模型下载到一半发现/分区满了这是家常便饭。我踩过的坑就是默认缓存目录放在home下而home分区通常比较小。解决办法就是提前设置HF_HOME到数据盘export HF_HOME/data/huggingface如果已经下了一半想迁移缓存目录直接移动目录修改环境变量新建软链接即可mv ~/.cache/huggingface /data/huggingface ln -s /data/huggingface ~/.cache/huggingface这里的软链接方案对某些把路径写死在代码里的库来说特别有用哪怕你不改环境变量也能让老路径指向新位置。6.5 动态模型加载失败报证书或SSL错误偶尔会出现SSL证书校验失败的问题特别是某些公司内网有SSL decryption中间代理的情况。可以临时关闭huggingface_hub的SSL校验来排查import os os.environ[CURL_CA_BUNDLE] 或者export HF_HUB_DISABLE_SSL1这只适合本地排查正常使用还是建议开启SSL校验别在生产环境顺手就把证书校验关了。6.6 Git LFS下载卡死或权限问题git clone方式下载大文件如果遇到以下两类问题一是LFS文件一直卡在Filtering content。基本是网络不稳定导致LFS请求挂起。处理办法是调整git LFS并发数git config --global lfs.concurrenttransfers 1这样会降低并发但明显提高稳定性。二是报LFS: Authentication required之类的权限错误。注意如果模型仓库是需要登录才能访问的gated model直接走git匿名clone是过不了权限验证的。但反过来如果你已经用huggingface-cli成功登录过官方账号凭证文件里会存有AccessTokengit LFS也能读到这时候别同时设置HF_ENDPOINT指向镜像否则可能认证时先连镜像站而在认证步骤失败。6.7 下载速度慢的最终排查思路如果你发现镜像速度也不理想按照以下顺序排查确认不是WiFi/移动网络临时波动用curl -I https://hf-mirror.com看延迟尝试关掉hf_transfer有时候并发太高反而被限速检查服务器是否有带宽限制策略换一台地域不同的机器对比测试确认是否开着代理工具代理与镜像同时启用有时会导致走弯路7. 个人实操中的一些体会最后分享几条我实际使用中攒下来的经验。第一环境变量配置这件事越早统一越好。如果你是在团队里建议把HF_ENDPOINT、HF_HOME写进团队的基础镜像和标准启动脚本里别让每个人各自在bashrc里面加不然总有漏配的机器出现各种奇怪问题。第二别过度依赖git clone下载模型。对普通大模型权重文件huggingface-cli的体验明显优于git lfs不管是断点续传还是并发下载都更成熟。git方式留给代码仓库就够了。第三对于需要频繁复用的基础模型比如中文Embedding模型、常用的base模型我建议下载完后单独备份一份到内部文件服务器版本固定后直接内网分发。镜像站再快也不如内网快。第四镜像站的同步有延迟所以当你要复现一些热门论文的最新模型时多留一点时间余量。比如周四周五新发的模型临到周末要复现很可能镜像上还没有做好等一等或者直接从官方源下载的预案。镜像站不是银弹但对国内开发者来说它解决了一个非常实际的问题让模型下载不再成为跑通实验的瓶颈。希望这篇文章里这些实操方法和排坑记录能帮你在配镜像的时候少走弯路。
