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 盘空间爆满。