【2026 最新】Show-Harness × GUMI 模擬器教學：沒有機械臂也能驗收 VLM Agent

想試「看畫面、自己決定下一步」的機器人 Agent，通常第一個阻力不是模型，而是硬體：機械臂、相機、校正與安全空間一樣都不能少。Show-Harness 把問題拆成可讀的語意動作介面；它附帶的 GUMI 模擬器，則讓你先在瀏覽器裡練習抓取、放置、記錄與攔截錯誤。

這篇會帶你完成一條「完全不接實體機械臂」的最小路徑：安裝 base 環境、用鍵盤錄一條 rollout、接 OpenAI-compatible 的 hosted／local VLM 做一次不出手的 dry run，最後用 10 次任務驗收表判斷系統是否值得繼續。你會得到一份能重跑、能抽查、也能及時停手的最小實驗。本文以 2026 年 9 月 14 日取得的官方 commit 137d571 為準；模擬成功只代表這個 synthetic scene 的控制與記錄管線通過，不等於實體安全或模型能力已通過。

GUMI 模擬器的控制迴圈

VLM Robot Agent ＝ 看畫面 → 選一個 semantic action → interpreter 執行 → 再看一次。

VLM 不必直接輸出馬達電流或關節角度，只要選 MV_FWD、MV_DOWN、GRASP、RELEASE 等有限詞彙。interpreter 再把同一個詞翻成特定機械臂的座標與控制命令。這就是 AI Agent Harness 的核心：把模型能做的事縮成可驗證、可拒絕的動作集合。若你想先補齊「觀察、狀態、動作與 rollout」的概念，可搭配 World Model 世界模型入門。

Show-Harness 與 GUMI 模擬器各自負責什麼？

Show-Harness 官方專案頁把系統分成 VLM、semantic action interface 與 embodiment-specific interpreter。論文的抽象介面包含六個平移方向、抓取、釋放、完成，以及可選的旋轉；但目前公開 rotation plugin 實作的是固定 base-Z yaw，不能把論文描述的多軸旋轉直接當成已交付功能。

把 semantic action 想成「意圖」，interpreter 才是「地方口音」。例如 MV_LEFT 對模型永遠代表往左，但不同 embodiment 的 base-frame 軸與正負號可以不同；公開的 Franka 與 Piper primitive 設定就不是同一個 Y 軸方向，而且 Piper 設定還把 lateral mapping 標成未驗證。這也是 harness 比直接叫模型吐座標更實用的原因：換硬體時應重驗翻譯層，不必讓模型重新學一套自然語言。

GUMI 是收集層：在動作執行前保存 agent view、wrist view、token、末端位姿與夾爪狀態，再寫入 actions.jsonl、metadata.json 和影片。它留下的是可轉換的訓練 pair，不是「完全免整理」的成品資料集；官方 converter 還會套 prompt、整理影像，並在 episode 末端合成 DONE。想看實機與 sim-to-real 的落差，可延伸讀 Microduck Sim-to-Real 分析與 Gemini Robotics 2 解讀。

「動作前保存」不是小細節。訓練時要回答的是「看到這一幀，下一步該選什麼」，所以第 t 列應對應 observation_t 與 action_t。另一方面，這也表示 log 裡有一列並不自動證明控制器完成了那個動作；執行錯誤、人工取消與任務失敗仍要靠事件、metadata 和影片交叉檢查。

步驟一：安裝乾淨的 base 環境

先準備 Git、Python 3.10 以上與一個現代瀏覽器。以下依照官方 README，並固定到本文驗證過的 commit，避免日後 main 分支變動造成指令漂移：

git clone https://github.com/showlab/Show-Harness.git
cd Show-Harness
git checkout 137d5718c3b7af0150764d8f9beeb252c9f2794a
bash scripts/setup.sh base

AlphaLab 在全新 clone 重跑官方 --sim 範例時，預設的configs/robot_piper.yaml仍會要求 repository 未提供的 configs/site/piper_arms.yaml，因此先出現 FileNotFoundError。最小繞法不是捏造實機校正，而是建立一份只含 VLM profile、沒有 site layer 的 sim 設定：

# /tmp/show-harness-sim.yaml
vlm_backend: sandbox
vlm_backends:
  sandbox:
    provider: openai
    base_url: http://127.0.0.1:8000/v1
    model: YOUR_VISION_MODEL
    api_key_env: SHOW_HARNESS_VLM_KEY

這份檔案只是避開缺失的實機 site layer，並替後面的 VLM operator 留一個 profile；它沒有任何機械臂校正值。接著啟動單臂 synthetic scene：

.venv/bin/python gumi/collect_rollouts_web.py data/rollouts_demo \
  --sim \
  --host 127.0.0.1 \
  --port 8600 \
  --seed 7 \
  --robot-config /tmp/show-harness-sim.yaml

只綁 127.0.0.1 很重要：GUMI 官方說明明確提醒 server 沒有驗證機制，不應直接暴露到不受信任的網路。瀏覽器開啟 http://127.0.0.1:8600，看到橘色目標方塊、灰色干擾方塊與藍色放置盤，就完成第一關。

步驟二：先用 GUMI 模擬器錄一條 rollout

先按 Start recording，再用 W／S／A／D 前後左右、R／F 或方向鍵上下、Z／X 旋轉、Space 切換抓取與釋放。每次移動在這個 GUMI scene 是 2 公分；位置也落在 2 公分格點上。瀏覽器按鍵與文字／API alias 並不完全相同：API 的上下是 Q／E，而 R 在 API 代表 RELEASE。寫自動化時一律送完整 token，最不容易誤觸。

官方 sim 程式的成功條件很具體：夾爪水平距離橘方塊不超過 3.5 公分、距桌面高度不超過 6 公分時才能抓取；放下後，橘方塊中心距藍盤中心不超過 4.5 公分才會開啟 CAN_STOP。看到綠色 TASK DONE 後再 Stop & Save，別在中途直接把失敗軌跡當成成功樣本。

第一條不用追求最短路徑。先從 agent view 判斷大方向，用 wrist view 做最後對齊；一次移動一格，抓取後先抬高，再移向藍盤並釋放。成功時應同時看到 task_done: true 與 can_stop: true；只看到「Released」不算。每次 --seed 或重置後配置可能不同，請依畫面決策，不要照抄本文的 30 步序列。

存檔後檢查 data/rollouts_demo/rollout_000/：至少應有 actions.jsonl、metadata.json、visualization.mp4 與每步對應的兩個視角。要注意 recorder 是在 controller 執行前寫入資料；若控制器後來報錯，該 row 仍可能存在，所以訓練前還要按成功狀態與影片做品質檢查。

最小資料驗收可以分三層。第一層看 metadata.json：sim、success、num_steps 是否符合這回合，步數是否等於 JSONL 列數。第二層抽查首尾與抓取前後四列：token、pre-action pose、gripper width，以及 agent／wrist 影像路徑是否都存在。第三層播放影片，找出卡住、反向來回、抓空或放錯後仍被保留的步驟。三層有一層對不上，就先把整個 episode 隔離，不要只刪看起來奇怪的一張圖，否則 observation 與 action 的時間對齊會被破壞。

若目標是之後微調，還要把「收集成功」與「資料可學」分開。成功軌跡可能充滿多餘繞路，失敗軌跡也可能含有很好的恢復示範；要不要保留，應由明確的資料政策決定。入門階段先保留原始 rollout 不動，另外輸出清理後版本，並記錄被排除的 episode 與原因，日後才有辦法重做 converter 或追查模型退化。每次清理都應另存 manifest，讓影像、token 與取捨理由能一起版本化。

步驟三：接 VLM，但第一輪禁止出手

把 base_url 與 model 換成你自己的 OpenAI-compatible 視覺端點；本機服務也要提供一個非空的測試 key，hosted 服務則應另建專用專案／key，並在供應商側設預算上限。不要把密鑰寫進 YAML：

export SHOW_HARNESS_VLM_KEY='your-scoped-key'

.venv/bin/python gumi/gpt_web_operator.py \
  --target-url http://127.0.0.1:8600 \
  --robot-config /tmp/show-harness-sim.yaml \
  --vlm-backend sandbox \
  --max-steps 50 \
  --max-repeat 1 \
  --confidence-threshold 0.75 \
  --trace-dir data/gpt_operator_traces/sandbox \
  --once --dry-run

--once --dry-run 仍會讀取兩張影像、要求模型回傳結構化 JSON，並把 prompt、原始畫面與 events.jsonl 寫入 trace；但它不會呼叫 /api/start、/api/step 或 /api/stop。AlphaLab 另用本機 mock OpenAI-compatible endpoint 驗證一次，event 為 outcome: dry_run，前後 steps 都是 0。這只證明 wiring 與「不出手」路徑，不能算 VLM 任務測試。

先打開 trace 看模型實際回了什麼。合法 decision 必須同時提供 phase、可從畫面核對的 evidence、下一個局部目標、左右手動作、confidence、finish 與 pause。單臂模式的 right 必須是 STILL。如果 evidence 只是「看起來可以」而沒有指出物體、夾爪或相對位置，即使 JSON 合法，也應先改 prompt 或人工暫停。

確認 trace 正常後，移除 --once --dry-run 開啟 dashboard。公開 operator 程式預設 paused，先看 camera view，再按 Step once。低於信心門檻會改成 pause；向下、旋轉、夾爪動作會被強制一次一個；模型說完成時，還要通過 teleop 的 can_stop。此外，推論期間若 recording、步數、夾爪或 holding 狀態改變，舊決策會被丟棄。這些是軟體安全閘門，不是碰撞偵測器。

步驟四：用 10 次任務做驗收

Show-Harness 論文的主要實驗設定在未另註明時採每任務 10 次、隨機物件位置、最多 50 steps，timeout 算失敗。這很適合當入門驗收骨架，但不要把論文中的作者報告結果當成你自己的分數。

每回合重置 scene，記錄六欄：task success、第一個錯誤動作、總 steps、模型 latency、人工接管次數、trace／rollout 路徑。成功率之外，再看三件事：同一錯誤是否重複、低信心是否真的停住、每個分數能否回到當時的畫面與 JSON。若要把評測做成長期回歸，可借用 Shadow Eval 的固定題庫思路；若想理解 mock device 與權限邊界，可看 Model Hardware Standard 教學。

• 先跑 human baseline：人類若無法穩定完成 10 次，先修 camera、action mapping 或 success gate，不要怪模型。
• 再跑 VLM baseline：固定 model、prompt、temperature、step size 與上限；一次只改一個變因。
• 錯誤要分類：看錯物體、方向相反、過早抓取、錯放、反覆來回、低信心未停，各自需要不同修法。
• 失敗也留收據：不要只保存成功影片；沒有失敗 trace，就無法判斷是感知、規劃、interpreter 還是人類接管造成。

AlphaLab 第一手結果：通過了什麼，還沒通過什麼？

在固定 commit 上，我們讓 deterministic、讀取 scene state 的 API driver 跑 10 個隨機配置，10 次都達成 GUMI 的橘方塊放盤條件並保存 rollout；每次使用 23～36 個 semantic actions。這證明 synthetic world、token parser、success gate 與持久化管線在這台電腦上能重跑。driver 直接讀了 simulator ground truth，因此這個 10／10 刻意不衡量視覺理解、規劃或泛化。

真正接 VLM 後，請把 10 次結果另開一張表，不能沿用上述分數。即使 VLM 在 GUMI 拿到 10／10，也只代表一個簡化桌面：它沒有完整物理碰撞、觸覺或力回饋；論文也把靈巧手、人形機器人與接觸密集任務列為尚待驗證範圍。更完整的機器人能力判讀，可參考 GPT-6 Astra 機械臂評測解析，重點同樣是把任務層成功率和單步能力拆開。

三個最容易踩的坑

1. 把 sim floor 搬到實機：GUMI scene 的 floor 來自內建桌高；換機械臂後必須重新校正 workspace 與桌面高度，不能照抄。
2. 把 Pause 當成急停：Pause 只能擋住尚未送出的決策，無法召回已送出的 command。接實機時，實體 e-stop 仍要放在手邊。
3. 只看 Stop gate：sim 的 can_stop 讀 scene ground truth；實機 backend 只知道曾非空 GRASP 後 RELEASE，並不知道物品是否放對地方。實機驗收一定要另加感測或人工確認。

結論：先驗證 harness，再評模型

Show-Harness × GUMI 模擬器最有價值的地方，不是讓一個 VLM 看起來像會操作機器人，而是把「看見什麼、選了什麼、是否被擋、實際留下什麼」串成可追查紀錄。回到開頭那條迴圈：看畫面、選有限動作、由 interpreter 執行、再觀察。今天的合格終點是手動完成一條 rollout、dry run 確認零出手，再用獨立的 10 次表測真 VLM。只有這三層分開，模擬器分數才不會被誤讀成實體安全證明。

常見問題 FAQ

1. 完全沒有機械臂也能跑嗎？

可以。使用 collect_rollouts_web.py --sim 會啟動內建 synthetic tabletop scene；不要加入任何 real overlay。

2. 一定要付費 VLM API 嗎？

不一定。operator 接受相容端點，本機 vision model 也可使用；但端點必須能處理影像與結構化 JSON。不同 server 的 OpenAI 相容程度不一，需先用 dry run 驗證。

3. 為什麼官方 sim 指令在乾淨 clone 會缺設定？

本文固定的 commit 中，預設 Piper config 宣告了一個 repository 未提供的必要 site layer。傳入獨立的最小 sim YAML，即可避免讀取實機設定。

4. semantic action 和鍵盤按鍵一樣嗎？

概念相同，alias 不一定相同。瀏覽器與 API 對上下、釋放的快捷鍵有差異；程式控制請直接送 MV_UP、MV_DOWN、RELEASE 等完整 token。

5. dry run 會完全不留下東西嗎？

不會出手，但會留下 prompt、event JSONL 與實際送給模型的 JPEG，方便追查判斷。

6. 10 次成功就能接實機嗎？

不能。10 次只是小樣本門檻；synthetic scene 還省略了碰撞、摩擦、遮擋、校正誤差與硬體失效。

7. rollout 可以直接拿去微調嗎？

先別急。應先排除控制失敗或錯標步驟，再用官方 converter 套 prompt、整理影像並合成 episode 結束 token。

8. 接實機前最低限度還要做什麼？

重新校正座標與 floor、縮小 workspace、降低速度、保留實體 e-stop、先逐步單動作測試，並以外部感測或人工驗證真正的任務完成。