1. 先把链路理清楚本地、镜像站、远程服务器之间到底发生了什么做深度学习或者大模型应用的同学十有八九都遇到过这个场景代码里写死了from_pretrained(bert-base-uncased)模型文件却卡在 huggingface.co 上下不动网络环境稍微波动一下连接就断几 GB 的权重文件下到一半只能重来。更麻烦的是目标机器是机房里的远程服务器没有外网权限或者外网访问 Hugging Face 官网非常不稳定根本没法在服务器上直接拉取。于是“先在自己的电脑上下载再想办法传上去”就成了最现实、也最可靠的方案。这个标题里最有价值的三个关键词——huggingface、镜像站、远程服务器——其实构成了一条完整的链路在你的本地机器上通过镜像站把模型权重下载完整再通过传输工具把文件打包、校验、传到目标服务器最后让服务器上的代码直接加载本地路径完全摆脱对官网的依赖。这不是一条死路恰恰是生产环境下最常采用的离线交付方案。整条链路中真正的技术难点只有三个模型文件能不能完整下载、传输过程会不会丢包或中断、服务器上的代码能不能认得出本地目录。搞清楚这条链路剩下的工作就是用合适的工具把每一环做好。这篇文章会按照“本地下载 → 传输 → 服务器离线加载”的顺序把每一步的细节和踩坑点都讲透。无论你是要部署一个 7B 模型的推理服务还是只是想把一个几百 MB 的 embedding 模型拷进内网集群这套流程都适用。先说结论整个方案的核心其实只有一条原则——让 Hugging Face 的库认为模型已经在本地绝不触发联网请求。所有配置都围绕这个原则来就不会走弯路。2. 本地下载环节用镜像站把模型完整拿到手2.1 两种最常用的下载方式huggingface-cli 与 snapshot_download本地下载模型主流工具就是 Hugging Face 官方提供的huggingface-cli以及代码里直接调用的snapshot_download方法。这两者底层逻辑相同但命令行更适合手动操作Python API 适合脚本批量处理。先讲命令行方式。配置镜像站最直接的方法是设置环境变量export HF_ENDPOINThttps://hf-mirror.com然后正常执行huggingface-cli download meta-llama/Meta-Llama-3-8B --local-dir /data/models/llama3-8b这里有几个关键点要说明。第一--local-dir是近几个版本才稳定支持的新参数语义非常清晰把模型库里的所有文件下载到指定目录目录内的文件结构跟官网仓库一致也就是config.json、model-00001-of-00002.safetensors这些文件会在本地目录里完整呈现。这个细节对后续“传输到服务器”至关重要因为保持文件结构不变服务器上加载时就不需要做任何路径改写。第二环境变量HF_ENDPOINT的作用范围是当前 shell。如果你不想每次开终端都重设建议写进~/.bashrc或者~/.zshrc里。但有一点要提醒如果你用 Python 的transformers库直接加载模型只要这个环境变量存在库在访问huggingface.co时就会自动改成访问镜像站这也就是为什么很多同学只设置了这个变量代码里什么都不改就能顺利下载模型的原因。第三如果你更喜欢用 Python 脚本等价写法是import os os.environ[HF_ENDPOINT] https://hf-mirror.com from huggingface_hub import snapshot_download snapshot_download( repo_idTHUDM/glm-4-9b-chat, local_dir/data/models/glm-4-9b-chat, max_workers8 )max_workers8代表用 8 个线程并发拉取文件。对于包含几十个权重分片的大模型并发下载速度提升非常明显。不过要注意并发数不建议开太大我实测 8 到 12 个线程是比较舒服的范围再大会触发镜像站的连接限制反而频繁断流。2.2 只有一两个权重文件的话用 wget 或 aria2 更快不是每次都需要下载整个模型仓库。比如你只想下载一个pytorch_model.bin或者一个单独的tokenizer.json那就没有必要启动 huggingface-cli。直接用wget拼 URL 就行但前提是你已经知道文件的确切路径。镜像站的 URL 规则很直白把官网地址https://huggingface.co替换成https://hf-mirror.com后面的仓库路径和文件名原样保留。例如wget -c https://hf-mirror.com/THUDM/glm-4-9b-chat/resolve/main/tokenizer.json -O /data/models/glm-4-9b/tokenizer.json-c参数表示断点续传。单文件下载时这招是救命稻草只要网络不断绝中断后重新执行它会从上次的位置继续而不是从头再来。但是wget是单线程遇到大文件好几个 GB 的 safetensors速度略吃亏。这种情况我强烈建议换成aria2caria2c -x 16 -s 16 -c https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/model-00001-of-00004.safetensors -d /data/models/qwen2.5-7b/-x 16表示从同一文件开启 16 个连接-s 16表示文件分 16 段下载-c同样是断点续传。对于大文件这个组合能把速度拉满而且稳定度相当好。如果机器上没装 aria2sudo apt install aria2或者brew install aria2几秒钟就能搞定。2.3 关于镜像站的几个“潜规则”先说结论网上流行的hf-mirror.com并非简单的反向代理它缓存了大量热门模型的完整文件所以对热门模型下载速度极佳冷门模型或者刚发布的新模型镜像站第一次拉取时要从源站转发速度就会明显下降。如果你下的是 Meta-Llama-3、Qwen、GLM 这些人气仓库基本能跑满本地带宽但要是某个只有几十次下载量的小仓库就得忍受一段时间的龟速。另外镜像站对 git 协议的支持并不完美。我见过不少人用git clone https://hf-mirror.com/xxx/model来拉仓库结果在拉 LFS 文件时报smudge filter错误。原因很简单模型仓库的大文件全部走 Git LFS镜像站对 LFS 的兼容偶尔会有问题。所以我的建议是放弃 git clone 思路一律使用 huggingface-cli 或者 wget/aria2 拉文件。这不是绕路而是少踩坑。下载完成后别急着传输先在本地做一件事对照官网仓库页面看文件列表检查有没有缺文件。最稳妥的做法是使用snapshot_download返回的 snapshot 目录或者用python -m huggingface_hub.scan_cache把缓存内容列出来确认模型文件齐全了再进入下一步。权重大文件最容易出现“0 字节”和“不完整分片”不检查就传输等于把隐患带到服务器上。3. 传输环节从本地到远程服务器稳比快更重要3.1 打包与压缩为什么一定要先打包再传模型目录里通常有成百上千个小文件——光一个tokenizer.json就几十 KBconfig.json几 KB还有一堆分片权重。如果你直接scp -r ./model_dir userserver:/data/models/会带来两个问题一是每个文件都要单独建立 SSH 连接做认证几百个文件就要认证几百次速度慢得离谱二是小文件传输更容易因为网络波动“静默失败”缺一个文件都不好排查。正确的姿势是先打包再传输。打包的目的有两个把散落的小文件合并成一个文件流大幅减少 SSH 握手次数同时保留目录结构和文件权限避免 tar 的软链接在传输后失效。tar -czf model_name.tar.gz /data/models/llama3-8b-c创建归档-z用 gzip 压缩-f指定文件名。权重文件本身已经是高度压缩的格式gzip 对 safetensors 和 bin 文件几乎压不动所以不要指望这个步骤能把体积减掉多少。它的核心价值是“聚合”而不是“减肥”。3.2 scp 基础用法与 password 问题打包完成后最直接的传输工具就是 scpscp model_name.tar.gz user192.168.1.100:/data/models/如果你习惯用密钥认证这一步基本零成本如果服务器只允许密码登录那么你需要提前安装sshpass之类的工具来自动化输入密码或者干脆手动输入。这里提醒一句如果文件特别大不要使用默认的 scp 协议也就是不要用 OpenSSH 9.0 之前那个基于 SCP 的旧协议建议加-O参数强制走 SFTP 协议否则大文件传输中一旦断连很难恢复进度scp -O model_name.tar.gz user192.168.1.100:/data/models/3.3 rsync 断点续传传输中断也不用重来scp 有个硬伤中断了就要重来。几百 GB 的模型传了三个小时最后 5% 处网络断了重新 scp 简直让人崩溃。这个问题 rsync 可以完美解决。rsync -avz --progress --partial /data/models/llama3-8b/ user192.168.1.100:/data/models/llama3-8b/参数拆解-a归档模式保留权限、软链接等属性-v显示详细输出-z传输时压缩对权重文件收益不大但小文件多的模型还是有帮助--progress显示每个文件的传输进度--partial保留部分传输的文件下次续传从断点继续--partial是我必须重点强调的参数。没有它rsync 在传输中断时会自动删除未完成的文件加上它之后中断的文件会保留在目标位置下次再执行同样的 rsync 命令时会自动基于已有文件做增量同步。这跟wget -c是一模一样的思路但 rsync 更聪明它会智能判断哪些文件已经完整哪些需要补传。如果想连目标目录里已有的无关文件也一并清理加--delete参数但模型场景下我一般不建议加免得误删其他模型文件。3.4 服务器无法直连本地时的“中间跳板机”方案有时候你的远程服务器不在公网必须登录一台跳板机再进入内网。这时候不能直接把文件推到最终服务器需要分两步# 第一步传到跳板机 scp model_name.tar.gz userjump_host:/tmp/ # 第二步从跳板机传到内网服务器 ssh userjump_host scp /tmp/model_name.tar.gz user192.168.1.100:/data/models/如果跳板机也不方便中转还有一个更取巧的方案ssh -L做端口转发把内网服务器的 SSH 端口映射到本地。这个概念稍微绕一点但实际用起来很顺手ssh -L 2222:192.168.1.100:22 userjump_host执行完之后本地机器的 2222 端口就相当于内网服务器 192.168.1.100 的 22 端口然后直接rsync -avz --progress --partial -e ssh -p 2222 model_name.tar.gz user127.0.0.1:/data/models/本质上就是让本地和最终服务器之间建立了一条通过跳板机的“逻辑直连”rsync 依然具有断点续传能力。这个方案遇到的机会不多但一旦遇到能让你的交付效率翻倍。3.5 传输校验md5sum 才是真正的“送达回执”传输完成后最怕的是“传了但没传全”。gzip 的 tar 包在解压时会自动校验 crc 校验码理论上能发现文件损坏但这只能判断 tar 包是否完整不能判断 tar 包里面的文件是否与官网一致。所以真正的安全做法是在本地先记录模型文件的哈希值服务器上解压后再做一次比对。本地在打包前执行find /data/models/llama3-8b -type f -exec md5sum {} \; /data/models/llama3-8b.md5服务器上解压后执行cd /data/models/llama3-8b md5sum -c /data/models/llama3-8b.md5md5sum -c会逐行校验文件哈希输出OK就是完整输出FAILED就要重新传送对应文件。这里不建议用 SHA256虽然更安全但大模型的几十个分片逐个算 SHA256 非常耗时本地算一次服务器再算一次时间成本都翻倍。模型权重出错的影响没有代码库那么致命md5 的碰撞风险在这个场景下完全可以接受。注意计算哈希是在解压后执行不是对 tar 包计算。tar 包内容变了或者部分损坏解压后的文件哈希才可能暴露问题这比单纯判断 tar 是否完整要精确得多。4. 服务器离线加载环节让代码只认本地目录4.1 目录结构保持一致加载代码一行不改前面我们在下载时用了--local-dir就是为了让本地目录结构跟 Hugging Face 仓库完全一致。这个一致性在服务器端价值很大任何一层目录被移动或者改名from_pretrained都会因为找不到模型 card也就是config.json而报错。举个例子。在官网仓库meta-llama/Meta-Llama-3-8B下面文件结构大致是config.json generation_config.json model-00001-of-00004.safetensors model-00002-of-00004.safetensors model-00003-of-00004.safetensors model-00004-of-00004.safetensors tokenizer.json tokenizer.model tokenizer_config.json只要服务器上/data/models/llama3-8b目录内也是这个结构代码里就可以直接用from transformers import AutoModelForCausalLM, AutoTokenizer model AutoModelForCausalLM.from_pretrained(/data/models/llama3-8b) tokenizer AutoTokenizer.from_pretrained(/data/models/llama3-8b)from_pretrained接受的参数既可以是 repo_id如meta-llama/Meta-Llama-3-8B也可以是本地路径。传入本地路径时transformers 会完全跳过联网查证环节直接读取本地文件。这就是“离线加载”的核心机制。4.2 环境变量兜底防止代码偷偷联网有些同学会有顾虑虽然我传了本地路径但 transformers 在加载时会不会因为内部逻辑需要而偷偷访问官网正常情况下加载本地路径不会联网但如果你调用的是类似AutoModel.from_pretrained(THUDM/glm-4-9b-chat)这种 repo_id 写法而服务器又没有外网权限它就会一直报连接错误。这时候需要用环境变量把联网请求彻底掐死。在服务器上设置export HF_HUB_OFFLINE1 export TRANSFORMERS_OFFLINE1 export HF_HOME/data/huggingface_cacheHF_HUB_OFFLINE1是告诉 huggingface-hub禁止一切外部请求只在本地缓存中找文件。TRANSFORMERS_OFFLINE1则是 transformers 库的独立开关双保险。HF_HOME要单独解释一下。如果你把模型放在/data/models/llama3-8b但 transformers 在加载时还会去HF_HOME下的modules或hub目录寻找 tokenizer 配置等元信息。如果你不希望它把任何文件写到默认的~/.cache/huggingface就手动指定一个目录通常也放在数据盘避免占满系统盘。4.3 常见坑safetensors 与 bin 格式差异模型权重文件有两种常见格式.safetensors和.bin。在下载时镜像站返回的文件取决于官网仓库里的实际文件。大多数新模型同时提供两种格式但如果你只下载了.bin在加载时可能会被提示缺少 safetensors 文件。这个问题在离线环境下尤其麻烦因为 transformers 在推断权重文件时会优先查找.safetensors找不到再回退到.bin。更让人头疼的是如果仓库里同时存在两种格式而本地只下载了其中一种可能会报“找不到 model.safetensors.index.json”之类的错误。解决办法有两个要么把两种格式的权重都下载齐全体积直接翻倍要么在下载前就确认好仓库提供的格式只下载对应的一种并把另一种格式的引用文件从本地目录中删掉。例如你决定使用.bin格式就把.safetensors相关文件清理干净最后在config.json里确认architectures字段没有对格式做特别要求。注意从 4.36 版本开始transformers 默认优先加载.safetensors。使用.bin文件时虽然不一定会报错但某些版本会打印一条 Warning。这不算致命问题但会让你在排查其他报错时多一层干扰。4.4 离线缓存目录技巧snapshot_download 与 HF_HUB_OFFLINE 联动如果你不想把模型目录手动搬到指定位置而是希望模型文件跟着 Hugging Face 的缓存目录走常见做法是这样在能上网的机器上正常执行huggingface-cli download meta-llama/Meta-Llama-3-8B此时文件会进入缓存的 snapshot 目录结构类似~/.cache/huggingface/hub/models--meta-llama--Meta-Llama-3-8B/snapshots/commit-hash/然后把整个models--meta-llama--Meta-Llama-3-8B目录直接传到服务器的HF_HOME/hub/下并在服务器上设置HF_HUB_OFFLINE1。这样即使你的代码里写的是from_pretrained(meta-llama/Meta-Llama-3-8B)transformers 也能在离线缓存里找到对应文件不会尝试访问官网。这个技巧非常适合团队内部统一镜像的场景每个人在自己的机器上把模型拉到缓存目录传到服务器后服务器上的代码可以完全不改还是用原本的 repo_id 写法。代价是缓存目录里有个refs子目录里面是.git格式的引用信息传输时务必保留完整目录结构不要只拷贝 snapshot 文件。5. 常见问题与排坑实录5.1 下载阶段的问题现象一huggingface-cli 卡在“Fetching 8 files”不动这是镜像站高并发下的常见表现说明当前请求数太多。解决方案可以先加HF_HUB_DISABLE_XET1来禁用 xet 协议重试新版本 huggingface-hub 引入了 xet与老镜像站兼容性一般然后重新下载。也可以在snapshot_download里减少max_workers降到 4 或 2让请求更温和。现象二某一两个文件始终下载失败很可能是镜像站冷门文件缓存过期。这时候不要无限重试转而用wget单独拉取该文件再通过huggingface-cli upload或者手动放回本地目录。或者等等再下换个网络时段比反复重试更能解决问题。5.2 传输阶段的问题现象三rsync 传输到一半报“connection reset by peer”这是网络层断连不用慌。重新执行同一条 rsync 命令即可--partial会保证已经传完的数据不重传。但要注意如果报错发生在文件写盘过程中目标文件可能是坏块最好先把对应文件删除再重新 rsync避免--partial误以为该文件已经完整。现象四传输速度慢到无法接受如果你用的是 Wi-Fi先检查是不是 2.4G 频段模型文件传输建议优先走有线或 5G 频段。如果服务器在公网可以评估压缩传输的收益虽然 safetensors 压不动但config.json、tokenizer.json这类文本文件很多rsync -z还是有意义的。小文件特别多的模型tar 聚合后再传比直接 rsync 目录快得多。5.3 离线加载阶段的问题现象五from_pretrained报“Connection error: cant reach huggingface.co”这通常是代码里传了 repo_id 而不是本地路径。要么把 repo_id 改成/data/models/llama3-8b这样的本地绝对路径要么设置HF_HUB_OFFLINE1且文件位于HF_HOME/hub的缓存目录。现象六模型能加载但 tokenizer 报错这大概率是 tokenizer 文件缺失。Hugging Face 仓库里通常有tokenizer.json、tokenizer_config.json、vocab.txt、tokenizer.model等不同模型需要的文件集合不同。离线环境没有自动下载补偿必须把所有相关文件都带全。校验方法官网仓库页面每个文件都看一眼一个不落。下表整理了这几种典型问题的速查方案环节典型报错核心原因解决动作下载卡住不动 / 超时镜像站并发限制降低并发数或加HF_HUB_DISABLE_XET1下载个别文件失败冷门文件未缓存用 wget 单独拉取并断点续传传输connection reset网络链路中断重新 rsync利用--partial续传传输速度过慢小文件太多 / 网络不稳先 tar 再传必要时启用压缩加载cant reach huggingface.co代码仍传 repo_id改用本地绝对路径或设置HF_HUB_OFFLINE1加载tokenizer 报错tokenizer 文件缺失对照官网补齐全部相关文件5.4 一个容易被忽略的文件数量问题大模型仓库中包含的文件数量远超想象。比如带分片权重的 7B 模型光.safetensors就有四到八个分片再加上tokenizer的多个文件以及各种配置文件总量轻松超过一百个。如果你在服务器上用了 ext4 文件系统inode 不够会导致拷文件报“No space left on device”但df -h又能看到剩余空间。遇到这种诡异问题先执行df -i查看 inode 剩余量而不是一味怀疑磁盘空间。这也是模型交付场景里最容易忽视的坑之一。6. 几条实操心得留给后面要走这条路的人整套流程走下来我个人体感是最容易出问题的环节不是下载反而是传输和离线加载之间的“缝隙”。很多人下载时很顺利但传到服务器后忘了设置HF_HUB_OFFLINE或者目录结构在解压时被套了外层文件夹导致from_pretrained里的路径指向错误花半小时排查才发现只是少了一个层级。所以我的建议是在动手之前先写一个小的验证脚本放在服务器上用最小的权重文件验证整个链路是否通。比如先下载一个几百 MB 的小模型走完“本地下载 → 打包 → 传输 → 解压 → 离线加载”全流程确认没问题之后再处理真正的大模型。这个半小时的预演能省下后面大文件传输失败的数个小时。最后再分享一个传输小技巧如果你的模型是同一个系列多个版本需要传到同一台服务器直接在服务器上做增量同步会非常快。因为config.json、tokenizer这些文件在不同版本间高度相似rsync 会自动复用已有的数据块传输量可能连总体积的十分之一都不到。这条经验在微调场景里特别实用我后面几次复用这个思路把好几个模型的同步时间从小时级压缩到了分钟级。