解决FunASR时间戳难题：Paraformer/SeacoParaformer模型ONNX导出全指南

【免费下载链接】FunASR A Fundamental End-to-End Speech Recognition Toolkit and Open Source SOTA Pretrained Models, Supporting Speech Recognition, Voice Activity Detection, Text Post-processing etc. 项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR

你是否在使用FunASR项目中的Paraformer或SeacoParaformer模型时，遇到过ONNX导出后时间戳支持缺失的问题？本文将深入分析这一高频痛点，提供从问题定位到解决方案的完整实操指南，帮助你在10分钟内解决时间戳导出难题。读完本文后，你将掌握模型结构分析、导出参数配置、时间戳提取验证的全流程技能。

项目背景与时间戳重要性

FunASR（Fundamental End-to-End Speech Recognition Toolkit）是一个开源的端到端语音识别工具包，支持语音识别、语音活动检测（VAD）、文本后处理等功能。其中Paraformer和SeacoParaformer模型作为SOTA（State-of-the-Art）的预训练模型，在实时语音转写场景中应用广泛。

时间戳（Timestamp）是语音识别结果中每个词或字符对应的音频时间位置信息，对于字幕生成、语音标注、实时字幕等应用至关重要。然而在将模型导出为ONNX格式时，时间戳信息常常丢失，导致下游应用无法准确定位语音内容的时间位置。

图1：FunASR项目架构图，展示了语音识别的完整流程，包括前端处理、编码器、解码器和后处理模块。时间戳生成通常在解码器后处理阶段完成。

相关模块路径：

• 官方文档：docs/tutorial/README_zh.md
• 模型源码：funasr/models/paraformer/、funasr/models/seaco_paraformer/
• ONNX导出工具：funasr/utils/export_utils.py

时间戳支持问题根源分析

Paraformer模型时间戳生成机制

在Paraformer模型中，时间戳生成主要依赖于ts_prediction_lfr6_standard函数，该函数位于funasr/utils/timestamp_tools.py。通过分析Paraformer的推理代码可知，时间戳计算需要pre_peak_index和alphas两个关键参数：

if pred_timestamp:
    timestamp_str, timestamp = ts_prediction_lfr6_standard(
        pre_peak_index[i],
        alphas[i],
        copy.copy(token),
        vad_offset=kwargs.get("begin_time", 0),
        upsample_rate=1,
    )

代码片段来自funasr/models/paraformer/model.py#L573-L579

然而，在ONNX导出过程中，默认配置并未包含这两个参数的输出。通过查看funasr/utils/export_utils.py中的导出逻辑，发现模型导出时仅保留了语音识别结果相关的输出节点，而忽略了时间戳计算所需的中间变量。

SeacoParaformer模型的特殊情况

SeacoParaformer作为Paraformer的改进版本，在时间戳生成上采用了不同的实现。当使用CifPredictorV3预测器时，模型会通过calc_predictor_timestamp方法生成时间戳相关参数：

if self.predictor_name == "CifPredictorV3":
    _, _, us_alphas, us_peaks = self.calc_predictor_timestamp(
        encoder_out, encoder_out_lens, pre_token_length
    )
else:
    us_alphas = None

代码片段来自funasr/models/seaco_paraformer/model.py#L427-L430

但在ONNX导出时，calc_predictor_timestamp方法并未被包含在导出的计算图中，导致时间戳相关参数丢失。

ONNX导出配置限制

ONNX导出工具funasr/utils/export_utils.py中的_onnx函数默认仅导出模型的主要输入输出节点。通过分析导出代码可知，动态轴配置和输出节点选择是影响时间戳支持的关键因素：

torch.onnx.export(
    model,
    dummy_input,
    model_path,
    verbose=verbose,
    opset_version=opset_version,
    input_names=model.export_input_names(),
    output_names=model.export_output_names(),
    dynamic_axes=model.export_dynamic_axes(),
)

代码片段来自funasr/utils/export_utils.py#L62-L71

如果模型的export_output_names方法没有包含时间戳相关的输出节点，这些信息就会在导出过程中被丢弃。

解决方案：修改导出配置以支持时间戳

步骤1：更新模型导出输出节点

首先需要修改Paraformer和SeacoParaformer模型的导出配置，确保时间戳计算所需的中间变量被包含在ONNX模型中。以Paraformer为例，需要修改模型的export_output_names方法，添加alphas和pre_peak_index作为输出节点。

步骤2：调整ONNX导出参数

在调用ONNX导出函数时，需要显式指定pred_timestamp=True参数，以触发时间戳生成逻辑。修改后的导出命令示例：

python -m funasr.export \
    --model-name "paraformer" \
    --export-dir "./export" \
    --type "onnx" \
    --pred-timestamp True \
    --opset-version 14

相关工具路径：

• ONNX导出脚本：runtime/onnxruntime/readme.md
• 导出配置示例：examples/industrial_data_pretraining/paraformer/

步骤3：验证时间戳输出

导出完成后，可以使用tests/test_asr_inference_pipeline.py脚本验证时间戳是否正确生成。测试代码示例：

def test_timestamp_export():
    model = load_onnx_model("./export/paraformer.onnx")
    audio = load_audio("test.wav")
    result = model.infer(audio, pred_timestamp=True)
    assert "timestamp" in result, "时间戳未生成"
    assert len(result["timestamp"]) == len(result["text"].split()), "时间戳数量与文本长度不匹配"

案例演示：完整导出流程与结果验证

Paraformer模型ONNX导出完整命令

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/fun/FunASR
cd FunASR

# 安装依赖
pip install -r requirements.txt

# 导出带时间戳支持的ONNX模型
python -m funasr.export \
    --model-name "paraformer" \
    --model-path "damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch" \
    --export-dir "./onnx_models/paraformer_timestamp" \
    --type "onnx" \
    --pred-timestamp True \
    --opset-version 14

SeacoParaformer模型导出注意事项

SeacoParaformer模型需要额外指定预测器类型为CifPredictorV3，以启用时间戳生成功能：

python -m funasr.export \
    --model-name "seaco_paraformer" \
    --model-path "damo/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch" \
    --export-dir "./onnx_models/seaco_paraformer_timestamp" \
    --type "onnx" \
    --pred-timestamp True \
    --predictor "CifPredictorV3" \
    --opset-version 14

时间戳结果示例

成功导出后，模型推理结果应包含类似以下格式的时间戳信息：

{
  "text": "你好世界",
  "timestamp": [
    {"word": "你好", "start": 0.5, "end": 0.8},
    {"word": "世界", "start": 0.9, "end": 1.2}
  ]
}

相关测试路径：

• 推理测试代码：tests/test_asr_vad_punc_inference_pipeline.py
• 性能基准：benchmarks/benchmark_pipeline_cer.md

总结与展望

本文深入分析了FunASR项目中Paraformer和SeacoParaformer模型ONNX导出时时间戳支持缺失的问题，通过修改模型导出配置和调整推理参数，成功解决了这一痛点。关键解决步骤包括：

1. 确保时间戳计算所需的中间变量（如alphas和pre_peak_index）被包含在ONNX导出中
2. 导出时显式启用时间戳生成功能（pred_timestamp=True）
3. 验证导出模型的时间戳输出是否与文本内容匹配

未来，随着FunASR项目的不断迭代，预计时间戳支持会更加完善。用户可以关注model_zoo/modelscope_models_zh.md获取最新的模型更新信息，或参与docs/reference/FQA.md中的社区讨论，获取更多技术支持。

相关资源：

• 模型动物园：model_zoo/modelscope_models_zh.md
• 常见问题：docs/reference/FQA.md
• 贡献指南：Acknowledge.md

通过本文介绍的方法，你可以轻松解决Paraformer和SeacoParaformer模型ONNX导出的时间戳支持问题，为语音识别应用添加精准的时间定位功能。如果遇到任何问题，欢迎在项目GitHub仓库提交issue或参与社区讨论。

点赞+收藏+关注，获取更多FunASR实用技巧！下期预告：《SeacoParaformer热词定制功能全解析》。

【免费下载链接】FunASR A Fundamental End-to-End Speech Recognition Toolkit and Open Source SOTA Pretrained Models, Supporting Speech Recognition, Voice Activity Detection, Text Post-processing etc. 项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR