#工作记录

以下是针对 TimeoutError: [WinError 10060] 的完整排查方案，适用于 FramePack项目中。

（一般该错误的发生原因请重点排查Hugging Face模型仓库受限需要登录的情形）

---

FramePack项目参考资料

FramePack部署（从PyCharm解释器创建和使用开始）保姆级教程-CSDN博客

接上篇，解决FramePack启动报错：“httpx.ReadError: [WinError 10054] 远程主机强迫关闭了一个现有的连接。“的问题_framepack 不能启动-CSDN博客

正常运行FramePack图生视频demo_gradio.py修改记录-CSDN博客

📌 错误描述

在使用 Python（尤其是 requests、urllib3 或 Hugging Face Hub）加载模型时，可能遇到如下错误：

TimeoutError: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。

最终通常表现为：

requests.exceptions.ConnectTimeout: HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded ...

---

🔍 发生原因

WinError 10060 是一个网络层面的连接超时错误，说明我们尝试访问的远程服务器（如 huggingface.co）在设定时间内未返回响应，可能是由于：

• 本地网络防火墙或杀毒软件拦截；

• 无法访问国外站点；

• 使用了错误或未开启的代理；

• Hugging Face 是 受限（gated）模型仓库，需要登录验证；

• DNS 配置错误或网络不可达。

---

✅ 解决方案汇总

✅ 1. 检查网络是否能访问 Hugging Face

先用浏览器访问模型页面，例如：

https://huggingface.co/lllyasviel/FramePackI2V_HY

或用命令行测试：

curl https://huggingface.co

如果能访问，则说明不是被阻挡；否则请继续下一步。

---

✅ 2. 配置代理

在 PowerShell 设置代理：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

我们需要将 127.0.0.1:7890 替换成自己科学上网软件（如XXXX）监听的 HTTP 代理端口。

---

✅ 3. 使用 Hugging Face Token 登录

部分模型是受限访问的，必须登录 Hugging Face 才能下载。

生成 Token：

前往 https://huggingface.co/settings/tokens 创建一个 read 权限的访问令牌。

登录 Hugging Face CLI：

huggingface-cli login

然后粘贴我们的 Token（输入不可见，按回车）。

然后输入Y（Yes）确认。

示例如下：

(.venv) PS F:\PythonProjects\FramePack> huggingface-cli login

    _|    _|  _|    _|    _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|_|_|_|    _|_|      _|_|_|  _|_|_|_|
    _|    _|  _|    _|  _|        _|          _|    _|_|    _|  _|            _|        _|    _|  _|        _|
    _|_|_|_|  _|    _|  _|  _|_|  _|  _|_|    _|    _|  _|  _|  _|  _|_|      _|_|_|    _|_|_|_|  _|        _|_|_|
    _|    _|  _|    _|  _|    _|  _|    _|    _|    _|    _|_|  _|    _|      _|        _|    _|  _|        _|
    _|    _|    _|_|      _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|        _|    _|    _|_|_|  _|_|_|_|

    To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Token can be pasted using 'Right-Click'.
Enter your token (input will not be visible):
Add token as git credential? (Y/n) Y
Token is valid (permission: fineGrained).
The token `stable_video_diffusion_img2vid.ipynb` has been saved to C:\Users\love\.cache\huggingface\stored_tokens
Your token has been saved in your configured git credential helpers (manager).
Your token has been saved to C:\Users\love\.cache\huggingface\token
Login successful.
The current active token is: `stable_video_diffusion_img2vid.ipynb`
(.venv) PS F:\PythonProjects\FramePack> 

 粘贴token：

 输入Y确认：

 成功之后我们会看到如下信息：

Your token has been saved to C:\Users\用户名\.cache\huggingface\token

完成后可以继续尝试访问模型：

可以看到已经没有以下报错信息了。

TimeoutError: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。 

---

✅ 4. 离线下载模型并本地加载（绕过联网）

在网络通畅机器上执行：

git lfs install
git clone https://huggingface.co/lllyasviel/FramePackI2V_HY

拷贝到我们的本地项目中后这样加载：

from diffusers_helper.models.hunyuan_video_packed import HunyuanVideoTransformer3DModelPackedtransformer = HunyuanVideoTransformer3DModelPacked.from_pretrained("./FramePackI2V_HY",torch_dtype=torch.bfloat16
).cpu()

---

✅ 5. 增加超时时间（备用方案）

如果是因为默认超时太短，可以手动设置较长超时时间，例如：

from huggingface_hub import hf_hub_downloadhf_hub_download(repo_id="lllyasviel/FramePackI2V_HY", timeout=60)

---

🧪 最佳实践：诊断代理是否生效

创建一个脚本测试我们的代理配置：

import requestsproxies = {"http": "http://127.0.0.1:7890","https": "http://127.0.0.1:7890",
}try:r = requests.get("https://huggingface.co", proxies=proxies, timeout=10)print("连接成功:", r.status_code)
except Exception as e:print("连接失败:", e)

---

✅ 总结

问题	解决方式
网络不可达	配置代理、检查 DNS
模型访问受限	登录 Hugging Face、申请模型访问权限
requests 超时	设置代理并延长 timeout
本地项目部署	使用离线加载方式加载模型

---

如果我们正在使用如 Gradio、Diffusers、Transformers 等框架，并遭遇类似问题，这些方法基本都适用。