企业官网建设流程全解析

TimesFM 模型权重下载失败（HfHubHTTPError）怎么排查？

【免费下载链接】timesfmTimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.项目地址: https://gitcode.com/GitHub_Trending/ti/timesfm

首次加载 TimesFM 模型（例如TimesFM_2p5_200M_torch）时，如果抛出HfHubHTTPError，说明模型权重从 Hugging Face Hub 的下载失败了。TimesFM 仓库本身不包含权重文件：权重（TimesFM 2.5 约 800 MB）在第一次使用时按需从 Hugging Face Hub 下载，并缓存在~/.cache/huggingface/（或环境变量$HF_HOME指定的目录）。

按项目文档的排查顺序，问题通常集中在三类原因：网络不通、缓存目录不可写或空间不足、缓存文件损坏。下面按照“先定位、再修复、后验证”的路径操作。

确认权重缓存位置与磁盘需求

修复前先确认两件事：缓存目录在哪里、这个目录有多少可用空间。

• 缓存目录默认是~/.cache/huggingface/，如果设置了HF_HOME环境变量，则以HF_HOME为准。
• 磁盘需求：TimesFM 2.5 的 safetensors 约 800 MB，加上 Hugging Face 缓存开销约 200 MB，总下载量约 1 GB（见 system_requirements.md 的 Disk Space 一节）。
• 加载入口 from_pretrained() 支持cache_dir参数指定自定义缓存目录，默认force_download=True会强制重新下载权重（即使已有缓存）。

第一步：运行预检脚本定位磁盘问题

项目提供了预检脚本 check_system.py，它会检查 RAM、GPU、磁盘空间、Python 版本和timesfm/torch是否已安装，其中磁盘检查专门针对模型下载：

python scripts/check_system.py --model v2.5

脚本会读取HF_HOME环境变量（未设置时默认~/.cache/huggingface/），检查该位置所在磁盘的可用空间。v2.5 模型要求至少 2 GB 磁盘空间。如果空间不足，Disk 检查会标记为 fail，并提示：

Free up space or set HF_HOME to a larger volume.

脚本在任一检查失败时以非零状态码退出，因此可以在脚本化流程中作为判断依据。Disk 检查 fail 基本可以确认下载失败的根因是空间不足或目录不可写；若 Disk 检查 pass 但下载仍然报错，再按下面的网络与缓存方向排查。

第二步：按原因执行修复

网络问题

api_reference.md 的错误处理表将HfHubHTTPError的成因标注为 "Download failed"，给出的修复项是：检查网络连接（Check internet）。确认机器能正常访问 Hugging Face Hub 后再重试加载。

缓存目录不可写或空间不足

将缓存目录指向一个可写、空间充足的磁盘（命令来自 system_requirements.md 的 "Model Download Fails" 一节）：

# /path/with/more/space 替换为本机一个可写且空间大于 1 GB 的实际目录 export HF_HOME=/path/with/more/space

设置后重新运行加载流程即可，权重会写入新的HF_HOME目录。

手动预下载权重

如果希望在加载模型前把权重准备好，文档给出的方式是手动下载（同样出自 system_requirements.md）：

huggingface-cli download google/timesfm-2.5-200m-pytorch

下载完成后，后续from_pretrained()调用即可命中本地缓存。

旧版文档补充：登录态与缓存损坏

v1 版本的排查文档 v1/TROUBLESHOOTING.md 针对 "Checkpoint download fails or is corrupted"（其记录的报错现象是HfFileNotFoundError: 404 Client Error，与HfHubHTTPError属于同一类 Hub 下载失败、但异常类型不同）给出了四项措施：

• 检查网络连接（Check internet connectivity）；
• 验证 Hugging Face Hub 访问权限：huggingface-cli login；
• 清除缓存后重试（注意副作用见下）；
• 必要时使用显式的 checkpoint 路径。

清除缓存的命令：

rm -rf ~/.cache/huggingface/

副作用说明：该命令会删除整个 Hugging Face 缓存目录，其中所有已缓存的模型（不只是 TimesFM）都会在下次使用时重新下载，请确认本机可以重新联网下载后再执行。此命令仅建议用于怀疑缓存文件损坏的场景。

第三步：验证修复结果

• 磁盘类问题：重新运行python scripts/check_system.py --model v2.5，确认 Disk 检查变为 pass（输出形如 "X GB available, exceeds 2 GB requirement"，具体数值随机器而异）。
• 手动下载：huggingface-cli download google/timesfm-2.5-200m-pytorch正常结束、无报错，说明权重已就绪。
• 模型加载：重新执行加载代码，按 api_reference.md 的说明，from_pretrained()成功时返回一个已初始化、尚未编译的模型实例：

import timesfm model = timesfm.TimesFM_2p5_200M_torch.from_pretrained( "google/timesfm-2.5-200m-pytorch", cache_dir=None, # Optional: custom cache directory force_download=True, # Re-download even if cached )

不再抛出HfHubHTTPError并能拿到模型实例，说明下载问题已解决。

边界与注意事项

• 权重只下载一次并缓存在本地；force_download默认为True，会强制重新下载，排查网络波动时可以留意这一点。
• 若报错不是HfHubHTTPError而是 404 类文件未找到，优先核对传入from_pretrained()的模型 ID（如google/timesfm-2.5-200m-pytorch）与revision参数是否为文档 Available Model Checkpoints 表中列出的有效值。
• 仓库中模型权重不随代码分发（SKILL.md 明确说明 weights 不在仓库内），因此“本地找不到权重文件”不是安装错误，属预期行为。

【免费下载链接】timesfmTimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.项目地址: https://gitcode.com/GitHub_Trending/ti/timesfm