modelhub-xc 1.1.0

ModelHub XC Community SDK - Python library for downloading models

[# ModelHub - XC社区模型下载SDK

ModelHub是一个用于从XC社区下载模型的Python SDK工具。它提供了简单易用的命令行工具和Python API接口，帮助用户快速下载和管理AI模型。

功能特点

• 🚀 简单易用的命令行工具
• 📦 完整的Python SDK支持
• 🔄 支持下载完整模型库或单个文件
• 📁 自动管理本地缓存
• 🌐 多源支持：自动识别并从ModelHub、ModelScope、HuggingFace下载
• 🔧 自动根据API返回的source字段选择正确的下载方式

安装

1. 安装 modelhub-xc

使用pip安装：

pip install modelhub-xc

2. 安装 Git LFS（下载大文件必需）

如果需要下载包含大文件（>100MB）的模型，请确保已安装 Git LFS：

# 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 lfs install

注意：大多数AI模型（如5GB左右的模型文件）使用Git LFS存储，未安装Git LFS将无法正确下载这些文件。

使用方法

命令行下载

1. 下载完整模型库（自动识别来源）

# 从ModelHub下载
modelhub-xc download --model mlx-community/Qwen3-8B-bf16

# 从ModelScope下载（自动识别）
modelhub-xc download --model Tencent-Hunyuan/HY-Embodied-0.5

# 从HuggingFace下载（自动识别）
modelhub-xc download --model tiiuae/falcon-7b

2. 下载单个文件到指定本地文件夹（仅支持ModelHub源）

# 下载README.md到当前路径下"dir"目录
modelhub-xc download --model mlx-community/Qwen3-8B-bf16 README.md --local_dir ./dir

3. 指定本地保存目录

modelhub-xc download --model mlx-community/Qwen3-8B-bf16 --local_dir ./models

SDK下载

1. 下载完整模型（自动识别来源）

from modelhub_xc import snapshot_download

# 从ModelHub下载
model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')

# 从ModelScope下载（自动识别）
model_dir = snapshot_download('Tencent-Hunyuan/HY-Embodied-0.5')

# 从HuggingFace下载（自动识别）
model_dir = snapshot_download('tiiuae/falcon-7b')

print(f"模型已下载到: {model_dir}")

2. 指定保存目录

from modelhub_xc import snapshot_download

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

3. 下载单个文件（仅支持ModelHub源）

from modelhub_xc import download_file

# 下载单个文件
model_dir = download_file(
    'mlx-community/Qwen3-8B-bf16',
    'README.md',
    local_dir='./dir'
)

API参考

snapshot_download

下载完整的模型快照。

参数：

• model_id (str): 模型ID，例如 'mlx-community/Qwen3-8B-bf16'
• local_dir (str, 可选): 本地保存目录，默认为 ~/.cache/modelhub/models/{model_id}
• branch (str, 可选): 分支名，默认为 'main'
• api_base_url (str, 可选): API基础URL，默认为 'https://modelhub.org.cn/api'

返回：

• str: 下载后的本地目录路径

download_file

下载模型中的单个文件。

参数：

• model_id (str): 模型ID
• filename (str): 要下载的文件名或路径
• local_dir (str, 可选): 本地保存目录，默认为当前目录
• branch (str, 可选): 分支名，默认为 'main'
• api_base_url (str, 可选): API基础URL

返回：

• str: 下载后的本地目录路径

项目结构

modelhub/
├── modelhub_xc/
│   ├── __init__.py          # 包初始化
│   ├── api.py               # 公共API接口
│   ├── api_client.py        # ModelHub API客户端
│   ├── gitea_client.py      # Gitea仓库客户端
│   ├── downloader.py        # 模型下载器
│   └── cli.py               # 命令行工具
├── tests/                   # 测试文件
├── setup.py                 # 安装配置
├── publish.sh               # PyPI发布脚本
├── .pypirc.example          # PyPI配置示例
└── README.md                # 项目文档

工作原理

多源支持

系统支持从三种来源下载模型：

1. ModelHub（默认）：通过ModelHub API查询模型信息，使用Gitea API下载文件
2. ModelScope：使用git clone从 https://www.modelscope.cn/{model_id}.git 克隆
3. HuggingFace：使用git clone从 https://hf-mirror.com/{model_id} 克隆（自动使用配置的token）

自动识别流程

1. 查询模型信息：通过ModelHub API (/computility/models/getByModelId/vo) 查询模型信息
2. 识别来源：从API返回的 source 字段识别模型来源
3. 选择下载方式：
   • 如果 source 为 ModelScope：使用git clone从ModelScope下载
   • 如果 source 为 HuggingFace：使用git clone从HuggingFace镜像下载
   • 如果 source 为空或其他值：使用Gitea API从ModelHub下载
4. 保存到本地：默认保存到 ~/.cache/modelhub-xc/models/{model_id}

开发指南

安装开发依赖

pip install -e .
pip install wheel twine

运行测试

python -m pytest tests/

构建和发布

1. 构建包：

python setup.py sdist bdist_wheel

2. 上传到PyPI：

# 配置.pypirc文件（参考.pypirc.example）
twine upload dist/*

或者使用发布脚本：

./publish.sh

配置PyPI上传

1. 复制配置文件示例：

cp .pypirc ~/.pypirc

2. 编辑 ~/.pypirc 文件，填入你的PyPI token：

[distutils]
index-servers =
    pypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-your-token-here

技术栈

• Python 3.6+
• requests: HTTP客户端
• setuptools: 包管理

常见问题

1. 下载的模型文件不完整或大文件丢失？

原因：大多数AI模型（如5GB左右的模型权重文件）使用Git LFS存储，如果未安装Git LFS，只会下载指针文件而不是实际文件。

解决方法：

# 安装 Git LFS
# macOS: brew install git-lfs
# Ubuntu: sudo apt-get install git-lfs
# Windows: 从 https://git-lfs.github.com/ 下载安装

# 初始化 Git LFS
git lfs install

# 重新下载模型
modelhub-xc download --model your-model-id

2. 下载速度慢？

模型文件通常较大，下载速度取决于网络连接。建议使用稳定的网络环境。

3. 下载中断如何处理？

目前不支持断点续传，如果下载中断，需要重新开始下载。

4. 如何查看可用的模型？

访问 https://modelhub.org.cn 浏览可用的模型列表。

5. Git LFS 检测失败怎么办？

如果看到"警告: 未检测到 Git LFS"，说明系统未安装Git LFS或未正确初始化：

# 检查是否已安装
git lfs version

# 如果未安装，参考安装章节安装 Git LFS

# 安装后初始化
git lfs install

许可证

Apache License 2.0

贡献

欢迎提交Issue和Pull Request！

联系方式

• 官网：https://modelhub.org.cn
• 邮箱：[e-mail]

更新日志

v1.1.0 (2026-04-10)

• ✨ 新增多源支持：自动识别并从ModelScope、HuggingFace下载
• 🔧 从API返回的source字段自动判断下载来源
• 🚀 ModelScope和HuggingFace使用git clone方式下载
• 🔐 配置文件存储HuggingFace token
• 📝 简化API和CLI接口，移除手动指定source和branch参数

v1.0.0 (2026-04-09)

• 初始版本发布
• 支持命令行下载
• 支持SDK接口
• 支持下载完整模型和单个文件
• 集成XC社区API和Gitea仓库 ]()