第16章 基于流式传输的机器人技术
Gemini 4 Argon 现已可用,欢迎体验。
首页 Gemini API 文档
使用流式传输进行机器人控制
gemini-robotics-er-2-streaming-preview 模型端点提供了一个专用的流式传输端点,该端点集成了 Live API,可实现你的应用与机器人之间实时的双向交互。这使得它非常适合需要快速反馈循环以及对环境做出反应式响应的智能体。
在 Google AI Studio 中试用
从 GitHub 克隆示例应用
使用场景
多机器人协同:多个机器人通过共享会话交换任务状态并分配子任务。 持续监控:机器人观察场景,并在特定事件发生时(例如容器达到填充液位)触发动作。 仓库与物流:执行拣货和包装的智能体,通过视觉验证物品、跟踪包装进度并从错误中恢复。
技术规格
下表列出了 Live API 的技术规格:
类别 详情
输入模态 音频(原始 16 位 PCM 音频,16kHz,小端序)、图像(JPEG <= 1FPS)、文本
输出模态 文本
协议 有状态 WebSocket 连接(WSS)
构建代理式架构
基于 Live API 构建的每个机器人智能体都遵循三个步骤:
将机器人能力声明为工具。机器人可执行的每个动作——导航、抓取、语音——都变成一个函数声明,包含名称、描述和参数模式。物理动作必须使用 "behavior": "BLOCKING",这样模型会在机器人完成动作后再选择下一步。 将多模态输入流式传输到持久会话中。打开一个 live.connect 会话,并在整个任务生命周期内保持其开启。当来自机器人传感器的视频帧、音频或文本到达时,立即发送。 在接收循环中处理工具调用。每次模型选择动作时,它都会发送一条 tool_call 消息。你的接收循环在机器人 SDK 上执行该函数,并回传一个 tool_response。会话保持开启,模型根据结果选择下一个动作。
以下部分展示了如何将这些步骤应用于三种常见模式:基础智能体循环、带有心跳的主动场景监控,以及通过 TTS 工具路由语音。
通过函数调用编排机器人
以下示例展示了如何在单个 Python 脚本中将这三个步骤串联起来。
步骤 1 — 工具定义 — 将机器人能力声明为函数声明。navigate 函数使用 "behavior": "BLOCKING",使模型在机器人到达航点之前不会调用其他工具。在同一个列表中为暴露额外的机器人能力添加更多函数声明。
步骤 2 — 输入辅助函数 — 展示了三个向会话流式传输不同模态输入的函数:用于命令的 send_text、带有可选文本提示的摄像头帧 send_image,以及来自麦克风的原始 PCM 音频 send_audio。
步骤 3 — 接收循环 — 并行运行,处理两种类型的消息:server_content 消息(模型的文本输出)和 tool_call 消息(模型请求的机器人动作)。当工具调用到达时,循环调用 execute_tool——一个你需用实际机器人 SDK 替换的存根——然后回传一个 tool_response,使模型可以选择下一个动作。 import asyncio from google import genai from google.genai import types
MODEL = "gemini-robotics-er-2-streaming-preview"
# ── 工具定义 ───────────────────────────────────────────────────────── tools = [ { "function_declarations": [ { "name": "navigate", "description": "将机器人导航到指定的航点。", "behavior": "BLOCKING", "parameters": { "type": "OBJECT", "properties": {"name": {"type": "STRING"}}, "required": ["name"], }, }, # 在此处添加更多函数定义 ] } ]
# ── 工具执行存根(用实际机器人 SDK 调用替换) ─────────────────── def execute_tool(name: str, args: dict) -> dict: print(f" [工具] {name}({args})") return {"status": "success"}
# ── 输入辅助函数 ──────────────────────────────────────────────────── def send_text(session, text: str): """发送文本轮次。""" return session.send_client_content( turns=types.Content(role="user", parts=[types.Part(text=text)]), turn_complete=True, )
def send_image(session, image_bytes: bytes, prompt: str = ""): """发送带有可选文本提示的 JPEG 图像。""" parts = [ types.Part( inline_data=types.Blob(data=image_bytes, mime_type="image/jpeg") ) ] if prompt: parts.append(types.Part(text=prompt)) return session.send_client_content( turns=types.Content(role="user", parts=parts), turn_complete=True, )
def send_audio(session, audio_chunk: bytes): """流式传输一块原始 PCM 音频(16位,16 kHz,单声道)。""" return session.send_realtime_input( media=types.Blob(data=audio_chunk, mime_type="audio/pcm;rate=16000") )
# ── 接收循环 ───────────────────────────────────────────────────────── async def receive_loop(session): """在会话结束前打印模型文本并处理工具调用。""" async for message in session.receive(): if message.server_content: sc = message.server_content if sc.model_turn and sc.model_turn.parts: for part in sc.model_turn.parts: if part.text: print(f"模型: {part.text}", end="", flush=True) if sc.turn_complete: print("\n[轮次完成]") elif message.tool_call: responses = [] for call in message.tool_call.function_calls: print(f"\n[工具调用] {call.name}({call.args})") result = execute_tool(call.name, call.args) responses.append( types.FunctionResponse( name=call.name, response=result, id=call.id, ) ) await session.send_tool_response(function_responses=responses)
# ── 主函数 ───────────────────────────────────────────────────────────── async def main(): client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) config = types.LiveConnectConfig( response_modalities=["TEXT"], tools=tools, system_instruction=types.Content( parts=[types.Part(text="你是一台机器人控制器。使用工具来执行命令。")] ), ) async with client.aio.live.connect(model=MODEL, config=config) as session: recv_task = asyncio.create_task(receive_loop(session)) # 将机器人感知回调和用户输入连接到上述辅助函数。 recv_task.cancel()
asyncio.run(main())
在每次工具响应后,接收循环保持活跃。模型构建并修订长程计划,而你无需预先编码整个动作序列。
主动时空推理
Live API 可以流式传输视频输入,但仅靠视频帧不会触发新的推理轮次。视频帧必须伴随文本或音频提示,才能触发模型响应。更多详情参见 Live API 功能。
要启用主动推理,请实现一个心跳机制:定期发送最新的摄像头帧,随后发送一个简短的文本提示,强制模型检查场景并做出明确决定。视频输入的速率限制为每秒一帧。
实现心跳
心跳协程在同一会话中作为一个单独的 asyncio 任务运行。它在等待每个轮次完成(er_turn_done)以避免打断正在进行中的推理的同时,机会性地瞄准 1 Hz 的节拍(与视频输入速率限制匹配): async def heartbeat(session, camera, er_turn_done: asyncio.Event): TARGET_INTERVAL_SEC = 1.0
while True: start_time = asyncio.get_running_loop().time()
frame = await camera.latest_jpeg() await session.send_realtime_input( video=types.Blob(data=frame, mime_type="image/jpeg") ) await session.send_realtime_input( text=( "[心跳] 如果没有活动任务,调用 'ack' 并等待用户" " 输入。如果有活动任务:观察场景。如果当前" " 步骤进展正确,调用 'ack'。如果当前步骤" " 已完成,使用下一步调用 'run_instruction'。如果" " 总体目标已实现,调用 'reset' 并通知用户。" ) )
# 在发送下一个心跳之前,等待模型完成响应 await er_turn_done.wait() er_turn_done.clear()
# 仅睡眠剩余时间以保持约 1 Hz 的节拍 elapsed = asyncio.get_running_loop().time() - start_time remaining = TARGET_INTERVAL_SEC - elapsed if remaining > 0: await asyncio.sleep(remaining)
更新接收循环
为了在模型完成轮次时发出信号,请更新你的 receive_loop 以设置 er_turn_done: # 在 receive_loop 中:当模型完成轮次时发出信号 if sc.turn_complete: er_turn_done.set()
通过外部 TTS 进行音频输出
Gemini Robotics ER 2 返回文本。你的应用通过注入的回调将完成的响应路由到单独的 TTS 提供商(例如 Gemini TTS)。 这使得你可以控制语音延迟、语音选择和打断行为,并允许你在不改变智能体逻辑的情况下更换 TTS 后端。
你还可以将 TTS 声明为一个工具,这样模型处理“说点什么”的方式就与“移动手臂”相同。在第一部分的工具列表中添加了以下函数声明: TOOLS = [ { "name": "send_message", "description": ( "通过 TTS 大声朗读一条消息,然后将其传递到" " 指定的目标。使用 target='user' 直接对用户说话," " 或使用对等智能体名称(例如 'duo')与另一个机器人" " 通信。" ), "parameters": { "type": "object", "properties": { "target": { "type": "string", "description": "接收者:'user' 或对等智能体名称。", }, "message": { "type": "string", "description": "要朗读和传递的消息。", }, }, "required": ["target", "message"], }, }, ]
通过将 TTS 包装在函数声明中,模型通过与其他任何机器人动作相同的工具调用路径来处理语音。你的应用通过注入的回调来满足该调用。
GitHub 上的示例
对于完整的可运行示例,包括 Spot 机器人零食获取演示和 Tinybot 云台问候世界,参见 Robotics Live API 示例。
接下来做什么
视频理解 — 瞬间查找和进度分类。 任务编排 — 无流式传输的长程任务。 Live API 概览 — 完整的 Live API 文档。