升级 huggingface_hub 后 cached_download 导入失败，先定位旧调用

升级依赖后，程序还没下载模型，就在导入阶段报：

cannot import name 'cached_download'

HELM 官方 issue #3779在 2025 年 7 月记录了同样的导入失败：报告者使用 Python 3.9 和 uv 虚拟环境运行 Stable Diffusion 评测。原报告没有给出 huggingface_hub 或 diffusers 的精确版本，不能补称它运行了 0.26.0。协作者建议迁移旧调用；临时回退建议也没有得到报告者的成功确认。

huggingface_hub 0.26.0 的发布记录明确删除了这个旧 API。账号权限、网络重试和模型缓存目录，不会让已经删除的 Python 导出符号重新出现。

先找到实际导入方

在发生错误的环境中记录：

python -c 'import sys,huggingface_hub; print(sys.executable); print(huggingface_hub.__version__); print(huggingface_hub.__file__)'
python -m pip check

从完整堆栈确认哪一个文件执行了 from huggingface_hub import cached_download。项目源码里可以搜索：

rg -n 'cached_download' src

src 换成自己的代码目录。若调用来自第三方包，核对该包版本及其支持的 hub 范围，优先升级到已经迁移的兼容版本。不要直接改 site-packages 中的一行导入，下一次重建会丢掉修改，也可能遗漏参数变化。

自己的 Hub 文件下载代码，要重写参数含义

旧函数接收的 URL，不能原样交给 hf_hub_download()。新调用应明确仓库、文件名、仓库类型和 revision；0.26.0 文件下载接口说明了这些字段。

下面是模型仓库的一份下载示例，需要网络、目标文件权限和磁盘空间：

import os
from huggingface_hub import hf_hub_download

path = hf_hub_download(
    repo_id=os.environ["MODEL_REPO_ID"],
    filename=os.environ["MODEL_FILE_NAME"],
    revision=os.environ["MODEL_REVISION"],
)
print(path)

使用已经核对的完整 commit 作为 MODEL_REVISION，避免在排查中混入另一份模型。私有或 gated 仓库沿用受保护的正常登录配置，不把 token 写在示例或日志中。

如果原调用下载的是任意第三方 URL，需要保留原任务的下载、完整性与缓存要求，选择适合那个地址的下载实现；不能把所有 URL 都解释成 Hub 仓库文件。

暂时锁旧版，只用于有边界的回退

依赖尚无兼容版本时，可以在独立环境评估 0.26.0 之前的组合，保留原锁文件与恢复入口。但“让导入成功”不是完整验收：其他依赖可能要求新版 hub，旧版本也可能失去后续修复。

因此不用一条全局降级命令覆盖所有项目，也不忽略 pip check 冲突。回退结果应进入项目依赖管理器，并安排旧调用迁移。

最终从锁文件重建一次干净环境：先导入原来报错的上层包，再下载一个已获准、固定 revision 的小文件，最后恢复实际加载入口。只单独导入 huggingface_hub，不会执行第三方包中那条残留调用。