GraspFruit

面向原生 Windows 的闭环水果抓取实验：自然语言关系指令由 VLM 定位目标，SAM 2.1 生成实例掩码，GraspNet 预测 6D 抓取，MuJoCo 中的 UR5e + Robotiq 2F-85 完成抓放， 最后通过视觉证据验证抓取和入篮结果。

当前场景包含 3 个苹果、3 根香蕉、3 只青绿色鸭梨，以及蓝、绿两个果篮。 固定映射为苹果→蓝框，香蕉和鸭梨→绿框。MuJoCo 真值只用于测试与 episode 结束后的评分，不参与运行时决策。

Demo

v0.1 · 单件抓放

Apple → blue bin	Banana → green bin
30 FPS MP4	30 FPS MP4

GIF 为约 1.5× 加速预览；MP4 保留真实仿真时长。两个演示均使用 VLM API + SAM2 + GraspNet，不是 mock perception。

v0.2 · 9 件水果全量分拣

俯视决策视角	前向展示视角
2× MP4	2× MP4

v0.2 在同一场景中完成 9/9 全量分拣：3 个苹果进入蓝框，3 根香蕉和 3 只青绿色 鸭梨进入绿框。俯视画面是 Qwen3-VL、SAM2 和抓取规划使用的视觉信号；前向画面仅同步 录制用于展示。两列演示均为 2× 加速，完整闭环仍逐件执行观察、抓放和视觉验证。

Pipeline

OBSERVE → GROUND → SEGMENT → PLAN_GRASP → PICK → VERIFY_PICK
        → PLACE → VERIFY_PLACE → DONE / RETRY / FAILED

• Ground：OpenAI-compatible 多模态 API 输出经 Pydantic 校验的目标框和果篮。
• Segment：SAM 2.1 base+ 接收框提示，按质量、框覆盖率和有效深度选掩码。
• Plan：目标掩码点云进入 GraspNet；候选依次经过碰撞、NMS、宽度、接近方向和 完整 IK 路径过滤。
• Execute：官方 UR5e/2F-85 模型执行预抓取、下降、闭合、抬升、入篮、释放、撤离。
• Verify：图像运动验证抓取，果篮区域深度变化验证放置；失败最多重试五次。

已验证环境

• Windows 11 x64
• Python 3.11
• PyTorch 2.10.0+cu128 / torchvision 0.25.0+cu128
• CUDA Toolkit 12.8
• Visual Studio 2022 v143 / MSVC 14.39
• RTX 5060 Laptop GPU (sm_120)
• MuJoCo 3.11.0

其他 CUDA/PyTorch 组合可能可用，但未在本仓库验证。

安装

1. 创建环境

conda env create -f environment-windows.yml
conda activate graspfruit
python -m pip install torch==2.10.0 torchvision==0.25.0 `
  --index-url https://download.pytorch.org/whl/cu128

2. 编译 Windows 依赖

从 x64 Native Tools Command Prompt for VS 2022 进入仓库，再运行：

call C:\Users\<YOU>\anaconda3\Scripts\activate.bat graspfruit
powershell -ExecutionPolicy Bypass -File scripts\setup_windows.ps1

脚本会获取固定版本的 SAM2、GraspNet baseline 和 GraspNetAPI，并应用 Windows/MSVC 兼容补丁。third_party/ 不提交到仓库。

3. 放置权重

GraspNet 权重不随仓库发布。接受其官方非商业研究许可后，将文件放到：

checkpoints/graspnet/checkpoint-rs.tar

也可使用：

powershell scripts\download_models.ps1 -CheckpointUrl "<official-direct-url>"

SAM2 权重在首次加载时由 Hugging Face 下载并缓存。

4. 配置 VLM API

API Key 只从环境变量读取，不要写入 YAML 或提交到 Git：

$env:GRASPFRUIT_VLM_API_KEY = "sk-..."
$env:GRASPFRUIT_VLM_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:GRASPFRUIT_VLM_MODEL = "qwen3-vl-plus"

如需持久保存，可使用 Windows 用户环境变量；重启终端后才会生效。

5. 环境检查

python -m graspfruit.env_check --strict
python scripts\validate_pick_place.py
python -m pytest -q

validate_pick_place.py 不调用 VLM/SAM/GraspNet，只验证机器人、真实网格、夹爪接触和 两个果篮；完整模型运行前应先通过这一硬闸门。

运行

全量分拣 9 个水果（功能 1）：

python -m graspfruit.demo --sort-all --seed 7 --record

全量模式会对每件水果重新执行观察、定位、分割、抓取规划、抓放和视觉验证；任一件未验证即停止， 最终结果写入 sort_result.json。项目级 Agent 操作约束见 .agents/skills/graspfruit-sort-all/SKILL.md。

单件自然语言抓放：

python -m graspfruit.demo `
  --command "把香蕉左边较小的苹果放进蓝色篮子" `
  --seed 7 `
  --record

不传 --command 时进入终端交互。--headless 关闭 Viewer。--record 会生成：

• replay.mp4：按仿真时间采样的连续 30 FPS 动作；
• presentation_replay.mp4：与俯视流同步的前向展示视角，仅用于观看，不参与视觉决策；
• summary.mp4：抓前、掩码、抓后和放后等关键帧摘要；
• RGB-D、VLM 原始/解析输出、SAM 掩码、候选、事件日志和 result.json。

运行产物写入 runs/，该目录默认不纳入 Git。

关键代码

graspfruit/
├── pipeline.py          # 闭环状态机、安全边界和重试
├── vlm.py               # OpenAI-compatible VLM + JSON schema
├── segmentation.py      # SAM2 框提示和稀疏关键帧跟踪
├── grasping.py          # 点云、GraspNet 推理和候选过滤
├── simulation.py        # UR5e/2F-85、IK、执行和连续录制
├── scene_builder.py     # 明亮场景、YCB 水果和果篮
└── verification.py      # 抓取/放置视觉验证

开发期可用 --mock-perception 跳过重模型，但结果会明确标记为 mock，不能计入正式实验。 固定种子批处理见 python -m graspfruit.batch --seeds 24。

Windows 踩坑

1. PowerShell 不能使用 call：call activate.bat 是 CMD 语法。在 PowerShell 用 conda activate graspfruit；或直接从 x64 VS Developer CMD 执行安装。
2. cl.exe not found：普通终端没有 MSVC 环境。必须打开 x64 VS Developer shell， 并确认 cl 显示 19.39.x。
3. PyTorch wheel 不等于 CUDA Toolkit：wheel 可运行 CUDA，但编译 PointNet++ 仍需 nvcc --version 可用。扩展成功后，普通推理终端不需要一直把 cl/nvcc 放在 PATH。
4. RTX 50 系列：构建前设置 TORCH_CUDA_ARCH_LIST=12.0。安装脚本已经代设。
5. 不要安装旧 k-NN 扩展：在线推理只需 PointNet++；旧 k-NN 是标签生成路径，容易在 新 PyTorch/Windows 上失败。
6. GraspNet 坐标约定：GraspNet local X 是接近轴，官方 Robotiq pinch TCP 的 local Z 是接近轴。直接把旋转矩阵交给 IK 会造成腕部错误姿态，本项目在机器人适配层转换。
7. 规划时机械臂乱动：不要在 Viewer 使用的 MjData 上迭代 IK。本项目使用独立规划 状态，规划为空时严格不发机器人命令。
8. 视频像幻灯片：关键帧不能充当动作录像。本项目在 MuJoCo _step 中按仿真时间 30 FPS 采样；summary.mp4 才是稀疏摘要。
9. 中文终端乱码：CMD 可先执行 chcp 65001 和 set PYTHONUTF8=1；PowerShell 7 通常默认 UTF-8。
10. Hugging Face 警告：未登录也能下载 SAM2；配置 HF_TOKEN 只影响限速，不影响模型。

更完整的安装和实验说明见 Windows setup 与 experiment protocol。

来源与许可

项目代码采用 MIT License。第三方组件和资产保留各自许可：

• 流程参考：VLM_Grasp_Interactive， 未复制其实现；
• UR5e 与 Robotiq 2F-85：MuJoCo Menagerie， 随附各模型许可；
• 苹果/香蕉/鸭梨：YCB Object and Model Set，本仓库使用的 扫描网格来自标记为 CC BY 4.0 的 ai-habitat/ycb 镜像，详见 graspfruit/assets/ycb;
• SAM2：Apache-2.0；
• GraspNet baseline、API 和 checkpoint：遵循各自官方许可，其中 baseline/checkpoint 仅限非商业研究用途，源码与权重不随本仓库再分发。

公开发布或商用前，请自行复核所有第三方条款。