下不动 Hugging Face：两个环境变量切到 ModelScope 与 Modelers

2026-08-09

本文所有事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中数字与命令均照抄仓库文档与源码。

LlamaFactory 装完之后第一个卡住很多人的环节，不是训练参数，是模型压根拉不下来。README 为这个场景准备的方案很直白：不改代码、不动 pip 源，改一个环境变量，把下载 Hub 从 Hugging Face 换成别的。

它给了两个变量，对应两个 Hub。这篇只讲这一件事——从环境变量到配置字段到 token 字段，一整条链路上有哪几处要同时改，以及改完之后如果还是不行，怎么判断问题根本不在下载源上。

两个变量，先把原文抄清楚

README 里这一节的标题字面写的是模型与数据集的下载来源切换——标题覆盖的是「模型」和「数据集」两类，不止模型权重一类。两个变量分别是：

USE_MODELSCOPE_HUB=1 —— 切到 ModelScope Hub
USE_OPENMIND_HUB=1 —— 切到 Modelers Hub

README 给这两条的触发条件写得很明确：Hugging Face 下载有问题时用 ModelScope 这条。

Linux / macOS 侧照抄：

export USE_MODELSCOPE_HUB=1

export USE_OPENMIND_HUB=1

Windows 侧写法不一样，README 在同一行的注释里给了对应写法，export 换成 set：

:: Windows 命令提示符
set USE_MODELSCOPE_HUB=1

:: Windows 命令提示符
set USE_OPENMIND_HUB=1

这个差别看着琐碎，但本站读者里 Windows 占多数，而 export 在 cmd 里是不认的命令。真正容易翻车的不是拼错，而是设变量的那个终端和跑训练的那个终端不是同一个——set 也好 export 也好，作用域都是当前会话。如果你在 A 窗口设了变量，转头在 B 窗口或者某个 IDE 内置终端里起训练，那条设置对它不生效。这一条属于命令行的通用常识，不是 LlamaFactory 的文档内容，但它是这类”我明明设了啊”的高频来源。

光设变量不够：`model_name_or_path` 也得跟着换

这是最容易漏的一步。README 在两个变量后面各跟了一句同样性质的要求：设完变量之后，把配置里的 model_name_or_path 填成对应 Hub 的 model ID。

README 给的两个示例分别是：

环境变量	对应 Hub	README 给的 model ID 示例
`USE_MODELSCOPE_HUB=1`	ModelScope	`LLM-Research/Meta-Llama-3-8B-Instruct`
`USE_OPENMIND_HUB=1`	Modelers	`TeleAI/TeleChat-7B-pt`

为什么必须换：model_name_or_path 在 src/llamafactory/hparams/model_args.py 里的默认值是 None，它是一个由你完整提供的标识串。环境变量决定”去哪个站点找”，这个字段决定”找哪个条目”。两处只改一处，等于换了个站点却还拿着旧站点的门牌号。

这两个 ID 的形状（组织/模型名）看着和 Hugging Face 上的写法很像，所以肉眼很难发现填错。判定动作很简单：把你配置里的 model_name_or_path 拿去你切换到的那个 Hub 上搜一遍，能对上就是对的，对不上就说明你还在用另一个站点的 ID。至于同一个模型在不同 Hub 上的 ID 是否一一对应，README 没有给映射表，我们也不推断，只能逐个去查。

第三层：三个 Hub token 字段

如果你要拉的条目需要鉴权，光有变量和 ID 还是不够。model_args.py 里有三个 token 字段，默认值都是 None：

字段	对应 Hub
`hf_hub_token`	Hugging Face
`ms_hub_token`	ModelScope
`om_hub_token`	Modelers（openMind）

三个字段和上面两个环境变量正好构成一组呼应：变量负责选站点，token 字段按站点分开存。这里要点明的是字段结构本身——它们是三个独立字段，不是一个通用 token，字段名与 Hub 是一一对应的。所以你切到 ModelScope 之后，还留着 hf_hub_token 那一栏有值、ms_hub_token 空着，从字段对应关系上看就是对不上号。至于这三个字段在代码里各自被谁读取、读取顺序如何，我们没有抽取过那部分实现，不做推断。

写这类值的时候有一条硬纪律：不要把明文 token 提交进 YAML 再推到仓库里。文中一律写成 <YOUR_API_KEY> 这种占位形式。密钥托管、走环境变量注入这类做法属于通用运维实践，不是 LlamaFactory 官方文档的内容，具体怎么做请结合你自己的环境评估。

一处必须知道的口径差：`trust_remote_code`

换源这件事绕不开一个相关字段。model_args.py 里 trust_remote_code 的源码默认值是 False；而 examples/ 下的示例 YAML——包括 train_lora/qwen3_lora_sft.yaml、inference/qwen3_lora_sft.yaml、merge_lora/qwen3_lora_sft.yaml——里都显式写了 trust_remote_code: true。

也就是说，同一个开关在两个层面上的取值不一致：代码层默认关，示例配置层显式打开。这是仓库里可以逐字核对的客观差异，说到这儿为止——哪个是”对的”、为什么不同步，我们没有依据，不做推断。

对切换下载源的人来说，这条的实际意义只有一句：你从示例 YAML 复制下来的那份配置，很可能已经带着 trust_remote_code: true 了，而你现在把模型来源换成了另一个站点。这个组合值不值得你保持原样，取决于你的具体场景和合规要求，我们不给”这样配就安全了”的结论。

数据集侧与评测侧的一点提醒

README 那一节的标题写的是”模型与数据集”，所以别默认它只跟权重文件有关。至于数据集侧具体是怎么走这两个变量的、哪些数据集路径会受影响，README 在这一节没有展开，我们也不替它补。

与之相关、且容易被误读成同一件事的，是 src/llamafactory/hparams/evaluation_args.py 里的 download_mode，它的默认值是 DownloadMode.REUSE_DATASET_IF_EXISTS，字面语义是若已存在则复用。这是评测那一路的参数，和 Hub 切换是两个层面的东西；两者之间会不会互相影响、切源后本地已有的副本会怎么处理，官方没给说明，我们不替它推断。真要确认，就去看你的缓存目录里实际落了什么——model_args.py 里的 cache_dir 默认是 None。

顺带把另一条常被混进来的提示摘清楚：README 在 Ascend NPU 的折叠块里确实另给了一条建议，让你在配置里设 double_quantization: false，并给了参考示例 examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml。这条讲的是量化参数——源码里 double_quantization 的默认值是 True，所以 NPU 场景需要显式关掉——它和下载源不是一回事，别把两件事的排查混在一起。

改完还是不行，怎么判断问题不在下载源

这是本文最该讲清楚的一段。下面这几种情况，说明你遇到的不是下载源的问题：

一、环境根本没装好。 README 用 > [!IMPORTANT] 强调了一句 Installation is mandatory.，而 Requirement 表里 python 一行写的是 Minimum 3.11、Recommend >=3.11。如果你的 Python 低于 3.11，那先解决版本，换多少个 Hub 都没用。从源码安装的四行原文是：

git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt

二、报错发生在模型已经加载之后。 如果日志里已经能看到模型结构、tokenizer、数据处理相关的信息，那说明下载这一步过去了，后面的错属于另一类问题，和 Hub 无关。

三、你要的其实是”完全不碰本地环境”。 README 自己列了三条免安装的试用路径：Colab（免费）、PAI-DSW（免费试用，https://gallery.pai-ml.com/#/preview/deepLearning/nlp/llama_factory）、AMD GPU Cloud（免费额度，在 AMD Developers Notebooks 仓库里）。另外还有官方 Docker 镜像这条路：

docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest

README 原文写明这个镜像基于 Ubuntu 22.04 (x86_64)、CUDA 12.4、Python 3.11、PyTorch 2.6.0、Flash-attn 2.7.4。

四、你搜到的”加速镜像站”来路不明。 README 里有一条声明值得原样转述：除了它自己列出的这些链接之外，其它所有网站都是未经授权的第三方网站，请谨慎使用。这条声明的用法是——当你搜到某个所谓的”官方镜像""在线版”时，先回 README 的链接列表比对一遍。我们不点名任何具体站点。

还有一个找错地方的坑：仓库名

搜下载问题的时候会遇到两种拼法。hiyouga/LlamaFactory 是这个仓库当前的真实路径，PyPI 包名是 llamafactory，命令行是 llamafactory-cli；但仓库内部字符串并不统一——src/llamafactory/launcher.py 的欢迎语里写的项目主页仍是带连字符的旧名 https://github.com/hiyouga/LLaMA-Factory，README 正文里也混用两种写法。

如实说到这儿就够了，改名时间、原因、有没有重定向我们都没核实过。对你的影响只有一条：翻 issue 找同类下载问题时，两种拼法都搜一遍。

一句话收口

这条链路上一共三处要对齐：环境变量（选站点）、model_name_or_path（选条目）、对应的 token 字段（过鉴权）。三处只改一处最常见，也最难自查，因为报错通常只会告诉你”找不到”。关于 model_name_or_path 之外的其它模型加载参数、以及 trust_remote_code 这条口径差的完整背景，我们另有专门篇目讲。

本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。安全相关做法请结合自身环境评估，本文不构成安全方案建议。