网络受限时的下载策略
下载权重卡住是常见问题，处理方式取决于网络条件。能连公网但慢，可以把下载源指向社区镜像或走企业代理；完全离线，则先在可达网络下载完整模型目录，再整体拷贝进内网，并在内网侧关闭联网校验，避免框架反复尝试联网导致启动卡顿。
镜像与代理
镜像与代理
# 指向社区镜像站
export HF_ENDPOINT=https://hf-mirror.com
# 或统一走企业代理
export https_proxy=http://<代理地址>:<端口>
# 下载到指定目录，便于整目录搬迁
huggingface-cli download <组织>/<模型> --local-dir ./models/<模型>
# 加速：启用高速传输（需先安装对应组件）
export HF_HUB_ENABLE_HF_TRANSFER=1离线搬迁
离线搬迁
# 搬到内网机器（保留目录结构）
rsync -avP ./models/<模型>/ user@内网机器:/data/models/<模型>/
# 内网侧关闭联网检查，避免启动时等待超时
export HF_HUB_OFFLINE=1
# 校验：比对文件清单与大小，或核对校验和三种策略对照
| 条件 | 推荐做法 | 代价 |
|---|---|---|
| 公网可达但慢 | 指向镜像或配置代理 | 依赖第三方服务的稳定性 |
| 带宽受限且有内网镜像 | 统一走企业自建镜像源 | 需要维护镜像同步 |
| 完全离线 | 外部下好整目录后搬运 | 迁移周期长，需校验清单 |
| 多节点部署 | 共享盘下好后分发 | 需要规划存储与权限 |
典型使用场景
- 企业内网模型准备：由一台可达外网的机器统一下载后分发
- 客户现场交付：把完整目录随安装包一起带走
- 带宽紧张时段：改用镜像源或代理，避开高峰
- 批量扩容：新节点从共享盘复制，避免重复占用公网带宽
- 排查启动慢：内网侧未关闭联网校验时，启动会卡在联网检测阶段
离线前要下载包含配置、分词器、权重与索引文件的完整目录：只拷权重文件是最常见的遗漏。
镜像站是第三方服务：敏感或受限模型不要经它中转，优先官方源或企业自建镜像，并核对文件清单与大小。