bugfix: real-time speech recognition module that caused missing words and update readme

Author: lovemefan

README-CN.md

@@ -64,7 +64,7 @@ RapidSpeech.cpp 并非"单模型推理工具"，而是一套面向真实业务
   基于 `ggml` 的高性能计算后端，支持从 INT4 到 FP32 的混合精度推理。
 
 - **架构层（Architecture Layer）**
-  插件式模型构建与加载机制，规划支持 FunASR-nano、CosyVoice、Qwen3-TTS 等主流模型体系。
+  插件式模型构建与加载机制，支持 FunASR-nano、CosyVoice、Qwen3-TTS 等主流模型体系。
 
 - **业务逻辑层（Business Logic）**
   内置环形缓冲区、VAD（端点检测）、文本前端（如音素化）以及多会话并发管理能力。
@@ -73,26 +73,24 @@ RapidSpeech.cpp 并非"单模型推理工具"，而是一套面向真实业务
 
 ## 🚀 核心特性
 
-- **极致量化支持**：原生支持 4-bit / 5-bit / 6-bit 量化方案，充分适配不同算力与带宽条件的硬件。
-- **零依赖部署**：纯 C/C++ 实现，最终产物为单一、轻量级二进制文件。
-- **GPU / NPU 加速**：针对语音模型特点，对 CUDA 与 Metal 后端进行定制化优化。
-- **统一模型格式**：ASR 与 TTS 统一采用扩展后的 **GGUF** 模型格式。
-- **Python 绑定**：通过 pybind11 提供 Python 接口，支持 pip 安装，一行代码即可调用。
+- [x] **极致量化支持**：原生支持 4-bit / 5-bit / 6-bit 量化方案，充分适配不同算力与带宽条件的硬件。
+- [x] **零依赖部署**：纯 C/C++ 实现，最终产物为单一、轻量级二进制文件。
+- [x] **GPU / NPU 加速**：针对语音模型特点，对 CUDA 与 Metal 后端进行定制化优化。
+- [x] **统一模型格式**：ASR 与 TTS 统一采用扩展后的 **GGUF** 模型格式。
+- [x] **Python 绑定**：通过 pybind11 提供 Python API，支持 `pip install` 一键安装。
 
 ------
 
 ## 🛠️ 快速开始
 
 ### 模型下载
 
-请从以下平台下载对应模型的 GGUF 格式文件：
+请从以下平台下载对应模型：
 
 - 🤗 Hugging Face：https://huggingface.co/RapidAI/RapidSpeech
 - ModelScope：https://www.modelscope.cn/models/RapidAI/RapidSpeech
 
-### C++ 构建
-
-#### 基本构建（仅 CPU）
+### 从源码构建
 
 ```bash
 git clone https://github.com/RapidAI/RapidSpeech.cpp
@@ -102,217 +100,213 @@ cmake -B build
 cmake --build build --config Release
 ```
 
-#### 启用 GPU 加速
+构建产物位于 `build/` 目录：
+- `rs-asr-offline` — 离线 ASR 命令行工具
+- `rs-asr-online` — 在线（流式）ASR 命令行工具
+- `rs-quantize` — 模型量化工具
+
+### C++ 命令行使用
 
-<details>
-<summary>🍎 macOS Metal（默认启用）</summary>
+#### 离线识别（rs-asr-offline）
 
-macOS 平台默认启用 Metal 加速，无需额外配置：
+**基础用法 — 不使用 VAD：**
 
 ```bash
-cmake -B build
-cmake --build build --config Release
+./build/rs-asr-offline \
+  -m /path/to/funasr-nano-fp16.gguf \
+  -w /path/to/audio.wav \
+  -t 4 \
+  --gpu true
 ```
 
-</details>
-
-<details>
-<summary>🖥️ NVIDIA CUDA</summary>
+**使用 VAD 分段（推荐，适合长音频）：**
 
 ```bash
-cmake -B build -DRS_CUDA=ON -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc
-cmake --build build --config Release
+./build/rs-asr-offline \
+  -m /path/to/funasr-nano-fp16.gguf \
+  -v /path/to/silero_vad_v6.gguf \
+  -w /path/to/audio.wav \
+  -t 4 \
+  --vad-threshold 0.5 \
+  --silence-ms 600
 ```
 
-</details>
+指定 VAD 模型后，工具会自动按语音活动分段，并输出带时间戳的分段识别结果。
 
-<details>
-<summary>🌋 Vulkan</summary>
+参数说明：
 
-```bash
-cmake -B build -DRS_VULKAN=ON
-cmake --build build --config Release
-```
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `-m, --model` | GGUF 模型文件路径（必填） | — |
+| `-w, --wav` | WAV 音频文件路径（16kHz，必填） | — |
+| `-v, --vad` | Silero VAD GGUF 模型路径（可选，启用 VAD 分段） | — |
+| `-t, --threads` | CPU 线程数 | 4 |
+| `--gpu` | 是否启用 GPU 加速（`true`/`false`） | true |
+| `--vad-threshold` | VAD 语音检测阈值（0~1，越低越灵敏） | 0.5 |
+| `--silence-ms` | 静默时长超过该值则切分段落（ms） | 600 |
+| `--max-segment-s` | ASR 输入的最大分段长度（秒） | 30.0 |
 
-</details>
+#### 在线/流式识别（rs-asr-online）
 
-<details>
-<summary>⚡ 华为 CANN（Ascend NPU）</summary>
+**WAV 文件（模拟流式）：**
 
 ```bash
-cmake -B build -DRS_CANN=ON
-cmake --build build --config Release
+./build/rs-asr-online \
+  -m /path/to/funasr-nano-fp16.gguf \
+  -v /path/to/silero_vad_v6.gguf \
+  -w /path/to/audio.wav \
+  -t 4 \
+  --vad-threshold 0.5 \
+  --silence-ms 600
 ```
 
-</details>
+**麦克风实时识别：**
 
-### C++ 命令行使用
+```bash
+./build/rs-asr-online \
+  -m /path/to/funasr-nano-fp16.gguf \
+  -v /path/to/silero_vad_v6.gguf \
+  --mic \
+  -t 4
+```
 
-构建完成后，使用 `rs-asr-offline` 进行离线语音识别：
+**两遍模式（CTC 快速解码 + LLM 重打分，仅 FunASR-Nano 支持）：**
 
 ```bash
-# 基本用法
-./build/rs-asr-offline \
-  -m /path/to/model.gguf \
-  -w /path/to/audio.wav
-
-# 指定线程数和 GPU
-./build/rs-asr-offline \
-  -m /path/to/model.gguf \
+./build/rs-asr-online \
+  -m /path/to/funasr-nano-fp16.gguf \
+  -v /path/to/silero_vad_v6.gguf \
   -w /path/to/audio.wav \
-  -t 8 \
-  --gpu 1
+  --two-pass
+```
+
+参数说明：
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `-m, --model` | ASR GGUF 模型文件路径（必填） | — |
+| `-v, --vad` | Silero VAD 模型文件路径（必填） | — |
+| `-w, --wav` | WAV 音频文件路径（16kHz） | — |
+| `--mic` | 使用麦克风输入（实时模式） | 关闭 |
+| `--mic-device` | 麦克风设备索引 | 自动 |
+| `--mic-chunk-ms` | 麦克风读取块大小（ms） | 32 |
+| `-t, --threads` | CPU 线程数 | 4 |
+| `--gpu` | 是否启用 GPU 加速（`true`/`false`） | true |
+| `--vad-threshold` | VAD 语音检测阈值（0~1，越低越灵敏） | 0.5 |
+| `--silence-ms` | 静默超时切分时长（ms） | 600 |
+| `--two-pass` | 启用两遍模式：CTC 解码 + LLM 重打分 | 关闭 |
+
+#### 模型量化（rs-quantize）
+
+```bash
+./build/rs-quantize /path/to/funasr-nano-fp16.gguf /path/to/output-q4_k.gguf q4_k
 ```
 
-**命令行参数：**
+支持的量化类型：`q4_0`, `q4_k`, `q4_k_m`, `q5_0`, `q5_k`, `q8_0`, `f16`, `f32`
 
-| 参数 | 说明                         | 默认值 |
-| --- |----------------------------|-----|
-| `-m, --model` | 模型文件路径（必选）                 | -   |
-| `-w, --wav` | WAV 音频文件路径（可选，不提供则使用测试正弦波） | -   |
-| `-t, --threads` | CPU 线程数                    | 4   |
-| `--gpu` | 是否启用 GPU 加速（`0`/`1`）       | 1   |
-| `-h, --help` | 显示帮助信息                     | -   |
+> ⚠️ **量化注意**：Q2_K 量化对 FunASR Nano 精度损失过大，会导致输出乱码，不推荐使用。推荐使用q4_k_m或q8
 
 ### Python 使用
 
 #### 安装
 
-**方式一：pip 安装（推荐）**
-
 ```bash
-# CPU 版本
+# 从 PyPI 安装（CPU 版本）
 pip install rapidspeech
 
 # CUDA 版本
 pip install rapidspeech-cuda
 
-# Metal 版本（macOS）
+# macOS Metal 版本
 pip install rapidspeech-metal
 ```
 
-**方式二：从源码构建**
+#### 从源码构建 Python 包
 
 ```bash
-git clone https://github.com/RapidAI/RapidSpeech.cpp
-cd RapidSpeech.cpp
-git submodule sync && git submodule update --init --recursive
-
-# 构建 Python 绑定
 pip install .
-
-# 或指定 CUDA 后端
+# 或指定后端
 RS_BACKEND=cuda pip install .
 ```
 
-#### Python API 使用示例
+#### Python API
 
 ```python
-import numpy as np
 import rapidspeech
+import numpy as np
 
-# 1. 初始化 ASR 离线识别器
-asr = rapidspeech.asr_offline(
-    model_path="/path/to/model.gguf",
+# 初始化 ASR 上下文
+ctx = rapidspeech.asr_offline(
+    model_path="funasr-nano-fp16.gguf",
     n_threads=4,
     use_gpu=True
 )
 
-# 2. 读取音频数据（float32, 16kHz, 单声道）
-# pcm 为 numpy float32 数组，值域 [-1.0, 1.0]
-pcm = load_wav("audio.wav")  # 自行实现 WAV 读取，或使用 soundfile / scipy.io.wavfile
-
-# 3. 推送音频数据
-asr.push_audio(pcm)
+# 读取 WAV 音频（16kHz, float32, 单声道）
+pcm = ...  # np.ndarray, shape=[N], dtype=float32
 
-# 4. 执行推理
-asr.process()
+# 推送音频并识别
+ctx.push_audio(pcm)
+ctx.process()
 
-# 5. 获取识别结果
-text = asr.get_text()
+# 获取识别结果
+text = ctx.get_text()
 print(f"识别结果: {text}")
 ```
 
-**完整的离线识别示例脚本**可参考 [`python-api-examples/asr/asr-offline.py`](./python-api-examples/asr/asr-offline.py)。
-
-运行示例：
+完整示例参见 [python-api-examples/asr/asr-offline.py](python-api-examples/asr/asr-offline.py)。
 
-```bash
-python python-api-examples/asr/asr-offline.py \
-  --model /path/to/model.gguf \
-  --audio /path/to/audio.wav \
-  --threads 4 \
-  --gpu 1
-```
+------
 
-#### Python API 参考
+## 📊 性能基准
 
-| 类/方法 | 说明 |
-| --- | --- |
-| `rapidspeech.asr_offline(model_path, n_threads=4, use_gpu=True)` | 创建离线 ASR 识别器 |
-| `asr.push_audio(pcm)` | 推送 float32 音频数据（numpy 一维数组） |
-| `asr.process()` | 执行推理，返回状态码（0=无输出, 1=有输出, -1=错误） |
-| `asr.get_text()` | 获取识别文本结果 |
+测试环境：Apple M1 Pro, funasr-nano-fp16.gguf, 15s 音频
 
-### C API 参考
+| 配置 | RTF | 耗时 | 备注 |
+|------|-----|------|------|
+| CPU -t 4 | 0.465 | 12.4s | 纯 CPU 推理 |
+| GPU -t 4 | 0.170 | 5.2s | Metal 加速 |
+| GPU -t 4 Q4_K | 0.756 | — | 量化模型在 GPU 上反量化开销增大 |
+| CPU -t 4 Q4_K | 0.530 | — | 量化模型 CPU 推理，模型体积 596MB（压缩 3.3x） |
 
-RapidSpeech 提供 C 语言接口，便于集成到其他语言和项目中。核心接口如下：
+> RTF（Real-Time Factor）= 处理时间 / 音频时长，越低越快。RTF < 1 表示快于实时。
 
-```c
-#include "rapidspeech.h"
+------
 
-// 初始化
-rs_init_params_t params = rs_default_params();
-params.model_path = "/path/to/model.gguf";
-params.n_threads   = 4;
-params.use_gpu     = true;
-rs_context_t* ctx = rs_init_from_file(params);
+## 🔧 模型格式转换
 
-// 推送音频并推理
-rs_push_audio(ctx, pcm_data, num_samples);
-int32_t status = rs_process(ctx);
+### ASR 模型（HF → GGUF）
 
-// 获取结果
-const char* text = rs_get_text_output(ctx);
+提供 HF 模型到 GGUF 格式的转换工具：
 
-// 释放资源
-rs_free(ctx);
+```bash
+python scripts/convert_hf_to_gguf.py \
+  --model /path/to/hf-model-dir \
+  --outfile /path/to/output.gguf \
+  --outtype f16
 ```
 
+### Silero VAD 模型（safetensors → GGUF）
 
-------
-
-## 🔧 开发与构建选项
-
-### CMake 选项
-
-| 选项 | 说明 | 默认值 |
-| --- | --- | --- |
-| `RS_BUILD_TESTS` | 构建测试可执行文件 | ON |
-| `RS_CUDA` | 启用 CUDA 加速 | OFF |
-| `RS_METAL` | 启用 Metal 加速（仅 macOS） | 自动检测 |
-| `RS_VULKAN` | 启用 Vulkan 加速 | OFF |
-| `RS_CANN` | 启用华为 CANN 加速 | OFF |
-| `RS_OPENCL` | 启用 OpenCL 加速 | OFF |
-| `RS_ENABLE_PYTHON` | 启用 Python 绑定（pybind11） | OFF |
-
-### 模型转换
-
-使用项目提供的脚本将 Hugging Face 模型转换为 GGUF 格式：
+用于 `rs-asr-online` 或离线 VAD 分段的 Silero VAD 模型转换：
 
 ```bash
-python scripts/convert_hf_to_gguf.py --model /path/to/hf-model --output /path/to/output.gguf
+python scripts/convert_silero_to_gguf.py \
+  --model /path/to/silero_vad_16k.safetensors \
+  --output /path/to/silero_vad_v6.gguf
 ```
 
+转换后的 VAD 模型也可直接从 [HuggingFace](https://huggingface.co/RapidAI/RapidSpeech) 或 [ModelScope](https://www.modelscope.cn/models/RapidAI/RapidSpeech) 下载。
+
 ------
 
 ## 🤝 参与贡献
 
 如果你对以下领域感兴趣，欢迎提交 PR 或参与讨论：
 
-- 适配更多模型（Qwen3-ASR、CosyVoice3 等）
-- 完善项目框架与性能优化
-- 改进文档与示例
+- 适配更多模型。
+- 完善项目框架。
+- 优化推理性能。
 
 ## 致谢