本次测试使用小智通信协议的第三方客户端项目：
本文档提供py-xiaozhi项目的完整依赖安装指南，包括系统级依赖和Python环境配置。请按照文档顺序进行安装。
一、Linux系统基础环境
版本要求
Python: 3.9.13+ (推荐3.10，最高3.11)
PyQt5: 5.15+
SoundDevice: 0.4.4+
FFmpeg: 4.0+
Opus: 1.3+
PortAudio: 19.0+
Linux (Debian/Ubuntu)
1、核心依赖
# 更新包管理器
sudo apt-get update
# 安装核心依赖
sudo apt-get install portaudio19-dev ffmpeg libopus0 libopus-dev \
build-essential python3-venv python3-pip \
libasound2-dev2、音频系统依赖
PulseAudio（推荐）
sudo apt-get install pulseaudio-utils3、GUI支持
# PyQt5 GUI依赖
sudo apt-get install python3-pyqt5 python3-pyqt5.qtmultimedia \
qtbase5-dev qt5-qmake qtmultimedia5-dev4、开发工具（可选）
# 编译依赖
sudo apt-get install gcc g++ make cmake pkg-config二、Python环境配置
使用Miniconda（推荐）
1. 下载Miniconda
| 操作系统 | 架构 | 下载命令 |
|---|---|---|
| Linux | x86_64 | wget -O Miniconda3-latest-Linux-x86_64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh |
| Linux | ARM64 | wget -O Miniconda3-latest-Linux-aarch64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh |
2. 安装Miniconda
Linux/macOS
# 添加执行权限
chmod +x Miniconda3-latest-*.sh
# 运行安装程序
./Miniconda3-latest-*.sh安装过程中的选择：
许可协议：按Enter或q跳过，输入yes接受
安装路径：使用默认路径（推荐）
初始化：输入yes（推荐）3. 配置环境（如需要）
# 如环境变量未自动配置
echo 'export PATH="$HOME/miniconda3/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 初始化conda
conda init4. 验证安装
conda --version5. 优化配置
# 关闭自动激活base环境
conda config --set auto_activate_base false
tony@tony-VirtualBox:~$ conda config --show | grep auto_activate
auto_activate: False
# 添加conda-forge频道
conda config --add channels conda-forge
tony@tony-VirtualBox:~$ conda config --show channels
channels:
- conda-forge
- defaults三、包管理器优化
换源工具（推荐）
# Linux/macOS
wget -O- aslant.top/chsrc.sh | sudo bash
# 配置pip源
chsrc set pip
tony@tony-VirtualBox:~$ chsrc set pip
[chsrc 测速] 测速中
^ 上游默认源 (https://pypi.org/simple) ... 53.81 KByte/s
- 北京外国语大学开源软件镜像站 ... 10.06 MByte/s
- 兰州大学开源社区镜像站 ... 9.32 MByte/s
- 吉林大学开源镜像站 ... 5.59 MByte/s
- 上海交通大学致远镜像站 ... 8.96 MByte/s
- 清华大学开源软件镜像站 ... 4.48 MByte/s
- 阿里巴巴开源镜像站(公网) ... 485.74 KByte/s
- 南京大学开源镜像站 ... 8.93 MByte/s
- 北京大学开源镜像站 ... 9.63 MByte/s
- 腾讯软件源(公网) ... 1023.75 KByte/s
- 华为开源镜像站 ... 8.50 MByte/s
- 华中科技大学开源镜像站 ... 9.02 MByte/s
最快镜像站: 北京外国语大学开源软件镜像站
选中镜像站: BFSU (bfsu)
--------------------------------
[chsrc 检查] ✓ 命令 python3 存在
[chsrc 运行] python3 -m pip config --user set global.index-url https://mirrors.bfsu.edu.cn/pypi/web/simple
Writing to /home/tony/.config/pip/pip.conf
[chsrc 运行] ✓ 命令执行成功
--------------------------------
chsrc: 全自动换源完成, 感谢镜像提供方: 北京外国语大学开源软件镜像站
tony@tony-VirtualBox:~$ conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
accepted Terms of Service for https://repo.anaconda.com/pkgs/main
tony@tony-VirtualBox:~$ conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
accepted Terms of Service for https://repo.anaconda.com/pkgs/r
tony@tony-VirtualBox:~$ conda create -n py-xiaozhi python=3.10 -y
2 channel Terms of Service accepted
Channels:
- conda-forge
- defaults
Platform: linux-64
Collecting package metadata (repodata.json): 四、项目依赖安装（需先下载项目源码）
注意源码目录不能是root用户与组
# 克隆项目
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi1. 创建项目环境
# 使用Conda（推荐）
conda create -n py-xiaozhi python=3.10 -y
conda activate py-xiaozhi2. 安装Python依赖（进入项目源码目录）
# Linux
pip install -r requirements.txt3. 验证安装
# 检查关键依赖
python -c "import sounddevice; print('SoundDevice OK')"
python -c "import opuslib; print('Opus OK')"
python -c "import PyQt5.QtCore; print('PyQt5 OK')"4. 运行程序
# 代码格式化
./format_code/sh
# 运行程序
python main.py5. 激活设备
首次在设备上运行程序，会根据设备信息生成一个6位的注册码，使用注册码登录https://xiaozhi.me/注册添加设备。
硬件后台添加设备： https://xiaozhi.me/
6. 客户端交互
2次运行时，首先进行项目源码目录。
# 切换到运行环境
conda activate py-xiaozhi
# 运行程序
python main.py
