深潜 Gemini Robotics SDK:Google DeepMind 如何用一套 SDK 打通机器人模型全生命周期
深潜 Gemini Robotics SDK:Google DeepMind 如何用一套 SDK 打通机器人模型全生命周期
Gemini Robotics SDK(代号 Safari SDK)是 Google DeepMind 为 Gemini Robotics 系列模型推出的官方工具包,用一个 Python pip 包覆盖机器人模型的完整生命周期:数据记录与上传、模型微调、模型服务部署、真机与仿真评估、检查点下载,甚至内置了基于自然语言的机器人 Agent 框架。本文将从新手视角带你快速了解它的安装方式与核心能力。🦾
一、它解决什么问题?
做机器人强化学习/模仿学习时,团队往往要自己拼凑一整套工具链:采集数据、传数据、训练模型、起服务、写评估脚本、部署到机器人。Gemini Robotics SDK 把这些环节封装成了统一接口:
- 数据记录:将相机图像、关节状态、动作等传感器数据以 MCAP 格式记录到磁盘(
safari_sdk/logging) - 模型训练与部署:通过 Flywheel 平台请求微调、部署模型服务、下载产物(
safari_sdk/flywheel) - 模型推理:提供高层 Policy 接口与底层 API 客户端两层模型交互能力(
safari_sdk/model) - Agent 框架:让 Gemini 模型"看懂环境、推理任务、控制硬件"(
safari_sdk/agent/framework)
📌 注意:该 SDK 并非 Google 官方支持产品,且大部分功能需要加入 Gemini Robotics Trusted Tester Program 后才能使用。
上图展示了 SDK 的数据记录流水线:机器人端各传感器以 ROS msg 输出,采集端订阅并转换为 protobuf 消息,由 Logger 统一落盘为 .mcap 文件,再上传至数据端点——图中青色模块(Logger、元数据、文件元数据)正是 SDK 提供的部分。
二、三步安装:最快上手 Gemini Robotics SDK
安装路径非常轻,支持三种方式:
| 方式 | 命令 | 适用场景 |
|---|---|---|
| PyPI 安装 | pip install safari-sdk |
日常使用(推荐) |
| 源码安装 | pip install -e .[dev] |
二次开发 |
| 构建 wheel | scripts/build_wheel.sh |
离线/内网部署 |
新手建议:先在虚拟环境中执行 pip install -r requirements.txt 固定依赖版本,避免上游包变动导致安装失败(依赖清单见 requirements.txt,版本约束在 pyproject.toml 中,要求 Python 3.10–3.13)。
安装完成后,终端里就多了一个 flywheel-cli,它是与 Gemini Robotics 平台交互的"遥控器":
flywheel-cli train # 训练模型(指定任务 ID 与数据时间范围)
flywheel-cli serve # 部署模型服务
flywheel-cli list # 查看训练任务
flywheel-cli upload_data # 上传采集数据
flywheel-cli download # 下载微调后的检查点
flywheel-cli data_stats # 查看可用于训练的数据统计
CLI 实现位于 safari_sdk/flywheel/flywheel_cli.py,数据上传还支持断点续传(resumable_upload_data.py)。
三、数据记录:机器人数据采集的正确姿势
Safari SDK 的日志模块(safari_sdk/logging)是数据飞轮的起点:
- EpisodicLogger:面向"回合制"采数(一集演示一个 episode),自动按
YYYY/MM/DD目录组织数据、写入传感器元数据与时间戳(episodic_logger.py) - C++ 高性能写入:底层用 C++ 线程池实现 MCAP 写入(thread_pool_log_writer.h),Python 层负责编排,兼顾易用与吞吐
- LeRobot 互转:仓库提供脚本把数据转成 LeRobot 数据集格式,方便对接生态工具(lerobot_data_conversion_script.py)
配套的演示脚本 example_logger_usage.py 展示了完整的"建 logger → 记录 episode → 写盘"流程,是新手读懂数据格式的很好入口。
四、模型推理:两层 API 各取所需
safari_sdk/model 提供了两个抽象层次(说明见 examples/model/README.md):
- 高层
GeminiRoboticsPolicy(推荐):实现 step-based 机器人交互模式——创建 Policy → 配置step_spec()→ 初始化状态 → 循环调用step(TimeStep)获取动作。与 dm_env 生态无缝衔接,适合直接接入控制回路。示例见 gemini_robotics_policy_example.py - 底层
genai_robotics.Client:直接暴露模型的generate_content接口,适合自定义观测序列化、压测原始推理延迟等精细控制场景
此外还内置了动作重采样、思考内容管理、观测到模型请求内容的转换等实用工具(action_chunk_resampling.py、thinking_manager.py、observation_to_model_query_contents.py),把模型与机器人控制频率之间的适配脏活都干了。
五、离线评估:不占真机就能量化模型好坏
想验证微调后的模型是否更准?examples/offline_eval 提供了一个独立的离线评估工具:回放 MCAP 演示数据,让模型"重演"一遍,然后计算动作预测误差:
- Chunk MSE(主指标):预测的 50 步动作块与实际动作块的整体均方误差
- Single Step MSE:仅第一步动作的误差
- Per-Joint MSE:按关节拆解的误差分布
最贴心的是任务元数据自动检测——相机名、本体感知键、任务指令全部从 MCAP 会话数据中自动解析,无需手动配置。典型用法:
# 1. 启动模型服务
flywheel-cli serve --training_recipe=gemini_robotics_on_device_v1 \
--model_checkpoint_path=/path/to/checkpoint.chkpt
# 2. 跑离线评估
python examples/offline_eval/offline_eval.py \
--dataset_path=/path/to/mcap_episodes/ \
--checkpoint_path=/path/to/checkpoint.chkpt
工具入口见 examples/offline_eval/offline_eval.py,MCAP 数据加载逻辑在 mcap_loader.py。
六、Agent 框架:用自然语言指挥机器人
Gemini Robotics 1.5 带来的 agentic 能力也被封装进了 SDK。safari_sdk/agent/framework 提供模块化架构,让 Agent 能感知环境、推理任务、控制硬件:
| 组件 | 目录 | 职责 |
|---|---|---|
| Agents | agents/ | 对接 Gemini Live API,提供对话与工具调用 |
| Embodiments | embodiments/ | 硬件适配层(如 Aloha 机械臂) |
| Tools | tools/ | 执行指令、成功检测、场景描述等原子能力 |
| Event Bus | event_bus/ | 组件间异步发布-订阅通信 |
官方示例 examples/aloha/agent/ 中的 simple_agent.py 就是一个对话式 Agent:用自然语言指令即可控制 Aloha 机器人,一条命令跑起来:
python examples/aloha/agent/run.py --agent_name=simple_agent
如果你用的是 Aloha 平台,examples/aloha 目录还提供了完整的评估环境(eval.py)和仿真评估(sim_eval.py)。
七、目录速查表:五分钟摸清仓库结构
| 目录/文件 | 内容 |
|---|---|
| safari_sdk/logging/ | 机器人数据记录(MCAP、episode 管理、C++ 写入器) |
| safari_sdk/model/ | 模型推理与模型服务接口 |
| safari_sdk/flywheel/ | 检查点获取、数据上传、微调请求 + flywheel-cli |
| safari_sdk/agent/ | Agent 框架与 UI(终端/浏览器操作界面) |
| safari_sdk/protos/ | 各传感器与元数据的 protobuf 定义 |
| examples/ | 推理、Aloha 评估、离线评估、日志示例 |
| Dockerfile / cmake/SafariDependencies.cmake | Docker 与 C++ 依赖构建配置 |
写在最后
Gemini Robotics SDK 的价值在于"把碎片化的机器人 ML 工具链收拢成一个包":pip install safari-sdk 之后,flywheel-cli + 分层 Python API 就能撑起从数据采集 → 上传 → 微调 → 部署 → 评估的完整闭环,外加一个可对话的 Agent 框架。如果你正在做 Gemini Robotics 方向的机器人学习研究,不妨先从 examples/ 里的脚本读起——它们比文档更诚实地展示了每一条生命周期的最短路径。🚀
