【开源自荐】py-xiaozhi：轻量级Python版小智AI语音助手（支持多模态交互、IoT控制与音乐播放，纯代码实现，无需硬件即可体验）

[huangjunsen0406]

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