Transformers 如何换镜像源

前言

年前在写《在前端实现 AI 推理》时，发现 HuggingFace 官方模型库存在国内访问困难的问题。虽然当时通过科学上网解决了模型下载，但最近在 Node.js 中使用 transformers.js 时发现代理配置失效（推测是 Node.js 的网络层限制，此前调用 Google Gemini API 时也遇到类似问题，最终改用 Python 实现接口）。这促使我开始寻找国内可用的镜像源方案。

主流镜像网站对比

1. HF-Mirror（推荐）

• 网址: hf-mirror.com
• 特点:
  1. 国内访问速度稳定的公益镜像站
  2. 完整支持模型/数据集下载、huggingface-cli 命令行工具和 hfd 下载器
  3. 提供清晰、简洁的使用文档和社区支持
• 适用场景: Python/Node.js 项目依赖、大模型持续集成

2. ModelScope（阿里巴巴）

• 网址: www.modelscope.cn
• 特点:
  1. 阿里达摩院维护的AI模型社区
  2. 提供在线 Notebook 和 GPU 运行环境
  3. 支持 git clone 和 git-lfs 原生操作
• 适用场景: 快速体验模型效果、国产特色模型获取

3. GitCode AI 社区

• 网址: ai.gitcode.com/models
• 特点:
  1. 基于 GitCode 平台的模型镜像
  2. 支持 git clone 和 git-lfs 原生操作
  3. 更新频率低于官方源、镜像也相对较少
• 适用场景: 小规模模型研究、Git 工作流兼容

镜像源使用指南

尽管 ModelScope 和 GitCode 都支持模型下载，但它们似乎并不直接支持作为 Hugging Face 的镜像源使用。所以我们只能依赖 HF-Mirror 作为镜像源进行模型下载。

Python 项目配置方案

方案一：临时环境变量（推荐）

# Linux/macOS
export HF_ENDPOINT=https://hf-mirror.com

# Windows PowerShell
$env:HF_ENDPOINT = "https://hf-mirror.com"

生效范围：当前终端会话

方案二：永久环境变量

# 写入Shell配置文件（~/.bashrc或~/.zshrc）
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc
source ~/.zshrc

适用于需要长期使用镜像源的开发环境

Node.js 项目配置方案

transformers.js 配置

在 Node.js 和浏览器环境中使用 transformers.js 时，不会自动读取 HF_ENDPOINT 环境变量，因此需要手动修改配置以指定正确的镜像源。

import { env } from '@huggingface/transformers';

// 必须在初始化前设置镜像源
env.remoteHost = 'https://hf-mirror.com';

完整示例

以下是一个 transformers.js 修改镜像源的使用示例

import { pipeline, env } from 'transformers.js';
env.remoteHost = 'https://hf-mirror.com';

(async function run() {
  const pipe = await pipeline('text-generation', 'Xenova/llama2.c-stories15M');
  const output = await pipe("Tell a joke", { max_new_tokens: 200 });
  console.log(output.map(x => x.generated_text).join('\n'));
})();

结语

通过合理选择镜像源方案，我们可以有效解决网络限制带来的 AI 模型资源获取问题。建议将环境变量配置写入项目文档的「快速开始」部分，以便团队协作时能够更方便地设置。对于企业级需求，可以考虑搭建私有镜像站，从而实现完全的自主管控和安全性保障。