Gemini Robotics-ER 2
Gemini Robotics-ER（Embodied Reasoning）是一個專為機器人設計的視覺語言模型。它能處理圖片、影片與音訊，並回傳文字：JSON 格式的點與框、計畫，或對你的機器人函式的呼叫。它永遠不會直接驅動馬達。ER 提出方案，由確定性程式碼執行。
此處的所有內容均經過官方文件（ai.google.dev, 2026 年 10 月）、ER 2 notebook（gemini_robotics_er.ipynb）以及 google-genai 2.31 / @google/genai 2.30 驗證。
1. 選擇端點與 API
| 模型 | API | 用途 | 不支援 |
|---|---|---|---|
gemini-robotics-er-2-preview | Interactions API client.interactions.create（亦支援舊版 generateContent） | 指向、邊界框、軌跡、空間邏輯、程式碼執行、函式呼叫編排、影片時間點查找與進度 | Live API |
gemini-robotics-er-2-streaming-preview | Live API client.aio.live.connect / ai.live.connect（WebSocket） | 即時代理：連續視訊（≤ 1 FPS）、音訊、BLOCKING 工具呼叫 | 結構化輸出、程式碼執行、快取、Interactions |
gemini-robotics-er-1.6-preview | — | 已棄用，至 2026 年 8 月 31 日。 更換模型字串即可。影片進度與串流需要 ER 2。 |
兩個 ER 2 端點皆接受文字、圖片、影片與音訊，僅輸出文字。限制：輸入 131,072 tokens，輸出 65,536 tokens。預設思考層級為 high。層級有 minimal、low、medium 與 high。官方文件建議使用 medium 作為延遲與品質之間的平衡點。
2. 選擇模式
需要一次性目標給腳本化運動？ -> 空間查詢（點／邊界框） references/spatial-reasoning.md
微小文字、量表、計數、裁切/縮放、註解？ -> 代理視覺（code_execution） references/agentic-vision.md
透過機器人 API 逐步執行多步驟任務？ -> 編排（function calling） references/orchestration.md
有沒有成功？何時？進度到哪？ -> 影片理解 references/video-progress.md
對攝影機/語音連續反應，< 1 秒循環？ -> Live API + 串流模型 references/live-api.md
請求/回應結構、SDK 細節、遷移？ -> Interactions API 參考 references/interactions-api.md
scripts/er_tools.py 提供已測試的輔助函式：圖片編碼、回應格式、防禦性解析器、編排迴圈、影片上傳與時間戳解析。執行方式為 --selftest（無需金鑰）或 --help。
3. 最簡正確呼叫
Python（pip install "google-genai>=2.9.0"；讀取 GEMINI_API_KEY）：
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-robotics-er-2-preview",
input=[{"type": "user_input", "content": [ # 或扁平的 parts 列表
{"type": "image", "data": png_b64, "mime_type": "image/png"}, # 媒體在文字之前
{"type": "text", "text": "指向紅色立方體。點座標為 [y, x]，正規化至 0-1000。"},
]}],
generation_config={"thinking_level": "medium"},
response_format={"type": "text", "mime_type": "application/json", "schema": {
"type": "object", "required": ["items"], "properties": {"items": {"type": "array", "items": {
"type": "object", "required": ["point", "label"], "properties": {
"point": {"type": "array", "items": {"type": "integer"}}, "label": {"type": "string"}}}}}}},
)
items = json.loads(interaction.output_text)["items"]
TypeScript（@google/genai >= 2.3.0；請求欄位為 snake_case；在伺服器端執行）：
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const interaction = await client.interactions.create({
model: 'gemini-robotics-er-2-preview',
input: [{ type: 'image', data: pngB64, mime_type: 'image/png' }, { type: 'text', text: prompt }],
generation_config: { thinking_level: 'medium' },
response_format: { type: 'text', mime_type: 'application/json', schema },
});
const parsed = JSON.parse(interaction.output_text ?? '{}');
使用 interaction.output_text（最終文字）、interaction.steps（類型化時間線：thought、function_call、code_execution_call、code_execution_result、model_output）以及 interaction.id（作為 previous_interaction_id 傳入）讀取回應。
4. 預防大多數錯誤的規則
- 座標為
[y, x]，正規化至 0–1000，相對於您發送的圖片。邊界框為[ymin, xmin, ymax, xmax]。使用u = x/1000*W與v = y/1000*H進行轉換。在每個提示中說明格式。 - 使用 Interactions 形狀。
input=[{"type": "image" | "text" | "video", ...}]、generation_config={...}與response_format={...}。永遠不要傳遞config=types.GenerateContentConfig(...)、PIL 圖片，或讀取 Interaction 的.text/.function_calls。這些屬於generateContent。 tools、system_instruction與generation_config為每次回合設定。 在每次interactions.create時重新傳送，包括使用previous_interaction_id的回合。- 不要使用
thinking_budget。ER 2 / Gemini 3+ 會回傳 400 錯誤。請使用thinking_level。 - 即使有 schema 也要防禦性解析。 移除圍欄、切片至外部 JSON、移除重複項與範圍外的座標，並限制數量（
er_tools.parse_er_json）。 - 拍攝攝影機必須等於反投影攝影機：相同姿態、內參、裁切與長寬比。拍攝時讓機器人避免遮擋目標。
- 您的機器人函式應回傳真實結果。 失敗時，傳送
is_error: true並附上原因，讓模型重新規劃。使用max_steps限制工具迴圈。在移動前，針對工作空間與關節限制驗證每個目標。 - Live API： 僅使用
"behavior": "BLOCKING"工具，每秒最多傳送 1 個影格，等待turn_complete後再進行下一次心跳（否則插話會取消動作），並處理tool_call_cancellation。 - 金鑰： 無限制的 API 金鑰會回傳
403，請在 AI Studio 中新增限制。絕不要在瀏覽器中暴露金鑰。對 Interactions 使用後端代理，對 Live 使用暫時性 token（它們僅適用於 Live）。 - 儲存： interactions 預設為儲存（
store=true：付費 55 天，免費 1 天）。store=false會停用previous_interaction_id。Interactions 是 Gemini Developer API 的功能，且gs://URI 無法讀取，因此請使用 Files API。
5. 有效的提示策略（來自文件與 notebook）
- 使用平實語言。如果某個詞彙失敗，嘗試同義詞（"washer" 或 "ring"）。
- 說 "DO NOT detect items that only match the description partially" 以減少誤判。
- 限制數量（"no more than 25 items"）。當需要特定部分時，每次查詢只要求一個點。
- 將複雜任務拆分為多個獨立提示，並平行執行獨立查詢（notebook 使用 ThreadPoolExecutor）。
- 為了精確度，多次查詢並取中位數點。
- 將圖片縮放至約 800 像素寬（notebook 有實作）以節省 tokens。針對小物件進行裁切或縮放。
- 思考層級：一般偵測或指向使用
low，計數、負載或可供性推理、成功偵測與影片使用high。medium是預設的折衷方案。 - 對於多張圖片或影片網格，在提示中描述佈局（"first 4 images = start, last 4 = now"；"views left-to-right: top, wrist"）。
6. 2D 抬升至 3D（摘要）
| 設定 | 方法 |
|---|---|
| 瀏覽器模擬（Three.js） | 從拍攝攝影機透過 NDC (x/500-1, 1-y/500) 進行光線投射。請參閱 threejs-rendering 技能。 |
| Python MuJoCo | 從同一攝影機渲染深度並反投影（mujoco-physics/scripts/panda_pick_place.py 中的 er_point_to_world）。檢查分割是否有遮擋。 |
| 真實 RGB-D | Z = 中位數深度，X = (u−cx)Z/fx，Y = (v−cy)Z/fy，然後 T_base←cam。 |
| 真實 RGB，僅桌面 | 將光線與平面 z = z_table 相交，然後加上物體高度的一半。 |
深度樣本或光線投射會擊中頂面，因此向下偏移至夾爪高度。盒子長寬比給出夾爪偏擺：跨短邊閉合。0–1000 的整數網格將每個單位量化為約 FOV/1000（對於 1 公尺寬的視野，約為 1 公釐/單位）。
7. 在 Franka 示範中
Franka 揀放示範（React + Vite + mujoco-js + Three.js）是這些技能所依據的參考應用程式。以下檔案名稱皆指涉此示範。
App.tsx::handleErSend從固定的俯視角度擷取 ≤640 像素的 PNG，並呼叫 ER。 它使用 SDK 1.xai.models.generateContent，搭配thinkingBudget: 0。點與 邊界框中心透過RenderSystem.project2DTo3D進行光線投射。SequenceAnimator接著對每個目標執行盲動的 15 步驟揀取。沒有驗證、編排或 Live API。- 金鑰透過 Vite
define（process.env.API_KEY）暴露給瀏覽器。這在示範中可行，但生產環境不適用。 - 請參閱
references/interactions-api.md#migrating-the-franka-demo了解確切的 1.x→2.x 差異，以及references/orchestration.md/references/video-progress.md了解如何加入閉迴路行為。
8. 安全
ER 可能產生幻覺或部分匹配物體。將每個輸出視為建議：
- 檢查工作空間邊界、可達性（IK 殘差）、碰撞與速度限制。
- 對於重要動作，要求人工確認，並保留實體緊急停止開關。
- 在更換硬體之前，先在與機器人相同 API 背後的模擬環境中開發。
- 攝影機與麥克風資料可能捕捉到人員。請取得同意、模糊人臉，並最小化留存時間。 請參閱 https://deepmind.google/models/gemini-robotics/safety。