使用SentenceTransformers调用HuggingFace模型遇SSL错误求解决方案

问题场景 #

我使用SentenceTransformers工具运行以下代码时，出现无法解决的SSL错误：

import torch
from sentence_transformers import SentenceTransformer

sentences = ['This framework generates embeddings for each input sentence',
    'Sentences are passed as a list of string.',
    'The quick brown fox jumps over the lazy dog.']

model = SentenceTransformer("paraphrase-multilingual-mpnet-base-v2")
embeddings = model.encode(sentences)

错误信息 #

返回的错误如下：

SSLError: (MaxRetryError("HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded with url: /api/models/sentence-transformers/paraphrase-multilingual-mpnet-base-v2 (Caused by SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1007)')))"), '(Request ID: b875fc51-82ec-4309-94ab-0d08f9ab067d)')

环境信息 #

• Python版本：3.10.12
• 相关包版本：

torch                    2.0.1
sentence-transformers    2.2.2
requests                 2.31.0

已尝试但无效的方案 #

• 添加verify=False请求huggingface：

  import requests
  r = requests.get('https://huggingface.com', verify=False)
  

• 使用verify=ssl.CERT_NONE替代verify=False
• 设置环境变量CURL_CA_BUNDLE=''并将requests降级至2.27.1：

  import os
  os.environ['CURL_CA_BUNDLE'] = ''
  

错误原因分析 #

该错误属于网络SSL握手异常，核心原因包括：

• 网络限制：所在网络（公司/校园网）的防火墙、代理拦截了与huggingface.co的HTTPS连接，导致连接中途断开触发EOF错误
• 本地证书问题：系统或Python环境的CA证书过期、缺失，无法验证huggingface的SSL证书
• 网络波动：不稳定的网络导致数据传输时连接意外中断

有效解决方法 #

1. 手动下载模型到本地加载 #

直接下载paraphrase-multilingual-mpnet-base-v2模型的全部文件到本地目录，然后指定本地路径加载：

from sentence_transformers import SentenceTransformer

# 替换为你本地模型文件的实际路径
model = SentenceTransformer("./paraphrase-multilingual-mpnet-base-v2")

2. 配置网络代理（针对防火墙/代理拦截场景） #

如果是网络拦截导致，在代码中设置代理后再加载模型：

import os
# 替换为你的代理地址和端口
os.environ['HTTP_PROXY'] = 'http://proxy.example.com:8080'
os.environ['HTTPS_PROXY'] = 'http://proxy.example.com:8080'

from sentence_transformers import SentenceTransformer
model = SentenceTransformer("paraphrase-multilingual-mpnet-base-v2")

3. 更新或修复本地SSL证书 #

• Windows：更新系统根证书，或手动安装huggingface网站的SSL证书
• Linux/macOS：更新CA证书库，再指定证书路径：

  pip install --upgrade certifi
  

  然后在代码中添加：

  import os
  import certifi
  os.environ['REQUESTS_CA_BUNDLE'] = certifi.where()
  

4. 借助transformers库提前下载模型 #

先用transformers库完成模型下载（会缓存到本地），再用SentenceTransformers加载：

from transformers import AutoTokenizer, AutoModel
from sentence_transformers import SentenceTransformer

# 触发模型下载到本地缓存
tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/paraphrase-multilingual-mpnet-base-v2")
model = AutoModel.from_pretrained("sentence-transformers/paraphrase-multilingual-mpnet-base-v2")

# 加载本地缓存的模型
st_model = SentenceTransformer("sentence-transformers/paraphrase-multilingual-mpnet-base-v2")

内容的提问来源于stack exchange，提问作者Quinten