# Related Code
main.py:main()       - 应用启动函数
src/ui.py:MainWindow - GUI 主窗口类
Makefile             - 开发命令

快速开始

安装方式

方式一：下载预编译包（推荐）

从 GitHub Releases 下载：

平台	文件
macOS (Apple Silicon)	hf-model-downloader-arm64.dmg
macOS (Intel)	hf-model-downloader-x86_64.dmg
Windows	hf-model-downloader.exe

方式二：Homebrew（macOS）

brew install --cask samzong/tap/hf-model-downloader

方式三：从源码运行

# 克隆仓库
git clone https://github.com/samzong/hf-model-downloader.git
cd hf-model-downloader

# 安装依赖（推荐使用 uv）
uv sync

# 运行
uv run main.py

基本使用

1. 选择平台

启动后，顶部有两个平台按钮：

• HuggingFace：国际主流模型平台
• ModelScope：国内阿里云魔搭社区

2. 配置下载

字段	说明	示例
类型	Model 或 Dataset	Model
仓库 ID	组织/模型名 格式	meta-llama/Llama-2-7b
保存路径	本地目录	~/models
Token	可选，私有仓库需要	hf_xxxxx
Endpoint	可选，自定义镜像地址	https://hf-mirror.com

3. 开始下载

点击「Download」按钮，进度会实时显示在日志区域。

使用镜像加速

HuggingFace 镜像

国内用户建议使用镜像站点加速下载：

1. 在 Endpoint 字段填入：https://hf-mirror.com
2. 或设置环境变量：HF_ENDPOINT=https://hf-mirror.com

ModelScope

ModelScope 本身就在国内，通常无需镜像。

获取 Token

HuggingFace Token

1. 访问 https://huggingface.co/settings/tokens
2. 创建新 Token（Read 权限即可）
3. 复制到应用的 Token 字段

ModelScope Token

1. 访问 https://modelscope.cn/my/myaccesstoken
2. 创建 Token
3. 复制到应用的 Token 字段

常见问题

Q: 下载中断后如何续传？

A: 直接重新下载，huggingface_hub 和 modelscope SDK 会自动检测已下载的文件并续传。

Q: 提示权限错误？

A: 该模型可能需要申请访问权限（如 Llama 系列）。请在平台网页上申请后再下载。

Q: macOS 提示「无法验证开发者」？

A: 右键点击应用，选择「打开」，然后在弹窗中确认。