modelhub-xc 4.1.0

ModelHub XC Community SDK - Python library for downloading models

ModelHub-XC 模型下载 SDK

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

功能特点 • 快速开始 • 使用示例 • API 文档 • 常见问题

---

✨ 功能特点

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

🚀 快速开始

安装

# 安装 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

使用

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

📖 使用示例

命令行使用

下载完整模型

# 下载到默认目录 (~/.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

下载单个文件

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

Python SDK 使用

下载完整模型

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'
)

下载单个文件

from modelhub_xc import download_file

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

批量下载

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

pip install modelhub-xc

2. 安装依赖工具

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

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-xet

# 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: 模型的本地目录路径

示例：

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: 文件的本地目录路径

示例：

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 会显示详细的安装指南，按提示安装即可：

# 安装 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 浏览完整的模型列表。

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                # 本文档

🔨 开发指南

开发环境设置

# 克隆仓库
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/

构建和发布

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

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

📦 技术栈

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

📄 许可证

Apache License 2.0

📮 联系方式

• 官网: https://modelhub.org.cn