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 是一个 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 和无头模式的跨平台基础。