简体中文 | English

项目简介

py-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。 本仓库是基于xiaozhi-esp32移植

演示

• Bilibili 演示视频

功能特点

🎯 核心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/                  # 工具函数
│   └oy views/                  # UI视图组件
├── libs/                       # 第三方原生库
│   ├── libopus/               # Opus音频编解码库
│   ├── webrtc_apm/            # WebRTC音频处理模块
│   └ой SystemAudioRecorder/   # 系统音频录制工具
├── config/                     # 配置文件目录
├── models/                     # 语音模型文件
├── assets/                     # 静态资源文件
├── scripts/                    # 辅助脚本
├── requirements.txt            # Python依赖包列表
└oy 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  | <-----------------+
     完成播放 +------------+

贡献指南

欢迎提交问题报告和代码贡献。请确保遵循以下规范：

1. 代码风格符合PEP8规范
2. 提交的PR包含适当的测试
3. 更新相关文档

社区与支持

感谢以下开源人员

排名不分前后

Xiaoxia zhh827 四博智联-李洪刚 HonestQiao vonweller 孙卫公 isamu2025 Rain120 kejily 电波bilibili君 赛搏智能

赞助支持

项目统计

许可证

MIT License

py-xiaozhi 快速上手指南

py-xiaozhi 是一个基于 Python 实现的小智语音客户端，旨在让开发者在无硬件条件下体验 AI 语音交互、多模态视觉及智能家居控制功能。本项目移植自 xiaozhi-esp32。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

系统要求

• 操作系统：Windows 10+、macOS 10.15+ 或 Linux
• Python 版本：3.9 - 3.12
• 硬件配置：
  • 内存：至少 4GB RAM（推荐 8GB+）
  • 存储：至少 2GB 可用空间（用于模型和缓存）
  • 音频：具备麦克风和扬声器设备
  • 网络：稳定的互联网连接

前置依赖

• 音频驱动：确保系统音频输入输出正常。
• 可选组件：
  • 若需使用语音唤醒功能，需下载 Sherpa-ONNX 模型（首次运行会自动提示或下载）。
  • 若需使用摄像头功能，需安装摄像头并支持 OpenCV。

提示：国内用户如遇网络问题，可考虑配置 pip 国内镜像源加速依赖安装。

2. 安装步骤

克隆项目

使用 git 克隆代码仓库：

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

国内加速：也可通过 Gitee 镜像克隆：

git clone https://gitee.com/huang-jun-sen/py-xiaozhi.git
cd py-xiaozhi

安装依赖

安装项目所需的 Python 库：

pip install -r requirements.txt

建议：每次拉取最新代码后，建议重新执行此命令以确保新增依赖已安装。

获取模型（可选）

首次运行时，若未检测到语音唤醒模型，程序通常会引导下载。如需手动准备，请参考项目文档中的模型存放路径（通常在 models/ 目录）。

3. 基本使用

安装完成后，您可以通过以下命令启动小智客户端。

启动图形界面模式（默认）

适用于桌面环境，提供完整的可视化交互界面：

python main.py

启动命令行模式

适用于无图形界面环境或嵌入式调试：

python main.py --mode cli

指定通信协议

默认使用 WebSocket，也可切换为 MQTT 协议：

# 使用 WebSocket (默认)
python main.py --protocol websocket

# 使用 MQTT
python main.py --protocol mqtt

基础操作流程

1. 启动程序：运行上述命令打开界面。
2. 激活交互：
   • 语音唤醒：说出配置的唤醒词（需提前开启该功能）。
   • 手动触发：点击界面上的按钮或使用全局快捷键。
3. 对话体验：对着麦克风说话，系统将进行语音识别、AI 处理并语音回复。
4. 功能扩展：尝试使用内置的 MCP 工具（如查询天气、播放音乐、控制智能家居等）。

---

更多详细配置、API 开发指南及故障排查，请参阅 官方项目文档。