想像一下，一個微型桌面機器人可以聽你說話，即時回复，根據指令跳舞，追蹤你的臉，偶爾還會講個冷笑話——所有這些都由 Gemini Live API 提供支援。

這正是Reachy Mini 對話應用程式的功能。它是一款開源的 Python 應用程式，可以將Pollen Robotics 的 Reachy Mini連接到即時語音 LLM，使機器人能夠進行全雙工音訊對話，同時透過頭部動作、天線擺動、舞蹈和情感表達來展現自己。

在本教程中，您將學習：

1. 架構工作原理－從麥克風到馬達。

2. 如何在自己的電腦上進行設定。

3. 如何在不寫任何一行 Python 程式碼的情況下，賦予機器人獨特的個性。

讓我們深入探討一下。

建築概覽

該應用程式分為四個相互協作的層：

┌─────────────┐
│  Your voice │  Microphone audio (16-bit PCM, 16 kHz)
└──────┬──────┘
       ▼
┌─────────────────────────────────────┐
│  fastrtc  (low-latency WebRTC I/O)  │
│  ─ streams audio to/from the LLM    │
│  ─ resamples between sample rates   │
└──────┬──────────────────┬───────────┘
       │                  │
       ▼                  ▼
┌──────────────┐   ┌──────────────────┐
│  Gemini Live │   │  OpenAI Realtime │   (pick one via MODEL_NAME)
│  Handler     │   │  Handler         │
└──────┬───────┘   └──────┬───────────┘
       │                  │
       ▼                  ▼
┌─────────────────────────────────────┐
│  Tool dispatch layer                │
│  ─ dance, play_emotion, camera,     │
│    move_head, head_tracking, ...    │
└──────┬──────────────────────────────┘
       ▼
┌─────────────────────────────────────┐
│  MovementManager  (60 Hz loop)      │
│  ─ sequential primary moves         │
│  ─ additive secondary offsets       │
│    (speech wobble + face tracking)  │
│  ─ idle breathing                   │
└──────┬──────────────────────────────┘
       ▼
┌─────────────┐
│ Reachy Mini │  Robot hardware / simulator
└─────────────┘

音訊循環

該應用程式的核心是AsyncStreamHandler （來自fastrtc庫）。預設後端是Gemini Live （ gemini_live.py中的GeminiLiveHandler ），它使用 Google GenAI SDK 透過session.send_realtime_input()實現雙向音訊串流傳輸。

如果您喜歡透過 OpenAI 的 API 使用基於 WebSocket 的串流傳輸，也可以使用另一個OpenAI Realtime後端（ openai_realtime.py中的OpenaiRealtimeHandler ）。您可以透過設定MODEL_NAME環境變數來切換後端——應用程式的其他部分不會知道或關心目前使用的是哪個後端。

以下是 Gemini 處理程序內部的簡化流程：

# 1. Microphone → Gemini
async def receive(self, frame):
    pcm_bytes = audio_to_int16(frame).tobytes()
    await self.session.send_realtime_input(
        audio=types.Blob(data=pcm_bytes, mime_type="audio/pcm;rate=16000")
    )

# 2. Gemini → Speaker
async def _run_live_session(self):
    async with client.aio.live.connect(model=..., config=...) as session:
        async for response in session.receive():
            if response.server_content and response.server_content.model_turn:
                for part in response.server_content.model_turn.parts:
                    audio_array = np.frombuffer(part.inline_data.data, dtype=np.int16)
                    await self.output_queue.put((24000, audio_array))

            if response.tool_call:
                await self._handle_tool_call(response)

音訊輸入為 16 kHz，音訊輸出為 24 kHz，轉錄和工具呼叫在同一會話中進行。

工具呼叫

當 LLM 決定讓機器人執行某些操作（例如跳舞、環顧四周、表達某種情緒）時，它會發出函數呼叫。應用程式會自動在 OpenAI 和 Gemini 格式之間轉換這些函數呼叫，然後透過BackgroundToolManager分發它們，從而確保音訊串流不會被阻塞：

LLM says: "dance(name='macarena')"
  → BackgroundToolManager starts a task
  → Task calls MovementManager.queue_move(MacarenaMove)
  → Result sent back to the LLM so it can narrate what happened

內建工具包括：

工具 | 功能介紹 |

|------|-------------|

| dance | 從開放式舞蹈庫中選擇一支舞蹈 |

| play_emotion | 播放一段錄製的情緒片段（開心、難過、驚訝…） |

| move_head | 向左/向右/向上/向下傾斜頭部 |

| camera | 捕捉影像並將其發送到 LLM 進行視覺理解 |

| head_tracking | 開啟或關閉臉部追蹤 |

| do_nothing | 明確保持空閒狀態（LLM 在決定不採取任何行動時使用此參數） |

運動系統

MovementManager在專用執行緒中執行一個60 Hz 的控制循環。它混合了兩種類型的運動：

• 主要動作（舞蹈、表情、常用姿勢）依序從隊伍中播放。一次只能播放一個動作。

• 次要偏移（語音反應式抖動、臉部追蹤）是疊加的——它們疊加在任何主要動作之上。

當沒有發生任何事情時，機器人會自動開始輕柔的呼吸動畫——伴隨著天線的輕微上下搖擺——因此它總是看起來栩栩如生。

連續視訊串流

連接相機後，Gemini 處理程序會執行1 FPS 的視訊循環，不斷向模型發送 JPEG 影格：

async def _video_sender_loop(self):
    while not self._stop_event.is_set():
        frame = self.deps.camera_worker.get_latest_frame()
        _, buffer = cv2.imencode(".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, 70])
        await self.session.send_realtime_input(
            video=types.Blob(data=buffer.tobytes(), mime_type="image/jpeg")
        )
        await asyncio.sleep(1.0)

這使得機器人能夠被動地感知視覺環境——它無需你要求就能對所看到的內容進行評論。

https://youtu.be/jkdvMEvG8T8

先決條件

在開始之前，請確保您已準備好：

• 已安裝Python 3.10 或更高版本

• Reachy Mini 機器人（實體或透過Reachy Mini SDK模擬）

• 來自AI Studio 的Gemini API 金鑰

• 一個能正常運作的麥克風和揚聲器

沒有機器人？您仍然可以探索程式碼並在模擬模式下執行——SDK 包含 MuJoCo 模擬器和桌面模型。

步驟 1：複製並安裝

此專案使用uv進行快速依賴管理（pip 也適用）。

# Clone the repo
git clone https://github.com/pollen-robotics/reachy_mini_conversation_app.git
cd reachy_mini_conversation_app

# Create a virtual environment (macOS example)
uv venv --python python3.12 .venv
source .venv/bin/activate

# Install dependencies
uv sync

選用附加項

想要人臉追蹤、局部視覺或YOLO功能？安裝對應的擴充功能：

uv sync --extra mediapipe_vision   # Lightweight head tracking
uv sync --extra yolo_vision        # YOLO-based face detection
uv sync --extra local_vision       # On-device VLM (SmolVLM2, GPU recommended)
uv sync --extra all_vision         # Everything

步驟 2：設定您的環境

cp .env.example .env

開啟.env並填寫：

# Your Gemini API key — that's all you need to get started
GEMINI_API_KEY=your-gemini-api-key-here

這是最低配置——該應用程式預設使用 Gemini Live。完整選項清單：

| 變數 | 描述 |

|----------|-------------|

| GEMINI_API_KEY | 您的 Gemini 金鑰。也接受GOOGLE_API_KEY 。 |

| MODEL_NAME | 預設為gemini-3.1-flash-live-preview 。設定為gpt-realtime則改用 OpenAI Realtime。 |

| OPENAI_API_KEY | 僅當您切換到 OpenAI 後端時才需要。 |

| REACHY_MINI_CUSTOM_PROFILE | 要載入的性格設定檔名稱（見下文）。 |

步驟 3：啟動 Reachy Mini 守護程式

對話應用程式透過 Reachy Mini SDK 守護程式與機器人進行通訊。此守護程式是作為Reachy Mini SDK安裝的一部分而安裝的，而不是安裝在對話應用程式的.venv檔案中。

開啟另一個終端並啟動SDK的虛擬環境：

# Navigate to wherever you cloned/installed the Reachy Mini SDK
cd path/to/reachy_mini
source reachy_mini_env/bin/activate

然後啟動守護程序（保持此終端執行）：

# Physical robot — auto-detects USB connection
reachy-mini-daemon

# Or simulation mode
reachy-mini-daemon --simulation

重要提示：守護程序必須在整個會話期間保持在獨立的終端中運作。切換回您的對話應用程式終端（已啟用.venv環境）以進行下一步操作。

>

如果在啟動對話應用程式時看到TimeoutError錯誤，則表示守護程式沒有執行。

步驟 4：啟動對話應用

在步驟 1 中的終端機（已啟動對話應用程式的虛擬環境）中，執行：

reachy-mini-conversation-app

搞定！機器人會開始輕輕呼吸，你就可以開始說話了。它預設以控制台模式運作——你的終端就成了它的互動介面。

Web UI 模式

想要一個帶有即時文字記錄和聊天機器人面板的視覺化介面？新增--gradio ：

reachy-mini-conversation-app --gradio

這將啟動一個名為 Gradio 的應用程式，地址為http://127.0.0.1:7860，您可以在其中查看對話、切換角色以及查看相機畫面。

更多 CLI 選項

# With MediaPipe head tracking
reachy-mini-conversation-app --head-tracker mediapipe

# Audio-only (no camera)
reachy-mini-conversation-app --no-camera

# Verbose logging
reachy-mini-conversation-app --debug

# Connect to a specific robot on the network
reachy-mini-conversation-app --robot-name my-reachy

客製化機器人的個性

有趣的地方就在這裡。這款應用程式使用設定檔系統——也就是控制機器人自我認知的純文字檔案。

概況結構

profiles/
├── default/
│   ├── instructions.txt   # System prompt
│   └── tools.txt          # Which tools are enabled
├── mars_rover/
│   ├── instructions.txt
│   └── tools.txt
├── noir_detective/
│   ├── instructions.txt
│   └── tools.txt
└── ...

塑造你的個性

1. 在profiles/下建立一個資料夾：

mkdir 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".

3. 建立一個名為tools.txt文件，列出機器人可以使用的工具：

dance
play_emotion
move_head
camera
head_tracking

4. 激活它：

# In your .env file
REACHY_MINI_CUSTOM_PROFILE="pirate_captain"

或直接從 Gradio 使用者介面的「個人化」面板進行切換—無需重新啟動。

可重複使用的提示符號片段

個人資料系統支援可組合提示。無需重複編寫文本，請引用共享片段：

# instructions.txt
[identities/witty_identity]
[passion_for_lobster_jokes]
You love to dance and will look for any excuse to bust a move.

每個[placeholder]都從src/reachy_mini_conversation_app/prompts/中提取內容。這可以保持個人資料的簡潔性，並允許您混合搭配不同的性格特徵。

自訂工具

您甚至可以透過將 Python 檔案放入設定檔資料夾來新增特定於設定檔的工具。例如，內建example設定檔包含一個名為sweep_look.py工具，該工具可讓機器人緩慢掃描房間：

# profiles/example/sweep_look.py
from reachy_mini_conversation_app.tools.core_tools import Tool

class SweepLookTool(Tool):
    name = "sweep_look"
    description = "Slowly look around the room in a sweeping motion."

    async def run(self, args, deps):
        # Queue a sequence of head movements...
        return {"status": "done", "description": "Finished looking around"}

在tools.txt中啟用它：

dance
play_emotion
sweep_look    # Your custom tool

Gemini Live 會話的底層運作原理

讓我們完整地追蹤一次對話，看看所有細節是如何銜接起來的。

1. 會話設定

應用程式啟動時，它會建立一個包含以下內容的LiveConnectConfig ：

• 系統提示（來自目前活動設定檔）

• 語音選擇（Gemini 支援：Aoede、Charon、Fenrir、 Kore （預設）、Leda、Orus、Puck、Zephyr）

• 每個已啟用工具的功能聲明

• 啟用音訊轉錄輸入和輸出

live_config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    system_instruction=types.Content(parts=[types.Part(text=instructions)]),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore"),
        ),
    ),
    tools=[{"function_declarations": declarations}],
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
)

2. 你說些什麼

您的麥克風音訊流經 fastrtc → receive() → 重採樣至 16 kHz → 以原始 PCM 位元組傳送至 Gemini。

3. 雙子座回應

響應流可以在一次操作中包含多種類型的資料：

• 音訊片段→ 排隊等待播放並輸入到HeadWobbler （用於產生語音反應式頭部搖擺）

• 輸入轉錄→ 聊天視窗中顯示“使用者所說的話”

• 輸出轉錄內容→ 在聊天視窗中顯示“機器人說的話”

• 工具呼叫→ 分發給BackgroundToolManager

• 中斷訊號→ 使用者闖入，清除音訊佇列

4. 工具執行

工具呼叫在背景任務中執行，因此不會阻塞音訊串流。工具完成後，其結果會以FunctionResponse形式傳回 Gemini，模型可以敘述發生了什麼事：

「我剛才為你跳了一小段開心的舞！💃」

5. 空閒行為

如果超過 15 秒無人說話且機器人處於空閒狀態，則控制器會發送一次輕推：

"You've been idle for a while. Feel free to get creative — dance, 
show an emotion, look around, do nothing, or just be yourself!"

這會觸發機器人自主選擇一個動作——可能是跳舞，也可能是好奇地歪頭——即使在暫停期間也能保持互動的活躍性。

部署選項

本地（建議用於開發）

只需按照上述步驟執行reachy-mini-conversation-app即可。該應用程式會連接到本地網路上的機器人守護程式。

Cloud Run（用於 Twilio 手機整合）

該應用程式還可以部署到 Google Cloud Run，並整合 Twilio 以進行電話通話。這是一種更高級的設定——請查看程式碼庫的部署文件以了解詳細資訊：

• 配置 Twilio 媒體串流

• 設定基於 IAM 的身份驗證

• 使用 Google Secret Manager 管理金鑰

內建個性

此倉庫自備 15 個現成的設定文件，方便您快速上手：

| 簡介 | 角色 |

|---------|-----------|

| default | 友善、簡潔且略帶幽默感的機器人助手 |

| mars_rover | 一輛探索火星的探測車 |

| noir_detective | 一位來自 20 世紀 40 年代電影的硬漢偵探 |

| victorian_butler | 一位舉止得體的英國管家 |

| mad_scientist_assistant | 一位興奮的實驗室助理 |

| bored_teenager | ……你懂的 |

| cosmic_kitchen | 一位太空主題烹飪節目主持人 |

| hype_bot | 對一切事物都充滿熱情 |

| captain_circuit | 一個超級英雄機器人 |

| chess_coach | 一位耐心細緻的西洋棋導師 |

| nature_documentarian | 大衛艾登堡風格 |

| sorry_bro | 為所有事情道歉 |

| tedai | 一位 TED 演講者 |

| time_traveler | 來自未來的訪客 |

試試看！每一種都會徹底改變機器人的行為和反應。

總結

Reachy Mini 對話應用程式展示了將即時語音 AI 與富有表現力的機器人技術相結合所能實現的無限可能。其成功的關鍵設計決策包括：

• 處理程序抽象化－預設使用 Gemini Live，也可選擇 OpenAI Realtime 作為替代方案。

• 後台工具調度－工具呼叫絕不會阻塞音訊串流。

• 分層運動系統－主運動+輔助偏移+空閒呼吸=總是充滿活力的機器人

• 純文字設定檔－無需編寫程式碼即可自訂個人化設置

整個專案採用 Apache 2.0 開源授權。您可以 fork 它，賦予您的機器人個性，並讓我們知道您建造了什麼！

連結：

• 📦 GitHub 倉庫

• 🤖 Reachy Mini SDK

• 💃舞蹈庫（擁抱臉）

• 😊表情庫（擁抱的表情）

• 🔑取得 Gemini API 金鑰

原文出處：https://dev.to/googleai/build-a-talking-robot-with-gemini-live-and-reachy-mini-20e2