pollen-robotics/reachy_mini_conversation_app

Reachy Mini 대화 앱 – 개요

목적 – Reachy Mini 로봇과 대화할 수 있는 Python 애플리케이션입니다. 음성을 Hugging Face 실시간 음성 모델로 스트리밍하고, 전사된 텍스트를 대규모 언어 모델(LLM) 어시스턴트로 보내며, 어시스턴트의 응답을 로봇 동작(춤, 머리 움직임, 감정 등)으로 변환합니다.

주요 기능

저지연 음성 – Hugging Face의 실시간 백엔드(또는 로컬 호스팅 엔드포인트)를 사용하여 음성-텍스트 및 텍스트-음성을 지원합니다.
비전 통합 – camera 도구는 프레임을 캡처하여 동일한 실시간 백엔드로 보내 이미지 분석을 수행합니다.
모션 블렌딩 – 큐 시스템이 고급 동작(춤, 포즈, 호흡)을 처리하고, "흔들림" 레이어가 음성 리듬에 반응합니다.
도구 생태계 – LLM은 도구 세트(예: dance, move_head, remember, 웹 검색, 날씨)를 호출할 수 있으며, 이는 로컬 Python 모듈 또는 원격 Hugging Face Spaces입니다.
개성 프로필 – 각 프로필은 프롬프트, 음성, 인사말, 기본 도구를 정의합니다. 선택적 웹 UI를 통해 즉시 개성을 전환할 수 있습니다.
장기 메모리 – 사용자에 대한 선택적 영구 사실을 저장하여 어시스턴트가 세션 간에 기억할 수 있습니다.
로컬 VAD 및 끼어들기 – 선택적 Silero 음성 활동 감지가 기기에서 실행되어 중단 처리를 빠르게 하고 로봇의 듣기를 원활하게 합니다.

작동 방식(아키텍처 개요)

사용자가 말함 → 마이크 오디오(16kHz)가 Hugging Face 실시간 서비스로 전송됩니다.
서비스는 전사 및 선택적으로 합성된 응답을 반환합니다.
전사된 턴은 LLM 어시스턴트로 전달되며, 어시스턴트는 도구를 요청할 수 있습니다.
앱은 도구를 실행하고(예: 로봇의 머리 움직이기, 감정 클립 재생, 웹 쿼리) 결과를 LLM에 반환합니다.
LLM의 최종 답변이 사용자에게 음성으로 전달되고 모션 블렌딩을 트리거할 수 있습니다.

저장소의 다이어그램(conversation_app_arch.svg)이 이러한 구성 요소를 시각화합니다.

시작하기

사전 요구 사항

Reachy Mini SDK가 먼저 설치되어 있어야 합니다(링크된 저장소 참조).
Python 3.12 및 종속성 관리를 위한 uv(권장) 또는 pip.
선택 사항: 호스팅 서비스를 사용하지 않으려면 로컬 Hugging Face 실시간 엔드포인트.

설치(uv 예시)

uv venv --python /opt/homebrew/bin/python3.12 .venv
source .venv/bin/activate
uv sync               # 런타임 종속성 설치
uv sync --group dev  # 개발 도구 설치(선택 사항)

(또는 기존의 python -m venv + pip install -e . 워크플로우를 사용하세요.)

구성

.env.example을 .env로 복사하고 다음 변수를 조정합니다:

HF_REALTIME_CONNECTION_MODE – deployed(기본값) 또는 local.
HF_REALTIME_WS_URL – 자체 호스팅 백엔드용 WebSocket URL.
LOCAL_VAD_ENABLED / LOCAL_BARGE_IN_ENABLED – 기기 내 음성 감지 및 중단을 전환합니다.
REACHY_MINI_MEMORY_ENABLED – 영구 메모리를 켜거나 끕니다.

웹 UI에서 편집한 설정은 settings.json에 저장되며 .env 기본값을 재정의합니다.

앱 실행

reachy-mini-conversation-app          # 콘솔 전용 모드
reachy-mini-conversation-app --ui    # 웹 UI도 시작(http://127.0.0.1:7860/)

Reachy Mini 데몬이 먼저 실행 중인지 확인하세요. 그렇지 않으면 TimeoutError가 표시됩니다.

CLI 플래그를 사용하면 카메라를 비활성화하고(--no-camera), 네트워크에서 특정 로봇을 선택하고(--robot-name), 자세한 디버깅을 활성화할 수 있습니다(--debug).

도구 – 어시스턴트가 할 수 있는 일

도구	기능	위치
`dance` / `stop_dance`	공개 댄스 라이브러리 데이터 세트에서 댄스 시퀀스를 큐에 넣거나 지웁니다.	핵심 설치
`play_emotion` / `stop_emotion`	감정 라이브러리 데이터 세트에서 짧은 감정 오디오 클립을 재생합니다.	핵심 설치
`camera`	프레임을 캡처하고 실시간 백엔드에서 실행합니다(카메라 필요).	핵심 설치
`move_head` / `head_tracking` / `sweep_look`	머리 포즈를 제어하거나 얼굴을 추적합니다.	핵심 설치
`remember` / `forget`	사용자에 대한 짧은 사실을 저장하거나 삭제합니다(`memory.v1.json`에 저장).	핵심 설치
`volume_control`	로봇 데몬을 통해 스피커 또는 마이크 볼륨을 가져오거나 설정합니다.	핵심 설치
`robot_status`	로봇 메타데이터(소프트웨어 버전, Wi-Fi IP, IMU, 설치된 앱)를 쿼리합니다.	핵심 설치
`pollen_robotics_reachy_mini_search_tool__search_web`	사전 게시된 Hugging Face Space를 통한 웹 검색.	원격 Space
`pollen_robotics_reachy_mini_weather_tool__get_weather`	현재 날씨 조회.	원격 Space
`pollen_robotics_reachy_mini_time_tool__get_time`	시간대 인식 시계 정보.	원격 Space
`pollen_robotics_reachy_mini_knowledge_tool__*`	회사/제품 FAQ 및 문서 검색.	원격 Space

Tool을 서브클래싱하는 Python 모듈을 만들어 src/reachy_mini_conversation_app/tools/에 배치하면 로컬 도구를 추가할 수 있습니다. 원격 도구는 MCP API를 구현하는 Hugging Face Space를 설치하여 추가됩니다.

사용자 정의 프로필 및 개성

프로필은 profiles/ 아래에 있습니다(또는 REACHY_MINI_CUSTOM_PROFILE로 지정된 사용자 정의 디렉토리). 각 프로필에는 profile.md 파일이 포함되어 있습니다:

프롬프트(Markdown 본문)는 어시스턴트의 페르소나를 형성합니다.
선택적 메타데이터(voice, greeting, default_tools).
UI에서 숨기기 위한 hidden 플래그.

UI를 사용하면 프로필을 생성, 선택, 편집하고 개성별로 개별 도구를 활성화/비활성화할 수 있습니다.

고급 주제

로컬 VAD: Silero VAD 모델 v6.2.1은 첫 실행 시 다운로드되어 캐시되고 ONNX Runtime으로 실행되어 1초 미만의 감지를 제공합니다.
끼어들기: 활성화하면 로봇이 응답 중 사용자가 말하는 것을 감지하면 재생 볼륨을 낮추어 원활한 중단을 허용합니다.
디버그 진단: --debug는 /static/vad-monitor.html과 VAD 확률 및 상태 변경을 스트리밍하는 /rpc WebSocket을 노출합니다(지연 시간 조정에 유용).
다중 로봇: --robot-name을 사용하여 동일한 서브넷의 특정 데몬을 지정합니다.

누가 사용할 수 있나요?

연구자 구현된 대화 에이전트를 구축하는 사람.
교육자 물리적 로봇에서 다중 모달 AI(음성, 시각, 동작)를 시연하는 사람.
취미 사용자 확장 가능한 도구 플러그인을 갖춘 플러그 앤 플레이 음성 제어 로봇을 원하는 사람.

라이선스

이 저장소는 MIT 라이선스로 배포됩니다(LICENSE 참조).