PY-XIAOZHI

简体中文

English

简体中文

English

Appearance

系统依赖安装 ​

概述 ​

本文档提供 py-xiaozhi 项目的完整依赖安装指南。

技术栈：

  • Python >= 3.10
  • GUI：PySide6
  • 包管理：uv (推荐) / pip

系统依赖 ​

Windows ​

bash
# 使用 Scoop 安装 (推荐)
scoop install ffmpeg

# 或使用 winget
winget install FFmpeg

Opus 编解码器：项目已包含 opus.dll，通常无需额外安装。如遇问题，将 /libs/windows/opus.dll 复制到应用程序目录或 C:\Windows\System32。

macOS ​

bash
# Homebrew 安装
brew install portaudio opus ffmpeg

# Xcode 命令行工具
xcode-select --install

Linux (Debian/Ubuntu) ​

兼容 Ubuntu 20.04 / 22.04 / 24.04 / 25.04 及 Raspberry Pi OS

请根据你的系统版本选择对应的安装命令。不同版本的 ALSA 包名和默认音频服务器有差异。

查看系统版本：

bash
lsb_release -d  # 或 cat /etc/os-release

Ubuntu 22.04 (推荐) ​

默认音频服务器：PipeWire（兼容 PulseAudio）

bash
sudo apt-get update
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound2-dev \
    pulseaudio-utils \
    libxcb-xinerama0 libxkbcommon-x11-0 \
    build-essential python3-venv python3-pip

Ubuntu 24.04 / 25.04 ​

默认音频服务器：PipeWire。ALSA 开发包改名为 libasound-dev（旧名 libasound2-dev 仍可用）。

bash
sudo apt-get update
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound-dev \
    pulseaudio-utils \
    libxcb-xinerama0 libxkbcommon-x11-0 \
    build-essential python3-venv python3-pip

Ubuntu 20.04 ​

注意：Ubuntu 20.04 默认 Python 为 3.8，需要先安装 Python 3.10+。

bash
# 1. 安装 Python 3.10+
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install -y python3.10 python3.10-venv python3.10-dev

# 2. 安装音频依赖（默认音频服务器：PulseAudio）
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound2-dev \
    pulseaudio-utils \
    build-essential

Raspberry Pi OS (Bookworm / Debian 12) ​

桌面版默认已安装 PipeWire，Lite 版需要手动安装音频服务器。

bash
sudo apt-get update

# 桌面版：PipeWire 已预装，只需安装开发依赖
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound-dev \
    pulseaudio-utils \
    build-essential python3-venv python3-pip

# Lite 版 (无桌面) 额外安装音频服务器：
# sudo apt-get install -y pipewire pipewire-pulse wireplumber

树莓派建议使用 USB 声卡，内置 3.5mm 音频口质量较差且延迟高。

音频权限 ​

bash
sudo usermod -a -G audio $USER
# 重新登录后生效

音频验证 ​

bash
# 检查音频服务器
pactl info | grep "Server Name"
# 预期输出：
#   PulseAudio → "Server Name: pulseaudio"
#   PipeWire   → "Server Name: PulseAudio (on PipeWire x.x.x)"

# 检查声卡设备
aplay -l           # 列出输出设备
arecord -l         # 列出输入设备

# 检查 PortAudio
python3 -c "import sounddevice; print(sounddevice.query_devices())"

重要：不要在 PipeWire 系统（Ubuntu 22.04+）上安装 pulseaudio 守护进程包，这会与 PipeWire 冲突。只需安装 pulseaudio-utils（提供 pactl 命令）。

Python 环境配置 ​

方式一：uv (推荐) ​

uv 是现代化的 Python 包管理器，速度快、自动管理虚拟环境。

安装 uv：

bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装项目依赖：

bash
uv sync

运行项目：

bash
uv run python main.py

方式二：pip + venv ​

bash
# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate      # Linux/macOS
# .venv\Scripts\activate       # Windows

# 安装依赖
pip install -r requirements.txt

方式三：Conda (可选) ​

仅在需要特殊 C++ 依赖 (如 CUDA/MKL) 时使用

bash
# 创建环境
conda create -n py-xiaozhi python=3.10 -y
conda activate py-xiaozhi

# 安装依赖
pip install -r requirements.txt

验证安装 ​

bash
# 使用 uv
uv run python -c "from PySide6.QtCore import qVersion; print('PySide6:', qVersion())"
uv run python -c "import sounddevice; print('SoundDevice OK')"
uv run python -c "import opuslib; print('Opus OK')"
uv run python -c "import sherpa_onnx; print('sherpa-onnx OK')"

# 使用 pip/venv
python -c "from PySide6.QtCore import qVersion; print('PySide6:', qVersion())"
python -c "import sounddevice; print('SoundDevice OK')"

故障排除 ​

SoundDevice 安装失败 ​

bash
# Ubuntu 20.04 / 22.04
sudo apt-get install -y portaudio19-dev libasound2-dev libportaudio2

# Ubuntu 24.04+
sudo apt-get install -y portaudio19-dev libasound-dev libportaudio2

# macOS
brew install portaudio

音频设备找不到 (Linux) ​

常见于树莓派或服务自启动场景，PortAudio 在音频服务就绪前初始化导致设备列表为空。

bash
# 1. 确认音频服务正在运行
pactl info

# 2. 如果 pactl 报错，检查音频服务
systemctl --user status pipewire pipewire-pulse  # PipeWire 系统
systemctl --user status pulseaudio               # PulseAudio 系统

# 3. 如果 aplay -l 有设备但 Python 看不到，重启音频服务
systemctl --user restart pipewire pipewire-pulse wireplumber

# 4. 树莓派 Lite 版：可能需要手动安装音频服务器
sudo apt-get install -y pipewire pipewire-pulse wireplumber
systemctl --user enable pipewire pipewire-pulse wireplumber
systemctl --user start pipewire pipewire-pulse wireplumber

PulseAudio 与 PipeWire 冲突 ​

如果误装了 pulseaudio 守护进程导致音频异常：

bash
# 移除 PulseAudio 守护进程（保留 pactl 工具）
sudo apt-get remove -y pulseaudio
sudo apt-get install -y pulseaudio-utils  # 只装命令行工具

# 重启 PipeWire
systemctl --user restart pipewire pipewire-pulse wireplumber

sherpa-onnx 导入失败 (macOS) ​

sherpa-onnx 需要 onnxruntime 动态库，macOS 上可能缺失：

bash
# 下载 onnxruntime
cd /tmp
curl -sL "https://github.com/microsoft/onnxruntime/releases/download/v1.17.1/onnxruntime-osx-arm64-1.17.1.tgz" -o onnxruntime.tgz
tar -xzf onnxruntime.tgz

# 复制动态库到 sherpa_onnx
cp onnxruntime-osx-arm64-1.17.1/lib/libonnxruntime.1.17.1.dylib \
   .venv/lib/python3.10/site-packages/sherpa_onnx/lib/

Opus 库缺失 ​

bash
# macOS
brew install opus

# Linux
sudo apt-get install -y libopus0 libopus-dev

PySide6 显示问题 (Linux) ​

bash
# 安装 Qt 运行库
sudo apt-get install -y libxcb-xinerama0 libxkbcommon-x11-0 libegl1

包管理器换源 (国内用户) ​

pip 换源 ​

bash
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

uv 换源 ​

bash
# 设置环境变量
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# 或在 pyproject.toml 中配置
# [tool.uv]
# index-url = "https://mirrors.aliyun.com/pypi/simple/"

版本要求 ​

依赖版本
Python>= 3.10
PySide6>= 6.6.0
SoundDevice>= 0.4.4
FFmpeg>= 4.0
Opus>= 1.3
PortAudio>= 19.0

注意事项 ​

  1. 推荐使用 uv 管理依赖，速度快且自动处理虚拟环境
  2. Python 版本：必须 >= 3.10，不支持 3.9 及以下
  3. 系统依赖优先：先安装系统依赖 (ffmpeg, opus, portaudio)，再安装 Python 依赖
  4. 不要混用包管理器：选择 uv 或 pip 其一，不要混用
  5. macOS sherpa-onnx：首次运行可能需要手动复制 onnxruntime 动态库