Hugging Face 离线加载指南：解决 OSError 无法连接模型的 4 种方案

Hugging Face 离线加载是大模型本地部署的核心需求。当 from_pretrained 抛出 OSError: We couldn\’t connect to \’https://huggingface.co\’ 错误时，开发者常困惑于网络配置、缓存路径与离线模式的正确用法。本文将提供一套经多环境验证的完整方案，帮助你在无网/内网/代理环境下顺利加载模型。

为什么会出现连接错误？先理解模型加载机制

理解加载流程是有效排查的前提。Transformers 的 from_pretrained 遵循以下查找顺序：

1. 检查本地缓存 (~/.cache/huggingface/hub/)
↓ 命中 → 直接加载（无需联网）
↓ 未命中 →
2. 尝试连接 huggingface.co 下载
↓ 成功 → 下载并缓存 → 加载
↓ 失败 → 抛出 OSError

关键结论：80% 的加载失败源于\”本地无缓存 + 网络不可达\”的组合，优先检查这两项可快速定位根因。

四大解决方案：从联网调试到纯离线部署

方案一：确保联网并重试（适用于开发调试）

若当前环境可访问外网，按顺序排查：

# 1. 测试 Hugging Face 连通性
curl -I https://huggingface.co
# 应返回: HTTP/2 200

# 2. 若使用代理，设置环境变量
export HTTP_PROXY=\”http://proxy.company.com:8080\”
export HTTPS_PROXY=\”http://proxy.company.com:8080\”
# Windows PowerShell:
$env:HTTP_PROXY=\”http://proxy.company.com:8080\”
$env:HTTPS_PROXY=\”http://proxy.company.com:8080\”

# 3. 清除可能损坏的缓存（谨慎操作）
rm -rf ~/.cache/huggingface/hub/models–meta-llama–Llama-2-7b-hf*

# 4. 重试加载（添加重试逻辑）
from transformers import AutoModelForCausalLM
import time, requests

def load_with_retry(model_name, max_retries=3):
for i in range(max_retries):
try:
return AutoModelForCausalLM.from_pretrained(model_name)
except requests.exceptions.RequestException as e:
if i == max_retries – 1:
raise
print(f\” 第 {i+1} 次重试，等待 5 秒…\”)
time.sleep(5)

model = load_with_retry(\”meta-llama/Llama-2-7b-hf\”)

最佳实践：在 CI/CD 或批量部署脚本中添加重试逻辑，避