FBddcz / embodied-jev

# 🤖 EmbodiedJev · 行知
## 🌐 点击进入在线实验展示 →
**🎬 直接看真实录像 · 🆚 对比模型决策 · ⚡ 看速度 · 💰 看费用**
**无需安装，打开就能看。** 🤝 欢迎分享你的复现，展示 **名字 · GitHub 账号 · 日期 · 任务 · 方法 · 结果**！
🎥 浏览实验 · 🧑‍🔬 社区作品 · 📖 投稿与复现指南
### 把具身 AI 实验，搬到你的浏览器里。
**📦 开箱体验三大仿真任务 · 🧠 本地小模型 / 云端 API · 🎮 看得见的每一步决策**
无需机械臂，无需先训练模型。跟着步骤启动，在自己的电脑上体验「观察 → 决策 → 执行 → 反馈」。
🚀 快速上手 · 🧠 接入模型 · 📊 实测结果 · 🤝 一起维护
**行而有据，知而能行。**
如果这个项目帮你迈出了具身 AI 的第一步，欢迎点一颗 **⭐ Star**，让更多人一起玩、一起改！
## ✨ 打开行知，你能做什么？
- 📦 **先玩起来，再接模型**：内置规则基线，无需 API Key、GPU 或模型权重，即可运行三个任务。首次安装依赖需要联网。
- 🦾 **真实物理交互**：MuJoCo + Franka Panda，夹爪接触、抓取、搬运和放置都有物理反馈。
- 🧠 **模型入口放在界面里**：可接 TypeSafe Jev、Claude 原生 API、OpenAI 兼容 API，以及本地 MiniCPM5-2B。
- 👀 **决策过程看得见**：查看阶段或短步选择、公开的动作说明、调用次数与延迟；有原生候选概率的接口还会显示概率。
- 🧭 **逐步规划也能试**：模型逐轮选择 XYZ 方向、步长和夹爪动作，执行后重新观测；可用原始图像输入并加入中途扰动。
- 📷 **相机自由组合**：仅外部、仅腕部、双相机或无相机；启用的视角按动作边界更新，腕部相机随手移动。
- 🆚 **同一任务，不同模型**：可选 2–3 路独立实验，统一任务和种子，真实运行后按仿真时间对齐回放。
- 🧩 **按自己的想法扩展**：多套具名模型接口、任务/场景预设、JSON 导入导出与独立输入测试，方便二次开发。
- 🧪 **执行前先预演**：在仿真副本里检查候选动作，拦截已配置的碰撞和抓取丢失情况。
- ⏯️ **实验随手控制**：运行、暂停、单步、停止、重置、轨迹回放、JSON 导出，一站完成。
- 💻 **本地工作台**：浏览器交互，桌面与手机尺寸均有适配；数据由本机服务处理，调用云端模型时发送任务状态，直接图像模式还发送已启用相机的 RGB。
## 🎯 三个任务，感受完整闭环
| 任务 | 你会看到什么 |
| --- | --- |
| 📥 搬运入盘 | 抓住红色方块，搬到蓝色托盘，松爪并撤离 |
| 🧱 方块堆叠 | 将红色方块放在固定蓝色方块上，检查支撑与稳定状态 |
| 🚧 越障搬运 | 抬高物体、越过障碍，再放到目标位置 |
抓取依靠双侧夹爪接触，成功由物理状态判定。页面中的“验证通过”对应实际仿真检查。
## 🧭 方法论：模型做选择，物理验证结果
每次动作之后重新观察，再决定下一步。模型负责当前选择；控制器负责动作转换与执行，成功由独立的物理条件判定。
 [code] 
| 控制模式 | 模型输入 | 模型输出 |
| --- | --- | --- |
| 预设技能 | 结构化状态或 RGB-D 检测坐标、可用技能 | 阶段与技能选择 |
| 逐步 XYZ | 状态、RGB-D 检测坐标，或已启用相机的 RGB | 一个 XYZ／夹爪短步候选 |
| 分层 XYZ | 状态或 RGB-D 检测坐标、接触事实、近期动作 | 子目标，再分别选择 X／Y／Z／夹爪方向 |
| 规则基线 | 同模式的可用观测 | 由程序选动作，零模型调用 |
原始图像目前只用于支持图像的 Chat／Claude 逐步模式；Jev 接收结构化文本，RGB-D 坐标来自本地检测器。无相机时使用结构化状态，外部／腕部相机可单独或同时启用。候选、几何计算与安全检查属于控制程序，不计作模型学到的能力。
## 🚀 零机器人基础，快速上手
**准备好 Python 3.11+、Node.js 22.12+ 和 Git。** 不需要机器人硬件，也不要求懂 MuJoCo。
### 1️⃣ 下载项目
 [code] 
### 2️⃣ 安装并启动
macOS / Linux：
 [code] 
 🪟 Windows PowerShell 命令 
 [code] 
Windows 提供上述启动方式；当前已验证的环境为 macOS 与 Linux CI。
### 3️⃣ 打开页面，运行第一个实验
访问 **http://127.0.0.1:8090** → 选择任务 → 保持“规则基线” → 点击 **运行实验**。🎉
拖动场景调整视角，单步查看动作，运行结束后拖动时间轴回放。右上角可导出实验 JSON。
> 💡 默认演示由规则策略决策，模型调用数为 **0**。接入并选择模型后，才会进行模型决策。浏览器标签页共享本机的单实验与对比实验；两种视图各自保留状态。
## 🆚 一屏对比：同一任务，不同决策
打开顶部 **模型对比**，选择 2–3 个模型，统一任务、种子和动作预算，再开始实验。没有 Key？可以先用两路规则基线体验完整操作。
*图中为双规则基线的界面示例，非云端模型对比成绩。*
- 🎛️ **自己选模型**：MiniCPM、Jev、GPT、Claude 等已配置入口；同一 API 也能填写不同模型 ID。
- 🍎 **依次 / 并行可选**：默认依次运行；并行最多两路，本地 MiniCPM 推理仍共用模型锁。
- 👀 **实时看差异**：每路独立机械臂场景、阶段、动作和运行状态，模型各自推进。
- ⏯️ **对齐看轨迹**：暂停或结束后，沿同一仿真时间回放；实际耗时保留模型等待，不能拿回放速度当推理速度。
- 📁 **记录带走**：导出各路配置、决策和轨迹。未接通的模型不生成模拟成绩，未知费用也不会显示为 0 美元。
接入方法和比较边界见 **模型对比指南**。完整轨迹回放来自这次运行，服务重启后需重新实验；目前还没有导入历史文件的入口。
## 🧠 给机械臂接上模型
| 方式 | 适合谁 | 需要准备 |
| --- | --- | --- |
| 🎮 规则基线 | 想先体验仿真和界面 | 安装项目即可 |
| 🍎 MiniCPM5-2B 本地 | 想研究小模型的决策能力 | 下载权重、安装本地推理依赖 |
| ⚡ TypeSafe Jev | 已有 TypeSafe 账号 | 官方 API Key |
| 🌐 OpenAI 兼容 API | 已有云端平台或本地服务 | Base URL、模型 ID、API Key |
| 🟠 Claude 原生 API | 想直接调用 Anthropic 模型 | Anthropic API Key、模型 ID |
| 🔌 结构化决策 API | 已有返回候选概率的服务 | 接口地址与协议适配 |
### 🌐 已有 API？在界面里填就行
点击 **决策模型** 旁边的插头图标