py-xiaozhi

环境要求

• Python 环境（项目 CI 在 Python 3.10 / 3.12 上验证）
• 内存至少 4GB，建议 8GB 以上
• CPU 支持 AVX 指令集
• 至少 2GB 可用磁盘空间（模型文件与缓存）
• 音频设备支持 16kHz 采样率；FFmpeg 需可从系统 PATH 找到

安装与启动步骤

1. 1获取源码

   把仓库克隆到本地并进入项目目录，后续所有命令都在该目录执行。

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

   复制

2. 2安装依赖（uv）

   使用 uv 同步依赖，适合只跑 CLI / GPIO 模式的基础安装。

   uv sync

   复制

3. 3pip 安装方式

   不使用 uv 时用 pip 可编辑安装；需要图形界面则安装 gui 额外依赖。

   pip install -e '.[gui]'

   复制

4. 4启动 GUI 模式

   默认启动图形界面，需已安装 gui 额外依赖；基础安装只跑 CLI。

   python main.py

   复制

5. 5启动 CLI 模式

   基础安装即可运行命令行模式，适合无图形环境或开发板场景。

   python main.py --mode cli

   复制

6. 6使用安装后的命令

   安装完成后可直接调用 xiaozhi 入口命令，GUI 仍需 gui 额外依赖。

   xiaozhi --mode cli

   复制

7. 7校验 wheel 包

   可选：在项目外的临时虚拟环境中安装 wheel，验证入口点和资源是否正常。

   python scripts/check_wheel.py dist/*.whl

   复制

关键配置

如何确认成功

执行 python main.py 后无报错并出现图形界面或命令行交互提示，即表示启动成功。

常见问题

注意事项

• 基础安装（uv sync 或 pip install -e .）只能跑 CLI / GPIO 模式，GUI 必须额外安装 gui 依赖。
• CPU 需支持 AVX 指令集，否则可能出现运行异常。
• wheel 包内含资源、唤醒词模型和原生库，路径位于 src/_resources，源码与 PyInstaller 布局沿用原有资源路径。