---

为何选择此工具？

并行下载

通过每个文件多连接和并发文件下载，最大化您的带宽：

• 每个文件最多 16 个并行连接（分块下载）
• 最多 8 个文件同时下载
• 中断后自动恢复

实时显示每个文件的状态、速度和预计完成时间。

交互式 GGUF 选择器

无需猜测该下载哪种量化。使用 -i 参数启用带有质量评分和显存估算的交互式选择器：

hfdownloader analyze -i TheBloke/Mistral-7B-Instruct-v0.2-GGUF

交互模式功能：

• 键盘导航：使用 ↑↓ 键浏览，空格键切换选择
• 质量评分：星级（★★★★☆）显示相对质量
• 显存估算：了解是否适合您的显存
• “推荐”徽章：我们突出显示最佳平衡选项 (Q4_K_M)
• 实时总计：选择时查看总大小
• 一键下载：按 Enter 键开始，或输入 c 复制命令

不使用 -i 时，输出为文本或 JSON 格式，非常适合脚本和与其他工具的管道操作。

Python 直接可用

下载的模型会保存到标准的 HuggingFace 缓存目录中。Python 库可以自动找到它们：

from transformers import AutoModel
model = AutoModel.from_pretrained("TheBloke/Mistral-7B-Instruct-v0.2-GGUF")  # 直接可用

此外，您还可以在 ~/.cache/huggingface/models/ 中找到人类可读的路径，方便浏览。

适用于企业防火墙后

全面支持代理，包括 SOCKS5、身份验证 和 CIDR 绕过规则：

hfdownloader download meta-llama/Llama-2-7b --proxy socks5://localhost:1080

---

快速开始

先试用一下——无需安装：

# 使用交互式 GGUF 选择器分析模型
bash <(curl -sSL https://g.bodaay.io/hfd) analyze -i TheBloke/Mistral-7B-Instruct-v0.2-GGUF

# 下载模型
bash <(curl -sSL https://g.bodaay.io/hfd) download TheBloke/Mistral-7B-Instruct-v0.2-GGUF

# 启动 Web UI
bash <(curl -sSL https://g.bodaay.io/hfd) serve

# 带认证的 Web UI
bash <(curl -sSL https://g.bodaay.io/hfd) serve --auth-user admin --auth-pass secret

喜欢吗？永久安装：

bash <(curl -sSL https://g.bodaay.io/hfd) install

现在可以直接使用：

hfdownloader analyze -i TheBloke/Mistral-7B-Instruct-v0.2-GGUF
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m
hfdownloader serve
hfdownloader serve --auth-user admin --auth-pass secret   # 带认证

文件会保存到 ~/.cache/huggingface/ 目录下——Python 库可以自动找到它们。

---

智能分析器

不确定仓库里有什么内容？先进行分析：

hfdownloader analyze <任意仓库>

对于 GGUF 模型，您将获得一个交互式选择器（见上方截图）。对于其他类型，分析器会自动检测并显示相关信息：

类型	显示内容
GGUF	带质量评分、显存估算和多选功能的交互式选择器
Transformers	架构、参数量、上下文长度、词汇表大小
Diffusers	流水线类型、组件、变体（fp16、bf16）
LoRA	基础模型、秩、alpha、目标模块
GPTQ/AWQ	位数、分组大小、估计显存
数据集	格式、配置、拆分、大小

多分支支持

有些仓库有多个分支（fp16、onnx、flax）。分析器允许您选择：

hfdownloader analyze -i CompVis/stable-diffusion-v1-4

Diffusers 组件选择器

对于 Stable Diffusion 模型，您可以精确选择所需的组件：

选择 unet、vae、text_encoder——跳过不需要的部分。命令会自动生成。

---

下载功能

内联过滤语法

无需额外标志即可下载特定文件：

# 只下载 Q4_K_M 量化
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m

# 下载多种量化
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m,q5_k_m

# 或者使用标志
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF -F q4_k_m -E ".md,fp16"

断点续传与校验

# 下载中断？再次运行即可自动续传
hfdownloader download owner/repo

# 严格校验
hfdownloader download owner/repo --verify sha256

# 预览将要下载的内容
hfdownloader download owner/repo --dry-run

高速模式

# 最大化并行度
hfdownloader download owner/repo -c 16 --max-active 8

标志	默认值	描述
-c, --connections	8	每个文件的连接数
--max-active	3	并发文件下载数量
-F, --filters		包含模式
-E, --exclude		排除模式
-b, --revision	main	分支、标签或提交

---

双层存储

我们为您的下载内容维护两种视图：

~/.cache/huggingface/
├── hub/                              # 第一层：HF 缓存（Python 兼容）
│   └── models--TheBloke--Mistral.../
│       └── snapshots/a1b2c3d4.../
│           └── model.gguf
│
└── models/                           # 第二层：人类可读
    └── TheBloke/
        └── Mistral-7B-GGUF/
            ├── model.gguf            → 指向 hub/... 的符号链接
            └── hfd.yaml              # 下载清单

第一层（hub/）：标准的 HuggingFace 缓存结构。Python 库可以自动处理。

第二层（models/）：人类可读的路径和符号链接。您可以像浏览普通文件夹一样查看下载内容。

Windows 注意：友好视图（第二层）需要使用符号链接，这通常需要管理员权限或启用 Windows 开发者模式。尽管如此，下载仍然会正常工作——文件会被存储在 HuggingFace 缓存中（第一层）——但不会创建人类可读的符号链接。

清单跟踪

每次下载都会生成 hfd.yaml 文件，以便您清楚地了解已下载的内容：

repo: TheBloke/Mistral-7B-Instruct-v0.2-GGUF
branch: main
commit: a1b2c3d4...
downloaded_at: 2024-01-15T10:30:00Z
command: hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF -F q4_k_m
files:
  - path: mistral-7b.Q4_K_M.gguf
    size: 4368438272

# 列出所有已下载的内容
hfdownloader list

# 获取特定下载的详细信息
hfdownloader info Mistral

---

Web 界面

现代化的网页界面，提供实时进度显示：

hfdownloader serve
# 打开 http://localhost:8080

缓存浏览器

浏览所有已下载的内容，支持统计、搜索和筛选功能：

各页面功能

页面	功能
分析	输入任意仓库，自动检测类型，查看文件及大小，选择 GGUF 量化格式
任务	实时 WebSocket 进度显示，支持暂停、恢复和取消操作，以及下载历史记录
缓存	浏览已下载的仓库，查看磁盘使用情况统计，支持搜索和筛选
镜像	配置目标位置，比较差异，执行推送和拉取同步
设置	令牌、连接、代理、验证模式等配置

服务器选项

hfdownloader serve \
  --port 3000 \
  --auth-user admin \
  --auth-pass secret \
  -t hf_xxxxx

---

镜像同步

在不同设备之间同步模型缓存——例如家庭、办公室、NAS 或 USB 驱动器。

# 添加镜像目标
hfdownloader mirror target add office /mnt/nas/hf-models
hfdownloader mirror target add usb /media/usb/hf-cache

# 比较本地与目标
hfdownloader mirror diff office

# 将本地缓存推送到目标
hfdownloader mirror push office

# 从目标拉取到本地
hfdownloader mirror pull office

# 仅同步特定仓库
hfdownloader mirror push office --filter "Llama,GGUF"

# 同步后验证完整性
hfdownloader mirror push office --verify

非常适合以下场景：

• 空气隔离环境：在家下载，同步到办公室
• 团队共享：中央 NAS 存储所有模型
• 备份：在外置驱动器上保留一份副本

---

代理支持

全面支持企业环境中的代理设置：

# HTTP 代理
hfdownloader download owner/repo --proxy http://proxy:8080

# SOCKS5（例如 SSH 隧道）
hfdownloader download owner/repo --proxy socks5://localhost:1080

# 带认证
hfdownloader download owner/repo \
  --proxy http://proxy:8080 \
  --proxy-user myuser \
  --proxy-pass mypassword

# 在下载前测试代理连通性
hfdownloader proxy test --proxy http://proxy:8080

支持的类型

类型	URL 格式
HTTP	http://host:port
HTTPS	https://host:port
SOCKS5	socks5://host:port
SOCKS5h	socks5h://host:port（远程 DNS）

配置文件

将代理设置保存在 ~/.config/hfdownloader.yaml 中：

proxy:
  url: http://proxy.corp.com:8080
  username: myuser
  password: mypassword
  no_proxy: localhost,.internal.com,10.0.0.0/8

---

安装

一键安装（推荐）

bash <(curl -sSL https://g.bodaay.io/hfd) install

就这么简单。适用于 Linux、macOS 和 WSL。

或者无需安装直接运行：

bash <(curl -sSL https://g.bodaay.io/hfd) download TheBloke/Mistral-7B-Instruct-v0.2-GGUF
bash <(curl -sSL https://g.bodaay.io/hfd) serve   # Web 界面

下载二进制文件

从 Releases 获取：

平台	架构	文件
Linux	x86_64	hfdownloader_linux_amd64_*
Linux	ARM64	hfdownloader_linux_arm64_*
macOS	Apple Silicon	hfdownloader_darwin_arm64_*
macOS	Intel	hfdownloader_darwin_amd64_*
Windows	x86_64	hfdownloader_windows_amd64_*.exe

从源码构建

git clone https://github.com/bodaay/HuggingFaceModelDownloader
cd HuggingFaceModelDownloader
go build -o hfdownloader ./cmd/hfdownloader

Docker

# 从 GitHub Container Registry 拉取镜像
docker pull ghcr.io/bodaay/huggingfacemodeldownloader:latest

# 或者本地构建
docker build -t hfdownloader .

# 运行（挂载本地 HF 缓存）
docker run --rm -v ~/.cache/huggingface:/home/hfdownloader/.cache/huggingface \
  ghcr.io/bodaay/huggingfacemodeldownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF

---

私有及受控模型

对于私有仓库或受控模型（如 Llama 等）：

# 通过环境变量设置令牌
export HF_TOKEN=hf_xxxxx
hfdownloader download meta-llama/Llama-2-7b

# 或者通过命令行参数
hfdownloader download meta-llama/Llama-2-7b -t hf_xxxxx

对于受控模型，您必须先在模型的 HuggingFace 页面上接受许可协议。

---

中国镜像

在中国境内使用 HuggingFace 镜像以加快下载速度：

hfdownloader download owner/repo --endpoint https://hf-mirror.com

或者在配置文件中设置：

endpoint: https://hf-mirror.com

---

CLI 参考

命令	描述
download	下载模型或数据集（默认命令）
analyze	下载前分析仓库
serve	启动带有 REST API 的 Web 服务器
list	列出所有已下载的仓库
info	显示已下载仓库的详细信息
rebuild	从 HF 缓存重新生成友好视图
mirror	在不同位置之间同步缓存
proxy	测试并显示代理配置
config	管理配置
version	显示版本信息

完整文档：docs/CLI.md • docs/API.md • docs/V3_FEATURES.md

---

v3.0 新增功能

功能	描述
HF 缓存兼容性	下载现在使用标准的 HuggingFace 缓存结构
双层存储	兼容 Python 的缓存 + 人类可读的符号链接
智能分析器	自动检测模型类型、GGUF 质量评级、内存估算
Web UI v3	现代化界面，支持实时 WebSocket 进度显示
镜像同步	在不同位置之间推送/拉取缓存
完整代理支持	HTTP、SOCKS5、认证、CIDR 绕过
清单跟踪	hfd.yaml 记录每次下载的内容、时间及方式

从 v2.x 升级

v3.0 默认使用 HF 缓存。若需保留 v2.x 行为：

hfdownloader download owner/repo --legacy -o ./my-models

---

环境变量

变量	用途
HF_TOKEN	HuggingFace 访问令牌
HF_HOME	覆盖 ~/.cache/huggingface
HTTP_PROXY	HTTP 请求代理
HTTPS_PROXY	HTTPS 请求代理
NO_PROXY	逗号分隔的绕过列表

---

许可证

Apache 2.0 — 可在个人和商业项目中自由使用。

---

HuggingFaceModelDownloader 快速上手指南

HuggingFaceModelDownloader 是一款基于 Go 语言开发的高效工具，专为加速从 HuggingFace Hub 下载模型而设计。它支持多线程并行下载、智能 GGUF 量化模型选择、断点续传以及完整的代理支持，完美适配国内网络环境和企业防火墙。

环境准备

• 操作系统：Linux、macOS、Windows (WSL 推荐) 或任何支持 Docker 的环境。
• 架构支持：x86_64 (AMD/Intel) 及 ARM64 (Apple Silicon/Raspberry Pi)。
• 前置依赖：
  • 无需安装 Go 环境：直接使用预编译二进制文件或一键安装脚本。
  • 网络要求：若能直接访问 HuggingFace 则无需额外配置；若受限，需准备 HTTP/SOCKS5 代理地址（见“基本使用”中的代理部分）。
  • 权限注意：在 Windows 上使用“人类可读路径”功能需要管理员权限或开启开发者模式以支持符号链接。

安装步骤

推荐使用官方提供的一键安装脚本，自动检测系统架构并配置环境变量。

方法一：一键安装（推荐）

在终端执行以下命令：

bash <(curl -sSL https://g.bodaay.io/hfd) install

安装完成后，可直接在任意目录使用 hfdownloader 命令。

方法二：免安装运行

如果不希望永久安装，可直接通过管道运行单次命令：

# 直接运行下载命令
bash <(curl -sSL https://g.bodaay.io/hfd) download <模型仓库名>

# 直接启动 Web UI
bash <(curl -sSL https://g.bodaay.io/hfd) serve

方法三：Docker 运行

适合容器化环境，直接挂载本地缓存目录：

docker run --rm -v ~/.cache/huggingface:/home/hfdownloader/.cache/huggingface \
  ghcr.io/bodaay/huggingfacemodeldownloader download <模型仓库名>

基本使用

1. 智能分析与交互式下载 (GGUF 模型首选)

对于量化模型（如 GGUF），工具提供交互式界面，可根据显存大小推荐最佳量化版本。

启动交互模式：

hfdownloader analyze -i TheBloke/Mistral-7B-Instruct-v0.2-GGUF

• 操作方式：使用 ↑ ↓ 浏览，空格 勾选，Enter 确认下载。
• 功能：显示质量评级、预估显存占用，并自动标记推荐版本（如 Q4_K_M）。

2. 快速下载指定模型

下载整个仓库：

hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF

下载特定量化版本（使用内联过滤器）：

# 仅下载 Q4_K_M 版本
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m

# 下载多个特定版本
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m,q5_k_m

下载后验证： 文件默认保存至 ~/.cache/huggingface/，Python (transformers, llama-cpp-python 等) 可直接识别并加载，无需额外配置路径。

3. 国内网络加速与代理支持

针对无法直连 HuggingFace 的情况，工具内置完整的代理支持。

使用 HTTP 代理：

hfdownloader download meta-llama/Llama-2-7b --proxy http://127.0.0.1:7890

使用 SOCKS5 代理（如 Clash/V2Ray）：

hfdownloader download meta-llama/Llama-2-7b --proxy socks5://127.0.0.1:7891

带认证的代理：

hfdownloader download owner/repo --proxy http://user:pass@proxy-ip:port

提示：也可将代理配置写入 ~/.config/hfdownloader.yaml 以避免每次输入。

4. 启动 Web 管理界面

提供可视化的下载管理、缓存浏览和进度监控。

# 启动服务，默认端口 8080
hfdownloader serve

# 带身份验证启动
hfdownloader serve --auth-user admin --auth-pass secret

启动后访问 http://localhost:8080 即可在浏览器中管理下载任务。

5. 私有模型下载

对于 Llama 等受控模型或私有仓库，需传入 Token：

# 方式 A：环境变量
export HF_TOKEN=hf_xxxxx
hfdownloader download meta-llama/Llama-2-7b

# 方式 B：命令行参数
hfdownloader download meta-llama/Llama-2-7b -t hf_xxxxx