本地部署Qwen2.5-VL出现报错：ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificat...如何解决？

🏆本文收录于《全栈 Bug 调优（实战版）》专栏。专栏聚焦真实项目中的各类疑难 Bug，从成因剖析 → 排查路径 → 解决方案 → 预防优化全链路拆解，形成一套可复用、可沉淀的实战知识体系。无论你是初入职场的开发者，还是负责复杂项目的资深工程师，都可以在这里构建一套属于自己的「问题诊断与性能调优」方法论，助你稳步进阶、放大技术价值。

bug菌¹

539人浏览 · 2026-02-05 18:00:30

bug菌¹ · 2026-02-05 18:00:30 发布

🏆本文收录于《全栈 Bug 调优（实战版）》专栏。专栏聚焦真实项目中的各类疑难 Bug，从成因剖析 → 排查路径 → 解决方案 → 预防优化全链路拆解，形成一套可复用、可沉淀的实战知识体系。无论你是初入职场的开发者，还是负责复杂项目的资深工程师，都可以在这里构建一套属于自己的「问题诊断与性能调优」方法论，助你稳步进阶、放大技术价值。

📌 特别说明：
文中问题案例来源于真实生产环境与公开技术社区，并结合多位一线资深工程师与架构师的长期实践经验，经过人工筛选与AI系统化智能整理后输出。文中的解决方案并非唯一“标准答案”，而是兼顾可行性、可复现性与思路启发性的实践参考，供你在实际项目中灵活运用与演进。

欢迎你 关注、收藏并订阅本专栏，与持续更新的技术干货同行，一起让问题变资产，让经验可复制，技术跃迁，稳步向上。

📢 问题描述

详细问题描述如下：我在本地部署qwen2.5-vl运行python web_demo_mm.py --checkpoint-path “Qwen/Qwen2.5-VL-7B-Instruct”
出现了如下报错：如何解决？

Traceback (most recent call last):
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connectionpool.py", line 464, in _make_request
    self._validate_conn(conn)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connectionpool.py", line 1093, in _validate_conn
    conn.connect()
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connection.py", line 790, in connect
    sock_and_verified = _ssl_wrap_socket_and_match_hostname(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connection.py", line 969, in _ssl_wrap_socket_and_match_hostname
    ssl_sock = ssl_wrap_socket(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\util\ssl_.py", line 480, in ssl_wrap_socket
    ssl_sock = _ssl_wrap_socket_impl(sock, context, tls_in_tls, server_hostname)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\util\ssl_.py", line 524, in _ssl_wrap_socket_impl
    return ssl_context.wrap_socket(sock, server_hostname=server_hostname)
  File "D:\Users\q4444\AppData\Local\Programs\Python\Python310\lib\ssl.py", line 512, in wrap_socket
    return self.sslsocket_class._create(
  File "D:\Users\q4444\AppData\Local\Programs\Python\Python310\lib\ssl.py", line 1070, in _create
    self.do_handshake()
  File "D:\Users\q4444\AppData\Local\Programs\Python\Python310\lib\ssl.py", line 1341, in do_handshake
    self._sslobj.do_handshake()
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)
 
During handling of the above exception, another exception occurred:
 
Traceback (most recent call last):
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connectionpool.py", line 787, in urlopen
    response = self._make_request(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connectionpool.py", line 488, in _make_request
    raise new_e
urllib3.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)
 
The above exception was the direct cause of the following exception:
 
Traceback (most recent call last):
  File "E:\AI_PYTORCH\.venv\lib\site-packages\requests\adapters.py", line 667, in send
    resp = conn.urlopen(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\connectionpool.py", line 841, in urlopen
    retries = retries.increment(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\urllib3\util\retry.py", line 519, in increment
    raise MaxRetryError(_pool, url, reason) from reason  # type: ignore[arg-type]
urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded with url: /Qwen/Qwen2.5-VL-7B-Instruct/resolve/main/config.json (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)')))
 
During handling of the above exception, another exception occurred:
 
Traceback (most recent call last):
  File "E:\AI_PYTORCH\Qwen2.5-VL\web_demo_mm.py", line 297, in <module>
    main()
  File "E:\AI_PYTORCH\Qwen2.5-VL\web_demo_mm.py", line 292, in main
    model, processor = _load_model_processor(args)
  File "E:\AI_PYTORCH\Qwen2.5-VL\web_demo_mm.py", line 61, in _load_model_processor
    model = Qwen2_5_VLForConditionalGeneration.from_pretrained(args.checkpoint_path, device_map=device_map)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\transformers\modeling_utils.py", line 311, in _wrapper
    return func(*args, **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\transformers\modeling_utils.py", line 4521, in from_pretrained
    resolved_config_file = cached_file(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\transformers\utils\hub.py", line 312, in cached_file
    file = cached_files(path_or_repo_id=path_or_repo_id, filenames=[filename], **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\transformers\utils\hub.py", line 557, in cached_files
    raise e
  File "E:\AI_PYTORCH\.venv\lib\site-packages\transformers\utils\hub.py", line 470, in cached_files
    hf_hub_download(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\utils\_validators.py", line 114, in _inner_fn
    return fn(*args, **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\file_download.py", line 1008, in hf_hub_download
    return _hf_hub_download_to_cache_dir(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\file_download.py", line 1071, in _hf_hub_download_to_cache_dir
    (url_to_download, etag, commit_hash, expected_size, xet_file_data, head_call_error) = _get_metadata_or_catch_error(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\file_download.py", line 1533, in _get_metadata_or_catch_error
    metadata = get_hf_file_metadata(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\utils\_validators.py", line 114, in _inner_fn
    return fn(*args, **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\file_download.py", line 1450, in get_hf_file_metadata
    r = _request_wrapper(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\file_download.py", line 286, in _request_wrapper
    response = _request_wrapper(
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\file_download.py", line 309, in _request_wrapper
    response = http_backoff(method=method, url=url, **params, retry_on_exceptions=(), retry_on_status_codes=(429,))
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\utils\_http.py", line 310, in http_backoff
    response = session.request(method=method, url=url, **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\requests\sessions.py", line 589, in request
    resp = self.send(prep, **send_kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\requests\sessions.py", line 703, in send
    r = adapter.send(request, **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\huggingface_hub\utils\_http.py", line 96, in send
    return super().send(request, *args, **kwargs)
  File "E:\AI_PYTORCH\.venv\lib\site-packages\requests\adapters.py", line 698, in send
    raise SSLError(e, request=request)
requests.exceptions.SSLError: (MaxRetryError("HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded with url: /Qwen/Qwen2.5-VL-7B-Instruct/resolve/main/config.json (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:997)')))"), '(Request ID: d01c06d4-7f9c-4ff3-8e3a-6c6635a6a8f1)')

全文目录：

📣 请知悉：如下方案不保证一定适配你的问题！

如下是针对上述问题进行专业角度剖析答疑，不喜勿喷，仅供参考：

✅️问题理解

你本地运行：

python web_demo_mm.py --checkpoint-path "Qwen/Qwen2.5-VL-7B-Instruct"

脚本内部调用：

Qwen2_5_VLForConditionalGeneration.from_pretrained(args.checkpoint_path)

这会触发 Hugging Face Hub 去下载模型文件（至少先拉 config.json）：

https://huggingface.co/Qwen/Qwen2.5-VL-7B-Instruct/resolve/main/config.json

但你的环境在发 HTTPS 请求时，在 TLS 握手阶段就失败了：

ssl.SSLCertVerificationError: certificate verify failed: unable to get local issuer certificate

也就是：Python/requests/urllib3 无法找到系统或 Python 自带的根证书链，导致无法验证 huggingface.co 的证书。
这在 Windows 上很常见，典型触发原因包括：

电脑/公司网络装了HTTPS 抓包代理（企业杀软、网关、Charles/Fiddler），会替换证书链，而你的 Python 不信任它
Python 虚拟环境里证书包（certifi）异常/过旧/被替换
环境变量设置了 HTTPS_PROXY/REQUESTS_CA_BUNDLE/CURL_CA_BUNDLE 指向不存在或错误证书
系统证书库异常（少见，但也有）
使用 HuggingFace 镜像/代理时证书链不完整

✅ 重点：这不是 Qwen 模型本身的问题，是下载模型时的 HTTPS 证书校验链问题。

✅️问题解决方案

我给你 3 套真实可行方案，从推荐到临时绕过都有。每套都有“怎么做 + 验证方法”。

🟢方案 A：修复证书链（最推荐，长期稳定）

目标：让 requests/urllib3 能正确找到可信 CA 根证书。

A1）升级/重装 certifi（最常见有效）
在你当前虚拟环境 E:\AI_PYTORCH\.venv 激活后执行：

python -m pip install -U certifi requests urllib3 huggingface_hub

然后验证 Python 能正确拿到 CA 路径：

python -c "import certifi; print(certifi.where())"

再做一次最小 HTTPS 测试：

python -c "import requests; print(requests.get('https://huggingface.co', timeout=10).status_code)"

✅ 如果返回 200 或 302，说明证书链好了。

A2）显式指定 CA 证书文件（适合企业代理/抓包环境）
如果你在公司网络或机器装了抓包代理（Fiddler/Charles/企业网关），通常需要把公司根证书导出为 .pem/.crt，然后告诉 requests 用它。

1）先检查你是否走代理（非常关键）：

python -c "import os; print('HTTPS_PROXY=', os.getenv('HTTPS_PROXY')); print('HTTP_PROXY=', os.getenv('HTTP_PROXY')); print('REQUESTS_CA_BUNDLE=', os.getenv('REQUESTS_CA_BUNDLE'))"

2）如果有代理/企业证书：把公司证书导出为 corp.pem（或让 IT 给），然后：

临时对当前终端生效：

$env:REQUESTS_CA_BUNDLE="C:\path\corp.pem"
$env:SSL_CERT_FILE="C:\path\corp.pem"

再测试：

python -c "import requests; print(requests.get('https://huggingface.co', timeout=10).status_code)"

✅ 这在“公司 HTTPS 中间人”场景下是最正确做法。

A3）把系统证书同步到 Python（补救型）
有时 Windows 系统证书是好的，但 Python 环境没用上（尤其某些发行版/被精简环境）。可以做：

python -m pip install -U pip
python -m pip install -U python-certifi-win32

然后重开终端再试 requests.get('https://huggingface.co')。

python-certifi-win32 会把 Windows 证书库合并到 certifi 使用路径里，对部分环境很有效。

🟣方案 B：完全离线加载模型（绕开 HTTPS 下载，最稳的“本地部署”方式）

你现在的 --checkpoint-path "Qwen/Qwen2.5-VL-7B-Instruct" 是“仓库名”，会必然联网拉文件。
如果你想“本地部署”，正确姿势是：提前把模型下载到本地文件夹，然后 --checkpoint-path 指向本地目录。

B1）在能联网的环境下载模型到本地（推荐用 huggingface-cli）：

pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct --local-dir E:\models\Qwen2.5-VL-7B-Instruct --local-dir-use-symlinks False

然后运行：

python web_demo_mm.py --checkpoint-path "E:\models\Qwen2.5-VL-7B-Instruct"

并建议强制离线模式（避免脚本再去联网确认）：

$env:HF_HUB_OFFLINE="1"
$env:TRANSFORMERS_OFFLINE="1"
python web_demo_mm.py --checkpoint-path "E:\models\Qwen2.5-VL-7B-Instruct"

✅ 这样就算你的网络 SSL 有问题，也不影响部署。

注意：--local-dir-use-symlinks False 在 Windows 上很重要，避免符号链接导致的一堆权限/路径问题。

B2）用镜像源/国内镜像（适合你网络访问 huggingface 困难）
如果你在国内网络直连 huggingface 不稳定，除了证书问题还可能经常超时。你可以设置 HF 镜像（若你有可用镜像域名）。
但⚠️不同镜像可靠性不一，我更推荐 B1 的“找一台网络正常的机器下载→拷贝模型目录→离线跑”。

🟡方案 C：临时跳过证书校验（能跑但不安全，不建议长期用）

如果你只是想“立刻跑起来验证”，可以临时禁用 SSL 校验。但我必须强调：这是不安全的，可能遭遇中间人攻击，只建议临时测试/内网隔离环境使用。⚠️

你可以在运行前设置环境变量（对 requests/hf hub 有时有效，有时不完全）：

$env:HF_HUB_DISABLE_SSL_VERIFICATION="1"
python web_demo_mm.py --checkpoint-path "Qwen/Qwen2.5-VL-7B-Instruct"

如果仍不行，那说明底层 requests 仍强校验，建议回到方案 A 或 B。

✅️问题延伸

1）为什么报错出在 `config.json`？

HF 下载流程是：先拉 config.json 判断模型结构、版本、需要哪些文件 → 再拉权重（safetensors/bin）、tokenizer、processor 等。
所以连 config 都拉不下来，说明问题发生在最外层：HTTPS 证书握手阶段。

2）这类问题如何快速定位属于哪一类？

你可以用下面这套“定位四问”快速判断根因：

✅ Q1：浏览器能打开 huggingface.co 吗？
- 能：网络通，但 Python 证书链可能坏/代理证书不信任
- 不能：网络/代理/DNS/防火墙问题
✅ Q2：终端里有没有 HTTPS_PROXY？
- 有：高概率公司代理/抓包，需导入公司根证书（方案 A2）
✅ Q3：python -c "import certifi; print(certifi.where())" 输出路径存在吗？
- 不存在/空：certifi 环境损坏（方案 A1）
✅ Q4：是否 WSL/Linux 里正常？
- WSL 正常：Windows 证书链/代理链问题更确定