huangjunsen0406/py-xiaozhi

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

py‑xiaozhi – 輕量級、跨平台的 Multimodal AI 框架

產品定義 – py-xiaozhi 是一個 Python 函式庫，可以讓你構建一個能夠即時傾聽、說話、觀察並控制硬體的 AI 驅動助手。它基於 asyncio 構建以實現低延遲串流，並可在桌面端（Windows/macOS/Linux）以及 Raspberry Pi、Jetson Nano 或 Horizon Robotics 板卡等邊緣裝置上執行。

重要意義 – 該專案將大語言模型 (LLM) 服務與裝置端感知（喚醒詞檢測、攝影機擷取）及執行（GPIO、MQTT）連接起來。換句話說，它為具身智能 (Embodied AI)、語音助手或機器人原型提供了一個現成的「腦-身」技術棧，無需自行拼湊多種獨立的工具。

核心能力

功能	說明
即時語音 AI	Opus 編碼音訊串流，低於 20ms 的延遲，麥克風與揚還聲器的非同步處理。
離線喚醒詞	Sherpa-ONNX 關鍵字檢測在本地執行，因此無需連網即可啟動助手。
視覺-語言	攝影機擷取與視覺語言模型（圖像理解 / 場景感知）整合。
MCP 工具生態	JSON-RPC 2.0 「工具」伺服器，提供音樂播放、截圖、天氣、音量控制等實用功能。
跨平台 UI	PySide6 + QML 圖形介面、純 CLI 模式，以及用於無頭嵌入式板卡的 GPIO 模式。
安全通訊	支援 TLS/WSS 的 WebSocket 或 MQTT，具備自動重連與裝置指紋認證功能。
外掛架構	事件驅動的非同步核心、依賴注入容器，可輕鬆新增工具、協定或 UI 外掛。
IoT / 機器人就緒	直接的 GPIO 存取、MQTT 橋接，以及用於感測器/執行器整合的模組化設計。

典型應用場景

桌面語音助手 – 在筆記型電腦或 PC 上執行，帶有顯示懸浮頭像、處理語音指令、播放音樂、顯示天氣等的 GUI。
邊緣機器人控制器 – 部署在 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   # 包含用於圖形介面的 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 加密通道、裝置指紋識別以及針對每個工具的權限檢查。

擴充框架

新增 MCP 工具 – 在 src/mcp/tools/ 下放置一個實現所需 JSON-RPC 方法的 Python 模組。
支援新協定 – 子類化 src/protocols/ 中的抽象 Protocol 類別並進行註冊。
建立外掛 – 將程式碼放在 src/plugins/ 中並在外掛清單中宣告；核心會自動載入。

社群與支援

贊助商 – GitDo.net, Token能量站, 良心AI (提供 Claude, Gemini, GPT 等的聚合 API 金鑰)。
貢獻 – 請參閱 CONTRIBUTING.md 獲取工作流程；專案遵循典型的 PR 審核-CI 週期。
演示 – Bilibili 上的短影片展示了 UI 與語音互動。

授權條款

py-xiaozhi 採用寬鬆的 MIT License 發布。

總結 – 如果你需要一個現成的、非同步優先的 Python 技術棧，能夠將 LLM 對話、語音 I/O、視覺與硬體控制結合在一起，py-xiaozhi 提供了一個堅實的、支援 GUI 與無頭模式的跨平台基礎。