pyVideoTrans

简体中文

English

简体中文

English

Appearance

Cannot find an appropriate cached snapshot folder错误？一篇文章彻底搞定huggingface下载难题 ​

作为一名AI开发者，当您满怀期待地写下 from_pretrained 时，最不想看到的可能就是一行鲜红的错误信息。而下面这个错误，相信很多使用 Hugging Face 的朋友都遇到过：

err[msg]=Cannot find an appropriate cached snapshot folder for the specified revision on the local disk and outgoing traffic has been disabled. To enable repo look-ups and downloads online, pass 'local_files_only=False' as input.

别担心，这通常不是一个大问题。但它往往是一个“连锁问题”的开始，尤其对于身处中国大陆的开发者。这篇文章将带您从源头彻底理解并解决这个错误，并提供针对中国区网络环境的最佳实践，让您和您的团队从此告别模型下载的烦恼。

第一步：解读并解决 local_files_only 错误 ​

这个错误信息其实非常直白，我们可以把它分解成两部分来理解：

  1. “Cannot find an appropriate cached snapshot folder... on the local disk”: 程序在你的电脑本地缓存目录中，没有找到它需要的模型文件。
  2. “and outgoing traffic has been disabled”: 同时，代码的设置（local_files_only=True）禁止了它联网去 Hugging Face Hub 下载这些文件。

通俗地说，就是“我要的东西本地没有，但你又不准我上网去拿，我只能报错了。”

如何解决？ ​

错误信息本身已经给出了答案：允许程序联网下载。

您只需要在加载模型或分词器（Tokenizer）的函数中，明确设置参数 local_files_only=False 即可。

错误代码示例:

python
from transformers import AutoModel

# 这种设置会禁止网络下载，如果本地没有缓存就会报错
model = AutoModel.from_pretrained("google-bert/bert-base-cased", local_files_only=True)

正确修复后的代码:

python
from transformers import AutoModel

# 设置为 False，允许程序在找不到本地缓存时，自动联网下载
model = AutoModel.from_pretrained("google-bert/bert-base-cased", local_files_only=False)

注意: 在很多新版本的 transformers 库中，local_files_only 的默认值已经是 False。如果您遇到此错误，说明您的代码或环境中明确地将其设置为了 True。

解决了这个问题，您可能会长舒一口气，重新运行代码。但很快，一个新的问题可能接踵而至——程序卡在 Downloading...，最后以 Connection Timeout (连接超时) 告终。

第二步：解决中国区的网络难题——超时与连接失败 ​

这是因为 Hugging Face 的服务器在国外，因众所周知的原因，从中国大陆无法直接访问。

幸运的是，我们有非常成熟且简单的解决方案。强烈推荐使用国内镜像源。

最佳解决方案：使用国内镜像 (hf-mirror.com) ​

社区驱动的镜像 hf-mirror.com 是目前最受推荐、最稳定可靠的 Hugging Face 镜像。您无需修改任何 Python 代码，只需设置一个环境变量即可。

huggingface_hub 库会自动识别这个名为 HF_ENDPOINT 的环境变量，并将所有下载请求指向这个国内镜像地址，从而实现高速、稳定的下载。

如何设置：

在运行您的 Python 程序之前，在您的终端中执行以下命令：

  • Linux / macOS 用户:

    bash
    export HF_ENDPOINT=https://hf-mirror.com

  • Windows (CMD) 用户:

    cmd
    set HF_ENDPOINT=https://hf-mirror.com

  • Windows (PowerShell) 用户:

    powershell
    $env:HF_ENDPOINT = "https://hf-mirror.com"

  • python代码中设置

    import os
os.environ['HF_ENDPOINT']='https://hf-mirror.com'

设置完毕后，您就可以正常运行之前的 Python 脚本了，下载速度将会有质的飞跃。

备选方案：设置网络代理 ​

如果您已经有一个稳定可靠的科学上网工具，也可以通过设置代理环境变量来解决问题。假设您的代理在本地 127.0.0.1，端口为 7890：

  • Linux / macOS:
    bash
    export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
  • Windows (CMD):
    cmd
    set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890

虽然此方法可行，但对于仅仅解决 Hugging Face 下载问题来说，使用镜像源（HF_ENDPOINT）是更推荐、更稳定、更专注的方案。

一站式解决方案 ​

下次再遇到 Cannot find an appropriate cached snapshot folder 错误，或任何 Hugging Face 下载相关的网络问题时，请遵循以下两个步骤，即可一劳永逸：

  1. 检查代码：确保在 from_pretrained 函数中没有错误地设置 local_files_only=True。如果需要联网，请移除该参数或将其设置为 local_files_only=False。

  2. 配置环境（中国区用户必做）：在终端或系统中设置环境变量 HF_ENDPOINT。

    bash
    export HF_ENDPOINT=https://hf-mirror.com