无法通过Unsloth与Hugging Face下载Llama 3.2 3B模型的排查求助

核心问题 #

1. 模型名称不匹配：开启4bit加载时，未使用Unsloth提供的带-bnb-4bit后缀的量化模型名，导致无法找到对应权重文件。
2. HF_TRANSFER下载不稳定：默认启用的hf_transfer在部分网络环境下易出现并行下载失败。
3. 本地缓存冲突：可能存在同名本地模型缓存，干扰远程模型加载。

解决步骤 #

1. 修正模型名称 #

开启load_in_4bit=True时，必须使用Unsloth预量化的4bit模型名称，修改代码中的model_name参数：

import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "0"  # 先禁用hf_transfer

from unsloth import FastLanguageModel
import torch

max_seq_length = 2048
dtype = None
load_in_4bit = True 

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/Llama-3.2-3B-Instruct-bnb-4bit",  # 加上-bnb-4bit后缀
    max_seq_length = max_seq_length,
    dtype = dtype,
    load_in_4bit = load_in_4bit,
    token = "hf_somethingprivate",
)

2. 禁用HF_TRANSFER提升下载稳定性 #

上述代码已通过环境变量禁用hf_transfer，也可在终端执行代码前先运行：

export HF_HUB_ENABLE_HF_TRANSFER=0

切换回传统下载方式，降低并行下载失败概率。

3. 清理本地冲突缓存 #

删除本地可能存在的同名模型缓存文件夹：

• Linux/macOS：删除~/.cache/huggingface/hub/models--unsloth--Llama-3.2-3B-Instruct
• Windows：删除C:\Users\<你的用户名>\.cache\huggingface\hub\models--unsloth--Llama-3.2-3B-Instruct
  删除后重新运行代码，确保加载远程最新模型文件。

4. 验证Token权限有效性 #

执行以下代码确认你的HF Token有权访问目标模型：

from huggingface_hub import HfApi
api = HfApi(token="hf_somethingprivate")
print(api.repo_exists("unsloth/Llama-3.2-3B-Instruct-bnb-4bit"))

返回True则权限正常；若返回False，需重新确认Hugging Face上的Llama模型访问申请是否通过，以及Token是否正确。

内容的提问来源于stack exchange，提问作者Worker1432