简体中文 | English
项目简介
py-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。 本仓库是基于xiaozhi-esp32移植
演示
功能特点
🎯 核心AI功能
- AI语音交互：支持语音输入与识别，实现智能人机交互，提供自然流畅的对话体验
- 视觉多模态：支持图像识别和处理，提供多模态交互能力，理解图像内容
- 智能唤醒：支持多种唤醒词激活交互，免去手动操作的烦恼（可配置开启）
- 自动对话模式：实现连续对话体验，提升用户交互流畅度
🔧 MCP工具生态系统
- 系统控制工具：系统状态监控、应用程序管理、音量控制、设备管理等
- 日程管理工具：全功能日程管理，支持创建、查询、更新、删除事件，智能分类和提醒
- 定时任务工具：倒计时器功能，支持延时执行MCP工具，多任务并行管理
- 音乐播放工具：在线音乐搜索播放，支持播放控制、歌词显示、本地缓存管理
- 12306查询工具：12306铁路票务查询，支持车票查询、中转查询、列车路线查询
- 搜索工具：网络搜索和网页内容获取，支持必应搜索和智能内容解析
- 菜谱工具：丰富菜谱库，支持菜谱搜索、分类查询、智能推荐
- 地图工具：高德地图服务，支持地理编码、路径规划、周边搜索、天气查询
- 八字命理工具：传统八字命理分析，支持八字计算、婚姻分析、黄历查询
- 摄像头工具：图像捕获和AI分析，支持拍照识别和智能问答
🏠 IoT设备集成
- 设备管理架构：基于Thing模式的统一设备管理，支持属性和方法的异步调用
- 智能家居控制：支持灯光、音量、温度传感器等设备控制
- 状态同步机制：实时状态监控，支持增量更新和并发状态获取
- 可扩展设计：模块化设备驱动，易于添加新设备类型
🎵 高级音频处理
- 多级音频处理：支持Opus编解码、实时重采样
- 语音活动检测：VAD检测器实现智能打断，支持语音活动实时监控
- 唤醒词检测：基于Sherpa-ONNX的离线语音识别，支持多唤醒词和拼音匹配
- 音频流管理：独立输入输出流，支持流重建和错误恢复
- 音频回声消除：集成WebRTC音频处理模块，提供高质量的回声消除功能
- 系统音频录制：支持系统音频录制，实现音频环回处理
🖥️ 用户界面
- 图形化界面：基于PyQt5的现代GUI，支持小智表情与文本显示，增强视觉体验
- 命令行模式：支持CLI运行，适用于嵌入式设备或无GUI环境
- 系统托盘：后台运行支持，集成系统托盘功能
- 全局快捷键：支持全局快捷键操作，提升使用便捷性
- 设置界面：完整的设置管理界面，支持配置自定义
🔒 安全与稳定
- 加密音频传输：支持WSS协议，保障音频数据的安全性，防止信息泄露
- 设备激活系统：支持v1/v2双协议激活，自动处理验证码和设备指纹
- 错误恢复：完整的错误处理和恢复机制，支持断线重连
🌐 跨平台支持
- 系统兼容：兼容Windows 10+、macOS 10.15+和Linux系统
- 协议支持：支持WebSocket和MQTT双协议通信
- 多环境部署：支持GUI和CLI双模式，适应不同部署环境
- 平台优化：针对不同平台的音频和系统控制优化
🔧 开发友好
- 模块化架构：清晰的代码结构和职责分离，便于二次开发
- 异步优先：基于asyncio的事件驱动架构，高性能并发处理
- 配置管理：分层配置系统，支持点记法访问和动态更新
- 日志系统：完整的日志记录和调试支持
- API文档：详细的代码文档和使用指南
系统要求
基础要求
- Python版本：3.9 - 3.12
- 操作系统：Windows 10+、macOS 10.15+、Linux
- 音频设备：麦克风和扬声器设备
- 网络连接：稳定的互联网连接（用于AI服务和在线功能）
推荐配置
- 内存：至少4GB RAM（推荐8GB+）
- 处理器：支持AVX指令集的现代CPU
- 存储：至少2GB可用磁盘空间（用于模型文件和缓存）
- 音频：支持16kHz采样率的音频设备
可选功能要求
- 语音唤醒：需要下载Sherpa-ONNX语音识别模型
- 摄像头功能：需要摄像头设备和OpenCV支持
请先看这里
- 仔细阅读 项目文档 启动教程和文件说明都在里面了
- main是最新代码，每次更新都需要手动重新安装一次pip依赖防止我新增依赖后你们本地没有
技术架构
核心架构设计
- 事件驱动架构: 基于asyncio的异步事件循环，支持高并发处理
- 分层设计: 清晰的应用层、协议层、设备层、UI层分离
- 单例模式: 核心组件采用单例模式，确保资源统一管理
- 插件化: MCP工具系统和IoT设备支持插件化扩展
关键技术组件
- 音频处理: Opus编解码、WebRTC回声消除、实时重采样、系统音频录制
- 语音识别: Sherpa-ONNX离线模型、语音活动检测、唤醒词识别
- 协议通信: WebSocket/MQTT双协议支持、加密传输、自动重连
- 配置系统: 分层配置、点记法访问、动态更新、JSON/YAML支持
性能优化
- 异步优先: 全系统异步架构，避免阻塞操作
- 内存管理: 智能缓存、垃圾回收
- 音频优化: 5ms低延迟处理、队列管理、流式传输
- 并发控制: 任务池管理、信号量控制、线程安全
安全机制
- 加密通信: WSS/TLS加密、证书验证
- 设备认证: 双协议激活、设备指纹识别
- 权限控制: 工具权限管理、API访问控制
- 错误隔离: 异常隔离、故障恢复、优雅降级
开发指南
项目结构
py-xiaozhi/
├── main.py # 应用程序主入口（CLI参数处理）
├── src/
│ ├── application.py # 应用程序核心逻辑
│ ├── audio_codecs/ # 音频编解码器
│ │ ├── aec_processor.py # 音频回声消除处理器
│ │ ├── audio_codec.py # 音频编解码基础类
│ │ └── system_audio_recorder.py # 系统音频录制器
│ ├── audio_processing/ # 音频处理模块
│ │ ├── vad_detector.py # 语音活动检测
│ │ └── wake_word_detect.py # 唤醒词检测
│ ├── core/ # 核心组件
│ │ ├── ota.py # 在线更新模块
│ │ └── system_initializer.py # 系统初始化器
│ ├── display/ # 显示界面抽象层
│ ├── iot/ # IoT设备管理
│ │ ├── thing.py # 设备基类
│ │ ├── thing_manager.py # 设备管理器
│ │ └── things/ # 具体设备实现
│ ├── mcp/ # MCP工具系统
│ │ ├── mcp_server.py # MCP服务器
│ │ └── tools/ # 各种工具模块
│ ├── protocols/ # 通信协议
│ ├── utils/ # 工具函数
│ └── views/ # UI视图组件
├── libs/ # 第三方原生库
│ ├── libopus/ # Opus音频编解码库
│ ├── webrtc_apm/ # WebRTC音频处理模块
│ └── SystemAudioRecorder/ # 系统音频录制工具
├── config/ # 配置文件目录
├── models/ # 语音模型文件
├── assets/ # 静态资源文件
├── scripts/ # 辅助脚本
├── requirements.txt # Python依赖包列表
└── build.json # 构建配置文件
开发环境设置
# 克隆项目
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi
# 安装依赖
pip install -r requirements.txt
# 代码格式化
./format_code.sh
# 运行程序 - GUI模式（默认）
python main.py
# 运行程序 - CLI模式
python main.py --mode cli
# 指定通信协议
python main.py --protocol websocket # WebSocket（默认）
python main.py --protocol mqtt # MQTT协议
核心开发模式
- 异步优先: 使用
async/await语法，避免阻塞操作 - 错误处理: 完整的异常处理和日志记录
- 配置管理: 使用
ConfigManager统一配置访问 - 测试驱动: 编写单元测试，确保代码质量
扩展开发
- 添加MCP工具: 在
src/mcp/tools/目录创建新工具模块 - 添加IoT设备: 继承
Thing基类实现新设备 - 添加协议: 实现
Protocol抽象基类 - 添加界面: 扩展
BaseDisplay实现新的UI组件
状态流转图
+----------------+
| |
v |
+------+ 唤醒词/按钮 +------------+ | +------------+
| IDLE | -----------> | CONNECTING | --+-> | LISTENING |
+------+ +------------+ +------------+
^ |
| | 语音识别完成
| +------------+ v
+--------- | SPEAKING | <-----------------+
完成播放 +------------+
贡献指南
欢迎提交问题报告和代码贡献。请确保遵循以下规范：
- 代码风格符合PEP8规范
- 提交的PR包含适当的测试
- 更新相关文档
社区与支持
感谢以下开源人员
排名不分前后
Xiaoxia zhh827 四博智联-李洪刚 HonestQiao vonweller 孙卫公 isamu2025 Rain120 kejily 电波bilibili君 赛搏智能