作为一个常年跟开源大模型打交道的人我几乎每天都要跟 Hugging Face 打交道。模型权重、tokenizer、数据集哪个都绕不开它。但很长一段时间里我下载一个 7B 模型都得盯在电脑前因为下载过程总会在某个文件上突然卡住或者一个十几 GB 的模型下到 90% 直接断掉cache 目录里躺着一堆.tmp文件干瞪眼。直到我把下载源头切到国内镜像站这个问题才算彻底解决。这篇就专门聊 Hugging Face 国内镜像的使用。我会直接说清楚镜像源怎么选、huggingface-cli 和 transformers 怎么配置、大文件下载如何加速和断点续传、以及我实际踩过的高频报错和排查链路。适合经常下载模型做微调、用 transformers 在线加载开源大模型、跑 RAG 项目需要频繁拉取 embedding 模型和数据集的工程师。新手也不用担心每一步我都会写到命令级别。1. 镜像源选型对比为什么我把下载地址固定到 hf-mirror.com1.1 直连下载的真实痛点我不去细究网络层面的具体原因只说实际体验huggingface.co 的网页端加载速度时好时坏但一旦涉及真正的模型文件下载问题就会被放大得非常明显。几个典型的症状大文件下载经常卡在 20%、50%、90% 等位置然后长时间无响应最后报Connection timeout。一次性下载目录里的全部文件时往往前面的文件下载得很快后面某个稍大的文件会反复失败导致整个任务被拖垮。huggingface_hub底层请求依赖 HTTPS遇到链路不稳定时重试逻辑并不总是足够“聪明”你可能要等很久才能等来一个失败结果。这些问题的本质是大文件传输对链路稳定性要求很高。模型文件动辄几 GB 到几十 GB甚至一个仓库里有多个分片文件任何一个分片传输出问题整个下载任务就会被卡住。文件越大暴露问题的概率就越高。这也是为什么在部分网络环境下直连下载小配置文件如config.json通常没问题但下载pytorch_model.bin或model-00001-of-00004.safetensors这类分片文件时就原形毕露。1.2 主流国内镜像源横向对比社区里关于镜像源的讨论不少我实际用下来国内的选项大致有这么几类镜像方案是否免费与 Hugging Face 路径一致性模型覆盖面我的使用体验hf-mirror.com是完全一致同步 HF 全量模型和数据集速度快稳定兼容性最好社区维护活跃ModelScope魔搭社区是不一致有自己的仓库体系国内热门模型较全但部分小众模型缺有自己的一套 API 和命令行不能直接替换 HF 路径各大云服务商内部托管的 HF 模型文件视情况部分一致通常只覆盖热门模型主要用于云环境内网加速个人使用门槛较高自建缓存代理自费看实现取决于缓存池适合团队内网长期使用前期搭建成本较高如果你只是个人下载模型或者团队内需要稳定复用 HF 资源我的建议是直接用 hf-mirror.com。它是目前社区用下来兼容性最好的方案核心原因是它和 Hugging Face 官方仓库的路径结构完全一致。也就是说你不需要学习新的 API、新的命令、新的目录结构只需要把请求地址切换过去原来怎么用 HF现在还怎么用。ModelScope 我也用过它对国内热门模型和数据集的支持确实不错尤其是中文社区模型下载速度也快。但问题是它的生态自成一体很多 Hugging Face 独有的参数、仓库结构和工具链不能无缝衔接。如果你迁移的成本很低也可以考虑但如果你已经有一整套基于huggingface_hub和transformers的代码换到 hf-mirror.com 基本是零成本切换。1.3 “换端不改命令”背后的原理HF_ENDPOINT 是核心开关为什么设置一个环境变量就能让整个 Hugging Face 生态自动走镜像这里的关键是huggingface_hub库的设计。在你安装transformers的时候huggingface_hub会被作为依赖一起装进来。它内部有一个全局配置项决定了所有请求发往哪个基础地址。这个基础地址在代码里通常被叫做endpoint默认值是https://huggingface.co。只要你设置了环境变量HF_ENDPOINThuggingface_hub在初始化的时候就会读取这个变量替换默认值然后后续的所有请求——包括拉取文件列表、下载模型权重、加载 tokenizer、下载数据集——全部发往你指定的这个新地址。这就是为什么 hf-mirror.com 好用它不只是提供了一个静态文件目录而是完整实现了 Hugging Face 的 API 路径约定。镜像站上的路径结构和huggingface.co保持一致huggingface_hub客户端只需要改基础地址剩下的逻辑完全不变。简单类比一下你平时从一个网盘下载文件网盘域名变了但文件的目录结构没有变那么只需要把你收藏夹里的根地址换掉所有子链接仍然有效。HF 镜像的实现思路就是这个。从使用便捷度来看整个配置过程只有一行环境变量的成本。我建议把这三个变量一起写进~/.bashrc或~/.zshrcexport HF_ENDPOINThttps://hf-mirror.com export HF_HOME/data/hf_cache export HF_HUB_ENABLE_HF_TRANSFER1HF_HOME是缓存根目录后面讲内网共享时你会用上它。HF_HUB_ENABLE_HF_TRANSFER是开启多线程下载的开关后面也会单独说。2. 最顺手的配置方式环境变量三件套与常用下载命令2.1 两条最核心的环境变量HF_ENDPOINT 与 HF_HOME上面提到的三个环境变量里最核心的是HF_ENDPOINT和HF_HOME。HF_ENDPOINT决定了你“从哪儿下载”这个前面已经说过。HF_HOME决定了缓存和配置文件放在哪里。默认情况下Hugging Face 会把缓存放在用户主目录下的.cache/huggingface包括hub模型和数据集的实际缓存文件即~/.cache/huggingface/hub。modulestrust_remote_codeTrue时加载的自定义代码模块。token存储登录凭据~/.huggingface/token或对应路径下的 token 文件。为什么要手动指定HF_HOME两个原因。一是很多服务器的系统盘空间有限而模型缓存动辄几十 GB放在系统盘很容易直接占满二是当你想把已经下载好的一整套缓存迁移到另一台机器时有一个统一目录会方便太多。我习惯把所有大模型相关的文件统一放在/data这种独立数据盘项目代码、模型权重、数据集全部分开避免互相干扰。如果你已经下载了一部分模型改完HF_HOME之后会发现之前的“已下载文件”好像凭空消失了。其实它们还在原来的默认目录只是 Hugging Face 不再去那边找了。这一点要提前知道别到时候以为文件被删了。2.2 huggingface-cli模型与数据集的标准下载姿势切换镜像源之后最常用的命令是huggingface-cli download。它的基本用法如下huggingface-cli download 模型仓库名 --local-dir 本地目录其中模型仓库名就是你在模型页面 URL 上看到的那段路径例如bert-base-uncased、microsoft/phi-2或者Qwen/Qwen2.5-7B-Instruct。举两个我常用的例子# 下载一个小模型做测试 huggingface-cli download bert-base-uncased --local-dir ./models/bert-base-uncased # 下载一个大模型的指定分片并排除不需要的文件 huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct --include *.json *.safetensors--include和--exclude这两个参数对带宽非常友好。很多时候你只需要模型权重不需要.onnx或.gguf这些额外格式或者你只需要 tokenizer 文件想快速在本地调试一下那完全可以只拉取tokenizer.json和config.json不需要把整个仓库的几 GB、几十 GB 都拉下来。如果下载过程因为网络抖动中断了重新执行同一条命令huggingface-cli会基于本地已有的缓存做校验和续传已经下载完成的部分不会重新传输。这是它比单纯用wget手动下载要靠谱的核心原因之一。如果你需要下载的是数据集命令也很接近huggingface-cli download --repo-type dataset 数据集仓库名 --local-dir ./datasets/数据集名注意这里多了一个--repo-type dataset参数。huggingface-cli不只管理模型还能管理数据集和 Space 仓库所以需要明确告诉它你下载的是哪一类仓库。2.3 transformers 在线加载模型时如何自动走镜像很多时候我不会把模型文件下载到本地目录而是让transformers在运行时自动从远端拉取。在没设置镜像之前这种场景最容易在加载过程中卡死。设置好HF_ENDPOINT之后一切顺滑。from transformers import AutoTokenizer, AutoModelForCausalLM tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen2.5-7B-Instruct) model AutoModelForCausalLM.from_pretrained( Qwen/Qwen2.5-7B-Instruct, torch_dtypeauto, device_mapauto )对外表现上代码一个字都不用改。transformers底层会通过huggingface_hub去 HTTP 请求模型仓库地址而这个仓库地址就已经被HF_ENDPOINT重定向到了镜像站。这里有一个容易忽略的细节from_pretrained方法本身有cache_dir参数你可以直接指定缓存位置避免临时文件散落各处。如果不指定它就会用HF_HOME指向的位置。model AutoModelForCausalLM.from_pretrained( gpt2, cache_dir/data/hf_cache, device_mapauto )如果你没有设置HF_ENDPOINT但仍然希望通过from_pretrained走镜像可以在代码里手动设置环境变量import os os.environ[HF_ENDPOINT] https://hf-mirror.com这个os.environ赋值必须在导入transformers之前、在第一次发起任何 Hugging Face 网络请求之前设置好。放到文件最顶上是最稳妥的。2.4 数据集走镜像datasets 库的 cache 与 load_dataset数据集的下载行为和模型权重类似也是通过huggingface_hub来完成的。用datasets库加载时它会把数据集文件缓存到本地。如果你设置了HF_ENDPOINT加载数据集时会自动走镜像。from datasets import load_dataset dataset load_dataset( c4, en, cache_dir/data/hf_datasets, splittrain[:1%] )load_dataset的cache_dir参数可以用来指定数据集缓存的存放位置。跟模型缓存类似如果你不设置就会用默认路径。这里有一个非常容易踩的坑加载大型数据集时比如c4、the_pile即使只取 1% 的分片也可能会触发整个分片文件的下载因为load_dataset需要读取完整的打包文件中的一部分。所以下载耗时和数据量的直觉判断往往有偏差建议先用小分片测试网络和数据流是否通畅再决定是否扩大下载范围。如果只想用 huggingface-cli 把数据集拉下来再离线加载到代码里可以这样做huggingface-cli download --repo-type dataset c4 --local-dir ./datasets/c4然后代码里改成dataset load_dataset(./datasets/c4, en, splittrain)这种“先下载再加载”的方式适合在共享服务器上反复使用同一份数据集的场景避免每次跑脚本都触发网络请求。3. 大文件传输优化hf_transfer 多线程加速与断点续传实操3.1 为什么几十 GB 的模型总在“最后一英里”失败大文件下载失败最常见的原因不是带宽不够而是长连接被中断。HTTP 下载一个 20 GB 的文件即使带宽很高也需要持续一段时间中间任何一个网络节点抖动都可能让连接断掉。如果下载工具不支持续传断掉之后只能从头再来这才是最浪费时间的。huggingface-cli实际上对断点续传的支持已经不错了默认会把下载过程的临时文件存在本地重新执行时会尝试从断点继续。但问题在于它默认的单线程下载速度并不总能踢满带宽。尤其当你的网络带宽本身很高时单线程下载通常只能跑到带宽上限的很小一部分白白浪费了资源。解决思路有两个方向一是让客户端使用多线程并发下载模型文件二是直接用支持分块续传的下载工具从镜像站的文件 URL 手动下载。两条路我都走过下面分别说。3.2 打开 hf_transfer 多线程加速实测提速效果明显huggingface_hub官方提供了一个 Rust 编写的加速模块叫hf_transfer。它利用多线程把文件拆成多个部分并发下载能大幅提升下载速度特别是对单个大文件的下载效果很显著。安装方式很简单pip install huggingface_hub[cli]这个命令会顺带安装hf_transfer。然后设置一个环境变量开启它export HF_HUB_ENABLE_HF_TRANSFER1设置好之后huggingface-cli download下载大文件时会自动走多线程分块策略。我在一台带宽比较充裕的服务器上实测之前用默认模式下载一个 7B 模型权重速度大概稳定在 12 MB/s 左右打开hf_transfer之后能跑到 40 MB/s 以上。不同网络的提升幅度不一样但一般都有明显改善。需要注意两点。第一hf_transfer在极个别时候会出现下载完成后文件校验不过的情况。如果你发现下载完的模型加载报错可以先关掉这个变量再下载一次排除它导致的问题。第二开启hf_transfer后断点续传的临时文件机制和默认模式不完全一样。如果你下载到一半想暂停临时文件可能不会像默认模式那样很好地在下次接着利用。真正需要反复断点续传的场景我建议关掉它优先保证传输可控。如果想把多线程加速能力用在代码里也可以直接调用hf_hub_downloadfrom huggingface_hub import hf_hub_download file_path hf_hub_download( repo_idQwen/Qwen2.5-7B-Instruct, filenamemodel-00001-of-00004.safetensors ) print(file_path)在设置了HF_ENDPOINT和HF_HUB_ENABLE_HF_TRANSFER1的情况下这个下载操作同样会自动走镜像和多线程。3.3 aria2 分片下载的备选方案有些场景下我不想依赖 Python 环境或者想在服务器上用一个独立的下载器来拉取文件。这时我会直接拼接 Hugging Face 镜像的文件 URL用它对应的直链下载。HF 仓库里每个文件的下载链接有一个固定规律https://hf-mirror.com/模型仓库名/resolve/main/文件名例如https://hf-mirror.com/bert-base-uncased/resolve/main/config.json https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/model-00001-of-00004.safetensors拿到直链之后aria2是一个非常好用的分块下载工具它能把一个文件拆成多个连接同时下载天然支持断点续传还支持--continuetrue。我常用的命令长这样aria2c -x 16 -s 16 -k 20M \ -d ./models/Qwen2.5-7B-Instruct \ -o model-00001-of-00004.safetensors \ https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/model-00001-of-00004.safetensors参数解释-x 16每个服务器的最大连接数这里用 16 个连接同时下载。-s 16将单个文件拆成 16 个分片。-k 20M每个分片的最小大小影响分片策略。-d下载目录。-o保存的文件名。如果某个分片网络出了问题重新执行这条命令aria2 会检查已有的临时分片文件只下载缺失的部分。对于那种“卡住”的下载任务这个工具比裸wget靠谱得多。不过用 aria2 有个前提你需要自己去获取目标仓库里所有需要下载的文件名。如果一个仓库里有 60 多个分片文件手动拼接就很痛苦。更合理的流程是先用huggingface-cli download --include *.safetensors让工具自动生成下载清单并下载遇到某个文件反复失败时再单独针对那个文件用 aria2 接力。用脚本先获取文件列表再逐批下载也是一种可行方案但日常使用中我建议优先依赖huggingface-cliaria2 更适合处理它搞不定的“硬骨头”。3.4 并发下载的正确姿势与文件校验一次性下载多个不同仓库的模型时你可能会想同时起多个下载任务来抢时间。这个完全可以但要注意控制并发数。我在实际操作中并行跑过 4 个huggingface-cli download进程没有太大问题但如果把并发数拉到 10 个以上会发现单个任务速度明显下降有时候还会触发镜像站的限流策略反而比逐个下载更慢。我的做法是把下载拆成两段第一段先把所有模型仓库里的小文件config、tokenizer、json 等拉下来。第二段再逐个下载大的权重文件或者用hf_transfer模式直接拉取。下载完成之后文件校验是很关键的一步。模型文件损坏往往是“悄无声息”的表面上文件大小一样实际上.safetensors文件已经不可用了。简单起见我会在下载完成后检查目录下所有文件的大小是否和 Hugging Face 仓库页面展示的一致。如果某个文件明显偏小或者目录里残留.tmp、.lock文件就说明上一个下载任务没有完整结束需要删除该文件重新下载。# 检查目录里有没有残留的临时文件和锁文件 find ./models/Qwen2.5-7B-Instruct -name *.tmp -o -name *.lock出现锁文件通常说明还有一个下载进程在运行或者上次进程非正常退出。这种情况先把相关进程杀掉再清理锁文件否则新的下载任务可能拒动。4. 高频报错排查链路证书、路径、转发变量与缓存权限4.1 SSL 证书报错与镜像源的信任问题使用镜像站时一个相对常见的问题是代码或命令行直接抛出 SSL 证书校验错误错误信息长这样requests.exceptions.SSLError: HTTPSConnectionPool(hosthf-mirror.com, port443): Max retries exceeded ... Caused by SSLError(SSLCertVerificationError(...))第一个念头不要是“关掉证书校验”环境变量HF_HUB_DISABLE_SSL_VERIFICATION虽然能强制关闭校验但不建议一上来就用这会降低安全性。先检查是不是系统 CA 证书库太久没更新或者 Python 环境缺少了证书依赖。在多数情况下更新一下系统中的 CA 证书就能解决# Debian/Ubuntu apt update apt install -y ca-certificates # CentOS/RHEL yum update -y ca-certificates如果你的网络环境特殊必须通过一些第三方信任代理去访问镜像站才会考虑临时关闭校验。这种情况下的操作是设置export HF_HUB_DISABLE_SSL_VERIFICATION1但请记住这只是“能用”和“好用”之间的妥协能不开就不开。真实业务环境里的信任链路出了问题要优先排查系统证书而不是一刀切关掉校验。4.2 镜像域名拼到 repo_id 里的低级错误很多初学者会犯一个很直接的错误在repo_id里直接写上了镜像站域名。下面写一个错误示例# 错误写法 AutoModel.from_pretrained(hf-mirror.com/Qwen/Qwen2.5-7B-Instruct)这样的写法在huggingface_hub里通常无法正确解析因为repo_id应该只是“命名空间/仓库名”不应该包含协议、域名和路径前缀。甚至在某些版本里model_name_or_path会被当成一个本地路径去找目录结果直接报local directory not found或者其他路径相关的错误。正确写法AutoModel.from_pretrained(Qwen/Qwen2.5-7B-Instruct)镜像域名是通过HF_ENDPOINT环境变量全局控制的不需要出现在代码里。对照一下操作错误写法正确写法$from_pretrained 模型名hf-mirror.com/Qwen/Qwen2.5-7B-InstructQwen/Qwen2.5-7B-Instructhuggingface-cli 仓库名hf-mirror.com/bert-base-uncasedbert-base-uncased手动拼接 URLhttps://huggingface.co/Qwen/Qwen2.5-7B-Instruct/resolve/main/...https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/...如果你非要在代码里手动控制直链下载那确实要把域名拼进 URL但只要走huggingface_hub相关 APIrepo_id就永远是纯净的仓库路径。4.3 网络转发相关环境变量带来的干扰huggingface_hub在网络请求时默认会读取环境里的HTTP_PROXY、HTTPS_PROXY、ALL_PROXY等变量。如果你在服务器上以前配置过这些变量下载时很容易出现“设了镜像站却还是超时”的诡异问题。这个坑为什么会存在因为镜像站地址被HF_ENDPOINT正确设置了但请求在发出的一瞬间被转发变量“劫持”走了根本没流经镜像站的直连通道而是在某个转发节点上等待超时。表现就是换了镜像、换了网络还是报一样的超时错误。排查方法是检查当前环境里存在哪些转发变量env | grep -i proxy如果输出了相关变量又确认当前场景不需要它就先清掉再测试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY清掉之后重新跑一次下载命令如果速度恢复就说明请求确实被转发变量干扰了。这个坑非常隐蔽它不会直接报“proxy error”而是让你误以为镜像站速度慢或者不稳定。我第一次遇到时排查了接近一小时最后才发现是旧环境变量在捣鬼。还需要注意某些镜像站或者企业内网环境确实需要这些转发变量才能访问公网。这种场景下就不要简单 unset而是要确保镜像站地址也在转发规则的允许列表里。企业内网的具体配置方式各不相同我建议先和网络管理员确认镜像站的域名是否已加到放行列表而不是自己盲目尝试绕过。4.4 磁盘缓存权限与空间不足下载大模型时最容易被忽略的是磁盘空间和权限问题。尤其是使用共享服务器时huggingface-cli download默认会把临时文件写到用户主目录的缓存中。如果主目录所在分区空间不够下载会直接失败报错大多是磁盘空间不足或者权限不足。解决方案就是前面提到的把HF_HOME指到空间充裕的数据盘export HF_HOME/data/hf_cache另外多个用户共享一台服务器时最好不要把公共模型下到某个人的家目录否则会产生“别人想用但没权限”的尴尬局面。比较规范的做法是建一个共享目录比如/data/models并设置好组权限# 建立一个共享模型目录赋予当前用户组读写权限 mkdir -p /data/models chmod -R 755 /data/models然后所有下载操作都指定--local-dir /data/models/xxx。这样团队协作时谁想用同一个模型直接从这个目录加载即可不用重复下载。如果你遇到 Hugging Face 在HF_HOME下反复创建缓存但又不重新下载的情况清理方法也很简单。把对应缓存目录里的blobs和snapshots里对应仓库的临时文件删掉注意不要直接删整个hub目录因为那里面可能还有别的正常缓存。# 先看具体缓存内容 du -sh /data/hf_cache/hub/* # 删掉特定仓库的残留 rm -rf /data/hf_cache/hub/models--Qwen--Qwen2.5-7B-Instruct这个路径命名规则我要提醒一下缓存目录里不是直接以仓库名命名的而是把命名空间和仓库名之间的/换成两个下划线并加上models--前缀。例如Qwen/Qwen2.5-7B-Instruct在缓存目录下对应的是models--Qwen--Qwen2.5-7B-Instruct。5. 进阶场景受限模型、数据集下载与内网共享缓存5.1 限权模型和私有模型怎么通过镜像下载Hugging Face 上有一部分模型是“受限模型”gated model比如 Meta 的 Llama 系列、Mistral 的一些商业授权模型。在官方页面下载前需要先登录 Hugging Face 账号并同意该模型的使用条款。这种情况不会因为换了镜像源就自动放开权限——镜像站只是搬运文件授权校验仍然由 Hugging Face 官方体系和用户侧 token 完成。正确流程分两步第一步先在官网或者代码里完成账号认证huggingface-cli login在浏览器打开返回的地址获取 access token 并粘贴到终端即可。认证信息会存放在~/.huggingface/token或HF_HOME下对应的 token 文件里。第二步在保持登录状态的情况下下载huggingface-cli download meta-llama/Llama-2-7b-chat-hf --local-dir ./llama2只要这个账号在官方已获得对应模型的授权镜像源侧的下载请求也会附带这个 token文件校验和授权判定都会走官方通道所以能正常下载。如果你没有完成huggingface-cli login直接去下载限权模型大概率会收到一个401 Unauthorized或者Repository Not Found的错误。这个报错容易让人误以为是镜像站同步不全实际上是授权没通过。排查思路很简单换一个公开模型试试如果公开模型能下载说明镜像通道没问题问题只在于授权。5.2 把下载好的 HF_HOME 变成团队共享缓存我们的团队里经常遇到“同一台服务器上有七八个人都在用同一个模型”的场景。如果每个人都各自下载一份模型权重几十 GB 的流量反复消耗在服务器本地上纯粹是浪费。一个非常实用的方案是集中建设一个模型缓存目录然后让所有人都复用。假设服务器上已经建立好了/data/hf_cache并且已经用这个HF_HOME下载过所有团队常用的模型。那其他同学在使用时只需要在自己的环境配置文件里指向同一个目录export HF_HOME/data/hf_cache这样当代码执行from_pretrained(Qwen/Qwen2.5-7B-Instruct)时huggingface_hub会先检查HF_HOME/hub里是否已经有该模型的缓存。如果有就直接从本地读文件完全不会触发网络请求。如果一个模型还没被下载过第一个触发的人会把它下载下来放入共享缓存后面的人再使用时就全部走缓存了。需要注意几个细节共享缓存的目录写权限要规划好。如果所有人都能写存在被误删的风险。建议下载动作由管理员统一负责普通成员只读。多个用户同时触发同一个模型的下载huggingface_hub会通过锁机制避免重复下载但最好还是避免这种竞争场景。数据集缓存的机制类似HF_DATASETS_CACHE可以单独指向共享目录。5.3 断网内网服务器上怎么“假装”在联网有些训练或推理服务器出于安全考虑完全无法访问公网。这种机器上要跑起开源模型就必须提前把模型打包带进去。我的做法是在一台有网络的工作机上先用镜像站把需要用的模型全部下载妥当然后压缩、拷贝到内网服务器上解压。但这里有个关键解压后的模型目录不一定能被transformers直接识别。因为默认情况下from_pretrained会优先把传入的路径当作一个 HF 仓库名去缓存目录里寻找而不是直接当作本地目录读取。解决方法是在代码里传入本地路径时确保这个路径下就是模型的完整文件。比如huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir /data/offline_models/Qwen2.5-7B-Instruct之后把这个/data/offline_models整个目录拷贝到内网服务器代码里直接写model AutoModelForCausalLM.from_pretrained( /data/offline_models/Qwen2.5-7B-Instruct, device_mapauto )当传入的路径是一个本地存在的目录时transformers会直接读取本地文件不走网络。如果传入的是一个模型名它会去缓存目录里找缓存目录里没有时才会尝试线上拉取。内网机器上可以设置一个假的HF_HOME配合刚才的共享缓存方案实现“一次下载全内网共用”。5.4 社区资源、排行榜与 Space 的下载限制镜像源对模型和数据集仓库的覆盖能力很强但对 Space 这类交互式应用它并不做直接代理。如果你看到一个 Space 很漂亮想把它 clone 下来本地跑两个办法一是从 Hugging Face 仓库下载该 Space 的代码文件这个可以尝试通过镜像拉取但交互运行时需要的后台依赖和资源镜像站无法完全模拟。二是用huggingface-cli download --repo-type space 用户名/仓库名把 Space 源码拉下来再根据它的requirements.txt和app.py在本地复现环境。这种做法在部分简单 Gradio 应用里是可行的复杂应用就需要自己补全外部依赖。至于模型排行、趋势等社区数据这些属于 Hugging Face 网站的动态页面内容不是镜像站同步的范围。如果你需要做模型选型或者调研建议直接在官网页面查看趋势数据需要实际权重时再切镜像下载。最后分享一点个人经验我自己的做法是维护一份“常用模型清单”把当前项目里所有会反复用到的模型和数据集写进一个 shell 脚本每周用定时任务在闲时自动跑一次huggingface-cli download更新到共享缓存目录。一开始会花一点时间配置但长期来看能省下大量重复下载的等待时间。还有一个小技巧如果某一次镜像站下载速度突然明显变慢不要反复重试硬等先看一眼是不是高峰时段换到凌晨再跑或者用HF_HUB_ENABLE_HF_TRANSFER1配合多线程尝试往往几分钟内就能恢复理想速度。镜像不是万能的但它确实是目前解决 Hugging Face 资源获取问题最省心的通路——只要用对方法它能变得很稳。