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 依赖包列表
安装运行
-
克隆项目仓库
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi
-
安装依赖
- 请根据项目根目录的docs下的文档进行安装其他第三方依赖
pip install -r requirements.txt # Windows/Linux
pip install -r requirements_mac.txt # macOS
- 运行程序
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密钥正确配置
贡献与支持
许可证
MIT License
py-xiaozhi 小智语音AI助手
GitHub地址
一个基于xiaozhi-esp32移植到Python实现的小智AI语音助手客户端，支持语音交互、多模态视觉识别、IoT设备控制、联网音乐播放等功能，无需专用硬件即可体验AI语音助手的智能交互。
预览
项目背景
本项目基于开源项目xiaozhi-esp32进行Python生态的移植重构，通过桌面端软件方案复现智能语音交互核心功能。相较于原ESP32硬件方案，本实现采用纯Python开发并整合PyAudio、Vosk等开源库，在保留唤醒词识别、语音对话、指令执行等核心功能的同时，实现了功能扩展，使普通用户无需专用硬件设备即可体验AI语音交互技术。
解决的痛点
解决方案
功能特点
语音交互
视觉多模态
IoT设备控制
音乐播放
系统功能
技术栈
项目结构
安装运行
克隆项目仓库
安装依赖
使用说明
基本操作
语音命令示例
配置说明
高级功能
状态流转图
常见问题解决
贡献与支持
许可证
MIT License