coderzc/open-xiaoai-bridge

Open‑XiaoAI Bridge – Xiaomi XiaoAI 스피커와 외부 AI 서비스 사이의 다리

무엇인가요 – Python 3.12+로 작성된 서버 사이드 구성 요소이며, Rust 클라이언트를 포함하고 있습니다. Docker 또는 베어메탈 환경에서 호스트에 실행되며, WebSocket을 통해 수정된 XiaoAI 스피커와 통신합니다. 스피커의 마이크/오디오 스트림을 가로채어 웨이크워드 감지, VAD, 선택적 오프라인 ASR를 수행한 후, 구성 가능한 여러 AI 백엔드 중 하나로 인식된 텍스트를 전달합니다. 응답은 스피커의 내장 TTS, Doubao 클라우드 TTS, OpenAI 호환 TTS 또는 로컬 MLX‑Audio 모델을 사용해 음성으로 변환되어 스피커로 재생을 위해 다시 전송됩니다.

핵심 기능 (README에 기재됨)

기능	기능 설명
OpenAI 호환 서비스	`/v1/chat/completions` 엔드포인트 (Hermes Agent API Server, OpenAI, Ollama, LM Studio 등)에 연결 가능.
QwenPaw 통합	인식된 텍스트를 Alibaba의 QwenPaw 에이전트에 HTTP 콘솔 API를 통해 전송하고, 에이전트의 응답을 재생.
OpenClaw 통합	명령을 OpenClaw 게이트웨이로 라우팅하며, 단일 실행 및 지속적인 다단계 대화 모두 지원.
XiaoZhi AI 통합	`xiaozhi‑esp32‑server` 프로토콜을 사용해 실시간 오디오 스트리밍 구현.
사용자 정의 웨이크워드	여러 중국어/영어 웨이크워드를 정의 가능하며, 각각 다른 AI 서비스나 OpenClaw 에이전트에 매핑 가능.
다중 에이전트 라우팅	하나의 스피커, 여러 웨이크워드 → 각 웨이크워드가 별도의 OpenClaw 세션을 선택 가능. 즉각적인 전환 가능.
지속적 대화	웨이크워드 이후, 다시 웨이크워드를 말하지 않고도 대화를 유지 가능. "소애 동학"을 말하면 중단.
VAD + KWS 프론트엔드	음성 활동 감지(VAD)로 오인 인식을 줄이고 전력 소모를 절감.
HTTP API	스피커 원격 제어 – 텍스트, URL, 파일 재생, TTS 트리거, 재생 중단, 상태 조회, 헬스 체크.
모듈식 설계	각 커넥터(XiaoZhi, OpenClaw, OpenAI, QwenPaw, API 서버, TTS)는 환경 변수로 온/오프 가능.

빠른 시작 (README에서)

스피커 준비 – SSH를 활성화하는 최신 펌웨어를 플래시하고, Rust 클라이언트(packages/client‑rust)를 설치.
모델 다운로드 – VAD + KWS(항상 필요) 및 원할 경우 로컬 오프라인 변환을 위해 Sherpa ASR를 다운로드. 모델 zip은 릴리스 페이지에 제공.

Docker Compose로 실행 (권장)

curl -O https://raw.githubusercontent.com/coderzc/open-xiaoai-bridge/main/config.py
curl -O https://raw.githubusercontent.com/coderzc/open-xiaoai-bridge/main/docker-compose.yml
# 필요 시 config.py / docker‑compose.yml 편집
docker compose up -d

./models를 컨테이너에 마운트하고 API를 포트 9092에서 노출.

로컬로 실행 – 리포지토리 복제 후 uv(Python)와 Rust 설치, 모델 파일을 core/models/에 배치한 후 시작:
```
API_SERVER_ENABLE=1 XIAOZHI_ENABLE=1 OPENCLAW_ENABLE=1 OPENAI_ENABLE=1 QWENPAW_ENABLE=1 ./scripts/start.sh
```
선택적으로 OPEN_XIAOAI_TOKEN으로 토큰 기반 클라이언트 인증을 활성화 가능.
서비스 구성 – config.py 편집. 각 백엔드(openai, openclaw, qwenpaw, xiaozhi)에는 엔드포인트 URL, API 키, 모델 이름, TTS 제공자 등을 설정하는 블록이 있음.

환경 변수 (요약)

변수	효과	기본값
`XIAOZHI_ENABLE`	XiaoZhi AI 백엔드 활성화	비활성
`OPENCLAW_ENABLE`	OpenClaw 커넥터 활성화	비활성
`OPENAI_ENABLE`	일반적인 OpenAI 호환 커넥터 활성화	비활성
`QWENPAW_ENABLE`	QwenPaw 커넥터 활성화	비활성
`API_SERVER_ENABLE`	HTTP 제어 API 활성화	비활성
`AUDIO_INPUT_ENABLE`	마이크 처리 활성화 (VAD/KWS/ASR에 필수)	활성
`API_SERVER_HOST` / `API_SERVER_PORT`	HTTP API 호스트/포트	`127.0.0.1` / `9092`
`OPEN_XIAOAI_TOKEN`	클라이언트 측 인증용 공유 비밀번호	없음 (인증 없음)
`CONFIG_PATH`	사용자 정의 `config.py` 경로	`./config.py`
`LOGLEVEL`	로깅 세부 수준	`INFO`

API 서버 (`API_SERVER_ENABLE=1` 시)

메서드	경로	목적
`POST`	`/api/play/text`	선택된 TTS로 텍스트 합성 후 스피커에서 재생
`POST`	`/api/play/url`	공개 URL에서 오디오 파일 스트리밍
`POST`	`/api/play/file`	로컬 오디오 파일 업로드 후 재생
`POST`	`/api/tts/doubao`	Doubao TTS 직접 호출 (클라우드 음성)
`GET`	`/api/tts/doubao_voices`	사용 가능한 Doubao 음성 ID 목록
`POST`	`/api/wakeup`	프로그래밍 방식으로 웨이크업 흐름 트리거
`POST`	`/api/interrupt`	현재 재생/TTS 중단
`GET`	`/api/status`	현재 재생 상태
`GET`	`/api/health`	간단한 헬스 체크

예시 사용법 (curl):

curl -X POST http://localhost:9092/api/play/text \
  -H "Content-Type: application/json" \
  -d '{"text": "안녕하세요, 저는 소애 동학입니다"}'

TTS 제공자 계층 구조

각 백엔드(openai, openclaw, qwenpaw)는 tts_provider를 지정 가능:
- xiaoai – 스피커 내장 TTS 사용 (추가 설정 없음)
- doubao – Volcano Engine 클라우드 TTS (app_id/access_key 필요)
- openai – 어떤 OpenAI 호환 /v1/audio/speech 서비스도 가능
- mlx_audio – 로컬 MLX‑Audio 서버 (Apple Silicon에서 유용)
tts_provider가 생략되면 원래 로직 적용: XiaoAI는 내장 TTS 사용, 다른 경우 Doubao로 백업.

브리지 작동 방식 (개요)

오디오 캡처 – 스피커의 Rust 클라이언트가 PCM 오디오를 WebSocket을 통해 전송 (open_xiaoai_server:4399).
전처리 – 서버는 수신 스트림에 대해 VAD와 KWS를 실행. 웨이크워드 일치 시 WakeupSessionManager가 세션 시작.
ASR – input_mode에 따라 다음 중 하나:
- local_asr – VAD → Sherpa ASR (오프라인) → 텍스트
- xiaoai_asr – 스피커의 내장 ASR를 브리지에 전달.
라우팅 – before_wakeup 후크 (config.py에서 사용자 편집 가능)는 "openai", "openclaw", "qwenpaw" 등의 문자열을 반환하여 이 세션의 타겟 백엔드 선택 가능.
백엔드 상호작용 – 선택된 커넥터가 텍스트를 원격 서비스에 전송, 응답 수신, 필요 시 TTS 실행 후 동일한 WebSocket을 통해 오디오를 스피커로 스트리밍.
지속적 대화 – XiaoAIConversationController가 ASR/AudioPlayer 이벤트 모니터링. "소애 동학" 또는 설정된 종료 문구를 말하면 세션 종료.

확장 및 사용자 정의

사용자 정의 웨이크워드 – KWS 설정에 새로운 키워드 정의. before_wakeup에서 적절한 식별자 반환으로 다른 백엔드에 매핑 가능.
다중 에이전트 라우팅 – 서로 다른 웨이크워드를 서로 다른 OpenClaw 에이전트에 할당하면 브리지 재시작 없이 에이전트를 즉시 전환 가능.
Docker 네트워킹 – 브리지 컨테이너가 호스트에서 실행 중인 서비스에 접근해야 할 경우, Mac에서는 host.docker.internal 별칭 사용 또는 network_mode: host 설정.
인증 – OPEN_XIAOAI_TOKEN 설정 시 Rust 클라이언트 측에서도 동일한 토큰 필요. 그렇지 않으면 어떤 클라이언트도 연결 가능.

누구에게 적합한가?

ChatGPT, Claude, LLaMA, 또는 사용자 정의 에이전트와 연결하고 싶은 XiaoAI 애호가.
저비용, 항상 작동하는 하드웨어 프론트엔드가 필요한 음성 중심 에이전트 개발 연구자.
Xiaomi 클라우드에 의존하지 않고 음성으로 로컬 서비스(예: Home Assistant)를 트리거하고 싶은 홈 오토메이션 애호가.

라이선스 및 커뮤니티

라이선스: MIT (LICENSE 참조).
스타 수: 배지에 표시. 프로젝트는 적극적으로 유지보수 중.
Docker 이미지: GitHub Container Registry (ghcr.io/coderzc/open-xiaoai-bridge)에 게시.
데모 영상: README에 두 개의 Bilibili 링크 제공.

요약

Open‑XiaoAI Bridge는 Xiaomi XiaoAI 스피커가 다양한 최신 LLM/에이전트 서비스의 프론트엔드로 작동할 수 있도록 해주는 진정한 오픈소스 통합 계층입니다. 웨이크워드 감지, 선택적 오프라인 음성 인식, 여러 백엔드로의 라우팅, 유연한 TTS 출력을 모두 간단한 config.py와 환경 변수로 구성 가능합니다.