robodock-sdk 0.1.16

Python SDK for RoboDock Platform - Data and Model Management

RoboDock SDK

Python SDK for RoboDock Platform - 提供数据管理、模型训练任务管理等功能。

特性

• 🚀 简洁的API设计
• 📦 腾讯云 COS 数据上传下载
• 🔄 训练任务状态管理
• 📊 数据集管理
• 🔐 安全的文件解压（防zip-slip攻击）

安装

使用pip安装

pip install robodock-sdk

从源码安装

git clone https://github.com/FII-AILab/robodock-sdk.git
cd robodock-sdk
pip install -e .

快速开始

基础用法

from robodock_sdk import RoboDockClient

# 创建客户端（使用默认配置）
client = RoboDockClient()

# 或者自定义配置
client = RoboDockClient(
    s3_access_key="<COS_SECRET_ID>",
    s3_secret_key="<COS_SECRET_KEY>",
    bucket_name="robodock-fii-sh-1256676747",
    region_name="ap-shanghai",
    api_url="http://192.168.1.2:31080"
)

# 获取数据集信息
dataset_info = client.get_dataset("dataset-uuid")

# 下载数据集
local_path = client.download_dataset(
    data_name="data.zip",
    uuid="data-uuid",
    dirname="singledata"
)

# 更新任务状态
client.update_run_status(
    unique_name="project-run",
    status="processing",
    start_time=1234567890000
)

# 上传模型（同步）
s3_key = client.upload_model(
    outdir_path="/path/to/model",
    upload_path="models/project/run"
)

# 上传模型（异步）
s3_key = client.upload_model_async(
    outdir_path="/path/to/model",
    upload_path="models/project/run"
)

使用底层Actions API

from robodock_sdk import RoboDockActions

actions = RoboDockActions(
    s3_access_key="<COS_SECRET_ID>",
    s3_secret_key="<COS_SECRET_KEY>",
    bucket_name="robodock-fii-sh-1256676747",
    region_name="ap-shanghai",
    api_url="http://192.168.1.2:31080"
)

# 获取运行信息
run_info = actions.get_run_info("run-uuid")

# 下载检查点
checkpoint_path = actions.download_checkpoint(
    online_path="checkpoints/model.tar",
    local_path="/local/path"
)

环境变量配置

SDK支持通过环境变量进行配置：

export PROJECT_NAME=my_project
export RUN_NAME=run_001
export DATASET_UUID=dataset-uuid-here
export OUTPUT_DIR=/workspace/checkpoints
export RESUME=true
export RESUME_FROM=previous-run-uuid

SDK 连接配置（优先级）

RoboDockClient / RoboDockActions 的配置优先级为：

1. 传入的参数
2. 环境变量
3. 内置默认值

支持的环境变量：

变量名	说明	默认值
S3_ENDPOINT_URL	S3 服务端点	http://192.168.1.6:9000
AWS_ACCESS_KEY_ID	S3 访问密钥	robodock
AWS_SECRET_ACCESS_KEY	S3 密钥	robodock
S3_BUCKET_NAME	S3 桶名称	robodock
S3_REGION_NAME	S3 区域	us-east-1
ROBOCK_SERVER_URL	RoboDock API URL	http://192.168.1.2:31080

完整的环境变量列表：

变量名	说明	默认值
PROJECT_NAME	项目名称	default_project
RUN_NAME	运行名称	default_run
DATASET_UUID	数据集UUID	-
OUTPUT_DIR	输出目录	/workspace/checkpoints
RESUME	是否恢复训练	false
RESUME_FROM	恢复的运行UUID	-
SAVE_INTERVAL	保存间隔	5000
BATCH_SIZE	批次大小	32
NUM_TRAIN_STEPS	训练步数	20000
LOG_INTERVAL	日志间隔	10

API文档

RoboDockClient

高层客户端接口，提供便捷的API调用。

方法

• get_dataset(uuid) - 获取数据集信息
• get_data(uuid) - 获取单条数据信息
• get_run(unique_name, unique_type) - 获取运行信息
• download_dataset(data_name, uuid, dirname) - 下载数据集
• download_checkpoint(online_path, local_path) - 下载检查点
• upload_model(outdir_path, upload_path) - 上传模型
• upload_model_async(outdir_path, upload_path) - 异步上传模型
• update_run_status(unique_name, status, **kwargs) - 更新运行状态

RoboDockActions

底层操作接口，提供更细粒度的控制。

方法

• get_dataset_info(uuid) - 获取数据集信息
• get_singledata_info(uuid) - 获取单条数据信息
• get_run_info(unique_name, unique_type) - 获取运行信息
• download_data(data_name, uuid, dirname) - 下载并解压数据
• download_checkpoint(online_path, local_path) - 下载并解压检查点
• upload_data(outdir_path, upload_path) - 压缩并上传数据
• upload_data_async(outdir_path, upload_path) - 异步压缩并上传数据
• update_singledata(uuid, checker_result, checker_info) - 更新数据检查结果
• update_run(unique_name, body, unique_type) - 更新运行状态

开发

Release Notes

发布说明请查看 CHANGELOG.md。

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest tests/

代码格式化

black robodock_sdk/

类型检查

mypy robodock_sdk/

示例

查看 examples/ 目录获取更多使用示例：

• examples/basic_usage.py - 基础用法示例
• examples/training_workflow.py - 完整训练流程示例

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！