modelhub-xc 3.8.0

ModelHub XC Community SDK - Python library for downloading models

ModelHub - XC社区模型下载SDK

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

功能特点

• 🚀 简单易用的命令行工具
• 📦 完整的Python SDK支持
• 🔄 支持下载完整模型库或单个文件
• 📁 自动管理本地缓存
• 🌐 多源支持：自动识别并从多个源下载模型
• 🔧 智能选择最佳下载方式

安装

1. 安装 modelhub-xc

使用pip安装：

pip install modelhub-xc

2. 安装必需工具

重要：为了支持下载大文件模型，您需要安装以下两个工具。SDK 会自动检查并在需要时使用它们。

安装 Git LFS

# macOS
brew install git-lfs
git lfs install

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

# CentOS/RHEL
sudo yum install git-lfs
git lfs install

# Windows
# 从 https://git-lfs.github.com/ 下载安装
# 安装后运行: git lfs install

安装 git-xet

# macOS
brew install git-xet
git xet install

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

# 其他系统
# 参考: https://about.xethub.com/

说明：

• SDK 会在首次使用时自动检查这两个工具是否已安装
• 如果缺少任何工具，会显示清晰的安装指南
• 安装完成后，SDK 会根据模型自动选择合适的工具

使用方法

命令行下载

1. 下载完整模型库

# 下载模型到默认缓存目录
modelhub-xc download --model mlx-community/Qwen3-8B-bf16

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

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

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

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                # 项目文档

工作原理

自动化下载流程

SDK 会自动处理所有下载细节，用户只需提供模型ID：

1. 查询模型信息：通过 ModelHub API 查询模型元数据
2. 智能路由：根据模型信息自动选择最佳下载方式
3. 工具选择：根据需要自动使用 Git LFS 或 git-xet
4. 本地缓存：默认保存到 ~/.cache/modelhub-xc/models/{model_id}

用户无需关心底层实现细节，SDK 会自动处理所有技术细节。

开发指南

安装开发依赖

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. 下载的模型文件不完整或缺少大文件？

原因：缺少必需的工具（Git LFS 或 git-xet）。

解决方法：按照安装章节安装两个工具

# 安装 Git LFS
brew install git-lfs
git lfs install

# 安装 git-xet
brew install git-xet
git xet install

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

2. SDK 提示缺少工具？

解决方法：SDK 会显示详细的安装指南，按照提示安装即可。

安装完成后检查：

# 检查 Git LFS
git lfs version

# 检查 git-xet
git xet --version

3. 下载速度慢？

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

4. 下载中断如何处理？

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

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

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

许可证

Apache License 2.0

贡献

欢迎提交Issue和Pull Request！

联系方式

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

更新日志

v1.5.0 (2026-04-13)

• ✨ 新增启动时工具预检查机制
• 🔧 在下载前自动检查 git-lfs 和 git-xet 是否已安装
• 📝 优化错误提示信息，提供清晰的工具安装指南
• 🎯 简化用户体验，自动处理所有技术细节
• 🚀 隐藏底层实现，用户无需了解不同源的区别

v1.1.0 (2026-04-10)

• ✨ 新增多源支持：自动识别并智能选择下载方式
• 🔧 自动判断使用 Git LFS 或 git-xet
• 🚀 优化下载流程和性能
• 🔐 改进认证和安全性
• 📝 简化 API 和 CLI 接口
• 📦 集成大文件下载支持

v1.0.0 (2026-04-09)

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