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

问题背景

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

代理连接失败（ProxyError / SSLError: KRB5_S_TKT_NYV）
大文件下载中断（unexpected EOF while reading）
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) all-MinLM-L6-v2
or
(2) all-MiniLM-L6-v2 · Hugging Face
下载文件
保存到本地目录，如 ./local_model/

从本地加载模型：

model = SentenceTransformer("./local_model")

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

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

from sentence_transformers import SentenceTransformer
import requestssession = 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`