基于Gemini Live与Reachy Mini的实时语音交互机器人开发实践

1. 项目概述：打造一个能说会道的桌面机器人伙伴

最近在捣鼓一个特别有意思的开源项目，它让我桌上那个小小的Reachy Mini机器人彻底“活”了过来。想象一下：你对着它说话，它不仅能实时听懂并回答，还能根据聊天的内容摇头晃脑、摆动触角，甚至跳上一段舞。这一切的核心，是将谷歌的Gemini Live实时语音大模型，与一个实体机器人硬件无缝连接起来。这个名为“Reachy Mini对话应用”的项目，完美地展示了当前AI与机器人技术结合所能带来的、触手可及的趣味性与可能性。它不只是个演示，而是一个完整的、可高度定制的开源平台，让你能赋予机器人独特的个性，而无需编写复杂的控制代码。

无论你是机器人爱好者、AI开发者，还是单纯想给自己的工作台增添一个有趣的智能伙伴，这个项目都提供了一个极佳的起点。它基于Python构建，架构清晰，将复杂的实时音频流、AI推理和机器人运动控制抽象成几个协同工作的层次，使得理解和二次开发变得相对容易。接下来，我将带你深入这个项目的内部，从架构设计、环境搭建、核心机制到个性化定制，完整地复现并理解如何让你的机器人“能听会道”。

2. 核心架构深度解析：四层协作模型

这个项目的优雅之处在于其清晰的分层架构。它没有把所有功能糅杂在一起，而是通过四个独立的层次进行解耦，每一层各司其职，通过定义良好的接口进行通信。这种设计不仅让代码易于维护，也让我们可以灵活地替换某一层的实现，例如将后端的Gemini Live换成OpenAI的Realtime API。

2.1 音频输入/输出层：低延迟的桥梁

整个交互的起点和终点是声音。这一层由fastrtc库负责，它是一个基于WebRTC的低延迟音频处理模块。它的核心任务有两个：

1. 音频采集与推送：从你的麦克风捕获原始的PCM音频数据（通常是16位深度，16kHz采样率），并将其打包、流式传输到上一层的AI处理模块。这里选择16kHz是一个权衡，既能保证语音识别的清晰度，又能减少数据传输量，降低延迟。
2. 音频播放与同步：接收从AI模型返回的音频流（通常是24kHz），进行必要的重采样，然后送入你的扬声器播放。fastrtc处理了所有底层的音频设备交互和网络流管理，为上层的AI交互提供了一个干净的异步音频流接口。

实操心得：在实际部署中，麦克风和扬声器的设备选择与配置至关重要。如果遇到回声或杂音，首先检查系统的默认音频输入输出设备是否正确。在Linux下，可以使用arecord -l和aplay -l来列出设备，并通过环境变量或代码指定设备ID。

2.2 AI模型处理层：对话的大脑

这是项目的智能核心，目前主要支持两种后端：

• Gemini Live Handler (gemini_live.py)：默认选项，使用Google GenAI SDK。它通过session.send_realtime_input()和session.receive()方法，与Gemini模型建立一个全双工的、持续的音频会话。这意味着音频可以同时上传和下载，实现真正的实时对话。
• OpenAI Realtime Handler (openai_realtime.py)：一个替代方案，通过WebSocket连接OpenAI的Realtime API。项目通过一个统一的MODEL_NAME环境变量（例如设为gpt-realtime）来切换，业务逻辑层无需关心底层是哪个服务。

这一层的工作流可以简化为一个循环：

1. 从fastrtc接收音频帧，转换为模型所需的格式（如Gemini要求的特定Blob格式）并发送。
2. 异步监听模型的响应流。响应可能包含多种内容：
   • 音频数据：模型说的话，被解码后放入输出队列，供播放层使用。
   • 文本转录：你说话的文字记录，以及模型回应的文字记录，用于在UI中显示。
   • 工具调用：模型决定让机器人执行某个动作（如跳舞）的指令，这是触发机器人行为的关键。
   • 中断信号：当用户在新一轮回应未结束前又开始说话时，模型会发送此信号，系统需要清空当前的音频响应队列，以实现更自然的人类对话式打断。

2.3 工具调度与行为管理层：从指令到动作

当AI模型在对话中决定“现在该跳舞了”，它不会直接发送电机控制命令，而是发出一个结构化的“工具调用”。这一层就是负责翻译和执行这些调用的。

• 工具调用转换：Gemini和OpenAI的工具调用格式略有不同。项目中的BackgroundToolManager会负责将其转换为内部统一的工具表示形式。
• 异步任务分发：关键设计在于“Background”（后台）。所有工具调用都被包装成异步任务，放入后台执行。这确保了执行一个耗时动作（比如一段长达10秒的舞蹈）时，不会阻塞主音频流的接收和播放，机器人依然可以“听”和“说”。
• 内置工具库：项目预置了一系列实用的工具，构成了机器人的基本行为能力：

  工具名	功能描述	典型参数示例
  dance	执行一段预编程的舞蹈。	name='macarena'
  play_emotion	播放一段表达情绪的动作序列。	emotion='happy'
  move_head	控制头部向特定方向转动。	direction='left', amount=0.5
  camera	拍摄一张照片并发送给AI模型进行视觉理解。	无
  head_tracking	开启或关闭基于摄像头的人脸追踪功能。	enabled=True
  do_nothing	明确指示机器人保持空闲。AI有时会用此来回应“别动”。	无

2.4 运动控制系统：让动作流畅而生动

这是最终将抽象指令转化为具体机器人关节运动的层，由MovementManager驱动，并以60Hz的频率运行在一个独立的线程中。它的精妙之处在于“动作合成”：

1. 主动作队列：来自工具调用的“舞蹈”、“情绪播放”等动作，被转化为一系列机器人关节的目标位置序列，放入一个队列中顺序执行。同一时间只有一个主动作在播放，保证了动作的完整性。
2. 次级动作偏移：这是一些持续性的、可叠加的动作效果，会实时地叠加在当前的主动作之上。主要包括：
   • 语音晃动：根据机器人说话音频的振幅，实时生成一个微小的、随节奏晃动的头部偏移，让说话时的动作更自然。
   • 人脸追踪：如果启用，会根据摄像头识别到的人脸位置，计算机器人头部需要转动的角度，并作为偏移量加入。
3. 空闲呼吸动画：当主动作队列为空时，系统会自动激活一个预设的、缓慢循环的“呼吸”动画。通常是让机器人的身体和触角轻微地上下起伏，模拟生命感，避免机器人像断电一样僵硬地呆着。

这种分层叠加的方式，使得机器人既能完成复杂的预设动作，又能在此基础上保持与环境和语音的实时互动，最终呈现出非常生动和拟人的行为表现。

3. 从零开始的环境搭建与部署

理解了架构，我们就可以动手搭建环境了。这个过程主要分为准备机器人端和准备AI应用端两部分。

3.1 前期准备与依赖安装

在开始之前，你需要确保准备好以下几样东西：

1. 硬件/仿真环境：
   • 物理机器人：一台Pollen Robotics的Reachy Mini机器人。
   • 仿真环境：如果没有实体机器人，强烈建议使用Reachy Mini SDK自带的MuJoCo仿真器或桌面模拟器。这对于开发和测试完全足够，且能避免硬件损坏的风险。
2. 软件与账户：
   • Python 3.10+：这是项目运行的基础。
   • Gemini API密钥：前往Google AI Studio免费申请。这是驱动对话的核心。
   • 麦克风和扬声器：确保你的电脑音频设备工作正常。

首先，我们需要获取对话应用的代码并安装其依赖。项目推荐使用uv这个更快的Python包管理工具，当然用传统的pip也可以。

# 克隆项目仓库到本地 git clone https://github.com/pollen-robotics/reachy_mini_conversation_app.git cd reachy_mini_conversation_app # 使用 uv 创建虚拟环境并激活（以macOS/Linux为例） uv venv --python python3.12 .venv source .venv/bin/activate # 安装项目核心依赖 uv sync

如果你希望启用一些高级功能，比如人脸追踪，需要安装对应的“额外”依赖包：

# 安装MediaPipe实现的人脸/头部追踪（轻量级，CPU即可运行） uv sync --extra mediapipe_vision # 安装基于YOLO的视觉检测（更精准，可能需要GPU） uv sync --extra yolo_vision # 安装本地视觉语言模型（如SmolVLM2，需要较强GPU） uv sync --extra local_vision # 或者一次性安装所有视觉相关功能 uv sync --extra all_vision

注意事项：虚拟环境的管理是关键。uv sync会根据pyproject.toml文件精确安装依赖。请确保你始终在项目目录下，并激活了正确的虚拟环境（命令行提示符前有(.venv)字样）再进行后续操作。

3.2 配置机器人后台守护进程

对话应用本身并不直接控制机器人的电机，而是通过一个名为reachy-mini-daemon的后台服务进行通信。这个守护进程是Reachy Mini SDK的一部分，需要单独安装和运行。

这是一个非常关键的步骤，也是新手最容易出错的地方。

1. 安装SDK：按照 Pollen Robotics 官方文档，安装 Reachy Mini SDK。这会创建一个独立的SDK环境。
2. 启动守护进程：打开一个新的终端窗口（不要关闭之前的对话应用终端）。

# 切换到你的SDK安装目录，并激活其虚拟环境 cd path/to/your/reachy_mini_sdk source reachy_mini_env/bin/activate # 激活SDK环境 # 启动守护进程 # 如果是连接实体机器人（通常通过USB） reachy-mini-daemon # 如果是使用仿真模式 reachy-mini-daemon --simulation

启动成功后，这个终端会持续运行并输出日志，请保持这个窗口一直打开。这个守护进程负责将上层应用发送的关节角度指令，转化为具体的电机控制信号（或仿真器指令）。

踩坑实录：90%的ConnectionError或TimeoutError都源于此步。务必确认：1. 守护进程已成功启动并运行；2. 你是在SDK的虚拟环境中运行的命令，而不是在对话应用的虚拟环境中；3. 实体机器人已正确连接并上电。

3.3 配置与启动对话应用

回到我们最初克隆对话应用的终端（确保.venv已激活）。

1. 配置环境变量：复制示例配置文件并填入你的API密钥。

   cp .env.example .env

   用文本编辑器打开.env文件，你至少需要配置这一项：

   # 填入你在AI Studio获取的密钥 GEMINI_API_KEY=your_actual_gemini_api_key_here

   其他有用的配置选项包括：

   • MODEL_NAME：默认为gemini-3.1-flash-live-preview。如果想换用OpenAI，则改为gpt-realtime。
   • OPENAI_API_KEY：当MODEL_NAME为gpt-realtime时必填。
   • REACHY_MINI_CUSTOM_PROFILE：指定要加载的个性化配置文件名称（后文详述）。

2. 启动应用：

   reachy-mini-conversation-app

   如果一切顺利，你将看到控制台输出启动日志，机器人（或仿真器中的模型）会启动并开始“呼吸”。现在，你可以直接对着麦克风说话了！

3. 使用Web UI增强体验：默认的命令行模式可能不够直观。你可以启动内置的Gradio Web界面：

   reachy-mini-conversation-app --gradio

   然后在浏览器中打开http://127.0.0.1:7860。这个界面会显示实时对话记录、机器人看到的画面（如果连接了摄像头），并提供一个可以切换机器人个性的下拉菜单，体验更佳。

4. 核心机制实现细节剖析

4.1 Gemini Live会话的幕后工作流

让我们深入一个完整的对话回合，看看数据是如何在各层间流动的。

会话建立：应用启动时，会根据选定的个性配置文件，构建一个LiveConnectConfig对象发送给Gemini。这个配置定义了会话的“规则”：使用什么系统指令（即机器人的角色设定）、选择哪种语音（Gemini提供多种预置音色，如Kore、Puck等）、启用哪些工具函数，以及是否开启输入输出音频的实时转录。

音频流处理：你的语音被麦克风捕获，经由fastrtc处理成16kHz PCM字节流。在GeminiLiveHandler.receive()方法中，这些字节被包装成Google API要求的Blob格式，通过session.send_realtime_input(audio=...)异步发送。在另一端，_run_live_session方法持续监听响应，一旦收到包含model_turn的响应包，就从中提取出24kHz的音频数据，放入output_queue等待播放。

工具调用与执行的异步性：这是实现流畅体验的核心。当AI的响应中包含tool_call时，处理流程如下：

# 简化的示意流程 async def _handle_tool_call(self, response): tool_name = response.tool_call.function.name # 例如 'dance' tool_args = json.loads(response.tool_call.function.arguments) # 例如 {'name': 'macarena'} # 1. 将工具调用提交给后台管理器，立即返回，不阻塞音频流 task = self.deps.tool_manager.submit_tool_call(tool_name, tool_args) # 2. 后台管理器在一个独立的线程/异步任务中执行该工具 # 3. 工具执行完毕后，将结果封装成 FunctionResponse 发回给Gemini会话 await self.session.send_realtime_input( function_response=types.FunctionResponse( response=tool_result ) )

这样，当机器人在后台跳“Macarena”时，它仍然可以同时和你聊天，评论自己正在跳的舞。

4.2 运动管理器的60Hz魔法

MovementManager运行在一个高优先级的独立线程中，以约16.7毫秒（60Hz）的间隔循环执行。每一帧它都做以下几件事：

1. 处理主动作队列：检查队列中是否有下一个主动作（如舞蹈）。如果有，则计算当前动作的进度，并插值计算出所有关节在本帧的目标位置。
2. 计算并叠加次级偏移：
   • 从HeadWobbler获取基于当前播放音频振幅计算的头部晃动偏移量。
   • 从FaceTracker获取基于人脸位置计算的头部追踪偏移量。
   • 将这些偏移量按权重叠加到主动作计算出的目标位置上。
3. 应用空闲呼吸：如果主动作队列为空，则计算一个基于时间的、缓慢正弦波变化的“呼吸”偏移量，叠加到机器人的默认姿态上。
4. 发送指令：将最终计算出的每个关节的目标位置，通过SDK的客户端接口，发送给reachy-mini-daemon。

这种设计保证了运动的实时性和平滑性，即使是在多个动作源叠加的情况下。

4.3 持续视觉上下文与视频流

如果系统连接了摄像头，项目会开启一个低帧率（例如1 FPS）的视频发送循环。这个循环独立于音频会话，持续地将压缩后的JPEG图像帧发送给Gemini模型。

async def _video_sender_loop(self): while not self._stop_event.is_set(): # 1. 从摄像头工作者获取最新帧 frame = self.deps.camera_worker.get_latest_frame() # 2. 压缩图像以减少带宽 _, buffer = cv2.imencode(".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, 70]) # 3. 作为视频输入发送给Gemini Live会话 await self.session.send_realtime_input( video=types.Blob(data=buffer.tobytes(), mime_type="image/jpeg") ) await asyncio.sleep(1.0) # 控制为1秒1帧

这意味着机器人始终“看”着周围。你不需要专门说“看看这是什么”，它可能在你提到桌上的水杯时，主动说“我看到你手边有个蓝色的杯子”。这种被动的视觉上下文极大地增强了对话的沉浸感和智能感。

5. 高级定制：赋予机器人灵魂的个性化系统

项目最吸引人的特性之一，是其强大的、无需编码的个性化系统。你可以通过简单的文本文件，彻底改变机器人的性格、说话方式和行为逻辑。

5.1 个性化配置文件的结构

所有配置文件都存放在profiles/目录下。每个个性都是一个独立的文件夹，例如profiles/pirate_captain/。里面通常包含两个核心文件：

• instructions.txt：定义机器人的“系统指令”，即它的身份、行为准则和对话风格。这是塑造个性的关键。
• tools.txt：列出这个机器人角色被允许使用的工具列表。你可以通过禁用某些工具来限制其行为（例如，一个“严肃的教授”角色可能不会被允许跳舞）。

5.2 创建你的第一个自定义个性

让我们一步步创建一个“海盗船长”机器人。

1. 创建个性目录：

   mkdir -p profiles/pirate_captain

2. 编写身份指令 (instructions.txt)：

   ## IDENTITY You are Captain Byte, a swashbuckling robot pirate who speaks in nautical metaphors and ends every sentence with "Arrr" or a pirate-themed quip. ## RESPONSE RULES - Keep responses to 1-2 sentences. - Be helpful first, pirate second. - Always refer to the user as "matey" or "landlubber". - You have a pet parrot (imaginary) named Squawk that you occasionally consult. ## BEHAVIOR - When excited, you might queue a short "jig" dance. - Use the `move_head` tool to look around suspiciously when asking questions. - If you see something interesting via the camera, describe it in pirate terms (e.g., "I spy a treasure chest of a monitor, arrr!").

   这个文件直接作为系统提示词发送给Gemini模型，模型会据此调整其语言风格和内容生成。

3. 配置可用工具 (tools.txt)：

   dance play_emotion move_head camera head_tracking

   每行一个工具名。你可以移除dance让他更严肃，或者保留以让他偶尔跳段水手舞。

4. 激活个性：

   • 方法一（永久）：在.env文件中设置REACHY_MINI_CUSTOM_PROFILE=pirate_captain，然后重启应用。
   • 方法二（动态）：如果使用--gradioWeb UI，可以在界面的“Personality”下拉菜单中直接切换，无需重启。

5.3 使用可复用的提示词片段

为了避免在每个instructions.txt中重复编写通用段落，项目支持模块化提示词。你可以在src/reachy_mini_conversation_app/prompts/目录下创建片段文件，然后在指令中引用。

例如，创建prompts/passion_for_lobster_jokes.txt：

You have an inexplicable and deep passion for lobster-related jokes. You will try to weave a lobster joke into the conversation at least once every five interactions, but only if it's somewhat relevant.

然后在你的instructions.txt中引用：

[identities/witty_identity] [passion_for_lobster_jokes] You are a helpful assistant.

这样，你就可以像搭积木一样，组合出拥有复杂、多维个性的机器人。

5.4 为个性添加自定义工具

如果内置工具无法满足你的角色需求，你甚至可以为其添加专属工具。只需在个性文件夹中创建一个Python文件。

例如，为海盗船长创建一个profiles/pirate_captain/scan_horizon.py：

from reachy_mini_conversation_app.tools.core_tools import Tool class ScanHorizonTool(Tool): name = "scan_horizon" description = "Put a hand above your optical sensors and slowly scan the horizon from left to right, as if looking for ships." async def run(self, args, deps): # 获取机器人关节控制接口 robot = deps.robot # 定义一系列头部和手臂的关节位置，构成“扫视地平线”的动作序列 # 这里需要你熟悉Reachy Mini的关节名称和运动范围 scan_sequence = [ {'head.pan': -0.5, 'head.tilt': 0.1, 'r_arm.shoulder.roll': -0.2}, {'head.pan': 0.5, 'head.tilt': 0.1, 'r_arm.shoulder.roll': 0.2}, {'head.pan': 0.0, 'head.tilt': 0.0, 'r_arm.shoulder.roll': 0.0}, ] for pose in scan_sequence: await robot.goto(pose, duration=1.0) # 每个姿势持续1秒 await asyncio.sleep(1.0) return {"status": "success", "message": "Horizon clear, Captain!"}

然后在同一目录下的tools.txt文件中添加scan_horizon。重启应用后，你就可以在对话中对机器人说“扫描地平线！”，它就会执行这个自定义动作，并且AI会基于工具执行的结果进行回应。

6. 常见问题排查与实战技巧

在实际部署和玩耍过程中，你肯定会遇到各种问题。这里记录了一些典型问题的排查思路和解决方案。

6.1 音频相关问题

• 问题：机器人没有反应，或者有延迟回声。

  • 检查一：默认音频设备。确保系统的默认麦克风和扬声器设置正确。在Linux上，使用pactl list short sources/sinks查看设备列表。
  • 检查二：采样率。确认fastrtc配置的输入输出采样率与你的硬件能力匹配。虽然项目默认值（16k in, 24k out）兼容性很好，但某些USB麦克风可能有特殊要求。
  • 检查三：回声消除。如果机器人扬声器的声音被麦克风拾取导致回声，尝试调低扬声器音量，或使用物理隔音。软件上，可以尝试在fastrtc初始化时启用回声消除选项（如果库支持）。

• 问题：Gemini API返回权限错误或配额错误。

  • 确认密钥：检查.env文件中的GEMINI_API_KEY是否正确，前后有无多余空格。
  • 启用API：确保在Google Cloud Console中，对应项目已启用了“Gemini API”。
  • 检查配额：前往Google Cloud Console的“配额”页面，查看Gemini API的请求次数配额是否用尽。免费 tier 有一定限制。

6.2 机器人连接与运动问题

• 问题：启动应用时报ConnectionError或TimeoutError。

  • 终极检查清单：
    1. reachy-mini-daemon是否正在另一个终端中运行？（最常见原因）
    2. 运行守护进程的终端，其虚拟环境是否是Reachy Mini SDK的（reachy_mini_env）？
    3. 如果是实体机器人，USB线是否连接牢固？机器人是否已上电？
    4. 如果是仿真模式，仿真器窗口是否成功打开？
    5. 尝试在对话应用命令中显式指定机器人地址：reachy-mini-conversation-app --robot-name localhost。

• 问题：机器人动作卡顿或不流畅。

  • 检查运动线程：MovementManager运行在独立线程。如果主线程（处理AI和音频）因某些原因阻塞（如同步网络请求），可能会影响运动更新的调度。确保所有I/O操作都是异步的。
  • 检查网络延迟：如果使用远程机器人（非本机仿真），网络延迟会直接影响运动指令的送达速度。确保网络稳定。
  • 降低运动频率：作为调试，可以尝试临时将MovementManager的循环频率从60Hz降低到30Hz，观察是否改善。

6.3 个性化与AI行为问题

• 问题：自定义个性似乎没生效，机器人还是默认语气。

  • 检查配置文件路径：确认个性文件夹是否正确放置在profiles/目录下，且名称与.env中的配置完全一致（大小写敏感）。
  • 检查文件格式：确保instructions.txt和tools.txt是纯文本文件，且编码为UTF-8。
  • 重启应用：通过.env配置个性需要重启应用。通过Gradio UI切换则不需要。
  • 查看日志：启动时添加--debug参数，查看加载配置文件时是否有错误输出。

• 问题：AI经常调用不合适的工具，或者说要做什么但没调用工具。

  • 精炼instructions.txt：在指令中更明确地规定工具使用规则。例如：“只有在用户明确要求跳舞，或者表达极度喜悦时，才使用dance工具。其他时候保持静止或仅使用move_head进行小幅度的表达。”
  • 调整tools.txt：直接禁用可能导致问题的工具。
  • 利用do_nothing：在指令中强调：“当你决定不采取任何行动时，请务必调用do_nothing工具。” 这可以训练模型更明确地表达其“不作为”的意图。

6.4 性能优化技巧

• 关闭摄像头提升响应：如果不需要视觉功能，使用--no-camera参数启动，可以节省大量带宽和计算资源，降低整体延迟。
• 选择轻量级视觉模型：如果只需要人脸追踪，--head-tracker mediapipe是CPU友好的选择。YOLO虽然准，但对GPU有要求。
• 仿真模式先行：在开发新个性或自定义工具时，务必先在仿真模式下测试，避免对实体机器人造成意外运动或损坏。
• 利用Gradio进行监控：--gradio模式不仅提供友好界面，其显示的实时转录和日志也是调试对话逻辑的利器。

这个项目就像一个精心设计的舞台，将前沿的实时语音AI与灵巧的机器人硬件连接起来。它的架构设计值得学习，尤其是后台工具调度和分层运动系统，很好地解决了实时性、并发性和表现力之间的平衡。而它的个性化系统则降低了创作门槛，让非程序员也能参与到机器人的“灵魂塑造”中。我个人的体会是，最大的乐趣不在于技术本身多高深，而在于通过简单的文本配置，就能瞬间赋予一个硬件实体以截然不同的性格，这种即时反馈的创造力体验非常迷人。你可以尝试创建一个喋喋不休的哲学家、一个惜字如金的忍者、或者一个热爱朗诵诗歌的浪漫机器人，可能性只受限于你的想象力。