johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2

Gemini Robotics-ER（具身推理）是一种专门为机器人设计的视觉语言模型。它可以处理图像、视频和音频，并输出文本：JSON 格式的点坐标和边界框、执行计划或调用您的机器人函数。它从不直接驱动电机。ER 负责提议，而确定性代码负责执行。

此处所有内容均已参照官方文档（ai.google.dev，2026 年 10 月）、ER 2 笔记本（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 输入 Token 和 65,536 输出 Token。默认思考级别为 high，可用级别为 minimal、low、medium 和 high。官方文档建议使用 medium 作为延迟与质量之间的平衡点。

2. 选择模式

需要为脚本化运动提供一次性目标？         -> 空间查询（点/边界框）  references/spatial-reasoning.md
微小文本、仪表盘、计数、裁剪/缩放、标注？  -> 智能视觉（代码执行）  references/agentic-vision.md
通过您的机器人 API 逐步完成多步骤任务？    -> 任务编排（函数调用）  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": [                       # 或者一个扁平的 part 列表
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # 媒体内容放在文本之前
        {"type": "text", "text": "指向红色立方体。Points 是 [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: '提示' }],
  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. 防止大多数 Bug 的规则

1. 坐标是 [y, x]，归一化到 0-1000，相对于您发送的图像。边界框是 [ymin, xmin, ymax, xmax]。使用 u = x/1000*W 和 v = y/1000*H 进行转换。在每个提示中都要声明此格式。
2. 使用 Interactions 形状。 input=[{"type": "image" | "text" | "video", ...}]、generation_config={...} 和 response_format={...}。切勿传递 config=types.GenerateContentConfig(...)、PIL 图像，也不要尝试在 Interaction 对象上读取 .text 或 .function_calls。这些属于 generateContent。
3. tools、system_instruction 和 generation_config 是按轮次设置的。 在每次 interactions.create 调用中重新发送它们，包括使用了 previous_interaction_id 的轮次。
4. 不要使用 thinking_budget 搭配 ER 2 / Gemini 3+，这可能导致 400 错误。请使用 thinking_level。
5. 即使定义了 Schema，也要进行防御性解析。 去除代码块标记，切片到外层 JSON，去除重复项和超出范围的坐标，并限制数量（参考 er_tools.parse_er_json）。
6. 捕获相机必须与反向投影相机一致： 姿态、内参、裁剪和宽高比必须相同。捕获时不要让机器人遮挡目标。
7. 您的机器人函数必须返回真实结果。 失败时，发送 is_error: true 并附上原因，以便模型重新规划。使用 max_steps 限制工具循环。在移动之前，针对工作空间和关节限位验证每个目标。
8. Live API： 仅使用 "behavior": "BLOCKING" 类型的工具，每秒最多发送 1 帧视频，在下一个心跳之前等待 turn_complete（否则“闯入”行为会取消当前动作），并处理 tool_call_cancellation。
9. 密钥： 不受限制的 API 密钥会返回 403 错误，因此请在 AI Studio 中添加限制。切勿将密钥发送到浏览器。对 Interactions API 使用后端代理，对 Live API 使用临时 Token（它们仅适用于 Live 场景）。
10. 存储： 交互记录默认存储（store=true：付费用户 55 天，免费用户 1 天）。store=false 会禁用 previous_interaction_id。Interactions 是 Gemini Developer API 的功能，不支持 gs:// URI，请改用 Files API。

5. 有效的提示编写技巧（来自官方文档和笔记本）

• 使用简单的语言。如果某个术语不奏效，尝试同义词（例如“垫圈”或“环”）。
• 添加“不要检测仅部分匹配描述的项目”以减少误报。
• 限制数量（例如“不超过 25 个项目”）。当需要特定部位时，一次查询只问一个点。
• 将复杂任务拆分为独立的提示，并并行运行独立的查询（笔记本中使用 ThreadPoolExecutor）。
• 为了提高精度，多次查询并取中位数点。
• 将图像调整到大约 800 像素宽（笔记本中如此操作）以节省 Token。对于微小物体可进行裁剪或缩放。
• 思考级别：使用 low 处理简单的检测或指向，使用 high 处理计数、负载或属性推理、成功检测和视频分析。medium 是默认的折中选择。
• 对于多张图像或视频网格，在提示中描述布局（例如“前 4 张图像 = 开始状态，后 4 张 = 当前状态”；“视图从左到右：顶部相机、腕部相机”）。

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.x 的 ai.models.generateContent，并设置了 thinkingBudget: 0。点坐标和边界框中心通过 RenderSystem.project2DTo3D 进行射线投射。然后 SequenceAnimator 为每个目标执行一个无需验证的 15 步盲抓取循环。整个流程没有验证、编排或 Live API。
• API 密钥通过 Vite 的 define 暴露给浏览器（即 process.env.API_KEY）。这在演示中是可以接受的，但在生产环境中绝对不行。
• 关于 1.x 到 2.x SDK 的精确差异，请参阅 references/interactions-api.md#migrating-the-franka-demo；关于添加闭环行为的指导，请参阅 references/orchestration.md / references/video-progress.md。

8. 安全注意事项

ER 可能会产生幻觉或部分匹配物体。请将每个输出都视为一个提案：

• 检查工作空间边界、可达性（逆运动学残差）、碰撞和速度限制。
• 对于重要后果的操作，要求人类确认，并保留物理急停按钮。
• 在仿真环境中，使用相同的机器人 API 进行开发，然后再切换到真实硬件。
• 摄像头和麦克风数据可能捕捉到人物。请获取同意，模糊人脸，并最小化数据保留时间。详见 https://deepmind.google/models/gemini-robotics/safety。