bodaay/HuggingFaceModelDownloader

🤖 HuggingFace 模型下载器 (hfdownloader)

它是什么 – 一个快速、并行且支持代理的命令行工具（用 Go 编写），用于从 HuggingFace Hub 拉取模型、数据集、LoRA、Diffusers 流水线等。它将文件存储在标准 HF 缓存中，因此现有的 Python 库（transformers、diffusers、llama.cpp 绑定等）可以自动找到它们，同时通过符号链接/硬链接提供人类可读的视图。

为什么你可能关心 – 大型模型文件可能达到数十 GB。hfdownloader：

将每个文件拆分为最多 16 个并行连接，并且可以同时下载 8 个文件，大幅减少实际耗时。
中断后自动恢复，并使用 SHA-256 验证 LFS 文件。
提供交互式 GGUF 选择器，显示质量星级、RAM 估算和“推荐”量化，方便选择量化模型的正确版本。
在企业防火墙后工作，支持完整的 HTTP/SOCKS5 代理、身份验证和 CIDR 绕过规则。
提供 Web UI（实时进度、缓存浏览器、镜像同步、设置），适合喜欢图形界面的用户。
包含镜像同步功能，可将本地缓存推送到 NAS、USB 驱动器或其他机器，或从中拉取——适用于隔离或团队环境。

如何获取

一行安装（无需 sudo）：bash <(curl -sSL https://g.bodaay.io/hfd) install
适用于 Linux、macOS 和 Windows 的预构建二进制文件位于 GitHub Releases 页面。
使用 Go 1.25+ 从源码构建：go build -o hfdownloader ./cmd/hfdownloader
Docker 镜像 ghcr.io/bodaay/huggingfacemodeldownloader（挂载你的 ~/.cache/huggingface 以保留缓存）。

典型命令行工作流

# 查看仓库内容（交互式 GGUF 选择器）
hfdownloader analyze -i TheBloke/Mistral-7B-Instruct-v0.2-GGUF

# 下载特定量化（或多个）
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m
# 或使用最大并行度下载所有内容
hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF -c 16 --max-active 8

# 将已缓存文件导出为普通目录（用于 llama.cpp、Ollama 等）
hfdownloader export TheBloke/Mistral-7B-Instruct-v0.2-GGUF ~/models/mistral

# 启动 Web UI (http://localhost:8080)
hfdownloader serve

关键概念

存储模式 1 – HF 缓存（默认） – 文件位于 ~/.cache/huggingface/hub/...（内容寻址的 blob）以及 ~/.cache/huggingface/models/ 下的人类可读符号链接树。Python 工具开箱即用。
存储模式 2 – 平面目录 – 使用 --local-dir <path> 或旧版 -o <dir> 获取包含真实文件的普通 <owner>/<repo>/ 文件夹，适用于不理解 HF 缓存布局的工具。
清单（hfd.yaml） – 每次下载都会写入一个小的 YAML 文件，描述仓库、提交、所选文件、大小以及使用的确切命令。hfdownloader list 和 hfdownloader info 可查询此元数据。
代理配置 – 可以通过每个命令传递（--proxy ...）或存储在 ~/.config/hfdownloader.yaml 中。
镜像同步 – 定义命名目标（hfdownloader mirror target add office /mnt/nas/hf-models），然后 push、pull 或 diff 以保持缓存同步。

谁应该使用

定期拉取大型 GGUF、GPTQ 或 Diffusers 模型的研究人员或工程师。
需要强大代理处理的企业网络中的团队。
希望享受 HF 缓存便利而不处理符号链接问题的 Windows 或 macOS 用户。
喜欢使用 Web 仪表板监控下载和管理共享模型缓存的任何人。

许可证 – Apache 2.0（个人和商业使用免费）。

快速链接

bodaay/HuggingFaceModelDownloader

🤖 HuggingFace 模型下载器 (hfdownloader)

相关