1.4k星！火爆的小智机器人python版来了！没有硬能轻松体验AI强大功能语音助手

项目简介

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

功能特点

• • AI语音交互：支持语音输入与识别，实现智能人机交互，提供自然流畅的对话体验。
• • 视觉多模态：支持图像识别和处理，提供多模态交互能力，理解图像内容。
• • IoT 设备集成：
• • 支持智能家居设备控制，包括灯光、音量、温度传感器等
• • 集成Home Assistant智能家居平台，控制灯具、开关、数值控制器和按钮设备
• • 提供倒计时器功能，支持延时执行命令
• • 内置多种虚拟设备和物理设备驱动，可轻松扩展
• • 联网音乐播放：基于pygame实现的高性能音乐播放器，支持播放／暂停／停止、进度控制、歌词显示和本地缓存，提供更稳定的音乐播放体验。
• • 语音唤醒：支持唤醒词激活交互，免去手动操作的烦恼（默认关闭需要手动开启）。
• • 自动对话模式：实现连续对话体验，提升用户交互流畅度。
• • 图形化界面：提供直观易用的 GUI，支持小智表情与文本显示，增强视觉体验。
• • 命令行模式：支持 CLI 运行，适用于嵌入式设备或无 GUI 环境。
• • 跨平台支持：兼容 Windows 10+、macOS 10.15+ 和 Linux 系统，随时随地使用。
• • 音量控制：支持音量调节，适应不同环境需求，统一声音控制接口。
• • 会话管理：有效管理多轮对话，保持交互的连续性。
• • 加密音频传输：支持 WSS 协议，保障音频数据的安全性，防止信息泄露。
• • 自动验证码处理：首次使用时，程序自动复制验证码并打开浏览器，简化用户操作。
• • 自动获取 MAC 地址：避免 MAC 地址冲突，提高连接稳定性。
• • 代码模块化：拆分代码并封装为类，职责分明，便于二次开发。
• • 稳定性优化：修复多项问题，包括断线重连、跨平台兼容等。

系统要求

• • 3.9 >= Python版本 <= 3.12
• • 支持的操作系统：Windows 10+、macOS 10.15+、Linux
• • 麦克风和扬声器设备

请先看这里！

• • 仔细阅读 项目文档 启动教程和文件说明都在里面了
• • main是最新代码，每次更新都需要手动重新安装一次pip依赖防止我新增依赖后你们本地没有

从零开始使用小智客户端（视频教程）

配置系统

项目使用分层配置系统，主要包括：

1. 1. 基础配置：设置基本运行参数，位于config/config.json
2. 2. 设备激活：设备身份信息，存储在config/efuse.json
3. 3. 唤醒词配置：语音唤醒相关设置
4. 4. 物联网设备：支持各种IoT设备的配置，包括温度传感器和Home Assistant集成

详细配置说明请参考 配置说明文档

IoT功能

py-xiaozhi提供丰富的IoT设备控制功能：

• • 虚拟设备：灯光控制、音量调节、倒计时器等
• • 物理设备集成：温度传感器、摄像头等
• • Home Assistant集成：通过HTTP API接入智能家居系统
• • 自定义设备扩展：提供完整的设备定义和注册框架

支持的设备类型和使用示例请参考 IoT功能说明

状态流转图

                        +----------------+
                        |                |
                        v                |
+------+  唤醒词/按钮  +------------+   |   +------------+
| IDLE | -----------> | CONNECTING | --+-> | LISTENING  |
+------+              +------------+       +------------+
   ^                                            |
   |                                            | 语音识别完成
   |          +------------+                    v
   +--------- |  SPEAKING  | 
     完成播放 +------------+

待实现功能

• • 新 GUI（Electron）：提供更现代、美观的用户界面，优化交互体验。

常见问题

• • 找不到音频设备：请检查麦克风和扬声器是否正常连接和启用。
• • 唤醒词不响应：请检查config.json中的USE_WAKE_WORD设置是否为true，以及模型路径是否正确。
• • 网络连接失败：请检查网络设置和防火墙配置，确保WebSocket或MQTT通信未被阻止。
• • 打包失败：确保已安装PyInstaller (pip install pyinstaller)，并且所有依赖项都已安装。然后重新执行python scripts/build.py
• • IoT设备不响应：检查对应设备的配置信息是否正确，如Home Assistant的URL和Token。

相关第三方开源项目

小智手机端

xiaozhi-esp32-server（开源服务端）

XiaoZhiAI_server32_Unity(Unity开发)

IntelliConnect(Aiot中间件)

open-xiaoai(小爱音响接入小智)

项目结构

├── .github                 # GitHub 相关配置
├── assets                  # 资源文件（表情动画等）
├── cache                   # 缓存目录（音乐等临时文件）
├── config                  # 配置文件目录
├── documents               # 文档目录
├── hooks                   # PyInstaller钩子目录
├── libs                    # 依赖库目录
├── scripts                 # 实用脚本目录
├── src                     # 源代码目录
│   ├── audio_codecs        # 音频编解码模块
│   ├── audio_processing    # 音频处理模块
│   ├── constants           # 常量定义
│   ├── display             # 显示界面模块
│   ├── iot                 # IoT设备相关模块
│   │   └── things          # 具体设备实现目录
│   ├── network             # 网络通信模块
│   ├── protocols           # 通信协议模块
│   └── utils               # 工具类模块