modelhub-xc 1.0.0

ModelHub XC Community SDK - Python library for downloading models

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

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

功能特点

• 🚀 简单易用的命令行工具
• 📦 完整的Python SDK支持
• 🔄 支持下载完整模型库或单个文件
• 📁 自动管理本地缓存
• 🌐 直接对接XC社区API和Gitea仓库

安装

使用pip安装：

pip install modelhub-xc

使用方法

命令行下载

1. 下载完整模型库

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

2. 下载单个文件到指定本地文件夹

# 下载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 --branch main

SDK下载

1. 下载完整模型

from modelhub_xc import snapshot_download

# 下载完整模型库
model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')
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. 下载单个文件

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 API查询模型的基本信息和Gitea仓库地址
2. 获取文件列表：通过Gitea API获取模型仓库中的文件列表
3. 下载文件：使用Gitea的下载接口下载模型文件到本地

开发指南

安装开发依赖

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. 下载速度慢？

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

2. 下载中断如何处理？

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

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

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

许可证

Apache License 2.0

贡献

欢迎提交Issue和Pull Request！

联系方式

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

更新日志

v1.0.0 (2026-04-09)

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