# ms-hf-download-project

**Repository Path**: aylerh/ms-hf-download-project

## Basic Information

- **Project Name**: ms-hf-download-project
- **Description**: modelscope(ms)或huggingface(hf)的模型或数据集下载平台
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 ModelScope & HuggingFace 下载加速平台

一个功能强大的模型/数据集下载管理平台，支持 ModelScope（魔搭）和 HuggingFace，提供断点续传、镜像加速、自动重试和直观的 Web 管理界面。

## ✨ 核心特性

- **多平台支持**：同时支持 ModelScope 和 HuggingFace 平台资源下载。
- **高速下载**：
  - 自动使用 HF 镜像站（hf-mirror.com）加速。
  - 支持多并发下载。
- **智能重试**:
  - ModelScope 下载失败时，可自动切换到 HuggingFace 镜像源重试（可配置）。
  - 支持断点续传，随时暂停/恢复。
- **可视化管理**：
  - 现代化 Web 界面，实时监控下载进度、速度和状态。
  - 支持创建、暂停、删除任务。
  - 自动文件分类存储。
- **容器化部署**：
  - 基于 Docker，一键部署。
  - 预置清华源，构建快速。
- 兼容性：
  兼容vllm启动的魔搭目录；

## 页面样式
![1](images/1.png)

## 🛠️ 快速开始

### 1. 启动服务

在项目根目录下，使用 PowerShell 或终端运行：

```powershell
docker compose down; docker compose up --build
```

### 2. 访问界面

服务启动后，打开浏览器访问：

http://localhost:8091

### 3. 使用方法

1.  **新建任务**：在首页选择平台（ModelScope/HuggingFace）、资源类型（模型/数据集），输入仓库 ID（如 `FunAudioLLM/Fun-CosyVoice3-0.5B-2512`）。
2.  **设置保存路径**：可点击“使用官方缓存”或“填入应用目录”按钮，快速切换到平台默认缓存目录或应用托管目录。
3.  **查看进度**：在下方列表实时查看下载进度、速度。
4.  **管理任务**：支持暂停、继续和删除任务。
5.  **文件位置**：应用托管目录默认挂载到项目根目录的 `models/` 文件夹；官方缓存目录则走 Docker volume 挂载。

## ⚙️ 配置说明

所有配置均可在 `.env` 文件中修改：

| 配置项 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `INNER_PORT` | 8091 | 容器内部端口 |
| `OUTER_PORT` | 8091 | 宿主机访问端口 |
| `MODELS_DIR` | /app/models | 容器内模型存储路径 |
| `MODELS_VOLUME` | ./models | 宿主机挂载到 `/app/models` 的目录 |
| `MS_CACHE_DIR` | /root/.cache/modelscope | 容器内 ModelScope 缓存路径 |
| `MS_CACHE_VOLUME` | H:/docker-data/modelscope | 宿主机挂载到 ModelScope 缓存的路径 |
| `HF_HOME` | /root/.cache/huggingface | 容器内 HuggingFace 缓存路径 |
| `HF_CACHE_VOLUME` | H:/docker-data/huggingface | 宿主机挂载到 HuggingFace 缓存的路径 |
| `ENABLE_FALLBACK_TO_HF` | True | 开启后，MS 下载失败会自动尝试 HF |
| `MAX_CONCURRENT_DOWNLOADS`| 3 | 最大并发下载任务数 |
| `HF_TOKEN` | (空) | 下载 Llama 等需授权模型时填写 |

### Windows 与 Linux 挂载示例

Windows 默认：

```yaml
volumes:
  - "H:/docker-data/modelscope:/root/.cache/modelscope"
  - "H:/docker-data/huggingface:/root/.cache/huggingface"
```

Linux 示例：

```yaml
volumes:
  - ~/.cache/modelscope:/root/.cache/modelscope
  - ~/.cache/huggingface:/root/.cache/huggingface
```

如果在 Linux 上运行，启动前把 `.env` 中的 `MS_CACHE_VOLUME` 和 `HF_CACHE_VOLUME` 改成对应宿主机路径即可。

## 📂 目录结构

```
.
├── app/
│   ├── downloader/     # 下载核心逻辑（HF, MS, 管理器）
│   ├── static/         # 前端静态资源 (CSS, JS)
│   ├── templates/      # HTML 模板
│   ├── config.py       # 配置管理
│   ├── main.py         # FastAPI 入口
│   ├── models.py       # 数据模型
│   ├── routes.py       # API 路由
│   └── storage.py      # 任务持久化存储
├── data/               # 任务数据存储 (JSON)
├── models/             # 模型下载目录 (挂载卷)
├── Dockerfile          # 容器构建文件
├── docker-compose.yml  # 容器编排文件
├── requirements.txt    # Python 依赖
└── .env                # 环境变量配置
```

## 📝 注意事项

*   **模型路径兼容**：配置路径已针对 Windows 本地与 Linux 容器环境做了兼容处理。
*   **镜像源**：Dockerfile 中已预置清华镜像源，无需担心构建时的网络问题。
*   **HF Token**：如果是下载 HuggingFace 上的 Gated 模型（如 Llama 2），请在界面或 `.env` 中填写 Access Token。