语音 ASR 服务

相关源文件

以下文件被用作生成此 wiki 页面时的上下文：

voice_asr_service 包为 IB-Robot 系统提供 Speech-to-Text（STT）接口。它集成 sherpa-onnx 引擎执行高性能本地推理，使用 Voice Activity Detection（VAD）切分语音，并通过状态机管理 idle、listening、recognizing 等状态之间的切换。

系统架构

VoiceASRNode 作为中心协调器，编排多个专用模块，用于处理来自麦克风或本地文件的音频流。

组件关系

下图展示 voice_asr_service 内部代码实体如何协作，将原始音频转换为文本命令。

Voice ASR Component Map

        graph TD
    subgraph "VoiceASRNode [voice_asr_service/voice_asr_node.py]"
        SM["StateMachine [state_machine.py]"]
        AC["AudioCaptureModule [audio_capture_module.py]"]
        FI["FileInputModule [file_input_module.py]"]
        VM["VADModule [vad_module.py]"]
        ASR["ASRInferenceModule [asr_inference_module.py]"]
        MM["ModelManager [model_manager.py]"]
    end

    MIC[("Microphone")] --> AC
    FILE[("Audio File")] --> FI
    
    AC -->|"Audio Chunks"| VM
    FI -->|"Audio Buffer"| VM
    
    VM -->|"Speech Segments"| ASR
    ASR -->|"Partial/Final Text"| OUT["/voice_command Topic"]
    
    SM -->|"ActiveMode & NodeState"| VAN["VoiceASRNode"]
    VAN -->|"Control Signals"| AC
    VAN -->|"Control Signals"| ASR
    VAN -->|"Model Config"| MM
    MM -->|"Resolved Model Paths"| ASR

来源：src/voice_asr_service/voice_asr_service/voice_asr_node.py:22-29、src/voice_asr_service/README.md:67-77

核心模块

1. ASR 推理模块

ASRInferenceModule 封装 sherpa-onnx 库。它同时支持流式模型（Transducer/Paraformer）和离线模型（Paraformer）。节点会根据目录结构或路径提示自动检测模型类型。

来源：src/voice_asr_service/voice_asr_service/asr_inference_module.py:1-143

2. VAD 模块

VADModule 识别语音边界，避免 ASR 引擎处理静音。它使用多层策略：

  1. Silero VAD：基于神经网络的高精度检测，支持 JIT 或 ONNX 后端 src/voice_asr_service/voice_asr_service/vad_module.py:107-160。

  2. 基于能量的 VAD：使用自适应能量阈值的回退机制 src/voice_asr_service/voice_asr_service/vad_module.py:175-180。

  3. 预滚缓冲区：维护一小段音频缓冲（realtime_pre_roll_seconds），避免句首被截断 src/voice_asr_service/voice_asr_service/voice_asr_node.py:154。

来源：src/voice_asr_service/voice_asr_service/vad_module.py:1-106

3. 音频采集模块

AudioCaptureModule 处理麦克风输入，在 pyaudio 或 sounddevice 之上提供统一接口。它管理 RingBuffer 以保存预滚音频，并在独立线程中运行，避免阻塞 ROS 主循环。

来源：src/voice_asr_service/voice_asr_service/audio_capture_module.py:1-130

4. 模型管理器

model_manager.py 模块负责解析并可选自动下载 ASR 模型 bundle。它根据配置参数选择合适的模型（流式或离线），并确保模型资源在本地可用。

来源：src/voice_asr_service/voice_asr_service/model_manager.py:1-179

5. 状态机

StateMachine 管理运行生命周期和交互模式 src/voice_asr_service/voice_asr_service/state_machine.py:1-40。

状态 (NodeState)

说明

IDLE

默认状态，不处理音频 src/voice_asr_service/voice_asr_service/state_machine.py:10。

LISTENING

主动监听音频，等待 VAD 触发 src/voice_asr_service/voice_asr_service/state_machine.py:11。

RECOGNIZING

VAD 已检测到语音，音频正在送入 ASR src/voice_asr_service/voice_asr_service/state_machine.py:12。

BUSY

正在处理文件输入或被 service 阻塞 src/voice_asr_service/voice_asr_service/state_machine.py:13。

来源：src/voice_asr_service/voice_asr_service/state_machine.py:8-15、src/voice_asr_service/README.md:90-98

数据流和 ROS 接口

该服务支持两种主要输入模式：实时麦克风 和 基于文件的识别。

识别序列

下图将识别请求的逻辑流程映射到内部类方法。

Recognition Logic Flow

        sequenceDiagram
    participant ROS as "ROS Interface"
    participant VAN as "VoiceASRNode"
    participant AC as "AudioCaptureModule"
    participant VM as "VADModule"
    participant ASR as "ASRInferenceModule"

    Note over ROS, ASR: Start Recognition Trigger
    ROS->>VAN: ~/start_recognition (Service)
    VAN->>VAN: _transition_state(LISTENING, "service_start")
    VAN->>AC: start_capture()
    
    loop Process Audio Timer
        AC->>VAN: _audio_queue.get()
        VAN->>VM: process(chunk)
        alt VADState.STARTING
            VAN->>VAN: _transition_state(RECOGNIZING, "speech_start")
            VAN->>ASR: create_stream()
        else VADState.SPEAKING
            VAN->>ASR: push_samples(chunk)
            ASR-->>ROS: /voice_partial (Topic)
        else VADState.ENDING
            VAN->>ASR: finalize_stream()
            ASR-->>ROS: output_topic (Topic)
            VAN->>VAN: _transition_state(LISTENING, "speech_end")
        end
    end

来源：src/voice_asr_service/voice_asr_service/voice_asr_node.py:388-460、src/voice_asr_service/README.md:144-161

ROS API 参考

Topics

来源：src/voice_asr_service/README.md:195-209

Services

来源：src/voice_asr_service/README.md:223-227

配置 (robot_config)

voice_asr_service 通常通过 robot_config launch 系统启动。generate_voice_asr_nodes builder 从机器人 YAML 中提取参数并解析文件路径。

参数

说明

默认值

active_mode

激活策略（manual、continuous）

continuous

model_path

模型目录或文件路径

""（为空且启用时自动下载）

tokens_path

tokens 文件路径

""（为空时自动解析）

provider

推理后端（cpu、cuda、coreml）

cpu

model_type

模型类型提示（auto、streaming、offline）

auto

auto_download_model

缺失时自动下载默认 bundle

True

max_recording_duration

单次实时录音最大时长

10.0

vad_sensitivity

VAD 灵敏度阈值（0.0 到 1.0）

0.6

realtime_pre_roll_seconds

拼接到识别前的音频缓冲

0.5

publish_partial

是否发布部分识别结果

True

output_topic

最终识别文本的 ROS topic

/voice_command

sample_rate

音频采样率

16000

chunk_size

以帧为单位的音频块大小

512

buffer_seconds

音频采集环形缓冲区大小，单位秒

5.0

device_index

音频输入设备索引

-1（自动检测）

device_name

音频输入设备名称（子串匹配）

""

exit_on_init_failure

ASR 初始化失败时退出节点

True

来源：src/robot_config/robot_config/config.py:109-130、src/robot_config/robot_config/launch_builders/voice_asr.py:132-185、src/voice_asr_service/voice_asr_service/defaults.py:3-23