huggingface-cli

Hugging Face 提供了 huggingface-cli 工具用于下载Model，不仅可以下载原始权重，也可以下载各种量化版本。

我在 Docker compose组合运行Ollama 遇到一个问题: 由于 AMD Radeon Instinct MI50 硬件架构比较陈旧，需要使用早期版本的 ollama 容器镜像，这导致后端 llama.cpp 无法兼容目前主流的 LLaMa(Large Language Model Meta AI) 3.3官方提供的GUFF格式，所以需要自己下载原始HuggingFace(HF)格式文件，使用旧版 llama.cpp 工具链来转换成兼容GUFF格式。

准备工作

首先要在下载模型的页面，例如 meta-llama/Llama-3.3-70B-Instruct 同意其License
然后在 Hugging Face的Settings -> Access Tokens 创建一个Access Token，注意这个token可以选择 Read 或 Write 类型，也可以完全控制设置权限

安装

我使用 Python virtualenv 来构建一个Python环境:

构建一个Hugging Face的virtualenv

sudo apt install python3.12-venv

python3 -m venv ~/hugging_face/venv
. ~/hugging_face/venv/bin/activate

安装工具并登录

安装工具

pip install -U "huggingface_hub[cli]"

警告

Hugging Face在国内已经被GFW屏蔽，所以你必须越过长城，执行以下命令采用 SSH Tunneling: 动态端口转发构建起一个socks代理:

用一条命令构建一个socks代理

ssh -D 1080 -C user@vpn.example.com

由于 hf 底层是基于Python的 requests 和 urllib3 库开发，所以可以直接读取系统的 标准环境变量 来使用SOCKS5代理(需要先安装 httpx[socks] ):

设置hf使用代理

# 安装python socks代理模块
pip install httpx[socks]

# 假设 SOCKS5 代理在本地 1080 端口，设置 socks5h 可以让域名解析也交给远程代理服务器完成(更安全，避免DNS污染)
# export ALL_PROXY=socks5h://127.0.0.1:1080
export http_proxy="socks5://127.0.0.1:1080"
export https_proxy="socks5://127.0.0.1:1080"
# 如果下载过程中涉及 git clone 或 git lfs 指令，还需要单独为Git设置代理
git config --global http.proxy socks5h://127.0.0.1:1080

登录Hugging Face

hf auth login

使用

下载模型:

下载Qwen3.5-35B-A3B

hf download Qwen/Qwen3.5-35B-A3B --local-dir ./Qwen3.5-35B-A3B-HF

下载Llama-3.3-70B

hf download meta-llama/Llama-3.3-70B-Instruct --local-dir ./Llama-3.3-70B-HF

镜像网站

虽然通过socks代理能够越过长城从Hugging Face下载模型，但是对于身在大陆，实际上下载速度还是乏善可陈，太浪费精力了。国内的 HF-Mirror 提供了Hugging Face镜像，而且无需登录就可以使用 hf 工具直接下载，速度飞快。

唯一的区别就就是在执行 hf 下载命令之前先设置环境变量 HF_ENDPOINT :

使用HF-Mirror镜像网站

# 设置镜像网站下载，无需代理
export HF_ENDPOINT=https://hf-mirror.com