modelhub-xc 1.0.0__tar.gz

modelhub_xc-1.0.0/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright (c) 2026 ModelHub XC Team
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

modelhub_xc-1.0.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: modelhub-xc
+Version: 1.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
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+[# ModelHub - XC社区模型下载SDK
+
+ModelHub是一个用于从XC社区下载模型的Python SDK工具。它提供了简单易用的命令行工具和Python API接口，帮助用户快速下载和管理AI模型。
+
+## 功能特点
+
+- 🚀 简单易用的命令行工具
+- 📦 完整的Python SDK支持
+- 🔄 支持下载完整模型库或单个文件
+- 📁 自动管理本地缓存
+- 🌐 直接对接XC社区API和Gitea仓库
+
+## 安装
+
+使用pip安装：
+
+```bash
+pip install modelhub-xc
+```
+
+## 使用方法
+
+### 命令行下载
+
+#### 1. 下载完整模型库
+
+```bash
+modelhub-xc download --model mlx-community/Qwen3-8B-bf16
+```
+
+#### 2. 下载单个文件到指定本地文件夹
+
+```bash
+# 下载README.md到当前路径下"dir"目录
+modelhub-xc download --model mlx-community/Qwen3-8B-bf16 README.md --local_dir ./dir
+```
+
+#### 3. 指定分支下载
+
+```bash
+modelhub-xc download --model mlx-community/Qwen3-8B-bf16 --branch main
+```
+
+### SDK下载
+
+#### 1. 下载完整模型
+
+```python
+from modelhub_xc import snapshot_download
+
+# 下载完整模型库
+model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')
+print(f"模型已下载到: {model_dir}")
+```
+
+#### 2. 指定保存目录
+
+```python
+from modelhub_xc import snapshot_download
+
+# 下载到指定目录
+model_dir = snapshot_download(
+    'mlx-community/Qwen3-8B-bf16',
+    local_dir='./my_models'
+)
+```
+
+#### 3. 下载单个文件
+
+```python
+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的下载接口下载模型文件到本地
+
+## 开发指南
+
+### 安装开发依赖
+
+```bash
+pip install -e .
+pip install wheel twine
+```
+
+### 运行测试
+
+```bash
+python -m pytest tests/
+```
+
+### 构建和发布
+
+1. 构建包：
+
+```bash
+python setup.py sdist bdist_wheel
+```
+
+2. 上传到PyPI：
+
+```bash
+# 配置.pypirc文件（参考.pypirc.example）
+twine upload dist/*
+```
+
+或者使用发布脚本：
+
+```bash
+./publish.sh
+```
+
+## 配置PyPI上传
+
+1. 复制配置文件示例：
+
+```bash
+cp .pypirc ~/.pypirc
+```
+
+2. 编辑 `~/.pypirc` 文件，填入你的PyPI token：
+
+```ini
+[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](https://modelhub.org.cn) 浏览可用的模型列表。
+
+## 许可证
+
+Apache License 2.0
+
+## 贡献
+
+欢迎提交Issue和Pull Request！
+
+## 联系方式
+
+- 官网：https://modelhub.org.cn
+- 邮箱：noreply@modelhub.org.cn
+
+## 更新日志
+
+### v1.0.0 (2026-04-09)
+
+- 初始版本发布
+- 支持命令行下载
+- 支持SDK接口
+- 支持下载完整模型和单个文件
+- 集成XC社区API和Gitea仓库
+]()

modelhub_xc-1.0.0/README.md

@@ -0,0 +1,233 @@
+[# ModelHub - XC社区模型下载SDK
+
+ModelHub是一个用于从XC社区下载模型的Python SDK工具。它提供了简单易用的命令行工具和Python API接口，帮助用户快速下载和管理AI模型。
+
+## 功能特点
+
+- 🚀 简单易用的命令行工具
+- 📦 完整的Python SDK支持
+- 🔄 支持下载完整模型库或单个文件
+- 📁 自动管理本地缓存
+- 🌐 直接对接XC社区API和Gitea仓库
+
+## 安装
+
+使用pip安装：
+
+```bash
+pip install modelhub-xc
+```
+
+## 使用方法
+
+### 命令行下载
+
+#### 1. 下载完整模型库
+
+```bash
+modelhub-xc download --model mlx-community/Qwen3-8B-bf16
+```
+
+#### 2. 下载单个文件到指定本地文件夹
+
+```bash
+# 下载README.md到当前路径下"dir"目录
+modelhub-xc download --model mlx-community/Qwen3-8B-bf16 README.md --local_dir ./dir
+```
+
+#### 3. 指定分支下载
+
+```bash
+modelhub-xc download --model mlx-community/Qwen3-8B-bf16 --branch main
+```
+
+### SDK下载
+
+#### 1. 下载完整模型
+
+```python
+from modelhub_xc import snapshot_download
+
+# 下载完整模型库
+model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')
+print(f"模型已下载到: {model_dir}")
+```
+
+#### 2. 指定保存目录
+
+```python
+from modelhub_xc import snapshot_download
+
+# 下载到指定目录
+model_dir = snapshot_download(
+    'mlx-community/Qwen3-8B-bf16',
+    local_dir='./my_models'
+)
+```
+
+#### 3. 下载单个文件
+
+```python
+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的下载接口下载模型文件到本地
+
+## 开发指南
+
+### 安装开发依赖
+
+```bash
+pip install -e .
+pip install wheel twine
+```
+
+### 运行测试
+
+```bash
+python -m pytest tests/
+```
+
+### 构建和发布
+
+1. 构建包：
+
+```bash
+python setup.py sdist bdist_wheel
+```
+
+2. 上传到PyPI：
+
+```bash
+# 配置.pypirc文件（参考.pypirc.example）
+twine upload dist/*
+```
+
+或者使用发布脚本：
+
+```bash
+./publish.sh
+```
+
+## 配置PyPI上传
+
+1. 复制配置文件示例：
+
+```bash
+cp .pypirc ~/.pypirc
+```
+
+2. 编辑 `~/.pypirc` 文件，填入你的PyPI token：
+
+```ini
+[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](https://modelhub.org.cn) 浏览可用的模型列表。
+
+## 许可证
+
+Apache License 2.0
+
+## 贡献
+
+欢迎提交Issue和Pull Request！
+
+## 联系方式
+
+- 官网：https://modelhub.org.cn
+- 邮箱：noreply@modelhub.org.cn
+
+## 更新日志
+
+### v1.0.0 (2026-04-09)
+
+- 初始版本发布
+- 支持命令行下载
+- 支持SDK接口
+- 支持下载完整模型和单个文件
+- 集成XC社区API和Gitea仓库
+]()

modelhub_xc-1.0.0/modelhub_xc/__init__.py

@@ -0,0 +1,10 @@
+"""
+ModelHub SDK for XC Community
+A Python SDK for downloading models from ModelHub XC community
+"""
+
+__version__ = '1.0.0'
+
+from .api import snapshot_download, download_file
+
+__all__ = ['snapshot_download', 'download_file']

modelhub_xc-1.0.0/modelhub_xc/api.py

@@ -0,0 +1,70 @@
+"""
+Public API for ModelHub SDK
+"""
+
+from typing import Optional, List
+from .downloader import ModelDownloader
+
+
+def snapshot_download(
+        model_id: str,
+        local_dir: Optional[str] = None,
+        branch: str = "main",
+        api_base_url: str = "https://modelhub.org.cn/api"
+) -> str:
+    """
+    下载完整的模型快照
+
+    Args:
+        model_id: 模型ID，例如 'mlx-community/Qwen3-8B-bf16'
+        local_dir: 本地保存目录，如果为None则使用默认目录 ~/.cache/modelhub-xc/models/{model_id}
+        branch: 分支名，默认为 'main'
+        api_base_url: API基础URL，默认为 'https://modelhub.org.cn/api'
+
+    Returns:
+        下载后的本地目录路径
+
+    Example:
+        >>> from modelhub-xc import snapshot_download
+        >>> model_dir = snapshot_download('mlx-community/Qwen3-8B-bf16')
+        >>> print(f"模型已下载到: {model_dir}")
+    """
+    downloader = ModelDownloader(api_base_url)
+    return downloader.download_model(model_id, local_dir=local_dir, branch=branch)
+
+
+def download_file(
+        model_id: str,
+        filename: str,
+        local_dir: Optional[str] = None,
+        branch: str = "main",
+        api_base_url: str = "https://modelhub.org.cn/api"
+) -> str:
+    """
+    下载模型中的单个文件
+
+    Args:
+        model_id: 模型ID，例如 'mlx-community/Qwen3-8B-bf16'
+        filename: 要下载的文件名或路径，例如 'README.md'
+        local_dir: 本地保存目录，如果为None则使用当前目录
+        branch: 分支名，默认为 'main'
+        api_base_url: API基础URL
+
+    Returns:
+        下载后的本地目录路径
+
+    Example:
+        >>> from modelhub-xc import download_file
+        >>> model_dir = download_file('mlx-community/Qwen3-8B-bf16', 'README.md', local_dir='./dir')
+    """
+    downloader = ModelDownloader(api_base_url)
+
+    if local_dir is None:
+        local_dir = '.'
+
+    return downloader.download_model(
+        model_id,
+        local_dir=local_dir,
+        files=[filename],
+        branch=branch
+    )

modelhub_xc-1.0.0/modelhub_xc/api_client.py

@@ -0,0 +1,55 @@
+"""
+ModelHub API Client
+Handles API requests to modelhub-xc.org.cn
+"""
+
+import requests
+from typing import Dict, Any, Optional
+
+
+class ModelHubAPIClient:
+    """ModelHub API客户端"""
+
+    def __init__(self, api_base_url: str = "https://modelhub.org.cn/api"):
+        self.api_base_url = api_base_url.rstrip('/')
+
+    def get_model_info(self, model_id: str) -> Dict[str, Any]:
+        """
+        通过modelId查询模型信息
+
+        Args:
+            model_id: 模型ID，例如 'mlx-community/Qwen3-8B-bf16'
+
+        Returns:
+            模型信息字典
+
+        Raises:
+            Exception: 当API请求失败时
+        """
+        url = f"{self.api_base_url}/computility/models/getByModelId/vo"
+        params = {'modelId': model_id}
+
+        try:
+            response = requests.get(url, params=params, timeout=30)
+            response.raise_for_status()
+
+            data = response.json()
+            if data.get('code') != 0:
+                raise Exception(f"API返回错误: {data.get('message', 'Unknown error')}")
+
+            return data.get('data', {})
+        except requests.RequestException as e:
+            raise Exception(f"查询模型信息失败: {str(e)}")
+
+    def get_gitea_url(self, model_id: str) -> Optional[str]:
+        """
+        获取模型的Gitea URL
+
+        Args:
+            model_id: 模型ID
+
+        Returns:
+            Gitea URL或None
+        """
+        model_info = self.get_model_info(model_id)
+        return model_info.get('giteaUrl')