# xiaomi

**Repository Path**: null_500_7265/xiaomi

## Basic Information

- **Project Name**: xiaomi
- **Description**: 智能语音助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小米智能语音助手

这是一个面向中文场景的智能语音助手项目。系统架构、模块职责和重构路线统一维护在 [系统架构设计](docs/系统架构设计.md)。

## 快速开始

新电脑 clone 仓库后，Ubuntu 下先安装系统依赖：

```bash
sudo apt-get install -y python3.12-venv git-lfs portaudio19-dev libportaudio2
```

创建基础开发环境：

```bash
scripts/setup_dev.sh
source .venv/bin/activate
```

默认只安装轻量基础依赖，并使用清华 PyPI 镜像。需要完整语音助手能力时，再按需安装重依赖和模型：

```bash
scripts/setup_dev.sh --qwen
scripts/setup_dev.sh --funasr --torch-cpu
scripts/init/init_sherpa_onnx_kws_model.sh
scripts/init/init_sherpa_onnx_asr_model.sh
scripts/init/init_moss_tts_nano_model.sh
```

检查本机环境：

```bash
python scripts/check_env.py
```

验证主应用入口的轻量 dry-run 闭环：

```bash
python -m xiaomi_assistant.app --prompt "测试一下"
```

默认 `dry-run` 不访问麦克风、模型或千问 API。需要本地录音、唤醒词、FunASR 或 MOSS-TTS-Nano 时，再显式切换模式和后端，例如 `--mode local --wakeword-backend sherpa --asr-backend funasr --tts-backend moss`。

使用实时 ASR 的 `local` 和 `online` 模式会持续进入下一轮对话，直到识别文本包含“退出”或“关闭”；需要只运行一轮时传 `--once`。固定 `--prompt` 和 fake ASR 调试默认仍只跑一轮，需要循环调试时传 `--loop`。

识别文本命中系统音量指令时，应用会先执行本地音量动作，不再把该轮文本交给 LLM。支持“音量调到 50%”“声音大一点”“声音小一点”“静音”“取消静音”等常见说法；`dry-run` 只模拟动作，`local`/`online` 默认通过 `pactl` 调节 PipeWire 默认输出。可用 `--disable-volume-control` 关闭，或用 `--volume-step-percent` 调整“大一点/小一点”的步进。

唤醒后的录音会先等待首个有效语音，超过 `--first-speech-timeout-seconds` 还没说话就直接回到等待，不会调用 ASR/LLM/TTS。检测到说话后，系统会把 `--pre-roll-seconds` 的开口前音频一起送给 ASR，减少漏掉第一个字；`--record-seconds` 是最长录音上限而不是固定录音窗口。长句被截断时可适当增大 `--record-seconds`，或用 `--end-silence-seconds` 和 `--silence-rms-threshold` 调整静音结束灵敏度；说话太轻被当作无语音时，可降低 `--silence-rms-threshold` 或 `--min-speech-seconds`。

sherpa-onnx 唤醒词监听默认使用单线程以降低常驻 CPU 占用。需要调参时可用 `--wakeword-num-threads` 和 `--wakeword-max-active-paths`；降低 `--wakeword-max-active-paths` 可能进一步降低占用，但也可能降低召回率。

## 千问配置

千问 API Key 不提交到 Git。需要使用大模型对话时，先复制模板：

```bash
cp config/.qianwen-apikey.example config/.qianwen-apikey
```

然后编辑 `config/.qianwen-apikey`：

```text
DASHSCOPE_API_KEY=你的 API Key
DEFAULT_MODEL=qwen3.7-plus
```

也可以通过环境变量覆盖：

```bash
export DASHSCOPE_API_KEY=你的 API Key
```

没有明确需要时，不要发起真实千问 API 调用。

## 模型初始化

初始化 sherpa-onnx 唤醒词模型：

```bash
scripts/init/init_sherpa_onnx_kws_model.sh
```

初始化 MOSS-TTS-Nano 语音合成模型：

```bash
scripts/init/init_moss_tts_nano_model.sh
```

初始化 sherpa-onnx 中文 ASR 模型：

```bash
scripts/init/init_sherpa_onnx_asr_model.sh
```

下载 GitHub/ModelScope 模型较慢时，可以走本地代理：

```bash
scripts/init/init_sherpa_onnx_asr_model.sh --proxy socks5h://192.168.1.168:7897
scripts/init/init_moss_tts_nano_model.sh --proxy socks5h://192.168.1.168:7897
HTTPS_PROXY=socks5h://192.168.1.168:7897 HTTP_PROXY=socks5h://192.168.1.168:7897 python scripts/init/init_funasr_model.py
```

初始化 FunASR ASR/VAD/PUNC 模型：

```bash
python scripts/init/init_funasr_model.py
```

也可以用脚本一次性初始化 sherpa-onnx KWS/ASR 和 FunASR 模型：

```bash
scripts/setup_dev.sh --all-models --torch-cpu
```

注意：`scripts/setup_dev.sh --models` / `--all-models` 当前仍会初始化历史 sherpa-onnx TTS 模型；项目选定的 TTS 方案是 MOSS-TTS-Nano，请单独执行 `scripts/init/init_moss_tts_nano_model.sh`。

模型会保存到 `models/`，该目录已被 `.gitignore` 忽略。

备注：已评估 `whisper.cpp`，由于资源占用较高，且滑动窗口式流式识别体验不适合当前语音助手场景，暂不作为项目测试入口。

## 现有测试入口

这些脚本用于验证各个底层能力。

| 脚本 | 作用 |
| --- | --- |
| `scripts/probes/test_sherpa_onnx_kws.py` | 唤醒词检测，支持麦克风和 wav 文件 |
| `scripts/probes/test_funasr_asr.py` | FunASR 流式中文语音识别 |
| `scripts/probes/test_sherpa_onnx_asr.py` | sherpa-onnx 流式中文语音识别 |
| `scripts/probes/test_qwen_api.py` | 千问 DashScope OpenAI 兼容接口对话 |
| `scripts/probes/test_moss_tts_nano.py` | MOSS-TTS-Nano ONNX CPU 语音合成和播放 |
| `scripts/init/init_sherpa_onnx_kws_model.sh` | 下载并初始化 sherpa-onnx KWS 模型 |
| `scripts/init/init_sherpa_onnx_asr_model.sh` | 下载并初始化 sherpa-onnx ASR 模型 |
| `scripts/init/init_moss_tts_nano_model.sh` | 克隆 OpenMOSS/MOSS-TTS-Nano 并下载 ONNX 模型 |
| `scripts/init/init_funasr_model.py` | 下载并初始化 FunASR ASR/VAD/PUNC 模型 |

查看麦克风设备：

```bash
python scripts/probes/test_sherpa_onnx_kws.py --list-devices
```

测试唤醒词：

```bash
python scripts/probes/test_sherpa_onnx_kws.py
```

测试语音识别：

```bash
python scripts/probes/test_funasr_asr.py
python scripts/probes/test_sherpa_onnx_asr.py
```

测试千问对话：

```bash
python scripts/probes/test_qwen_api.py --prompt "用一句话介绍小米汽车。"
```

测试语音合成：

```bash
python scripts/probes/test_moss_tts_nano.py --text "小米小米，我已经准备好了。"
```

## 依赖分层

基础依赖：

```bash
scripts/create_venv.sh
```

千问 API：

```bash
scripts/create_venv.sh --qwen
```

FunASR 语音识别：

```bash
scripts/create_venv.sh --funasr --torch-cpu
```

依赖文件按功能拆分：

- `requirements.txt`：基础语音 I/O 和 sherpa-onnx。
- `requirements-qwen.txt`：千问 API 客户端。
- `requirements-funasr.txt`：FunASR 和 ModelScope。
- `requirements-torch.txt`：PyTorch 和 torchaudio。

## 麦克风权限

如果只有 `sudo` 能看到麦克风：

```bash
sudo arecord -l
```

但普通用户看不到：

```bash
arecord -l
```

可以把当前用户加入 `audio` 组：

```bash
sudo usermod -aG audio "$USER"
```

执行后需要注销并重新登录，再重新测试。

## 音频输出排障

如果 `aplay` 或 TTS 播放没有声音，先参考 `docs/audio-output-troubleshooting.md`。该文档记录了 MCP01 USB 声卡的默认输出、PipeWire profile、ALSA 默认 PCM 和硬件 mixer 排查流程。

## 本地文件约定

以下内容是本地运行产物，不提交到 Git：

- `.venv/`
- `models/`
- `downloads/`
- `config/.qianwen-apikey`
- `*.wav`、`*.mp3`、`*.flac`

提交前建议检查：

```bash
git status --short --ignored
```