MiniMax-AI/MiniMax-M1：MiniMax-M1，世界上第一個開放權重、大規模的混合注意力推理模型。

一、問題背景

?【筆記】解決部署國產AI Agent 開源項目 MiniMax-M1時 Hugging Face 模型下載緩存占滿 C 盤問題：更改緩存位置全流程-CSDN博客

在執行huggingface-cli download MiniMaxAI/MiniMax-M1-80k命令下載模型時，進度條顯示完成但最終報錯，終端輸出以下錯誤信息：

RuntimeError: Data processing error: CAS service error : Error : single flight error: Real call failed: ReqwestMiddlewareError(Middleware(Request failed after 5 retriesCaused by:0: error sending request for url (https://transfer.xethub.hf.co/...)1: client error (Connect)2: tls handshake eof))

核心問題是與 Hugging Face 的 Xethub 服務器通信時，TLS 握手中斷導致下載失敗。

二、錯誤原因分析

1. 網絡連接問題：
   • 網絡波動、丟包或防火墻攔截導致與transfer.xethub.hf.co服務器的 TLS 握手中斷。
   • 代理服務器配置錯誤或公司網絡限制訪問外部資源。
2. 服務器端臨時故障：
   • Xethub 服務器高負載或維護，無法完成文件傳輸。
3. DNS 解析異常：
   • 本地 DNS 緩存錯誤，無法正確解析服務器域名。

三、解決方案步驟

1. 檢查網絡連接

• 切換網絡環境：從當前網絡（如公司網）切換至家庭網絡或手機熱點，排除特定網絡限制。
• 驗證網站訪問：瀏覽器打開https://huggingface.co，確認 Hugging Face 服務可用。

2. 關閉代理與防火墻

• 臨時取消代理設置（Windows 命令行）：

  set HTTP_PROXY=
  set HTTPS_PROXY=
  

• 若使用公司 / 學校網絡，聯系管理員放行huggingface.co與xethub.hf.co域名。

3. 刷新 DNS 緩存

• 以管理員身份打開 CMD，執行：

  ipconfig /flushdns
  

4. 調整下載參數（關鍵）

• 降低并發線程并增加超時：

  bash

  # 設置環境變量（當前會話生效）
  set HF_HUB_ENABLE_HF_TRANSFER=0  # 關閉Xet傳輸協議
  set HF_HUB_DOWNLOAD_TIMEOUT=300  # 超時時間延長至300秒# 帶參數下載（可斷點續傳）
  huggingface-cli download MiniMaxAI/MiniMax-M1-80k --resume-download --thread-count 4
  

5. 手動下載與修復

• 步驟 1：訪問模型頁面
  打開https://huggingface.co/MiniMaxAI/MiniMax-M1-80k，逐個下載文件。
• 步驟 2：存儲至指定路徑
  將文件存至G:\huggingface_cache\models--MiniMaxAI--MiniMax-M1-80k\snapshots\[COMMIT_ID]（[COMMIT_ID]查看模型頁面哈希值）。
• 步驟 3：修復緩存索引

  huggingface-cli scan-cache --fix
  

6. 使用替代下載源

• 若模型提供第三方鏡像（如 GitHub、百度網盤），優先從鏡像下載后手動放置到緩存目錄。

四、下載恢復與驗證

• 斷點續傳：

  huggingface-cli download MiniMaxAI/MiniMax-M1-80k --resume-download

  

• 驗證緩存路徑：
  下載完成后，檢查G:\huggingface_cache目錄是否生成模型文件，確認 C 盤舊緩存未被占用。

?

?

五、總結與注意事項

1. 網絡穩定性是關鍵：大模型下載（2GB+）需確保網絡穩定，建議避開高峰時段。
2. 代理與防火墻配置：企業環境中提前與 IT 部門溝通，放行 Hugging Face 相關域名與端口。
3. 錯誤重試策略：單次下載失敗后，可等待 5-10 分鐘再試，避免短時間頻繁請求觸發服務器限制。
4. 離線部署方案：若需頻繁使用模型，可一次性下載所有文件至移動硬盤，后續通過環境變量指向離線路徑。

通過以上步驟，可有效解決因網絡問題導致的 Hugging Face 模型下載失敗，并確保緩存正確存儲至指定磁盤（如 G 盤），避免 C 盤空間爆滿。