py-xiaozhi 多模态 AI 交互框架

核心信息

以下信息由程序从官方接口读取，不经模型改写。

仓库地址: https://github.com/huangjunsen0406/py-xiaozhi
许可证: MIT
语言: Python
维护方: huangjunsen0406
主页: https://huangjunsen0406.github.io/py-xiaozhi/
核验日期: 2026-11-01

它是什么

py-xiaozhi 是基于 Python 异步架构构建的多模态 AI 交互框架。py-xiaozhi 支持实时语音流、视觉语言任务和 IoT 设备控制。py-xiaozhi 演进自 xiaozhi-esp32 固件项目。py-xiaozhi 采用 MIT 许可证。

主要能力

多模态视觉功能提供摄像头采集与视觉语言模型集成,用于图像理解和场景感知。
MCP 工具生态是一个模块化的 JSON-RPC 2.0 工具服务器,涵盖音乐播放器、摄像头、截图、应用管理、天气和音量控制。
py-xiaozhi 提供 PySide6 + QML 图形界面、CLI 和 GPIO 三种界面模式,适配桌面、无头服务器和嵌入式环境。
离线唤醒词功能基于 Sherpa-ONNX 的设备端关键词检测,并支持自定义唤醒词。
py-xiaozhi 提供 GPIO 接口,用于机器人控制、硬件驱动和传感器集成。
WebSocket / MQTT 双协议通信支持 WSS/TLS 加密传输和自动重连。

怎么上手

基本要求中,Python 版本为 3.10 - 3.12。
基本要求中列出的操作系统是 Windows 10+、macOS 10.15+ 和 Linux。
基本要求中需要麦克风和扬声器设备。
语音唤醒作为可选功能,需要下载 Sherpa-ONNX 语音识别模型。
摄像头功能作为可选功能,需要摄像头设备和 OpenCV 支持。
main 分支包含最新代码;每次更新后需手动重新安装 pip 依赖,以确保获得新的依赖。

摘自 README · bash

# Clone project
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi

# Base install (CLI / GPIO mode)
uv sync                                    # Recommended (uv users)
# or: pip install -e .                    # pip users

# GUI mode (extra: PySide6 + qasync)
uv sync --extra gui                        # Recommended (uv users)
# or: pip install -e '.[gui]'             # pip users

# Full development environment (GUI + test / packaging tools)
uv sync --extra gui --group dev

# Code formatting
./format_code.sh

# Run program - GUI mode (default; requires gui extra)
python main.py

# Run program - CLI mode (base install is enough)
python main.py --mode cli

# Specify communication protocol
python main.py --protocol websocket  # WebSocket (default)
python main.py --protocol mqtt       # MQTT protocol

摘自 README · bash

# Installed command (GUI still needs the gui extra)
xiaozhi --mode cli
# Equivalent module entry point
python -m src --mode cli

# Full regression suite, including Qt model tests without a display
uv run --extra gui --extra tui python -m pytest -q -W error::RuntimeWarning

# Build sdist, then build the wheel from that sdist
uvx --from build pyproject-build
# Install the wheel into a temporary venv outside the checkout and verify it
python scripts/check_wheel.py dist/*.whl

适合谁

py-xiaozhi 可部署于 Windows、macOS、Linux 桌面以及 ARM 嵌入式平台(Raspberry Pi、Horizon Robotics RDK、Jetson Nano)。跨平台部署涵盖 Windows 10+、macOS 10.15+ 和 Linux(x86_64 与 ARM)。推荐配置中的内存为至少 4GB RAM,推荐 8GB 以上。

推荐配置中的存储为至少 2GB 可用磁盘空间,用于模型文件和缓存。基本要求中列出稳定的互联网连接,用于 AI 服务和在线功能。事件驱动架构基于 asyncio 异步事件循环。

分层设计将应用层、协议层和 UI 层分离。依赖注入通过 bootstrap 容器管理组件生命周期。插件系统加载音频、UI、MCP 工具及其他组件。

配置系统提供分层配置、点号访问和动态更新。源码检出、已安装的 wheel 和冻结构建共用同一个主入口函数。导入 py-xiaozhi 启动器时不会解析参数,也不会初始化配置和日志。

对于 wheel 安装,FFmpeg 从系统 PATH 中解析。PR 和分支推送会运行 3.10/3.12 上的 Python 测试以及已安装 wheel 的检查。

本站已收录的相关工具。