Gemini Robotics ER 2 API 教程：实时流式机器人、函数调用与迁移

Google 于 2026 年 7 月 30 日开放 Gemini Robotics ER 2 Public Preview。这次不是只替换一个模型名称，而是同时提供标准推理与实时流式两条接入路线：

• gemini-robotics-er-2-preview：适合单次图片、视频分析和多步骤工具编排。
• gemini-robotics-er-2-streaming-preview：通过 Live API 持续接收音频、视频和文本，适合低延迟机器人交互。

旧版 gemini-robotics-er-1.6-preview 将于 2026 年 8 月 31 日停止服务。已经在使用旧模型的项目，应尽快完成模型名替换与回归测试，不要等到停服当天才迁移。

快速结论：应该选择哪个端点

如果机器人接到一张照片后再规划动作，或需要分析一段已经录制的视频，优先使用标准端点。如果机器人需要持续观察摄像头、接收语音指令，并在会话中反复调用移动、抓取等工具，选择实时流式端点。

两者都能接收文本、图像、视频和音频，但输出都是文本。如果机器人需要说话，还要把文本交给外部 TTS 服务，或将 TTS 声明为一个可调用工具。

ER 2 的 Embodied Reasoning 是什么

ER 是 Embodied Reasoning，也就是“具身推理”。普通视觉模型更关注图片中有什么，具身推理模型还需要理解物体在哪里、如何到达、任务进行到了哪一步，以及下一步应该调用什么机器人动作。标准版 ER 2 建立在 Gemini 3.5 Flash 之上，官方重点列出的能力包括：

• 空间推理：识别点位、跟踪对象、生成边界框和规划轨迹。
• Agentic Vision：结合代码执行和图像处理完成视觉分析。
• 视频理解：寻找关键时刻，判断任务进度与完成状态。
• 工具编排：把自定义机器人 API 组合成长流程。
• 多机器人协作：根据任务状态协调不同设备。

这并不意味着模型可以直接安全控制真实硬件。模型负责理解与决策建议，开发者仍要在工具执行层限制速度、范围、权限和停止条件。

标准版与流式版的功能差异

两个模型名字相近，支持的 Gemini API 功能却不完全相同。

标准版还支持 Computer Use、Google Maps Grounding 等能力，但不支持 Live API。流式版专门为持久连接和传感器输入优化，不要因为名字中都有 ER 2，就假设两边的配置参数能够原样互换。两者的输入 token 上限都是 131,072，输出 token 上限都是 65,536。高分辨率输入和较高 Thinking 等级会增加延迟，需要平衡速度与推理质量时， 官方建议从 Medium Thinking 开始测试。

准备 Python SDK 和 API Key

安装或更新 Google Gen AI SDK：

1

pip install -U google-genai

然后在环境变量中配置 API Key：

1

$env:GEMINI_API_KEY = "你的_API_Key"

不要把密钥直接写进代码仓库。 如果请求返回 403， 还要检查 API Key 是否完全未受限制。 Robotics API 要求为密钥添加适当的 API 限制， 未限制的密钥可能被拒绝。

示例一：用标准端点定位图片中的物体

下面的例子先上传图片， 再要求模型返回最多十个目标点。 坐标顺序是 [y, x]， 并归一化到 0 至 1000。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

from google import genai

PROMPT = """
Point to no more than 10 items in the image.
Return JSON objects with point coordinates in [y, x] order,
normalized to 0-1000, and an identifying label.
"""

client = genai.Client()
uploaded_file = client.files.upload(file="my-image.png")

response = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type,
        },
        {"type": "text", "text": PROMPT},
    ],
    generation_config={"thinking_level": "high"},
)

print(response.output_text)

拿到输出后不要立刻驱动机械臂。 至少应增加以下验证：

1. 确认结果可以解析为预期的 JSON 结构。
2. 确认每个坐标都在 0 至 1000 范围内。
3. 把归一化坐标换算成原图像素坐标。
4. 拒绝未知标签、空标签和数量异常的结果。
5. 通过相机标定将二维位置转换到机器人坐标系。
6. 在执行前检查工作空间、碰撞风险和置信条件。

如果物体太小或遮挡严重， 可以先裁剪并放大目标区域。 光线、对比度和相机视角都会影响空间判断， 高精度任务可重复查询并使用一致性结果， 但这仍不能替代传感器与安全控制器。

示例二：把机器人动作声明为工具

模型不应该直接拼接并执行机器人 SDK 命令。 更稳妥的方式是只暴露经过审核的工具， 并对参数进行白名单验证。 流式 Robotics Live API 中的物理动作必须声明为阻塞调用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

tools = [
    {
        "function_declarations": [
            {
                "name": "navigate",
                "description": "Navigate to a named safe waypoint.",
                "behavior": "BLOCKING",
                "parameters": {
                    "type": "OBJECT",
                    "properties": {
                        "name": {"type": "STRING"},
                    },
                    "required": ["name"],
                },
            }
        ]
    }
]

"behavior": "BLOCKING" 的含义是： 模型发出动作调用后， 必须等待执行端返回结果， 才能继续规划下一步。 例如机器人正在移动到安全点， 模型不能在移动尚未完成时， 又假设它已经到位并调用抓取工具。 工具执行层还应做到：

• 只允许预先定义的动作名和安全点位。
• 限制机械臂速度、力度、关节角度和活动区域。
• 为每次动作设置超时和取消机制。
• 保留硬件急停与独立安全联锁。
• 把成功、失败、超时和传感器状态明确返回给模型。
• 对危险动作增加人工确认或策略引擎审批。
• 记录模型请求、工具参数、执行结果和时间戳。

模型输出的自然语言只能作为建议， 不能绕过工具层直接变成电机指令。

实时流式端点如何工作

gemini-robotics-er-2-streaming-preview 使用专用 Live API， 通过持久、带状态的 WebSocket 连接保持会话。 典型循环分为三步：

1. 在会话配置中声明机器人动作工具。
2. 持续发送摄像头、麦克风或文本输入。
3. 接收工具调用，执行机器人 SDK，再回传工具结果。

音视频输入还有明确约束：

• 音频使用原始 PCM、16-bit、16 kHz、小端格式。
• 视频以 JPEG 图片帧发送，最高 1 FPS。
• 视频帧本身不会自动触发模型推理。
• 需要用文本或音频指令触发回应。
• 若要持续主动监控，可定期发送 heartbeat 提示。

最后一点很容易踩坑。 持续上传摄像头画面， 不代表模型会在看到异常时主动开口或调用工具。 仓库巡检、生产线监控等场景， 应设计明确的心跳指令， 例如要求模型检查最新画面是否出现阻塞、跌落或人员进入危险区。 心跳频率也不应无限提高。 要结合 1 FPS 视频上限、延迟、配额和实际风险窗口， 确定合理的检查周期。

从 ER 1.6 迁移到 ER 2

最小代码变更是替换模型字符串：

1
2
3

OLD_MODEL = "gemini-robotics-er-1.6-preview"
NEW_MODEL = "gemini-robotics-er-2-preview"
STREAMING_MODEL = "gemini-robotics-er-2-streaming-preview"

但正式迁移不能只看请求是否返回 200。 建议按以下顺序处理：

1. 盘点所有代码、环境变量和配置文件中的旧模型名。
2. 按业务类型选择标准版或流式版，避免机械替换错误。
3. 检查当前依赖的 API 能力是否被目标端点支持。
4. 更新 SDK，并在测试环境使用受限 API Key。
5. 重新验证工具 schema、阻塞行为和错误处理。
6. 用固定测试集对比旧版与 ER 2 的结果。
7. 小流量灰度上线，观察延迟、失败率和动作中止率。
8. 在 2026 年 8 月 31 日前移除旧版回退路径。

回归测试集至少应覆盖：

• 图片中的指点坐标和边界框。
• 小物体、遮挡物体和低对比度场景。
• 仪表读数与物体朝向判断。
• 视频关键时刻、任务进度和完成状态。
• 多步骤函数调用的顺序与停止条件。
• 工具失败、超时和返回异常格式。
• 人员进入工作区后的拒绝或安全响应。
• 不同 Thinking 等级下的延迟与质量。

Public Preview 阶段仍可能调整行为或接口， 生产项目应锁定 SDK 版本， 记录模型标识与测试结果， 并持续关注更新日志。

安全、隐私与生产部署

机器人模型的错误可能造成真实财产损失或人身风险。 开发者需要对物理环境和最终动作负责， 不能把“模型判断正确”当成安全认证。 生产环境建议把系统拆成三层：

• 理解层：ER 2 负责感知、推理和提出工具调用。
• 策略层：验证权限、参数、状态和安全规则。
• 执行层：机器人控制器执行动作并提供硬件保护。

涉及人员的摄像头与麦克风数据时， 应提供明确告知并取得必要同意。 尽量减少个人数据采集， 可以避开可识别人员的画面， 或在上传前进行人脸模糊等处理。 日志中也不要无期限保存原始音视频、精确位置和身份信息。 应设置访问控制、保留期限与删除机制， 并根据部署地区完成合规评估。

常见问题

ER 2 可以直接输出机器人动作吗？

它可以通过函数调用选择开发者定义的机器人动作， 但真实动作仍由你的工具执行层完成。 物理操作应使用阻塞式调用， 并经过参数验证和安全联锁。

标准版能使用 Live API 吗？

不能。 实时流式会话必须使用 gemini-robotics-er-2-streaming-preview。

流式版会自动监控所有视频帧吗？

不会。 视频帧不会单独触发推理， 需要文本、音频指令或定期 heartbeat。

流式版会直接生成语音吗？

不会，模型输出是文本。 语音播报需要外部 TTS， 也可以把 TTS 封装成工具。

为什么 API Key 返回 403？

先检查密钥是否没有设置任何限制。 官方说明未受限制的 API Key 会被拒绝， 应为其配置适当的 API 限制， 同时确认项目和 API 权限正确。

现在是否应该迁移？

应该。 旧版 gemini-robotics-er-1.6-preview 将在 2026 年 8 月 31 日停止服务。 先用固定场景完成对比测试， 再逐步切换生产流量。

总结

Gemini Robotics ER 2 把机器人 API 分成两条清晰路线： 标准版负责更完整的空间、视频和多步骤推理， 流式版负责低延迟的持续音视频交互。 真正决定项目可靠性的， 不仅是选择正确的模型名， 还包括阻塞式函数调用、工具白名单、状态回传、硬件联锁， 以及针对真实场景建立可重复的回归测试。 如果仍在使用 ER 1.6， 现在就应该开始迁移， 并在停服日期前完成灰度上线与回退方案收尾。

官方资料

• Gemini API 更新日志
• Gemini Robotics ER 概览
• Gemini Robotics ER 实时流式指南