?#工作記錄

以下是針對 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 等框架，并遭遇類似問題，這些方法基本都適用。