huangjunsen0406/py-xiaozhi

Open-source AI assistant ecosystem with MCP integrations, multimodal workflows, IoT support, and cross-platform voice interaction.

py‑xiaozhi – 가볍고 크로스 플랫폼을 지원하는 멀티모달 AI 프레임워크

개요 – py-xiaozhi는 실시간으로 소리를 듣고, 말하고, 보고, 하드웨어를 제어할 수 있는 AI 기반 어시스턴트를 구축할 수 있는 Python 라이브러리입니다. 저지연 스트리밍을 위해 asyncio를 기반으로 구축되었으며, 데스크톱(Windows/macOS/Linux)뿐만 아니라 Raspberry Pi, Jetson Nano, Horizon Robotics 보드와 같은 에지 디바이스에서도 실행됩니다.

중요성 – 이 프로젝트는 대규모 언어 모델(LLM) 서비스와 온디바이스 인지(웨이크 워드 감지, 카메라 캡처) 및 동작(GPIO, MQTT)을 연결합니다. 즉, 여러 별도의 도구를 결합할 필요 없이 임바디드 AI(Embodied AI), 음성 비서 또는 로봇 프로토타입을 위한 준비된 "뇌-신체" 스택을 제공합니다.

핵심 기능

기능 상세 내용
실시간 음성 AI Opus 인코딩 오디오 스트리밍, 20ms 미만의 지연 시간, 마이크 및 스피커의 비동기 처리.
오프라인 웨이크 워드 Sherpa-ONNX 키워드 감지가 로컬에서 실행되어 인터넷 연결 없이도 어시스턴트를 활성화할 수 있습니다.
시각-언어 통합 카메라 캡처와 시각-언어 모델(이미지 이해 / 장면 인식)의 통합.
MCP 도구 생태계 음악 재생, 스크린샷, 날씨, 볼륨 조절 등의 유틸리티를 노출하는 JSON-RPC 2.0 "도구" 서버.
크로스 플랫폼 UI PySide6 + QML 그래픽 UI, 순수 CLI 모드, 그리고 헤드리스 임베디드 보드용 GPIO 전용 모드.
보안 통신 TLS/WSS를 지원하는 WebSocket 또는 MQTT, 자동 재연결 및 디바이스 핑거프린트 인증.
플러그인 아키텍처 이벤트 기반 비동기 코어, 의존성 주입 컨테이너, 새로운 도구, 프로토콜 또는 UI 플러그인의 쉬운 추가.
IoT / 로봇 공학 준비 완료 직접적인 GPIO 액세스, MQTT 브리지, 센서/액추에이터 통합을 위한 모듈형 설계.

주요 사용 사례

  • 데스크톱 음성 비서 – 플로팅 아바타를 보여주고, 음성 명령을 처리하며, 음악을 재생하고, 날씨를 보여주는 GUI를 갖춘 노트북 또는 PC에서 실행.
  • 에지 로봇 컨트롤러 – Raspberry Pi 또는 Jetson Nano에 배포하여 웨이크 워드로 듣기를 시작하고, 카메라 프레임을 처리하며, GPIO를 통해 모터를 구동.
  • 스마트 홈 허브 – MQTT를 통해 다른 장치와 연결하고, LLM이 자연어 의도 파싱을 처리하는 동안 도구 API(예: 조명 켜기/끄기)를 노출.
  • 연구용 프로토타입 – 인프라를 처음부터 구축할 필요 없이 멀티모달 파이프라인(음성 → LLM → 시각 → 동작)을 빠르게 프로토타입화.

시작하기 (빠른 시작 가이드)

# 1. 저장소 클론
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi

# 2. 의존성 설치 (권장: uv, 그렇지 않으면 pip)
uv sync                # 기본 설치 (CLI / GPIO 모드)
# uv sync --extra gui   # 그래픽 UI를 위한 PySide6 포함
# pip install -e.      # pip 사용자를 위한 대안

# 3. 어시스턴트 실행
# GUI 모드 (extra 설치 시 기본값)
python main.py

# CLI 전용 모드 (GUI 없음, 헤드리스 보드에 유용)
python main.py --mode cli

# 통신 프로토콜 선택 (기본값은 WebSocket)
python main.py --protocol mqtt

문서 – 전체 시작 튜토리얼, 설정 참조 및 API 문서는 https://huangjunsen0406.github.io/py-xiaozhi/에서 확인할 수 있습니다. Bilibili에서 비디오 가이드도 제공됩니다.

아키텍처 개요

  • 이벤트 기반 비동기 코어 (asyncio 루프) – 모든 I/O(오디오, 네트워크, 카메라)가 블로킹 없이 실행됩니다.
  • 계층형 설계 – 애플리케이션 로직 → 프로토콜 계층(WebSocket/MQTT) → UI 계층(PySide6/CLI/GPIO).
  • 의존성 주입 – 부트스트랩 컨테이너가 컴포넌트를 생성하고 연결하여 플러그인 추가를 쉽게 만듭니다.
  • 보안 – TLS 암호화 채널, 디바이스 핑거프린팅 및 도구별 권한 확인.

프레임워크 확장하기

  1. 새로운 MCP 도구 추가 – 필요한 JSON-RPC 메서드를 구현한 Python 모듈을 src/mcp/tools/ 아래에 넣습니다.
  2. 새로운 프로토콜 지원 – src/protocols/의 추상 Protocol 클래스를 상속받아 등록합니다.
  3. 플러그인 생성 – src/plugins/에 코드를 배치하고 플러그인 매니페스트에 선언하면 코어가 자동으로 로드합니다.

커뮤니티 및 지원

  • 스폰서 – GitDo.net, Token能量站, 良心AI (Claude, Gemini, GPT 등의 통합 API 키 제공).
  • 기여 – 워크플로우는 CONTRIBUTING.md를 참조하세요. 프로젝트는 전형적인 PR 리뷰-CI 사이클을 따릅니다.
  • 데모 – 짧은 Bilibili 비디오에서 UI와 음성 상호작용을 확인할 수 있습니다.

라이선스

py-xiaozhi는 허용적인 MIT License 하에 배포됩니다.

요약 – LLM 채팅, 음성 I/O, 시각 및 하드웨어 제어를 결합한 준비된 async-first Python 스택이 필요하다면, py-xiaozhi는 GUI와 헤드리스 옵션을 모두 갖춘 견고한 크로스 플랫폼 기반을 제공합니다.

관련

  • 프로젝트
    MervinPraison/PraisonAI

    PraisonAI는 자율적이고 자기 개선 가능한 AI 에이전트를 구축하기 위한 오픈소스 프레임워크입니다. 5계층 스택(Prompt → Context → Harness → Loop → Graph)에 더해, 로컬 또는 원격 사전(Docker, e2b, Modal 등)에서 에이전트를 실행할 수 있는 관리형 에이전트 계층을 제공합니다. Python SDK(`praisonaiagents`)는 선언형 에이전트, MCP 프로토콜을 통한 도구 통합, 루프 제어(예산, 도움말 루프 탐지), 그래프 오케스트레이션(라우팅, 병렬, 반복)을 제공합니다. CLI, 시각적 흐름 빌더, 대시보드, JavaScript SDK가 생태계를 완성하며, 100개 이상의 LLM 제공업체를 지원하고 MIT 라이선스입니다.

  • 프로젝트
    xinnan-tech/xiaozhi-esp32-server

    xiaozhi-esp32 프로젝트를 위한 백엔드 서버로, ESP32 장치가 음성, 시각 및 스마트 홈 제어 기능을 갖춘 AI 어시스턴트가 될 수 있도록 합니다.

  • 프로젝트
    78/xiaozhi-esp32

    LLM과 Model Context Protocol (MCP)를 통합한 오픈소스 ESP32 기반 AI 음성 챗봇 프레임워크로, 실시간 음성 상호작용과 하드웨어 제어를 지원합니다.

  • Dispatch
    Qwen 3.5‑397B‑A17B 출시: 1 M 토큰 컨텍스트와 최첨단 멀티모달 성능을 갖춘 하이브리드 선형‑어텐션 MoE 모델

    Qwen 3.5‑397B‑A17B는 토큰당 17 billion 파라미터만 활성화하는 397 billion 파라미터 멀티모달 모델로, 언어, 코딩, 추론 및 비전 작업에서 최첨단 성능을 제공하면서 이전 모델보다 최대 19배 빠릅니다.

  • 프로젝트
    modelscope/ms-agent

    MS‑Agent는 도구 호출, 메모리, 다중 모달 입력, 스킬 검색 시스템을 갖춘 경량 Python 프레임워크입니다. ModelScope의 Model Calling Protocol (MCP)을 사용해 LLM에 접근하며, React/FastAPI 웹 UI를 제공하고, 코드 생성, 짧은 동영상 생성, 심층 리서치 워크플로우용 사전 구축 프로젝트도 포함합니다.