人工智能

Reachy Mini Conversation App

约 3 分钟阅读 阅读
reachy_mini_conversation_app 语音智能体 Hugging Face Reachy Mini

源码安装

克隆 Reachy Mini Conversation App

git clone https://github.com/wang-junjian/reachy_mini_conversation_app
cd reachy_mini_conversation_app

创建虚拟环境并安装依赖

uv venv --python 3.12
source .venv/bin/activate
uv sync

⚠️ 注意：要完全复现此仓库 uv.lock 文件中的依赖关系，请运行 uv sync --frozen 命令。这将确保 uv 直接从 lock 文件安装依赖项，而无需重新解析或更新任何版本。

安装可选功能

uv sync --extra local_vision         # Local PyTorch/Transformers vision
uv sync --extra yolo_vision          # YOLO face-detection backend for head tracking
uv sync --extra mediapipe_vision     # MediaPipe-based head-tracking
uv sync --extra all_vision           # All vision features

合并额外功能或包含开发依赖项：

uv sync --extra all_vision --group dev

运行 Speech to Speech（实时模式）

speech-to-speech \
    --mode realtime \
    --device mps \
    --stt faster-whisper \
    --faster_whisper_stt_model_name small \
    --faster_whisper_stt_gen_language zh \
    --language zh \
    --llm_backend mlx-lm \
    --model_name mlx-community/Qwen3.5-4B-OptiQ-4bit \
    --init_chat_prompt "你是一位乐于助人、待人友善的人工智能助手。你礼貌谦和、尊重他人，且回复力求简洁。" \
    --tts qwen3 \
    --no_enable_live_transcription

运行应用

配置环境变量

编辑配置文件 .env

HF_REALTIME_CONNECTION_MODE=local
HF_REALTIME_WS_URL=ws://localhost:8765/v1/realtime
BACKEND_PROVIDER=huggingface

运行 Reachy Mini Conversation App

实时语音对话

reachy-mini-conversation-app

实时语音对话，使用 mediapipe 进行头部追踪。

reachy-mini-conversation-app --head-tracker mediapipe

架构分析

Reachy Mini Conversation App 是一个分层实时对话机器人应用。

📐 整体架构

项目采用四层分层架构：

用户 → UI层 → 后端处理 → 工具执行 → 机器人运动
       ↑                           ↓
       ←—— 音频/结果反馈 ←———————←

🔧 核心模块详解

1. 后端处理层 (base_realtime.py, huggingface_realtime.py, openai_realtime.py, gemini_live.py)

后端特点应用场景
Hugging Face默认，支持本地端点快速原型，隐私优先
OpenAI Realtime低延迟GPT-4对话高质量对话
Gemini Live多模态能力复杂推理任务
  • 统一抽象：ConversationHandler 基类定义通用接口
  • 核心职责：音频流处理、工具调用分发、实时转录

2. 对话处理器 (ConversationHandler)

实现：HuggingFaceRealtimeHandler / OpenAIRealtimeHandler / GeminiLiveHandler

关键方法：

  • receive() - 接收音频帧
  • emit() - 输出音频或事件
  • apply_personality() - 应用个性化配置
  • change_voice() - 切换语音

3. 工具层 (tools/ 目录)

核心工具框架：

  • core_tools.py 基类 - 所有工具的抽象
  • core_tools.py - 工具运行时依赖注入

内置工具：

move_head          - 头部姿态控制
dance / stop_dance - 编舞库集成
play_emotion / stop_emotion - 情感动作
camera             - 图像捕获与分析
head_tracking      - 面部追踪
idle_do_nothing    - 空闲模式

异步调度：BackgroundToolManager

  • 非阻塞工具执行
  • 可追踪、可取消
  • 完成通知机制

4. 运动控制层 (MovementManager)

分层设计：

主要动作（互斥）       次要动作（加性）
─────────────────     ──────────────
舞蹈                 头部摇晃（语音同步）
情感                 头部追踪（面部识别）
呼吸                 
姿态转移

控制特点：

  • 独立工作线程 + 命令队列
  • 60Hz 控制环，单点控制 robot.set_target()
  • 安全插值避免跳跃

5. 摄像头与视觉 (CameraWorker)

  • 线程安全的帧缓冲
  • 可选头部追踪：YOLO / MediaPipe
  • 面部丢失延迟（2s）+ 平滑插值

视觉处理：

  • 远端：调用后端LLM分析
  • 本地（可选）：SmolVLM2本地部署 (--local-vision)

📦 个性化系统 (Profiles)

结构：profiles/<name>/

instructions.txt     - 系统提示词模板
tools.txt           - 启用工具列表
voice.txt           - 声音选择（可选）
sweep_look.py       - 自定义工具（可选）

特性：

  • 内置配置 vs 外部配置
  • 配置热加载（Gradio UI）
  • 个性化管理：PersonalityUI / HeadlessPU
  • 锁定模式：LOCKED_PROFILE 常量禁用切换

🎛️ UI层

双UI支持：

UI类型特点适用
Gradio (--gradio)完整Web界面交互、实时转录
控制台 (默认)终端输出无头部署、服务器
设置面板FastAPI REST后台配置管理

🔌 配置与扩展性

配置：config.py

  • 环境变量驱动：.env / 启动参数
  • 后端选择、API密钥、连接模式、本地模型

外部扩展：

REACHY_MINI_EXTERNAL_PROFILES_DIRECTORY=./external_content/external_profiles
REACHY_MINI_EXTERNAL_TOOLS_DIRECTORY=./external_content/external_tools
AUTOLOAD_EXTERNAL_TOOLS=1  # 便捷模式自动加载

📊 数据流示例

用户语音 
  ↓
UI (Gradio/Console) 
  ↓
后端 (HF/OpenAI/Gemini)
  ├→ LLM理解意图
  ├→ 生成工具调用
  └→ 返回音频
  ↓
工具调度器
  ├→ dance: 运动队列
  ├→ camera: 图像捕获
  ├→ move_head: 头部控制
  └→ 返回结果
  ↓
运动管理器 → 机器人控制
  ├→ 主动作执行
  ├→ 次动作混合
  └→ 60Hz 实时控制

🎯 核心设计优势

  1. 多后端支持 - 灵活切换LLM服务
  2. 可扩展工具系统 - 内置+自定义+外部工具
  3. 实时性 - 低延迟音频流、60Hz运动控制
  4. 分层架构 - 各层相对独立，便于修改
  5. 个性化 - 配置文件驱动，无需代码改动
  6. 安全运动 - 线程隔离、平滑插值、互斥控制

相关文章