sandlake-storage-sdk 1.0.9

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

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

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

特性

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

安装

pip install -r requirements.txt

快速开始

1. 基础配置

编辑 config.cfg 配置文件：

[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. 下载模型

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. 下载数据集

from platform_downloader import PlatformDownloader

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

4. 下载单个文件

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. 上传模型

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. 上传数据集

from platform_downloader import PlatformDownloader

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

7. 上传单个文件

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 类

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

初始化

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

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

snapshot_download

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

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

下载单个文件。

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

snapshot_upload

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

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

上传单个文件。

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

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

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

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

get_model_info

获取模型详细信息。

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

便捷函数

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）：

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

对应 S3 路径：

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

高级用法

文件过滤

# 只下载模型权重和配置文件
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"]
)

并发下载

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

自定义配置

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 命令：

# 下载模型
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

异常处理

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)	通过配置文件或参数

开发计划

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

许可证

MIT License