large-file-upload-sdk 3.3.1

Large File Upload SDK - Support chunked upload, resumable transfer, and Token authentication

File Upload Server

星河启智二期用于上传大文件的服务器 - 基于 FastAPI 构建，文件存储到阿里云 OSS

功能特性

• ✅ OSS 直传: SDK 通过 oss2 直接上传到 OSS，支持断点续传和分片上传
• ✅ MD5校验: 可选的文件MD5校验，确保数据完整性
• ✅ Token认证: 类似HuggingFace的Token认证机制，安全便捷
• ✅ 权限控制: 支持用户角色和数据集访问权限管理
• ✅ 使用限制: 支持文件大小和每日上传次数限制
• ✅ 上传记录: 自动保存上传记录到数据库，支持查询和统计
• ✅ RESTful API: 提供完整的REST API接口
• ✅ Docker支持: 支持容器化部署

架构

用户电脑 ---(oss2 直传)--> 阿里云 OSS (inspire-alluxio-prod)
   |                              |
   +--- SDK 获取凭证 --> 服务器 ---+--- 记录上传完成
                                  +--- 通知前端

文件存储路径: oss://inspire-alluxio-prod/{dataset_id}/{filename}

快速开始

安装 SDK

pip install large-file-upload-sdk

上传文件

from file_upload_sdk import FileUploadSDK

sdk = FileUploadSDK(
    base_url="https://file-upload-server.ai4s.com.cn",
    access_token="hf_your_token_here",
)

result = sdk.upload_file(
    file_path="/path/to/local_file.csv",
    dataset_id="my-dataset",
    progress_callback=lambda p: print(f"\r上传进度: {p:.1f}%", end="", flush=True),
)

print()
if result["success"]:
    print(f"上传成功! 路径: {result.get('file_path', '')}")
else:
    print(f"上传失败: {result['error']}")

Token 认证

# 方式1：直接使用已有Token
sdk = FileUploadSDK(
    base_url="https://file-upload-server.ai4s.com.cn",
    access_token="hf_your_token_here",
)

# 方式2：使用用户信息自动获取Token
sdk = FileUploadSDK(
    base_url="https://file-upload-server.ai4s.com.cn",
    user_id=12345,
    user_name="张三",
)

服务端部署

环境变量

配置项	说明
OSS_ENDPOINT	OSS Endpoint（默认 https://oss-cn-wulanchabu.aliyuncs.com）
OSS_BUCKET	OSS Bucket（默认 inspire-alluxio-prod）
OSS_ACCESS_KEY_ID	OSS AccessKey ID（必填）
OSS_ACCESS_KEY_SECRET	OSS AccessKey Secret（必填）
MYSQL_HOST	MySQL 地址
MYSQL_PORT	MySQL 端口
MYSQL_USER	MySQL 用户名
MYSQL_PASSWORD	MySQL 密码
MYSQL_DATABASE	MySQL 数据库名

Docker 部署

docker run -d \
  --name file-upload-server \
  -p 8000:8000 \
  -e OSS_ACCESS_KEY_ID=your_ak \
  -e OSS_ACCESS_KEY_SECRET=your_sk \
  -e MYSQL_HOST=your_mysql_host \
  -e MYSQL_PASSWORD=your_mysql_password \
  file-upload-server

API 接口

服务启动后访问 http://localhost:8000/docs 查看完整的API文档

主要接口

接口	方法	说明
/health	GET	健康检查
/api/token/generate	POST	生成访问令牌
/api/token/verify	POST	验证令牌有效性
/api/token/revoke	DELETE	撤销访问令牌
/api/oss-upload/init	POST	获取 OSS 上传凭证
/api/oss-upload/complete	POST	通知上传完成
/api/oss-upload/status/{task_id}	GET	查询上传任务状态
/api/upload/records	GET	查询上传记录
/api/upload/records/stats	GET	获取上传统计信息

相关文档

• Token认证使用指南
• 上传记录功能指南
• 上传记录API文档