py-xiaozhi 小智语音AI助手GitHub地址一个基于xiaozhi-esp32移植到Python实现的小智AI语音助手客户端，支持语音交互、多模态视觉识别、IoT设备控制、联网音乐播放等功能，无需专用硬件即可体验AI语音助手的智能交互。## 预览## 项目背景本项目基于开源项目xiaozhi-esp32进行Python生态的移植重构，通过桌面端软件方案复现智能语音交互核心功能。相较于原ESP32硬件方案，本实现采用纯Python开发并整合PyAudio、Vosk等开源库，在保留唤醒词识别、语音对话、指令执行等核心功能的同时，实现了功能扩展，使普通用户无需专用硬件设备即可体验AI语音交互技术。## 解决的痛点- 硬件依赖高：传统语音助手需要专用硬件，成本高且不便携，本项目仅需普通电脑和麦克风- 学习门槛高：市面上缺乏开源的AI语音交互学习平台，本项目提供完整源码和详细文档- 功能单一：大多数开源语音助手功能单一，本项目集成多种智能交互功能- 二次开发难：闭源系统难以进行个性化定制，本项目采用模块化设计便于扩展- 跨平台支持差：很多语音助手只支持特定平台，本项目支持Windows、macOS和Linux## 解决方案- 纯软件实现：使用Python实现全功能AI语音助手，无需专用硬件- 开源代码：提供完整源代码和详细文档，便于学习和二次开发- 多功能集成：集成语音交互、多模态视觉、IoT控制、音乐播放等多种功能- 模块化设计：采用分层架构设计，各功能模块职责明确，便于扩展和定制- 跨平台支持：经过充分测试，确保在Windows、macOS和Linux系统上稳定运行## 功能特点### 语音交互- 双重交互模式：支持长按对话模式（按住说话，松手发送）和自动对话模式（自动检测语音并发送）- 语音唤醒：支持自定义唤醒词激活系统，免去手动操作（默认使用"小智小智"作为唤醒词）- 实时打断：支持在AI回答过程中随时打断，实现更自然的对话体验- 连续对话：智能保持对话上下文，无需重复唤醒即可继续对话- 加密音频传输：采用WSS协议，保障音频数据的安全传输### 视觉多模态- 摄像头控制：支持通过语音命令打开/关闭摄像头- 图像智能识别：集成智普视觉大模型，能够分析和描述摄像头捕获的画面内容- 多场景支持：适用于物体识别、场景描述、文字识别等多种视觉任务### IoT设备控制- 统一设备管理：采用ThingManager统一管理所有IoT设备- 灵活扩展架构：基于Thing基类的设备抽象，便于添加自定义设备- 虚拟设备支持：内置灯控、温度传感器等虚拟设备，便于功能演示- 设备状态同步：实时同步和显示设备状态变化### 音乐播放- 在线音乐搜索：支持通过歌名、歌手搜索在线音乐资源- 播放控制：支持播放、暂停、上一首、下一首等基本控制- 歌词显示：支持显示当前播放歌曲的歌词- 播放进度控制：支持查看和调整播放进度- 本地缓存：自动缓存播放过的音乐，减少流量消耗### 系统功能- 双界面模式：支持图形界面(GUI)和命令行界面(CLI)两种运行模式- 跨平台音量控制：提供统一的音量控制接口，支持各大主流操作系统- 系统状态可视化：直观显示系统当前状态和操作反馈- 丰富的配置选项：支持通过config.json自定义各项功能参数- 自动验证码处理：首次使用时自动复制验证码并打开浏览器，简化用户操作## 技术栈- 后端：Python 3.9-3.12- 音频处理：PyAudio, Opus (音频编解码)- 语音识别：Vosk (离线语音唤醒)- GUI界面：Tkinter (轻量级跨平台界面)- 通信协议：WebSocket/MQTT (双协议支持)- 多媒体：Pygame (高性能音乐播放)- IoT控制：自定义协议 (设备抽象和管理)- 视觉识别：OpenCV, 智普视觉API## 项目结构├── .github # GitHub 相关配置├── config # 配置文件目录├── docs # 详细文档目录├── hooks # PyInstaller钩子目录├── libs # 依赖库目录├── resources # 资源文件目录├── scripts # 实用脚本目录├── src # 源代码目录│ ├── audio_codecs # 音频编解码模块│ ├── audio_processing # 音频处理模块│ ├── constants # 常量定义│ ├── display # 显示界面模块│ ├── iot # IoT设备相关模块│ │ ├── things # 具体设备实现│ │ ├── thing.py # 设备基类│ │ └── thing_manager.py # 设备管理器│ ├── protocols # 通信协议模块│ ├── utils # 工具类模块│ └── application.py # 应用程序主类├── LICENSE # 项目许可证├── README.md # 项目说明文档├── main.py # 程序入口点└── requirements.txt # Python 依赖包列表## 安装运行1. 克隆项目仓库 git clone https://github.com/huangjunsen0406/py-xiaozhi.git cd py-xiaozhi 2. 安装依赖 - 请根据项目根目录的docs下的文档进行安装其他第三方依赖 pip install -r requirements.txt # Windows/Linux pip install -r requirements_mac.txt # macOS 3. 运行程序 python main.py # 默认GUI模式 python main.py --mode cli # 命令行模式 python main.py --protocol mqtt # 使用MQTT协议 ## 使用说明### 基本操作- 启动程序：运行main.py- 语音交互：点击麦克风按钮或使用唤醒词激活- 结束对话：等待AI回复完成或点击停止按钮- 打断功能：在AI回答过程中使用F3键或界面按钮打断- 音量调节：使用界面上的音量滑块调节### 语音命令示例- 基础交互："你好"、"你是谁"、"谢谢"、"再见"- 灯光控制："打开/关闭客厅的灯"- 音乐播放："播放周杰伦的稻香。"- 摄像头控制："打开摄像头"、"识别画面"、"关闭摄像头"- 音量控制："把音量调到50%"、"音量调小一点"### 配置说明- 唤醒词设置：在config.json中设置USE_WAKE_WORD为true- 摄像头配置：配置CAMERA部分的参数，包括摄像头索引和视觉API密钥- 音频设置：调整AUDIO部分的参数，包括采样率和缓冲区大小- 协议选择：设置默认通信协议（WebSocket或MQTT）### 高级功能- 自定义IoT设备：通过继承Thing基类创建自定义设备- 视觉识别配置：接入智普视觉大模型API，实现更强大的视觉分析能力- 自动化任务：设置定时任务或条件触发的自动化场景## 状态流转图 +----------------+ | | v |+------+ 唤醒词/按钮 +------------+ | +------------+| IDLE | -----------> | CONNECTING | --+-> | LISTENING |+------+ +------------+ +------------+ ^ | | | 语音识别完成 | +------------+ v +--------- | SPEAKING | <-----------------+ 完成播放 +------------+## 常见问题解决- 找不到音频设备：检查麦克风和扬声器是否正常连接和启用- 唤醒词不响应：确认config.json中USE_WAKE_WORD设置为true，模型路径正确- 网络连接失败：检查网络设置和防火墙配置，确保WebSocket通信未被阻止- 视觉识别失败：确认摄像头权限已授予，智普API密钥正确配置## 贡献与支持- 欢迎提交Issues和Pull Requests- 遵循PEP8代码规范和模块化设计原则- 加入社区讨论群交流使用心得- 支持项目发展，成为项目赞助者## 许可证MIT License