Metadata-Version: 2.1
Name: modelhub-xc
Version: 4.0.0
Summary: ModelHub XC Community SDK - Python library for downloading models
Home-page: https://modelhub.org.cn
Author: ModelHub XC Team
Author-email: noreply@modelhub-xc.org.cn
License: Apache License 2.0
Keywords: modelhub-xc,model,download,xc,ai
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: requests >=2.25.0

# ModelHub-XC 模型下载 SDK

<div align="center">

**简单、快速、可靠的 AI 模型下载工具**

[![PyPI version](https://badge.fury.io/py/modelhub-xc.svg)](https://pypi.org/project/modelhub-xc/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)

[功能特点](#功能特点) •
[快速开始](#快速开始) •
[使用示例](#使用示例) •
[API 文档](#api-参考) •
[常见问题](#常见问题)

</div>

---

## ✨ 功能特点

- 🚀 **开箱即用** - 一条命令即可下载模型，无需复杂配置
- 📦 **智能下载** - 自动选择最佳下载方式，支持多源智能路由
- 💪 **大文件支持** - 创新的 HTTP 直接下载方案，稳定可靠
- 📊 **实时进度** - 精美的进度条显示，下载状态一目了然
- 🔧 **自动配置** - 首次使用自动初始化所需工具
- 🌐 **多源支持** - 无缝支持国内外主流模型仓库
- 🎯 **用户友好** - 清晰的错误提示和帮助信息



## 🚀 快速开始

### 安装

```bash
# 安装 SDK
pip install modelhub-xc

# 安装必需工具
brew install git-lfs git-xet  # macOS
# 或
sudo apt-get install git-lfs  # Linux
curl -sSf https://raw.githubusercontent.com/xetdata/xet-tools/main/scripts/install.sh | sh
```

### 使用

```bash
# 下载模型（就这么简单！）
modelhub-xc download --model mlx-community/Qwen3-8B-bf16 --local_dir ./models
```

## 📖 使用示例

### 命令行使用

#### 下载完整模型

```bash
# 下载到默认目录 (~/.cache/modelhub-xc/models/)
modelhub-xc download --model mlx-community/Qwen3-8B-bf16

# 下载到指定目录
modelhub-xc download --model mlx-community/Qwen3-8B-bf16 --local_dir ./my_models

# 指定分支
modelhub-xc download --model username/model-name --local_dir ./models --branch develop
```

#### 下载单个文件

```bash
# 下载特定文件
modelhub-xc download --model mlx-community/Qwen3-8B-bf16 README.md --local_dir ./docs
```

### Python SDK 使用

#### 下载完整模型

```python
from modelhub_xc import snapshot_download

# 简单下载
model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')
print(f"✓ 模型已下载到: {model_dir}")

# 指定目录
model_dir = snapshot_download(
    'mlx-community/Qwen3-8B-bf16',
    local_dir='./my_models'
)
```

#### 下载单个文件

```python
from modelhub_xc import download_file

# 下载配置文件
file_path = download_file(
    'mlx-community/Qwen3-8B-bf16',
    'config.json',
    local_dir='./configs'
)
print(f"✓ 文件已下载到: {file_path}")
```

#### 批量下载

```python
from modelhub_xc import snapshot_download

models = [
    'mlx-community/Qwen3-8B-bf16',
    'ZhipuAI/chatglm3-6b',
    'baichuan-inc/Baichuan2-7B-Chat'
]

for model_id in models:
    try:
        model_dir = snapshot_download(model_id)
        print(f"✓ {model_id} 下载成功")
    except Exception as e:
        print(f"✗ {model_id} 下载失败: {e}")
```

## 🔧 安装说明

### 1. 安装 SDK

```bash
pip install modelhub-xc
```

### 2. 安装依赖工具

SDK 需要以下工具来处理大文件下载：

#### Git LFS

```bash
# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt-get install git-lfs

# CentOS/RHEL
sudo yum install git-lfs

# Windows - 从官网下载
# https://git-lfs.github.com/
```

#### git-xet

```bash
# macOS
brew install git-xet

# Linux
curl -sSf https://raw.githubusercontent.com/xetdata/xet-tools/main/scripts/install.sh | sh

# Windows - 参考官方文档
# https://about.xethub.com/
```

**💡 提示：**
- SDK 会在首次使用时自动运行 `git lfs install` 和 `git xet install`
- 如果缺少工具，SDK 会显示详细的安装指南
- 安装完成后即可立即使用，无需额外配置

## 📚 API 参考

### `snapshot_download()`

下载完整的模型仓库。

**参数：**
- `model_id` (str): 模型ID，格式为 `username/model-name`
- `local_dir` (str, 可选): 本地保存目录
  - 默认: `~/.cache/modelhub-xc/models/{model_id}`
- `branch` (str, 可选): 分支名，默认 `'main'`
- `api_base_url` (str, 可选): API 地址，默认 `'https://modelhub.org.cn/api'`

**返回：**
- `str`: 模型的本地目录路径

**示例：**
```python
from modelhub_xc import snapshot_download

# 基础用法
model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')

# 完整参数
model_dir = snapshot_download(
    model_id='mlx-community/Qwen3-8B-bf16',
    local_dir='./models',
    branch='main'
)
```

### `download_file()`

下载模型仓库中的单个文件。

**参数：**
- `model_id` (str): 模型ID
- `filename` (str): 文件名或路径
- `local_dir` (str, 可选): 本地保存目录，默认为当前目录
- `branch` (str, 可选): 分支名，默认 `'main'`
- `api_base_url` (str, 可选): API 地址

**返回：**
- `str`: 文件的本地目录路径

**示例：**
```python
from modelhub_xc import download_file

# 下载 README
file_dir = download_file(
    'mlx-community/Qwen3-8B-bf16',
    'README.md',
    local_dir='./docs'
)

# 下载配置文件
config_dir = download_file(
    'mlx-community/Qwen3-8B-bf16',
    'config.json'
)
```

## 💡 技术亮点

### 🎯 创新的大文件下载方案

传统方案依赖 git-lfs/git-xet 的桥接服务，容易受网络环境影响。我们创新性地采用：

1. **跳过 LFS 克隆** - 使用 `GIT_LFS_SKIP_SMUDGE=1` 快速克隆仓库结构
2. **智能文件扫描** - 自动识别 LFS 大文件（通过 `.gitattributes` 和文件特征）
3. **HTTP 直接下载** - 绕过桥接服务，直接从镜像站下载
4. **实时进度显示** - 精确的下载进度和速度显示

**优势：**
- ✅ 更稳定 - 不依赖第三方桥接服务
- ✅ 更快速 - 减少重定向，直接下载
- ✅ 更友好 - 实时进度反馈

### 🌐 智能多源路由

SDK 会自动：
1. 查询模型元数据
2. 识别模型来源
3. 选择最佳下载方式
4. 使用对应的工具和配置

用户无需关心底层细节，一切都是自动的！

## ❓ 常见问题

### Q: 下载速度慢怎么办？

**A:** 模型文件通常较大（几GB到几十GB），下载速度取决于：
- 网络带宽
- 服务器负载
- 文件大小

建议使用稳定的网络环境。

### Q: 下载中断了怎么办？

**A:** 当前版本暂不支持断点续传，如果下载中断，需要重新开始。我们正在开发断点续传功能。

### Q: 提示缺少工具怎么办？

**A:** SDK 会显示详细的安装指南，按提示安装即可：

```bash
# 安装 Git LFS
brew install git-lfs  # macOS
sudo apt-get install git-lfs  # Linux

# 安装 git-xet
brew install git-xet  # macOS
curl -sSf https://raw.githubusercontent.com/xetdata/xet-tools/main/scripts/install.sh | sh  # Linux

# 验证安装
git lfs version
git xet --version
```

### Q: 如何查看可用的模型？

**A:** 访问 [https://modelhub.org.cn](https://modelhub.org.cn) 浏览完整的模型列表。

### Q: 支持哪些模型仓库？

**A:** 目前支持：
- ModelScope（国内，稳定快速）
- HuggingFace（国际，通过镜像访问）
- 更多源持续添加中...

### Q: 下载的模型保存在哪里？

**A:**
- 默认位置：`~/.cache/modelhub-xc/models/{model_id}`
- 可通过 `--local_dir` 参数自定义

## 🏗️ 项目结构

```
modelhub-xc/
├── modelhub_xc/
│   ├── __init__.py          # 包初始化
│   ├── api.py               # 公共 API 接口
│   ├── api_client.py        # API 客户端
│   ├── downloader.py        # 下载管理器
│   ├── git_cloner.py        # Git 克隆工具
│   ├── gitea_client.py      # Gitea 客户端
│   ├── config.py            # 配置管理
│   ├── cli.py               # 命令行工具
│   └── _sources.py          # 源配置（编译为二进制）
├── tests/                   # 测试文件
├── setup.py                 # 安装配置
├── publish.sh               # 发布脚本
├── build_secure.sh          # 安全构建脚本
└── README.md                # 本文档
```

## 🔨 开发指南

### 开发环境设置

```bash
# 克隆仓库
git clone https://github.com/your-org/modelhub-xc.git
cd modelhub-xc

# 安装开发依赖
pip install -e .
pip install wheel twine Cython

# 运行测试
python -m pytest tests/
```

### 构建和发布

```bash
# 使用自动化脚本（推荐）
./publish.sh

# 或手动构建
./build_secure.sh
twine upload dist/*
```

## 📦 技术栈

- **Python** 3.6+
- **requests** - HTTP 客户端
- **Cython** - 源码保护
- **Git LFS** - 大文件支持
- **git-xet** - 分布式存储

## 📄 许可证

[Apache License 2.0](LICENSE)

## 📮 联系方式

- **官网**: https://modelhub.org.cn
