Spaces:
Running
Running
stouchinglhh
Claude
sync processor from GitLab c697b6e: 版本 1.19.4 / 前端 1.12.4 —— 服务端 i18n(首屏不再闪英文)、推理模块并入模型页、前端抽出 shared/、缓存键改用前端号
bb59211 | # processor | |
| [中文](README.zh-CN.md) | [English](README.md) | |
| > 文档版本：2026-09-28 · 后端版本：`1.19.4` · 前端版本：`1.12.3` | |
| processor 是 EgoData 的数据采集、处理、审核和导出服务，面向具身智能与机器人 | |
| 操作数据。系统由 FastAPI 后端、异步 Worker、Web 审核页面和 Workflow Studio 组成。 | |
| > 项目文档：[项目文档介绍](docs/README.md)。 | |
| ```text | |
| 采集端上传 → 项目匹配 → 工作流处理 → AI/人工审核 → LeRobot/HDF5 导出 | |
| ``` | |
| ## 文档导航 | |
| - [系统组成](#1-系统组成) | |
| - [安装与启动](#7-安装与启动) | |
| - [代码目录](#2-代码目录) | |
| - [项目数据结构](#3-项目数据结构) | |
| - [视频数据规范](#4-视频数据规范) | |
| - [工作流模块](#5-工作流模块) | |
| - [Web Workflow Studio 前端模块说明](#web-workflow-studio-前端模块说明) | |
| - [处理结果保存](#6-处理结果保存) | |
| - [配置](#8-配置) | |
| - [API](#9-api) | |
| - [测试与排障](#10-测试与排障) | |
| ## 1. 系统组成 | |
| ```text | |
| 采集端 | |
| │ | |
| ▼ | |
| FastAPI 后端 | |
| ├── 项目、Episode、工作流和审核 API | |
| ├── 上传接收、解压、规范化和数据校验 | |
| └── 调度 Worker 处理任务 | |
| │ | |
| ▼ | |
| Worker | |
| ├── MediaPipe 手部关键点 | |
| ├── RGB-D metric 3D 手部关键点 | |
| ├── 通过 API 进行 AI 标注 | |
| └── 视频与标注质量审核 | |
| │ | |
| ▼ | |
| Web 审核页面 | |
| ├── 原始 RGB 视频 | |
| ├── 浏览器 SVG/Canvas 关键点叠加 | |
| └── 深度视频伪彩色预览 | |
| │ | |
| ▼ | |
| LeRobot v2.1 / v3.0 或 HDF5 | |
| ``` | |
| 本机 `processor/` 目录是前端和后端代码的唯一来源。远端服务器只提供数据目录 | |
| 或 SFTP 存储，不作为本项目的前端、后端代码来源；服务器中的旧代码已废弃。 | |
| ## 2. 代码目录 | |
| <details> | |
| <summary>点击展开：代码目录</summary> | |
| ```text | |
| processor/ | |
| ├── app/ # FastAPI、存储、工作流、处理和导出逻辑 | |
| ├── worker/ # 异步处理 Worker | |
| ├── scripts/ # 部署、启动、检查和数据维护脚本 | |
| ├── web/ | |
| │ ├── templates/ # Web 页面模板 | |
| │ ├── static/ # CSS、JavaScript 和前端构建产物 | |
| │ └── workflow-studio/ # React + Vite 工作流编辑器源码 | |
| ├── tests/ # 自动化测试 | |
| ├── requirements*.txt # Python 依赖清单 | |
| ├── deploy.py # 跨平台部署入口 | |
| ├── deploy.sh # Linux 部署入口 | |
| ├── deploy.bat # Windows 部署入口 | |
| └── .env.example # 配置模板 | |
| ``` | |
| 运行数据默认存储在 `STORAGE_DIR`： | |
| ```text | |
| data/ | |
| ├── sessions/ # 项目数据集 | |
| ├── state/ # 系统状态、队列、运行记录和导出任务 | |
| └── tmp/ # 上传和 Worker 临时文件 | |
| ``` | |
| 运行数据、模型权重、压缩包、凭据和虚拟环境不应提交到 Git。`requirements*.txt` 和 | |
| `package.json` 等依赖清单应保留在仓库中。 | |
| </details> | |
| ## 3. 项目数据结构 | |
| <details> | |
| <summary>点击展开：项目数据结构、Episode、Chunk 和 Meta</summary> | |
| 一个项目就是一个数据集根目录。规范的项目根目录固定只有 `data/`、`meta/`、`videos/` | |
| 三个目录，不在项目下创建额外的批次级数据目录： | |
| ```text | |
| data/sessions/<project>/ | |
| ├── data/ | |
| │ └── chunk-000/ | |
| │ ├── episode_000000.parquet | |
| │ └── episode_000001.parquet | |
| ├── meta/ | |
| │ ├── info.json | |
| │ ├── stats.json | |
| │ ├── tasks.json | |
| │ └── episodes/ | |
| │ └── chunk-000/ | |
| │ ├── episode_000000.parquet | |
| │ └── episode_000001.parquet | |
| └── videos/ | |
| └── chunk-000/ | |
| ├── observation.images.head_rgb/ | |
| │ └── episode_000000.mp4 | |
| └── observation.images.head_depth/ | |
| └── episode_000000.mp4 | |
| ``` | |
| ### Episode 和 Chunk | |
| - Episode 编号从 `000000` 开始； | |
| - `episode_000000` 至 `episode_000999` 存储在 `chunk-000`； | |
| - `episode_001000` 开始使用 `chunk-001`； | |
| - 每个 chunk 最多包含 1000 个 Episode； | |
| - `data`、`meta/episodes` 和 `videos` 使用相同的 Episode/Chunk 对应关系； | |
| - 采集批次名称用于业务追踪，不替代数据集的 `episode_index`。 | |
| ### Meta 目录 | |
| 规范的 `meta/` 目录包含： | |
| - `info.json`：数据集版本、FPS、帧数、feature 和路径模板； | |
| - `stats.json`：数据字段统计信息； | |
| - `tasks.json`：任务 ID 和任务描述； | |
| - `episodes/chunk-XXX/episode_XXXXXX.parquet`：单个 Episode 的时间戳、设备信息、视频 | |
| 信息、采集元数据、校准信息和处理状态。 | |
| 时间戳、设备信息和校准信息写入对应的 Episode。审核页和标注页只使用当前 Episode 的 | |
| 真实视频、深度流和元数据。 | |
| </details> | |
| ## 4. 视频数据规范 | |
| <details> | |
| <summary>点击展开：视频源、深度存储和前端伪彩色预览</summary> | |
| ### 视频源 | |
| | 类型 | 源名称示例 | 说明 | | |
| | --- | --- | --- | | |
| | 单目 RGB | `head_rgb` | 普通 RGB 视频 | | |
| | Metric 深度 | `head_depth` | 独立的真实深度视频 | | |
| | 双目 RGB | `stereo_left_rgb`、`stereo_right_rgb` | 左、右 RGB 视频 | | |
| | 双目深度 | `stereo_depth` | 独立深度视频 | | |
| RGB 和 Depth 始终作为独立数据流保存。纯 Depth 流不会被当作 RGB，也不会与 RGB 流重复 | |
| 保存。 | |
| ### 深度存储 | |
| 新的真实深度视频统一使用： | |
| ```text | |
| HEVC (H.265) in MP4 / hvc1 / gray12le / qp=6 / range=full | |
| ``` | |
| 深度视频保存的是 12-bit 对数深度码，不是伪彩色图像： | |
| ```text | |
| 100–5000 mm 对数深度 → 0..4095 gray12le 码值 | |
| ``` | |
| `meta/info.json` 中对应的 feature 使用 `video.is_depth_map=true` 标记，并记录深度编码 | |
| 参数。读取端将码值反量化为毫米。原始深度视频在处理和导出时保持不变。 | |
| ### 前端深度预览 | |
| 深度伪彩色只用于浏览器预览，不写回数据集： | |
| ```text | |
| HEVC gray12le | |
| │ | |
| └── 浏览器 Canvas：深度码 → JET 伪彩色 | |
| ``` | |
| 预览颜色规范： | |
| - 无效深度：黑色； | |
| - 近距离：蓝紫色； | |
| - 中距离：绿色、黄色； | |
| - 远距离：橙色、红色。 | |
| 打开 Episode 时会预加载深度预览数据。RGB 视频、双目 RGB 视频和导出数据不经过伪彩色 | |
| 转换，也不会生成额外的伪彩色视频。 | |
| </details> | |
| ## 5. 工作流模块 | |
| <details> | |
| <summary>点击展开：输入、处理、审核、导出模块和节点状态</summary> | |
| 工作流由 Input、Process、Review 和 Export 四类模块组成。端口具有明确的数据类型， | |
| 每个分支只处理连接到对应端口的数据。没有输入连接的分支标记为 | |
| `Skipped · Missing Input`，不会阻塞其他已连接分支。 | |
| ### 输入模块 | |
| - `RGB Camera`：单路 RGB 视频； | |
| - `RGB-D Camera`：RGB 视频和 Depth； | |
| - `Stereo RGB Camera`：Left RGB Video 和 Right RGB Video； | |
| - `Stereo RGB-D Camera`：左右 RGB 视频和 Depth； | |
| - `Glove Sensor`：手套压力、关节或传感器数据。 | |
| ### 处理模块 | |
| - `MediaPipe Hand`：从 RGB 视频提取 2D 手部关键点； | |
| - `Human Annotation`：人工标注； | |
| - `AI Annotation`：通过配置的 API 进行视频/片段标注； | |
| - `RGB_TO_2D_BareHand`：裸手 2D 手部关键点； | |
| - `RGB_TO_2D_BlackGlove`：黑手套 2D 手部关键点； | |
| - `RGB-D_3D_BareHand`：使用 RGB 视频和 Depth 计算真实 metric 3D 裸手关键点； | |
| - `RGB-D_3D_BlackGlove`：使用 RGB 视频和 Depth 计算真实 metric 3D 黑手套关键点。 | |
| `RGB_TO_2D_*` 的 `Spatial` 按钮只控制浏览器中的空间预览，不生成虚假 3D 数据，也不会 | |
| 向导出数据写入 3D 值。`RGB-D_3D_*` 的 `RGB Video` 和 `Depth` 是独立输入端，应分别连接 | |
| 对应的采集端输出。 | |
| ### Web Workflow Studio 前端模块说明 | |
| 以下模块是当前前端调色板和画布实际注册的模块。模块名称、端口名称和连接类型由前端 | |
| 注册表统一维护，不会被陈旧工作流或废弃后端目录覆盖。旧类型 | |
| `rgb_hand_3d`、`black_hand_rgb_3d`、`stereo_triangulate` 和 `black_glove_hand` 仅在加载 | |
| 旧工作流时做映射，新工作流调色板不显示这些类型。 | |
| #### 采集端模块（Input） | |
| | 前端模块 | 输入端 | 输出端 | 用途与规则 | | |
| | --- | --- | --- | --- | | |
| | `RGB Camera` | 无 | `RGB Video` | 单目 RGB 视频。设备从当前项目数据中选择；留空时自动匹配。 | | |
| | `RGB-D Camera` | 无 | `RGB Video`、`Depth` | 输出同一设备的 RGB 和真实深度流；Depth 只能连接到深度输入端。 | | |
| | `Stereo RGB Camera` | 无 | `Left RGB Video`、`Right RGB Video` | 双目 RGB 输入；连接一侧时建立对应的左右关系。 | | |
| | `Stereo RGB-D Camera` | 无 | `Left RGB Video`、`Right RGB Video`、`Depth` | 双目 RGB 加真实深度；Depth 用于 RGB-D 3D 处理。 | | |
| | `Glove Sensor` | 无 | `Glove Sensor Data` | 压力、关节或手套传感器数据，不输出视频；可直接连接质量审核。 | | |
| #### 视频和关键点处理模块（Process） | |
| | 前端模块 | 输入端 | 输出端 | 用途与规则 | | |
| | --- | --- | --- | --- | | |
| | `Human Annotation` | `RGB Video` | `Annotation` | 在 RGB 视频上进行帧级人工标注。 | | |
| | `AI Annotation` | `RGB Video` | `Annotation` | 通过本地或 API VLM 进行视频/片段标注；部署时推荐使用 API。 | | |
| | `RGB_TO_2D_BareHand` | `RGB Video` | `Hand 2D` | 裸手 2D 关键点；`Spatial` 仅用于显示，不导出 metric 3D。 | | |
| | `RGB_TO_2D_BlackGlove` | `RGB Video` | `Hand 2D` | 黑手套 2D 关键点；没有 Depth 时不计算 metric 3D。 | | |
| | `RGB-D_3D_BareHand` | `RGB Video`、`Depth` | `Hand 3D` | 使用 RGB 和真实 Depth 计算 metric 3D 裸手关键点；缺少分支时跳过。 | | |
| | `RGB-D_3D_BlackGlove` | `RGB Video`、`Depth` | `Hand 3D` | 使用 RGB 和真实 Depth 计算 metric 3D 黑手套关键点；不会从磁盘寻找或回退到 RGB 估计。 | | |
| `MediaPipe Hand` 保留用于历史工作流和后端兼容，但新工作流调色板不显示。所有节点都 | |
| 支持鼠标悬停说明，提示模块用途和允许连接的数据类型。 | |
| #### 审核模块（Review） | |
| | 前端模块 | 输入端 | 输出端 | 用途与规则 | | |
| | --- | --- | --- | --- | | |
| | `Human Review` | `Review Target` | `Reviewed Data` | 人工检查视频、关键点或标注结果，再进入后续流程。 | | |
| | `AI Quality Review` | `Quality Review Target` | `Reviewed Data` | 检查视频解码、帧连续性、黑屏、冻结、标注覆盖率和传感器数据。 | | |
| #### 导出模块（Export） | |
| | 前端模块 | 输入端 | 输出端 | 用途与规则 | | |
| | --- | --- | --- | --- | | |
| | `LeRobot Export` | `Exportable Data` | `Dataset` | 导出 LeRobot v2.1 或 v3.0；版本在节点上选择。 | | |
| | `HDF5 Export` | `Exportable Data` | `Dataset` | 使用配置的压缩参数导出 HDF5 数据集。 | | |
| #### Workflow Studio 界面功能 | |
| <details> | |
| <summary>点击展开：前端界面组件说明</summary> | |
| | 界面组件 | 功能 | | |
| | --- | --- | | |
| | `NodePalette` | 按 Input、Process、Review、Export 分类显示节点；支持搜索、分类折叠和悬停说明。 | | |
| | `WorkflowCanvas` | 支持拖拽创建节点、端口连线、移动、选择、缩放、网格对齐和小地图导航。 | | |
| | `WorkflowNode` | 渲染卡片标题、输入输出端口、项目设备选择/输入框、`Spatial` 和 API 设置按钮。 | | |
| | `WorkflowDrawer` | 查看工作流列表、创建和加载工作流，并刷新当前项目的输入源。 | | |
| | `PipelineToolbar` | 提供新建、保存、另存为、导出工作流 JSON 和运行操作；黄色圆点表示有未保存修改。 | | |
| | `NodeSettingsModal` | 配置 AI Annotation 的 API 厂商、模型、地址和密钥字段。 | | |
| | `DeletableEdge` | 显示数据连接线；选中后可以删除。 | | |
| 设备选择始终绑定当前项目。新的空工作流不会显示其他项目的设备；数据上传后，每个卡片 | |
| 的选择框只显示与该卡片 RGB、RGB-D、双目或手套类型匹配的真实数据源。 | |
| </details> | |
| ### 审核与执行规则 | |
| 输入端和输出端必须按照端口名称连接。没有输入连接的处理分支直接跳过，不影响其他分支。 | |
| 只有在 RGB Video 和 Depth 都可用时，RGB-D 3D 才会产生真实 metric 3D 数据。 | |
| 节点状态限制为： | |
| ```text | |
| Connected | |
| Processing | |
| Completed | |
| Skipped · Missing Input | |
| Completed with Warning | |
| ``` | |
| </details> | |
| ## 6. 处理结果保存 | |
| <details> | |
| <summary>点击展开：处理结果、上传解压和清理规则</summary> | |
| Worker 完成处理后，结果合并到对应 Episode： | |
| ```text | |
| data/chunk-000/episode_000000.parquet | |
| └── 2D 关键点、metric 3D、传感器和标注字段 | |
| meta/episodes/chunk-000/episode_000000.parquet | |
| └── processing_*、run_id、节点状态和输出索引 | |
| ``` | |
| 原始 RGB/Depth 视频不会被覆盖。手部关键点预览在浏览器中叠加到原始 RGB 视频上，不保存 | |
| 第二份骨骼视频。系统级运行记录位于 `data/state/runs/`，导出临时产品位于 | |
| `data/state/exports/`；两者都不属于项目数据集目录。 | |
| 上传压缩包的流程为：接收 → 解压 → 规范化 → 写入项目 → 校验 → 更新状态。只有完整解压、 | |
| 原子提交和校验全部成功后，上传临时文件和解压临时目录才会清理；失败时保留暂存内容供 | |
| 重试和诊断。 | |
| </details> | |
| ## 7. 安装与启动 | |
| ### Linux | |
| ```bash | |
| cd "processor" | |
| cp .env.example .env | |
| # 编辑 .env，设置 API_KEY、WORKER_API_KEY、JWT_SECRET 和存储配置。 | |
| chmod +x deploy.sh | |
| ./deploy.sh | |
| ``` | |
| 常用参数： | |
| ```bash | |
| python deploy.py --check-only # 只检查，不安装、不修改配置、不启动服务。 | |
| python deploy.py --skip-vllm # 不启动本地 VLM，AI 标注使用 API。 | |
| python deploy.py --no-services # 前台运行，不安装自启动服务。 | |
| ``` | |
| 当前 AI 标注部署使用 API。使用 `--skip-vllm`，然后在 Workflow Studio 的 | |
| `AI Annotation` 设置中配置 API 厂商、模型和地址。 | |
| ### Windows | |
| ```bat | |
| cd /d "processor" | |
| copy .env.example .env && deploy.bat | |
| ``` | |
| ### 手动启动后端 | |
| ```bash | |
| cd "processor" | |
| source .venv-linux/bin/activate | |
| export PYTHONPATH="$PWD" | |
| ./scripts/run_backend_linux.sh | |
| ``` | |
| 也可以直接运行： | |
| ```bash | |
| uvicorn app.main:app --host 0.0.0.0 --port 8000 | |
| ``` | |
| ### 启动 Worker | |
| ```bash | |
| cd "processor" | |
| export EGODATA_SERVER_URL=http://127.0.0.1:8000 | |
| export EGODATA_WORKER_API_KEY='与服务端一致的 Worker API Key' | |
| ./scripts/run_worker_linux.sh | |
| ``` | |
| Windows 使用 `scripts/run_worker_windows.ps1`。Linux 和 Windows 的虚拟环境相互独立， | |
| 不能跨系统复制。 | |
| ### Workflow Studio | |
| ```bash | |
| cd "processor/web/workflow-studio" | |
| npm ci | |
| npm run dev | |
| ``` | |
| 生产构建： | |
| ```bash | |
| npm run build | |
| ``` | |
| 构建产物写入 `web/static/workflow-studio/`，由 FastAPI 页面服务加载。 | |
| ## 8. 配置 | |
| <details> | |
| <summary>点击展开：环境变量和安全配置</summary> | |
| 配置写入 `processor/.env` 或环境变量，不提交到仓库： | |
| | 配置 | 作用 | | |
| | --- | --- | | |
| | `STORAGE_DIR` | 数据和系统状态根目录 | | |
| | `STORAGE_BACKEND` | `local` 或 `sftp` | | |
| | `SFTP_*` | 远端数据目录和 SSH 连接配置 | | |
| | `API_KEY` | 采集端和受保护接口的 API Key | | |
| | `WORKER_API_KEY` | Worker 领取和回传任务使用的 API Key | | |
| | `JWT_SECRET` | Web 登录态签名密钥 | | |
| | `UPLOAD_STAGING_DIR` | 上传压缩包的本地暂存目录 | | |
| | `HOST` / `PORT` | Web/API 监听地址和端口 | | |
| | `PUBLIC_BASE_URL` | 对外访问地址 | | |
| 完整模板见 [`.env.example`](.env.example)。生产环境必须使用随机密钥并限制 `.env` 权限。 | |
| 不要在日志、工作流 JSON、前端代码或文档中写入密码、Token、API Key 和数据库凭据。 | |
| </details> | |
| ## 9. API | |
| <details> | |
| <summary>点击展开：主要 API 和 OpenAPI 文档</summary> | |
| 服务启动后可访问： | |
| ```text | |
| GET /health | |
| GET /docs | |
| GET /openapi.json | |
| ``` | |
| 主要 API 分组： | |
| ```text | |
| /api/v1/auth/* 登录和认证 | |
| /api/v1/projects/* 项目和 Episode | |
| /api/v1/workflows/* 工作流定义 | |
| /api/v1/session/* 采集端上传 | |
| /api/v1/video/* 视频、深度和关键点预览 | |
| /api/v1/annotations/* 标注和审核 | |
| /api/v1/export/* 数据导出 | |
| /api/v1/worker/* Worker 任务领取与回传 | |
| ``` | |
| 完整接口契约以运行中的 FastAPI OpenAPI 文档为准。 | |
| </details> | |
| ## 10. 测试与排障 | |
| <details> | |
| <summary>点击展开：测试命令和常见排障步骤</summary> | |
| 后端和 Worker 基础检查： | |
| ```bash | |
| cd "processor" | |
| python -m compileall app worker | |
| python deploy.py --check-only | |
| PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q tests/test_depth_codec.py | |
| ``` | |
| 前端检查： | |
| ```bash | |
| cd "processor/web/workflow-studio" | |
| npm run build | |
| ``` | |
| 排障顺序： | |
| 1. 访问 `/health`，确认服务和存储可用； | |
| 2. 检查 `STORAGE_DIR` 是否指向实际数据目录； | |
| 3. 检查上传状态和当前 Episode 的实际文件； | |
| 4. 检查 Worker 是否在线、能领取任务并发送心跳； | |
| 5. 检查 `data`、`meta/episodes`、`videos` 的 Episode 编号是否一致； | |
| 6. RGB-D 3D 节点检查 `RGB Video` 和 `Depth` 是否分别接线； | |
| 7. 深度预览异常时检查视频是否为 `gray12le`，不要把伪彩色预览当作原始深度数据。 | |
| </details> | |
| ## 11. 版本约定 | |
| <details> | |
| <summary>点击展开：版本维护规则</summary> | |
| - 后端版本在 `app/version.py` 中维护，**只管后端**； | |
| - **前端版本在 `web/VERSION` 中维护**。它覆盖 `processor/web/` 下的全部前端代码 | |
| （`templates/`、`static/`、`workflow-studio/`），**不只是那个 React SPA**。 | |
| `web/workflow-studio/package.json` 里的 version 只代表 SPA 自己，三者互相独立、不必同步。 | |
| - **改了前端就只 bump `web/VERSION` 这一个文件**。它一个号管两件事： | |
| ① 模板里的 `?v={{ asset_version }}` 缓存键（读了它浏览器才会重新拉 JS/CSS） | |
| ② 提交信息里的「前端 X」。 | |
| 两个用途共用一个数，不会出现"提交信息写 1.12.3、浏览器却拿 1.12.2"这种对不上的情况。 | |
| 改前端**不需要**动后端版本号。 | |
| - 改完 `web/VERSION` 要**重启服务**才生效（`app/web_version.py` 启动时读一次就缓存）。 | |
| - 修复和小调整增加修订号；新增功能增加次版本号；重大架构变更增加主版本号； | |
| - 发布前应同步记录软件版本、数据格式和 API 变化。 | |
| 当前版本：后端 `1.19.4`，前端 `1.12.3`。 | |
| </details> | |