# Embodied-VLM-Explorer

**Repository Path**: my420254/Embodied-VLM-Explorer

## Basic Information

- **Project Name**: Embodied-VLM-Explorer
- **Description**: 具身 VLM/VLA 路线预研：一步一观测任务执行探索
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Embodied-VLM-Explorer

面向具身任务的 VLM / VLA 闭环预研项目。该项目用于验证“看一帧、生成一步动作、执行后再观察”的视觉语言动作路线，重点关注模型决策、动作接口、执行反馈和状态闭环，而不是完整替代底层感知、抓取、导航和运动规划系统。

## 项目定位

具身智能系统可以有两条典型路线：

- 端到端 VLA：图像和指令直接输入模型，模型输出机器人动作；
- 模块化 Agent Runtime：感知、状态、规划、技能、执行和反思分层解耦。

本项目是第一条路线的轻量预研版本。它把 VLM/VLA 闭环抽象成一个最小可运行流程：

```text
Instruction + Observation
  -> VLM / Policy
  -> Next Skill Action
  -> Action Validator
  -> Simulator / Robot Bridge
  -> Updated Observation
```

通过这个预研，可以清楚看到 VLM/VLA 路线的优点和边界：它能把视觉、语言和动作压到统一接口里，但在低延迟、长程状态记忆、动作可控性、错误恢复和可复现实验上会遇到明显工程挑战。

## 预研结论

| 观察 | 结论 |
| --- | --- |
| VLM/VLA 能把视觉状态、语言任务和下一步动作统一到一个接口 | 适合做快速原型和候选动作生成 |
| 每一步都调用视觉语言模型会带来明显延迟 | 高并发或实时控制场景需要 runtime 做缓存、任务状态和技能约束 |
| 单帧 observation 缺少长程任务记忆 | 需要显式 history、state diff 和 checkpoint |
| 模型输出动作不一定可执行 | 必须经过 action validator、skill contract 和底层 affordance 检查 |
| 出错后很难定位是感知错、规划错还是执行错 | 后续需要拆分 Understanding / Planning / Execution / Reflection |

因此这个仓库的价值不是作为最终方案，而是把早期端到端路线的边界验证清楚，为后续 ALFRED SFT 和 Embodied Agent Runtime 提供选型依据。

## 与后续工作的关系

该项目对应具身任务探索的早期阶段，后续工作自然演进为两条更稳定的路线：

- **ALFRED SFT**：将原始轨迹清洗成 `Goal + History + Observation -> Next Action` 数据，用 Qwen2.5-7B-Instruct + LoRA 训练下一步宏动作模型；
- **Embodied Agent Runtime**：用 LangGraph、CommandBus、任务栈、中断恢复和反思重试，将任务执行从单步预测升级为可常驻运行的系统框架。

因此，`Embodied-VLM-Explorer` 的价值不是展示最终系统，而是解释为什么具身智能研发需要从端到端闭环探索，逐步转向更可控的结构化数据和分层运行时。

## 参考路线

本项目的路线设计参考了以下公开研究和开源工程，但代码为独立轻量实现：

| 参考项目 | 核心思路 | 可借鉴点 |
| --- | --- | --- |
| [OpenVLA](https://github.com/openvla/openvla) | 开源 Vision-Language-Action 模型，支持 LoRA / full fine-tuning 和 REST 部署 | VLA 输入输出格式、LoRA 微调、远程模型服务 |
| [VoxPoser](https://github.com/huangwl18/VoxPoser) | LLM/VLM 生成 3D value maps，再由 planner/controller 执行 | 语言约束、空间价值图、感知与控制接口分离 |
| [ReKep](https://github.com/huangwl18/ReKep) | VLM 生成关系关键点约束，闭环优化机器人轨迹 | 关键点约束、扰动恢复、闭环 replanning |
| [SayCan reimplementation](https://github.com/Yuito-sug/saycan-reimplementation) | 语言模型结合 affordance 选择可执行技能 | 技能库、可行性打分、语言规划和底层能力对齐 |

## 当前实现

仓库提供一个无外部依赖的 Python tabletop simulator，用来演示最小闭环：

- `Observation`：机器人位置、手持物、可见物体和物体位置；
- `RuleBasedVLMPolicy`：代替真实 VLM/VLA 输出下一步动作；
- `TabletopSimulator`：执行 `NavigateTo`、`Pickup`、`Put` 并更新环境；
- `StepTrace`：记录每一步 observation summary、动作、执行结果和错误信息；
- `frontend/`：Vue3 轨迹面板骨架，展示如何把闭环事件渲染给前端。

```mermaid
flowchart LR
    A[Task Instruction] --> B[Observation]
    B --> C[Policy / VLM Adapter]
    C --> D[Skill Action]
    D --> E[Action Validator]
    E --> F[Tabletop Simulator]
    F --> G[Execution Result]
    G --> H[StepTrace]
    G --> B
```

## 代码模块

| 模块 | 说明 |
| --- | --- |
| `embodied_vlm_explorer/config.py` | 桌面场景、物体、位置和默认任务配置 |
| `embodied_vlm_explorer/schemas.py` | `Observation`、`SkillAction`、`StepTrace` 等结构定义 |
| `embodied_vlm_explorer/perception.py` | observation 摘要和状态抽取 |
| `embodied_vlm_explorer/policy.py` | rule-based VLM policy，占位真实 VLM/VLA |
| `embodied_vlm_explorer/simulator.py` | `NavigateTo`、`Pickup`、`Put` 的状态更新逻辑 |
| `embodied_vlm_explorer/runner.py` | 闭环执行器，组织 observation -> action -> feedback |
| `frontend/` | Vue3 前端轨迹面板骨架 |

## 运行方式

```bash
python scripts/run_demo.py --task "把土豆放到盘子里"
```

输出示例：

```text
task: 把土豆放到盘子里
success: True
[step 0] NavigateTo('counter') -> True: navigated to counter
[step 1] Pickup('potato_01') -> True: picked up potato_01
[step 2] NavigateTo('table') -> True: navigated to table
[step 3] Put('potato_01', 'plate_01') -> True: placed potato_01 on plate_01
```

结构化输出：

```bash
python scripts/run_demo.py --task "把土豆放到盘子里" --json
```

## 测试

```bash
python -m pytest tests
```

如果本地没有 `pytest`，可以先运行：

```bash
python scripts/run_demo.py --task "把土豆放到盘子里" --json
```

## 技术边界

当前仓库刻意保持轻量，不包含以下模块：

- 真实 RGB-D 感知；
- 目标检测、分割、关键点跟踪；
- 机械臂 IK、抓取姿态估计、底盘路径规划；
- ROS2 action server；
- 大模型在线推理服务。

这些模块在真实机器人系统中必须由独立组件承担。项目的核心价值是把上层 VLM/VLA 任务闭环、动作接口和状态反馈抽象清楚，为后续 ALFRED SFT 和 LangGraph runtime 提供路线依据。

## 与后续系统的衔接

| 阶段 | 项目 | 解决的问题 |
| --- | --- | --- |
| 路线预研 | `Embodied-VLM-Explorer` | 验证看一步做一步、动作接口、状态回写和路线边界 |
| 模型微调 | [`ALFRED-SFT-Brain`](https://github.com/my420254/ALFRED-SFT-Brain) | 用结构化轨迹训练下一步宏动作模型 |
| 运行时框架 | [`Embodied-Agent-Runtime`](https://github.com/my420254/Embodied-Agent-Runtime) | 解决常驻监听、中断恢复、取消暂停、失败反思和外部系统接入 |

这三个阶段共同表达一个清晰技术路线：先验证端到端视觉闭环的可能性，再用 ALFRED 构造可评测的结构化动作预测任务，最后用 LangGraph runtime 把模型能力放进可长期运行的任务系统。

## 许可

MIT License.