解决 Hugging Face SentenceTransformer 下载失败的完整指南：ProxyError、SSLError与手动下载方案

问题背景

在使用 Hugging Face 的 SentenceTransformer 加载预训练模型 all-MiniLM-L6-v2 时，遇到了以下错误：

1. 代理连接失败（ProxyError / SSLError: KRB5_S_TKT_NYV）
2. 大文件下载中断（unexpected EOF while reading）
3. trust_remote_code 参数不兼容（TypeError）

经过多次尝试，最终成功解决。本文将详细记录问题原因和解决方案，帮助遇到类似问题的开发者。

---

错误日志分析

1. 代理连接失败（ProxyError / SSLError）

初始报错：

urllib3.exceptions.ProxyError: ('Unable to connect to proxy', SSLError(1, '[SSL: KRB5_S_TKT_NYV] unexpected eof while reading (_ssl.c:1091)'))

原因：

• 网络环境需要通过代理访问 Hugging Face，但 Python 请求未正确配置代理。
• 代理可能使用了 Kerberos 认证（KRB5_S_TKT_NYV），导致 SSL 握手失败。

2. 大文件下载中断（EOF Error）

在下载 model.safetensors（90.9MB）时，连接意外终止：

ssl.SSLError: [SSL: KRB5_S_TKT_NYV] unexpected eof while reading (_ssl.c:2570)

原因：

• 代理服务器不稳定，中断了长时间连接。
• 企业网络可能限制大文件下载。

3. trust_remote_code 参数错误

TypeError: __init__() got an unexpected keyword argument 'trust_remote_code'

原因：

• trust_remote_code 是 transformers 库的参数，但 SentenceTransformer 不支持。

---

解决方案

1. 正确配置代理

（1）如果网络需要代理，设置环境变量：

import os
os.environ["HTTP_PROXY"] = "http://your-proxy:port"  # 替换为实际代理
os.environ["HTTPS_PROXY"] = "http://your-proxy:port"

（2）如果需要用户名和密码：

os.environ["HTTP_PROXY"] = "http://username:password@proxy-ip:port"

（3） 如何从电脑查找代理的IP地址和端口号呢？

2. 临时禁用 SSL 验证（仅调试）

如果代理证书不受信任，可临时关闭 SSL 验证：

import ssl
ssl._create_default_https_context = ssl._create_unverified_context

注意：生产环境不建议这样做，可能存在安全风险。

3. 手动下载模型

如果代理不稳定，最佳方案是手动下载：

1. 访问模型页面：
   (1) all-MinLM-L6-v2
   or
   (2) all-MiniLM-L6-v2 · Hugging Face

2. 下载文件

3. 保存到本地目录，如 ./local_model/

4. 从本地加载模型：

   model = SentenceTransformer("./local_model")
   

4. 调整超时和重试（可选）

如果网络较差，可以增加超时时间：

from sentence_transformers import SentenceTransformer
import requests

session = requests.Session()
session.timeout = 120  # 2分钟超时
model = SentenceTransformer("all-MiniLM-L6-v2", request_session=session)

---

最终代码示例

import os
from sentence_transformers import SentenceTransformer

# 1. 设置代理（如果需要）
os.environ["HTTP_PROXY"] = "http://your-proxy:port"
os.environ["HTTPS_PROXY"] = "http://your-proxy:port"

# 2. 方式1：直接在线下载（可能仍受网络影响）
try:
    model = SentenceTransformer("all-MiniLM-L6-v2")
except Exception as e:
    print("在线下载失败，改用本地模型:", e)
    # 3. 方式2：手动下载后从本地加载
    model = SentenceTransformer("./local_model")

print("模型加载成功！")

---

总结

问题	解决方案
代理连接失败	设置 HTTP_PROXY / HTTPS_PROXY
SSL 证书错误	临时禁用 SSL 验证（仅调试）
大文件下载中断	手动下载模型并本地加载
trust_remote_code 错误	该参数不适用于 SentenceTransformer

推荐方案：
✅ 优先手动下载模型，避免代理问题。
✅ 如果必须在线下载，确保代理配置正确并增加超时时间。

希望这篇指南能帮助你顺利加载 Hugging Face 模型！