【Gradio】Gradio 启动规避 Huggingface 代理问题

在国内访问 Huggingface 官方源，时常会因为网络问题导致模型下载速度慢甚至失败。为了解决这个问题，可以将 Huggingface 源切换到国内镜像，极大提升模型和数据集的下载速度。以下介绍三种常见的切换方式，并附常用国内镜像源和注意事项。

环境变量设置镜像源

设置 HF_ENDPOINT 环境变量后，Huggingface 的各类工具（如 transformers、datasets、diffusers 等）均会自动使用指定镜像。

Linux/macOS 下执行：

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

Windows 命令行执行：

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

也可以将该变量添加到系统环境变量中，实现全局生效。

from_pretrained 方法直接指定镜像

部分模型加载方法支持在代码中直接指定镜像，适合只对单次调用加速，无需全局配置。例如：

from transformers import AutoModel

model = AutoModel.from_pretrained(
    "bert-base-uncased", 
    mirror="hf-mirror.com"
)

该方式无需更改环境变量，代码中显式指定镜像即可。

修改 Huggingface 配置文件

Huggingface 会在本地生成配置文件（一般在 ~/.cache/huggingface/hub/config.json）。手动编辑该文件，添加或修改如下内容：

{
  "endpoint": "https://hf-mirror.com"
}

保存后，Huggingface 工具会自动读取新的 endpoint，从而走国内镜像源。

常用国内镜像源一览

镜像名称	地址
官方推荐镜像	https://hf-mirror.com
阿里云模型库	https://modelscope.cn
清华大学镜像	https://mirrors.tuna.tsinghua.edu.cn/huggingface

注意事项：

• 镜像和官方源同步存在延迟，部分新模型、新数据集可能尚未同步；
• 部分私有模型、授权模型无法通过镜像下载；
• 下载大模型建议配合 huggingface-cli 工具，避免因中断导致重复下载；
• 如遇到配置、环境变量无效等问题，可尝试清除本地缓存后重试。

额外技巧：避免代理干扰

部分环境下，如果设置了 HTTP 代理，可能影响镜像源访问。可在代码中临时取消代理设置：

import os
os.environ.pop('HTTP_PROXY', None)
os.environ.pop('HTTPS_PROXY', None)
os.environ['NO_PROXY'] = '127.0.0.1,localhost'

总结

切换 Huggingface 镜像源后，国内访问 Huggingface 生态会更加顺畅。无论是通过环境变量、配置文件，还是直接在代码里指定镜像，都能有效提升模型、数据集的下载速度和体验。遇到卡顿、下载失败等问题时，优先尝试切换国内镜像。

持续关注镜像源状态，结合自身需求灵活选择配置方式，可极大提升 Huggingface 的使用效率。