Tele_Robot_Data_Platform

项目简介

本仓库当前实际可运行项目位于 VeloData/ 目录，提供一套围绕机器人数据采集、导入、索引、预览、标注、评分、导出和恢复的端到端数据工作流平台。围绕大文件、视频流、HDF5/LeRobot/UMI 多格式数据、对象存储和异步任务进行设计。

交接文档已整理到根目录 docs/，阅读顺序建议从本文档开始，再进入快速启动、环境配置和架构文档。

项目解决什么问题

主要解决以下几类问题：

• 将本地文件夹、ZIP 包或挂载目录中的机器人采集数据导入系统。
• 对 HDF5、LeRobot、UMI 三类数据源做格式识别、索引入库和资产登记。
• 将原始资产统一落到 MinIO / ZIP / 挂载路径三类来源下，并通过统一读取层提供下载、预览和派生能力。
• 为数据管理页面提供会话、Episode、流信息、遥测、自动预标注、评分和导出能力。
• 通过 Redis + RQ worker 处理索引、播放派生、帧 chunk 恢复、LeRobot 标准化、自动评分、自动预标注等异步链路。
• 支持软删除与恢复，恢复后重新触发必要索引。

核心功能

• 文件上传：前端按分片上传，支持 SHA256 秒传匹配。
• ZIP 导入：ZIP 上传后不整包解压，后端通过 ZIP 中央目录远程索引文件。
• 挂载导入：管理员可从白名单目录直接导入挂载路径，UMI 导入前会做格式预检查。
• 入库索引：批次索引后生成 Dataset / Session / Episode / EpisodeAsset / EpisodeStream 等记录。
• 派生文件：支持 HDF5/UMI 转 LeRobot、预览 MP4、按需 chunk 帧缓存、自动预标注结果包等资产。
• 预览播放：Episode 详情页可请求预览视频、逐帧读取、遥测曲线、标注和自动预标注。
• 缓存恢复：帧请求优先读本地缓存和 Redis，未命中时通过 MinIO 中的 chunk tar 恢复。
• 恢复流程：Dataset / Episode 为软删除，恢复后会重新建立运行态索引。

技术栈

• 前端：React 18、TypeScript、Vite、Ant Design、React Router、Zustand、Axios、Recharts
• 后端：FastAPI、SQLAlchemy Async、Alembic、Pydantic Settings、JWT
• 数据库：MySQL 8
• 缓存与队列：Redis、RQ、RQ Scheduler
• 对象存储：MinIO（S3 兼容）
• 媒体与数据处理：ffmpeg、h5py、OpenCV、PyArrow、Pandas
• 自动预标注：Grounding DINO + SAM2（通过 vision worker）
• 部署：Docker Compose、Nginx（前端容器内）、Shell 脚本

目录结构说明

Tele_Robot_Data_Platform/
├── README.md
├── .env.example                  # 根级配置索引文件，实际运行不直接读取
├── docs/                         # 交接文档
└── VeloData/                     # 实际项目根目录
    ├── docker-compose.yml
    ├── docker-compose.prod.yml
    ├── Makefile
    ├── start-dev.sh
    ├── reset-dev.sh
    ├── scripts/                  # 部署、备份、巡检等脚本
    ├── infra/mysql/init.sql
    ├── server/                   # FastAPI + worker + Alembic + tests
    │   ├── app/
    │   │   ├── api/v1/           # API 路由入口
    │   │   ├── models/           # ORM 模型
    │   │   ├── services/         # 上传、索引、派生、导出、遥测等核心服务
    │   │   └── workers/          # RQ 任务入口
    │   ├── alembic/
    │   ├── scripts/
    │   └── tests/
    └── web/                      # React 前端
        ├── src/pages/
        ├── src/api/
        ├── src/routes/
        └── src/stores/

快速启动

所有实际命令均建议先进入 VeloData/：

cd VeloData
make dev-setup

开发时最稳妥的启动方式是分开启动基础设施、后端、worker、前端：

cd VeloData
make start-infra

cd server
cp .env.example .env
source venv/bin/activate
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

新开终端：

cd VeloData/server
source venv/bin/activate
rq worker --worker-class rq.worker.SimpleWorker --with-scheduler --url redis://localhost:6379/0 velodata-indexing velodata-tasks velodata-score

再开终端：

cd VeloData/web
cp .env.example .env
npm run dev

详细步骤见 docs/01-快速开始.md。

文档导航

• 快速启动
• 部署说明
• 环境变量与关键配置
• 系统架构与主链路
• API 总览
• 上传与索引工作流
• 预览、播放与缓存链路
• 数据模型总览
• 异步任务与状态机
• 资产存储、下载与恢复
• 接口契约明细
• 数据流与时序图
• 状态流转矩阵
• 排障手册

常见命令

以下命令均在 VeloData/ 目录执行：

make help
make start-infra
make dev-setup
make dev-backend
make dev-frontend
make migrate
make seed
make test-backend
make test-telemetry-api
make vision-setup
make vision-up
./start-dev.sh
./reset-dev.sh

当前项目状态说明

项目状态可概括为：

• 核心链路已具备：上传、ZIP/挂载导入、索引、Episode 预览、遥测、自动评分、LeRobot 导出、软删除与恢复。
• 前端主入口已具备：/collect/upload、/collect/mount-import、/data-management、/sessions/:sessionId/episodes、/episodes/:id、/notifications。
• 自动预标注链路已接入，但依赖独立 vision worker、模型文件和可用的 PyTorch/SAM2 环境。
• storage 路由当前仍是占位实现，POST /episodes/{episode_id}/derive 当前返回 not_implemented。
• users、reviews 路由在后端总路由中未启用，前端审核页面也已注释禁用。