Metadata-Version: 2.4
Name: sandlake-storage-sdk
Version: 1.0.4
Summary: Sandlake Storage SDK - 基于 S3 存储后端的模型和数据集下载/上传 SDK，提供类似 ModelScope 风格的 API
Home-page: https://github.com/yourusername/sandlake-storage-sdk
Author: Your Name
Author-email: your.email@example.com
Keywords: s3,sandlake,storage,model,dataset,download,upload,snapshot,platform,downloader,modelscope
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.28.0
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.65.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 平台模型和数据集下载/上传 SDK

基于 S3 存储后端的模型和数据集下载/上传 Python SDK，提供类似 ModelScope 风格的简洁 API。

## 特性

- 🚀 **类似 ModelScope 的 API**: `snapshot_download`, `snapshot_upload` 等
- 📦 **模型ID映射**: 支持 `org/name` 格式的模型ID自动映射到 S3 路径
- ⚡ **并发传输**: 支持多线程并发上传/下载大模型的多个文件
- 📊 **进度显示**: 内置进度条显示传输进度
- 🔍 **文件过滤**: 支持 `allow_patterns` 和 `ignore_patterns` 文件过滤
- 🔄 **断点续传**: 基于 S3 的特性支持断点续传
- 🏗️ **可扩展**: 易于扩展支持更多存储后端

## 安装

```bash
pip install -r requirements.txt
```

## 快速开始

### 1. 基础配置

编辑 `config.cfg` 配置文件：

```ini
[s3]
endpoint_url = http://192.168.95.85:9000
access_key = admin
secret_key = 2wsx@WSX
bucket = sandlake

[platform]
models_prefix = models
datasets_prefix = datasets
cache_dir = ~/.cache/platform
max_workers = 4
```

### 2. 下载模型

```python
from platform_downloader import PlatformDownloader, snapshot_download

# 方式1: 使用便捷函数
download_dir = snapshot_download(
    model_id="company/llm-model",
    local_dir="./models"
)

# 方式2: 使用下载器类
downloader = PlatformDownloader()
download_dir = downloader.snapshot_download(
    model_id="company/llm-model",
    local_dir="./models"
)
```

### 3. 下载数据集

```python
from platform_downloader import PlatformDownloader

downloader = PlatformDownloader()
dataset_dir = downloader.snapshot_download(
    model_id="company/training-data",
    repo_type="dataset",
    local_dir="./datasets"
)
```

### 4. 下载单个文件

```python
from platform_downloader import model_file_download

file_path = model_file_download(
    model_id="company/llm-model",
    file_path="config.json",
    local_dir="./models"
)
```

### 5. 上传模型

```python
from platform_downloader import PlatformDownloader, snapshot_upload

# 方式1: 使用便捷函数
s3_path = snapshot_upload(
    model_id="company/llm-model",
    local_dir="./models"
)

# 方式2: 使用下载器类
downloader = PlatformDownloader()
s3_path = downloader.snapshot_upload(
    model_id="company/llm-model",
    local_dir="./models"
)
```

### 6. 上传数据集

```python
from platform_downloader import PlatformDownloader

downloader = PlatformDownloader()
s3_path = downloader.snapshot_upload(
    model_id="company/training-data",
    local_dir="./datasets",
    repo_type="dataset"
)
```

### 7. 上传单个文件

```python
from platform_downloader import model_file_upload

s3_key = model_file_upload(
    model_id="company/llm-model",
    file_path="config.json",
    local_path="./local/config.json"
)
```

## API 参考

### PlatformDownloader 类

主要下载器类，提供完整的下载功能。

#### 初始化

```python
downloader = PlatformDownloader(config=None, config_file=None)
```

- `config`: `PlatformConfig` 配置对象
- `config_file`: 配置文件路径

#### snapshot_download

下载完整的模型或数据集。

```python
download_dir = downloader.snapshot_download(
    model_id="org/name",           # 模型ID
    repo_type="model",             # 类型: "model" 或 "dataset"
    local_dir="./downloads",       # 本地保存目录
    cache_dir=None,                # 缓存目录
    revision="latest",             # 版本标签
    allow_patterns=None,           # 允许的文件模式
    ignore_patterns=None,          # 忽略的文件模式
    show_progress=True,            # 是否显示进度
    max_workers=4                  # 并发线程数
)
```

#### model_file_download

下载单个文件。

```python
file_path = downloader.model_file_download(
    model_id="org/name",
    file_path="config.json",
    repo_type="model",
    local_dir="./downloads"
)
```

#### snapshot_upload

上传完整的模型或数据集目录。

```python
s3_prefix = downloader.snapshot_upload(
    model_id="org/name",           # 模型ID
    local_dir="./models",          # 本地目录路径
    repo_type="model",             # 类型: "model" 或 "dataset"
    revision="latest",             # 版本标签
    allow_patterns=None,           # 允许的文件模式
    ignore_patterns=None,          # 忽略的文件模式
    show_progress=True,            # 是否显示进度
    max_workers=4                  # 并发线程数
)
```

#### model_file_upload

上传单个文件。

```python
s3_key = downloader.model_file_upload(
    model_id="org/name",
    file_path="config.json",       # 目标文件路径
    local_path="./local/config.json",  # 本地文件路径
    repo_type="model",
    revision="latest"
)
```

#### list_models / list_datasets

列出可用的模型和数据集。

```python
models = downloader.list_models()       # 列出所有模型
models = downloader.list_models(org="company")  # 按组织过滤

datasets = downloader.list_datasets()   # 列出所有数据集
```

#### get_model_info

获取模型详细信息。

```python
info = downloader.get_model_info("org/name")
print(info["files"])  # 模型文件列表
```

### 便捷函数

```python
from platform_downloader import (
    snapshot_download,
    model_file_download,
    dataset_file_download,
    snapshot_upload,
    model_file_upload,
    dataset_file_upload
)

# 下载模型
snapshot_download("org/model", local_dir="./models")

# 下载模型文件
model_file_download("org/model", "config.json", local_dir="./models")

# 下载数据集文件
dataset_file_download("org/dataset", "data.json", local_dir="./datasets")

# 上传模型
snapshot_upload("org/model", local_dir="./models")

# 上传模型文件
model_file_upload("org/model", "config.json", local_path="./local/config.json")

# 上传数据集文件
dataset_file_upload("org/dataset", "data.json", local_path="./local/data.json")
```

## 存储结构

### S3 路径映射规则

模型ID `org/model-name` 映射到 S3 路径：

```
s3://bucket/models/org/model-name/
```

数据集ID `org/dataset-name` 映射到 S3 路径：

```
s3://bucket/datasets/org/dataset-name/
```

### 版本管理

支持版本标签（revision）：

```python
# 下载特定版本
snapshot_download("org/model", revision="v1.0")
```

对应 S3 路径：

```
s3://bucket/models/org/model/v1.0/
```

## 高级用法

### 文件过滤

```python
# 只下载模型权重和配置文件
downloader.snapshot_download(
    "org/model",
    allow_patterns=["*.bin", "*.json", "*.safetensors"]
)

# 排除文档文件
downloader.snapshot_download(
    "org/model",
    ignore_patterns=["*.md", "*.txt", "*.rst"]
)

# 组合使用
downloader.snapshot_download(
    "org/model",
    allow_patterns=["*.bin"],
    ignore_patterns=["*_test.bin"]
)
```

### 并发下载

```python
# 使用更多线程加速下载
downloader.snapshot_download(
    "org/model",
    max_workers=8
)
```

### 自定义配置

```python
from platform_downloader import PlatformDownloader, PlatformConfig

config = PlatformConfig(
    endpoint_url="http://your-s3-server:9000",
    access_key="your-access-key",
    secret_key="your-secret-key",
    bucket="your-bucket",
    models_prefix="models",
    datasets_prefix="datasets",
    cache_dir="/data/cache",
    max_workers=8
)

downloader = PlatformDownloader(config=config)
```

## 命令行工具（可选扩展）

安装后可以使用 `platform-dl` 命令：

```bash
# 下载模型
platform-dl download model org/name --local_dir ./models

# 下载数据集
platform-dl download dataset org/name --local_dir ./datasets

# 下载单个文件
platform-dl download-file model org/name config.json --local_dir ./models

# 上传模型
platform-dl upload model org/name --local_dir ./models

# 上传数据集
platform-dl upload dataset org/name --local_dir ./datasets

# 上传单个文件
platform-dl upload-file model org/name config.json ./local/config.json

# 列出模型
platform-dl list models

# 列出数据集
platform-dl list datasets

# 获取模型信息
platform-dl info org/name

# 显示帮助
platform-dl --help
platform-dl upload --help
```

## 异常处理

```python
from platform_downloader import (
    PlatformDownloader,
    ModelNotFoundError,
    DatasetNotFoundError,
    DownloadError
)

downloader = PlatformDownloader()

try:
    model_dir = downloader.snapshot_download("org/model")
except ModelNotFoundError:
    print("模型不存在")
except DownloadError as e:
    print(f"下载失败: {e}")
```

## 与 ModelScope API 对比

| 功能 | ModelScope | 本平台 SDK |
|------|-----------|-----------|
| 下载模型 | `snapshot_download(model_id)` | `snapshot_download(model_id)` |
| 下载文件 | `model_file_download(model_id, file_path)` | `model_file_download(model_id, file_path)` |
| 下载数据集 | `snapshot_download(dataset_id, repo_type="dataset")` | `snapshot_download(dataset_id, repo_type="dataset")` |
| 本地目录 | `local_dir="./models"` | `local_dir="./models"` |
| 文件过滤 | `allow_patterns`, `ignore_patterns` | `allow_patterns`, `ignore_patterns` |
| 认证 | `HubApi.login(token)` | 通过配置文件或参数 |

## 开发计划

- [x] 支持模型/数据集上传
- [x] 支持命令行工具
- [ ] 支持断点续传（HTTP Range 请求）
- [ ] 支持模型信息缓存
- [ ] 支持下载速度限制
- [ ] 支持代理配置
- [ ] 支持模型搜索 API

## 许可证

MIT License
