# xiaozhi-pi

**Repository Path**: genvex/xiaozhi-pi

## Basic Information

- **Project Name**: xiaozhi-pi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小智 Linux 融合版 (Python)

> 基于 CyberCAM-Apps 的 Python 版小智助手，移植到 Radxa Rock 5T / ARM64 Linux  
> SDL2 图形界面 + sherpa-onnx 离线唤醒词 + WebSocket 云端对话

---

## 📋 目录

- [项目概述](#项目概述)
- [技术架构](#技术架构)
- [硬件需求](#硬件需求)
- [快速开始](#快速开始)
- [详细构建指南](#详细构建指南)
- [配置说明](#配置说明)
- [唤醒词工作原理](#唤醒词工作原理)
- [常见问题](#常见问题)
- [许可证](#许可证)

---

## 项目概述

本项目是 [小智 AI 语音助手](https://xiaozhi.me) 的 Linux 移植版，基于 [CyberCAM-Apps](https://github.com/netseye/CyberCAM-Apps) 的 Python 实现，针对 ARM64 Linux 平台（如 Radxa Rock 5T）进行适配。

### 核心特性

- **离线唤醒词**：基于 sherpa-onnx + Zipformer 模型，无需联网即可唤醒
- **云端对话**：WebSocket 连接小智服务端，支持实时语音交互
- **图形界面**：SDL2/pygame 渲染，状态/表情/字幕完整 UI
- **跨平台**：ARM64/x86_64 Linux 均可运行

### 与原版差异

| 项目 | 原版 (K230) | 本版 (Rock 5T) |
|------|-------------|----------------|
| 硬件平台 | 嘉楠 K230 (RISC-V) | Radxa Rock 5T (ARM64) |
| 唤醒引擎 | sherpa-onnx C++ + SpaceMi RVV | sherpa-onnx Python (CPU) |
| 图形渲染 | OpenCV + walnutpi.Display | SDL2 / pygame |
| 音频采集 | K230 板载 I2S | USB 麦克风 (sounddevice) |
| 输入设备 | GPIO + 触摸屏 | 键盘 (pygame events) |

---

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                    main_sdl2.py                          │
│                   (主程序入口)                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ display_sdl2 │  │  assistant   │  │  wakeword    │  │
│  │  (pygame UI) │  │  (状态机)    │  │ (sherpa-onnx)│  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                 │                  │          │
│         │            ┌────┴────┐             │          │
│         │            │         │             │          │
│         │       ┌────┴──┐ ┌───┴───┐         │          │
│         │       │ audio │ │protocol│         │          │
│         │       │(Opus) │ │  (WS)  │         │          │
│         │       └───────┘ └───┬───┘         │          │
│         │                     │             │          │
│  ┌──────┴───────┐  ┌─────────┴──────┐  ┌───┴───────┐  │
│  │ USB Mic/Spk  │  │  wss://api     │  │ USB Mic   │  │
│  │  (ALSA)      │  │ .tenclass.net  │  │ 16kHz PCM │  │
│  └──────────────┘  └────────────────┘  └───────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## 硬件需求

### 最低配置

| 组件 | 要求 |
|------|------|
| CPU | ARM64 (Cortex-A76+) 或 x86_64 |
| 内存 | 2GB+ |
| 系统 | Debian 12 / Ubuntu 22.04+ |
| 音频 | USB 麦克风 + 喇叭 (或 USB 音频卡) |
| 显示 | HDMI (可选，X11/Xvfb 均可) |

### 推荐配置 (已验证)

- **主板**: Radxa Rock 5T (RK3588, 8GB RAM, NVMe)
- **音频**: USB 音频卡 (Y11 或类似)
- **显示**: HDMI 1280x400 或 Xvfb 虚拟显示
- **系统**: Debian 12 (6.1.84-8-rk2410)

---

## 快速开始

### 一键安装

```bash
# 1. 克隆项目
git clone https://gitee.com/genvex/xiaozhi-pi.git
cd xiaozhi-pi

# 2. 运行构建脚本
chmod +x setup.sh
./setup.sh

# 3. 启动
./run.sh
```

### 手动安装

```bash
# 系统依赖
sudo apt install python3 python3-venv libopus0 libopus-dev \
    libasound2-dev libsdl2-dev fonts-wqy-zenhei

# Python 环境 (需要 Python 3.9 - 3.13; pygame/sherpa-onnx 无 cp314 wheel)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 下载唤醒词模型
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models-v1/\
sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
tar -xjf sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
cp sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/*.onnx wake/model/
cp sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/tokens.txt wake/model/

# 配置
cp config.example.json config.json
# 编辑 config.json 设置音频设备号

# 启动
python3 main_sdl2.py
```

---

## 详细构建指南

### Step 1: 系统环境准备

```bash
# Debian 12 / Ubuntu 22.04
sudo apt update
sudo apt install -y \
    python3 python3-venv python3-pip \
    libopus0 libopus-dev \
    libasound2-dev \
    libsdl2-dev libsdl2-image-dev \
    fonts-wqy-zenhei \
    git curl wget

# 禁用 PipeWire (如果与 ALSA 冲突)
systemctl --user stop pipewire pipewire-pulse wireplumber 2>/dev/null || true
systemctl --user disable pipewire pipewire-pulse wireplumber 2>/dev/null || true
```

### Step 2: 拉取源码

```bash
# 方式 A: 直接克隆本仓库
git clone https://gitee.com/genvex/xiaozhi-pi.git
cd xiaozhi-pi

# 方式 B: 从上游 sparse checkout
git clone --depth 1 -b codex/xiaozhi-app \
    --filter=blob:none --sparse \
    https://github.com/netseye/CyberCAM-Apps.git /tmp/CyberCAM-Apps
cd /tmp/CyberCAM-Apps && git sparse-checkout set app/xiaozhi
cp -r app/xiaozhi/* ~/xiaozhi-linux-py/
```

### Step 3: Python 环境

> Python 版本要求 3.9 - 3.13 (pygame 与 sherpa-onnx 均未发布 cp314 wheel,
> Python 3.14 无法安装依赖)。

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Step 4: 唤醒词模型

```bash
# 下载 sherpa-onnx KWS 模型 (4.9MB)
cd wake/model
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models-v1/\
sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
tar -xjf sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2 \
    --strip-components=1
rm sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
cd ../..
```

### Step 5: 音频设备配置

```bash
# 查看可用音频设备
source .venv/bin/activate
python3 -c "import sounddevice as sd; print(sd.query_devices())"

# 记录你的 USB 麦克风/喇叭设备号
# 编辑 config.json 填入 input_device 和 output_device
```

### Step 6: 显示环境

```bash
# 方式 A: 物理显示器 (HDMI)
export DISPLAY=:0

# 方式 B: 虚拟显示 (无头服务器)
Xvfb :99 -screen 0 1280x800x24 &
export DISPLAY=:99
```

### Step 7: 启动

```bash
source .venv/bin/activate
python3 main_sdl2.py
```

首次运行会生成 `device.json` 并提示激活码，访问 https://xiaozhi.me 完成绑定。

### 无头 / 离线调试

```bash
# 无显示环境: 使用虚拟 SDL 后端, 无需 Xvfb
SDL_VIDEODRIVER=dummy ./run_headless.sh
```

设备身份存于 `device.json` (首次运行自动生成并打印激活码);
把已绑定设备的 `device.json` 拷到新机器即可跳过激活。
`config.json` 中 `websocket_url` / `access_token` 非空时直接使用, 跳过 OTA 请求。

---

## 配置说明

### config.json

```json
{
  "ota_url": "https://api.tenclass.net/xiaozhi/ota/",
  "input_device": 5,
  "output_device": 5,
  "max_listen_seconds": 30,
  "no_speech_timeout_seconds": 6,
  "speech_level_threshold": 0.08,
  "wake_word_enabled": true,
  "wake_word": "你好小智",
  "wake_word_device": "plughw:5,0",
  "wake_word_score": 3.5,
  "wake_word_threshold": 0.1
}
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `input_device` | ALSA 输入设备号 | 自动检测 |
| `output_device` | ALSA 输出设备号 | 自动检测 |
| `wake_word_enabled` | 是否启用唤醒词 | true |
| `wake_word` | 唤醒词文本 | 你好小智 |
| `wake_word_score` | 检测增益 (越高越灵敏) | 3.5 |
| `wake_word_threshold` | 触发阈值 | 0.1 |

### device.json (自动生成)

```json
{
  "device_id": "XX:XX:XX:XX:XX:XX",
  "client_id": "uuid-xxxx-xxxx"
}
```

设备身份信息，首次运行自动生成，绑定后不可更改。

---

## 唤醒词工作原理

### 模型信息

- **名称**: sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01
- **来源**: [k2-fsa/sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)
- **架构**: Zipformer (流式 ASR)
- **训练数据**: WenetSpeech (1万小时中文)
- **参数量**: 3.3M (int8 量化后 4.9MB)
- **许可**: Apache 2.0

### 工作流程

```
麦克风 16kHz PCM
    ↓ (每 100ms 一帧)
sherpa-onnx OnlineRecognizer
    ↓ (流式推理)
拼音 token 匹配
    ↓ (score > 0.1)
触发回调 → 开始对话
```

### 关键词定义 (keywords.txt)

```
x iǎo zh ì x iǎo zh ì :3.5 #0.10 @小智小智
n ǐ h ǎo x iǎo zh ì :3.5 #0.10 @你好小智
```

支持自定义唤醒词，修改拼音 token 和阈值即可。

---

## 常见问题

### Q: 音频设备找不到

```bash
# 查看所有设备
python3 -c "import sounddevice as sd; print(sd.query_devices())"

# 如果 USB 设备不显示，检查:
aplay -l          # ALSA 播放设备
arecord -l        # ALSA 录音设备
cat /proc/asound/cards
```

### Q: SDL2 窗口打不开

```bash
# 检查 DISPLAY 环境变量
echo $DISPLAY

# 如果没有物理显示器，用 Xvfb:
sudo apt install xvfb
Xvfb :99 -screen 0 1280x800x24 &
export DISPLAY=:99
```

### Q: 唤醒词不响应

- 检查 `wake/model/` 下 4 个文件是否完整
- 调整 `wake_word_score` (增大到 5.0 更灵敏)
- 检查麦克风是否正常工作: `arecord -d 3 test.wav && aplay test.wav`

### Q: WebSocket 连接失败

- 检查网络: `ping api.tenclass.net`
- 确认设备已绑定: 删除 `device.json` 重新激活
- 检查 OTA 返回的 WebSocket URL

---

## 许可证

- 本项目代码: Apache License 2.0
- 唤醒词模型: Apache License 2.0 (sherpa-onnx)
- 原始项目: [CyberCAM-Apps](https://github.com/netseye/CyberCAM-Apps)

---

## 相关链接

- 小智官网: https://xiaozhi.me
- sherpa-onnx: https://github.com/k2-fsa/sherpa-onnx
- CyberCAM-Apps: https://github.com/netseye/CyberCAM-Apps
- Radxa Rock 5T: https://radxa.com/products/rock5/5t