py-xiaozhi 完全入门指南 - 无需硬件体验 AI 小智语音功能的 Python 开源客户端

py-xiaozhi 是一个基于 Python 的开源语音客户端，旨在帮助用户在没有专用硬件的情况下体验 Xiaozhi AI 的功能。它支持语音交互、图像识别、IoT 设备集成和在线音乐播放等功能，适用于 Windows、macOS 和 Linux 系统。本指南将详细介绍 py-xiaozhi 的安装、配置、运行及功能使用，适合初学者和高级用户。

1. 项目概述

py-xiaozhi 是从 xiaozhi-esp32 移植而来的开源项目，提供以下核心功能：

• AI 语音交互：通过麦克风实现自然语言对话
• 视觉多模态：支持图像识别和处理，提供多模态交互体验
• IoT 设备集成：支持智能家居设备控制，构建智能生态
• 联网音乐播放：基于 Pygame 的高性能音乐播放器，支持播放控制、歌词显示和本地缓存
• 图形化界面：提供直观的 GUI，支持小智表情和文本显示
• 语音唤醒：支持唤醒词激活（默认关闭）
• 自动对话模式：实现连续对话，提升交互流畅度
• 跨平台音量控制：适配不同操作系统

项目托管在 GitHub，文档和教程可在 项目文档 查看。

2. 系统要求

在开始使用 py-xiaozhi 之前，请确保你的设备满足以下要求：

Python 版本

• Python 版本：3.9 到 3.12（建议使用最新稳定版本）

操作系统

• Windows 10 或更高版本
• macOS 10.15（Catalina）或更高版本
• Linux（常见发行版如 Ubuntu、Debian 等）

硬件要求

• 麦克风：用于语音输入
• 扬声器：用于语音输出
• 稳定的网络连接：支持在线功能如音乐播放和 AI 交互
• 磁盘空间：至少 500MB 可用空间（用于项目文件和依赖）

3. 下载与安装

3.1 下载项目

1. 访问 GitHub 仓库
2. 选择以下任一方式获取项目：
   • 克隆仓库（推荐，方便后续更新）：

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

   • 下载 ZIP 文件：点击 GitHub 页面上的”Code”按钮，选择”Download ZIP”，然后解压到本地
3. 确保已安装 Git（用于克隆和更新）或解压工具

3.2 安装 Python

1. 确认 Python 版本为 3.9-3.12：
   • 运行 python --version 或 python3 --version 检查版本
   • 如果未安装或版本不符，前往 Python 官网 下载并安装
2. 确保 pip（Python 包管理器）可用：
   • 运行 pip --version 或 pip3 --version 检查
   • 如果不可用，参考 Python 官方文档安装

3.3 安装依赖

1. 进入项目目录：

   cd py-xiaozhi

2. 安装依赖：
   • 如果项目提供 requirements.txt，运行：

     pip install -r requirements.txt

   • 如果没有明确列表，参考 项目文档 或 GitHub 的 README 获取依赖列表

注意：主分支更新后可能引入新依赖，需重新运行 pip install 确保环境一致。

4. 配置

py-xiaozhi 的配置文件位于 config/ 目录，主要包括：

• config.json：存储通用设置，如语音唤醒词、通信协议、API 密钥等
• efuse.json：涉及硬件或特定功能配置（视项目需求而定）

4.1 配置步骤

1. 打开 config/ 目录，找到 config.json
2. 根据需求修改以下关键字段（具体字段参考 配置说明文档）：
   • 唤醒词：设置触发语音交互的关键词（默认关闭）
   • 协议：选择 mqtt 或 websocket 作为通信协议
   • API 密钥：若需使用在线 AI 服务，输入相关密钥
   • 设备设置：配置麦克风和扬声器设备 ID（可通过运行脚本来检测）
3. 保存文件，确保格式为有效 JSON

4.2 IoT 功能配置

若需使用 IoT 功能（如控制智能家居设备），参考 IoT 功能文档：

1. 配置 IoT 设备连接参数（如 IP 地址、端口）
2. 确保设备与 py-xiaozhi 在同一网络
3. 测试连接是否正常

5. 运行 py-xiaozhi

5.1 启动命令

py-xiaozhi 通过 main.py 启动，支持以下参数：

参数	描述	可选值
--mode	运行模式	gui（图形界面）或 cli（命令行）
--protocol	通信协议	mqtt 或 websocket

示例命令：

python main.py --mode gui --protocol websocket

• GUI 模式：提供图形界面，显示小智表情和交互文本，适合初学者
• CLI 模式：适合嵌入式设备或无图形界面的环境，适合高级用户

5.2 首次运行

1. 确保麦克风和扬声器正常工作
2. 运行上述命令，程序会初始化并等待语音输入
3. 如果启用唤醒词，需说出唤醒词（如”小智”）激活交互
4. 测试语音交互，例如说”今天天气如何”或”播放一首歌”

6. 功能使用

6.1 AI 语音交互

功能：通过麦克风输入语音，与 Xiaozhi AI 进行自然对话。

使用方法：

1. 启动程序后，等待提示音或界面指示
2. 说出指令，如”讲个笑话”或”查询新闻”
3. 程序会通过扬声器或界面返回响应

提示：启用连续对话模式可实现无需重复唤醒的流畅交互。

6.2 视觉多模态

功能：支持图像上传和识别，结合语音进行多模态交互。

使用方法：

1. 在 GUI 模式下，上传图片（支持 JPG、PNG 等格式）
2. 说出相关指令，如”描述这张图片”
3. Xiaozhi 会分析图像并返回描述

注意：确保网络连接稳定，需要额外的 API 配置（智谱多模态大模型）。

6.3 IoT 设备集成

功能：控制智能家居设备，如灯、空调等。

使用方法：

1. 参考 IoT 功能文档 配置设备
2. 使用语音指令，如”打开客厅灯”
3. 验证设备状态是否变化

提示：确保设备支持 MQTT 或 WebSocket 协议。

6.4 联网音乐播放

功能：通过 Pygame 播放在线音乐，支持播放、暂停、停止和歌词显示。

使用方法：

1. 说出指令，如”播放周杰伦的歌”
2. 程序会从在线源获取音乐并播放
3. 支持控制指令，如”暂停”或”下一首”

注意：本地缓存功能需足够磁盘空间。

6.5 语音唤醒与连续对话

• 语音唤醒：说出配置的唤醒词激活交互（默认关闭）
• 连续对话：启用后无需重复唤醒，适合长时间交互
• 设置方法：在 config.json 中启用相关选项

6.6 音量控制

功能：跨平台音量调整，适应不同场景。

使用方法：通过语音指令（如”调高音量”）或 GUI 界面调整。

7. 学习与支持资源

7.1 官方文档

• 项目官网：huangjunsen0406.github.io/py-xiaozhi
• 包含快速入门、配置指南和功能说明
• GitHub 文档：
  • 配置说明
  • IoT 功能说明

7.2 视频教程

• Bilibili 视频
• 提供视觉化的安装和使用指导，适合初学者

7.3 社区支持

• GitHub Issues：访问 Issues 页面 提交问题或查看常见问题解答
• 社区讨论：参与 GitHub Discussions 或相关论坛，获取其他用户的经验分享

8. 注意事项

• 定期更新：py-xiaozhi 是开源项目，主分支可能频繁更新。运行 git pull 获取最新代码，并重新安装依赖
• 网络依赖：在线功能（如音乐播放、AI 交互）需要稳定网络
• 调试：
  • 如果语音识别失败，检查麦克风设置和网络连接
  • 如果 GUI 不显示，确保已安装必要的图形库（如 PyQt 或 Tkinter）
• 兼容性：某些功能（如 IoT）可能需要特定硬件或协议支持，提前确认设备兼容性
• 当前时间：本指南基于 2025 年 5 月 20 日的信息，建议查阅最新文档以获取更新

9. 故障排除

问题	可能原因	解决方法
程序无法启动	依赖缺失或版本不兼容	运行 pip install -r requirements.txt，检查 Python 版本
语音识别失败	麦克风未正确配置	检查系统音频设置，确认麦克风可用
IoT 设备无法连接	网络或协议配置错误	参考 IoT 文档，检查设备 IP 和协议
GUI 界面不显示	缺少图形库或环境问题	安装 PyQt/Tkinter，检查显示器设置
音乐播放失败	网络不稳定或 API 配置错误	检查网络，确认 API 密钥有效

如遇其他问题，查看 GitHub Issues 或提交新问题。

关键资源

• GitHub 仓库
• 项目文档
• Bilibili视频教程