PY-XIAOZHI

Appearance

系统依赖安装 ​

系统依赖安装 ​

Windows ​

  1. 安装 FFmpeg

    bash
    # 方法一：使用 Scoop 安装（推荐）
scoop install ffmpeg

# 方法二：手动安装
# 1. 访问 https://github.com/BtbN/FFmpeg-Builds/releases 下载
# 2. 解压并将 bin 目录添加到系统 PATH

  2. Opus 音频编解码库

    • 项目默认会自动引入 opus.dll，无需手动安装
    • 如遇问题，可将 /libs/windows/opus.dll 复制到以下位置之一：
      • 应用程序目录
      • C:\Windows\System32

Linux (Debian/Ubuntu) ​

bash
# 安装系统依赖
sudo apt-get update
sudo apt-get install python3-pyaudio portaudio19-dev ffmpeg libopus0 libopus-dev

# 安装音量控制依赖（以下三选一）
# 1. PulseAudio 工具（推荐）
sudo apt-get install pulseaudio-utils

# 2. 或者 ALSA 工具
sudo apt-get install alsa-utils

# 3. 如果需要使用 alsamixer 方式，还需要安装 expect
sudo apt-get install alsa-utils expect


sudo apt install build-essential python3-dev

macOS ​

bash
# 使用 Homebrew 安装系统依赖
brew install portaudio opus python-tk ffmpeg gfortran
brew upgrade tcl-tk

Python 依赖安装 ​

方式一：使用 venv（推荐） ​

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

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

# 3. 安装依赖
# Windows/Linux
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
# macOS
pip install -r requirements_mac.txt -i https://mirrors.aliyun.com/pypi/simple

方式二：使用 Conda ​

bash
# 1. 创建 Conda 环境
conda create -n py-xiaozhi python=3.12

# 2. 激活环境
conda activate py-xiaozhi

# 3. 安装 Conda 特定依赖
conda install conda-forge::libopus
conda install conda-forge::ffmpeg

# 4. 安装 Python 依赖
# Windows/Linux
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
# macOS
pip install -r requirements_mac.txt -i https://mirrors.aliyun.com/pypi/simple

注意事项 ​

  1. 建议使用 Python 3.9.13+ 版本，推荐 3.12
  2. Windows 用户无需手动安装 opus.dll，项目会自动处理
  3. 使用 Conda 环境时必须安装 ffmpeg 和 Opus
  4. 使用 Conda 环境时请勿和esp32-server共用同一个Conda环境，因为服务端websocket依赖版本高于本项目
  5. 建议使用国内镜像源安装依赖，可以提高下载速度
  6. macOS 用户需使用专门的 requirements_mac.txt
  7. 确保系统依赖安装完成后再安装 Python 依赖
  8. esp32-server视频部署教程 新版！小智ai服务端本地部署完整教程，支持DeepSeek接入