FSMN-VAD二次开发：自定义输出格式修改教程
1. 引言
1.1 业务场景描述
在语音识别、音频处理和智能对话系统中，语音端点检测（Voice Activity Detection, VAD）是至关重要的预处理步骤。它能够自动识别音频中的有效语音片段，剔除静音或无意义的背景噪声，从而提升后续任务的效率与准确性。
基于达摩院 ModelScope 平台提供的iic/speech_fsmn_vad_zh-cn-16k-common-pytorch模型构建的 FSMN-VAD 离线服务，已具备高精度的中文语音段落切分能力。其默认输出为 Markdown 表格形式，适用于可视化展示，但在实际工程集成中，往往需要将结果以结构化数据格式（如 JSON、CSV 或 XML）返回，便于下游系统解析使用。
1.2 痛点分析
原始项目采用 Gradio 构建 Web 交互界面，输出结果直接渲染为 Markdown 表格，虽然对用户友好，但存在以下问题：
- 难以对接后端服务：前端无法直接提取结构化数据进行二次处理。
- 缺乏灵活性：不支持按需定制输出字段、时间单位或数据格式。
- 不利于自动化流水线集成：无法被脚本化调用并获取机器可读的结果。
1.3 方案预告
本文将详细介绍如何对 FSMN-VAD 的输出逻辑进行二次开发，实现自定义输出格式的功能扩展。我们将从代码结构解析入手，逐步演示如何封装检测结果为 JSON 格式，并提供多种输出模式切换机制，最终实现一个既支持 Web 展示又兼容 API 调用的增强版 VAD 工具。
2. 技术方案选型与架构设计
2.1 原始输出机制分析
当前process_vad函数通过字符串拼接生成 Markdown 表格：
formatted_res += "| {i+1} | {start:.3f}s | {end:.3f}s | {end-start:.3f}s |\n"该方式耦合度高，不利于复用和扩展。理想做法是先生成结构化中间数据，再根据需求格式化输出。
2.2 改造目标与技术选型
| 目标 | 实现方式 |
|---|---|
| 输出结构化数据 | 使用 Python 字典 + 列表组织语音片段信息 |
| 支持多格式输出 | 封装format_output(data, format_type)函数 |
| 兼容原生展示 | 在 Web 界面中仍可显示 Markdown 表格 |
| 提供 API 接口潜力 | 返回 JSON 可被外部程序调用 |
我们选择JSON 作为核心中间表示格式，因其具有良好的跨语言兼容性、易读性和广泛支持。
3. 核心代码改造与实现
3.1 定义统一数据结构
首先，在process_vad中分离“检测”与“格式化”两个职责。新增函数用于生成标准化结果对象：
def generate_segments_data(segments): """ 将模型原始输出转换为结构化数据列表 :param segments: 模型返回的时间戳列表，如 [[start_ms, end_ms], ...] :return: 包含序号、开始/结束时间(s)、时长(s)的字典列表 """ data = [] for i, seg in enumerate(segments): start_sec = round(seg[0] / 1000.0, 3) end_sec = round(seg[1] / 1000.0, 3) duration = round(end_sec - start_sec, 3) data.append({ "index": i + 1, "start_time": start_sec, "end_time": end_sec, "duration": duration }) return data此函数确保所有时间单位统一为秒（保留三位小数），并以标准字典形式组织数据。
3.2 实现多格式输出适配器
接下来实现format_output函数，支持多种输出格式：
import json import csv from io import StringIO def format_output(data, format_type="markdown"): """ 根据指定格式输出结果 :param data: 结构化语音片段数据（list of dict） :param format_type: 输出格式类型，支持 'markdown', 'json', 'csv' :return: 格式化后的字符串 """ if not data: return "未检测到有效语音段。" if format_type == "json": return json.dumps({"segments": data, "total_count": len(data)}, ensure_ascii=False, indent=2) elif format_type == "csv": output = StringIO() writer = csv.DictWriter(output, fieldnames=["index", "start_time", "end_time", "duration"]) writer.writeheader() writer.writerows(data) return output.getvalue() elif format_type == "markdown": md = "### 🎤 检测到以下语音片段 (单位: 秒):\n\n" md += "| 片段序号 | 开始时间 | 结束时间 | 时长 |\n" md += "| :--- | :--- | :--- | :--- |\n" for item in data: md += f"| {item['index']} | {item['start_time']:.3f}s | {item['end_time']:.3f}s | {item['duration']:.3f}s |\n" return md else: raise ValueError(f"不支持的输出格式: {format_type}")该函数实现了三种主流格式：
markdown：保持原有 UI 显示效果；json：适合 API 返回或配置文件导出；csv：便于 Excel 打开或批量处理。
3.3 修改主处理函数逻辑
更新process_vad函数，使其先生成结构化数据，再根据配置决定输出格式：
# 可通过环境变量控制输出格式 OUTPUT_FORMAT = os.getenv("VAD_OUTPUT_FORMAT", "markdown").lower() def process_vad(audio_file): if audio_file is None: return "请先上传音频或录音" try: result = vad_pipeline(audio_file) if isinstance(result, list) and len(result) > 0: segments = result[0].get('value', []) else: return "模型返回格式异常" if not segments: return "未检测到有效语音段。" # 第一步：生成结构化数据 structured_data = generate_segments_data(segments) # 第二步：按需格式化输出 return format_output(structured_data, OUTPUT_FORMAT) except Exception as e: return f"检测失败: {str(e)}"通过环境变量VAD_OUTPUT_FORMAT控制输出格式，无需修改代码即可切换行为。
4. 功能验证与测试
4.1 测试准备
创建一段包含多个语音片段的.wav文件（建议采样率 16kHz），用于测试多段检测能力。
4.2 不同输出格式测试
Markdown 输出（默认）
设置环境变量：
export VAD_OUTPUT_FORMAT=markdown python web_app.py上传音频后，右侧输出区域将显示如下内容：
### 🎤 检测到以下语音片段 (单位: 秒): | 片段序号 | 开始时间 | 结束时间 | 时长 | | :--- | :--- | :--- | :--- | | 1 | 1.234s | 3.567s | 2.333s | | 2 | 5.123s | 8.456s | 3.333s |JSON 输出（API 友好）
export VAD_OUTPUT_FORMAT=json python web_app.py输出变为：
{ "segments": [ { "index": 1, "start_time": 1.234, "end_time": 3.567, "duration": 2.333 }, { "index": 2, "start_time": 5.123, "end_time": 8.456, "duration": 3.333 } ], "total_count": 2 }可用于前后端分离架构中的 RESTful 接口响应体。
CSV 输出（数据分析友好）
export VAD_OUTPUT_FORMAT=csv python web_app.py输出为：
index,start_time,end_time,duration 1,1.234,3.567,2.333 2,5.123,8.456,3.333可直接导入 Pandas 或 Excel 进行统计分析。
5. 高级优化建议
5.1 添加时间单位配置选项
可在前端增加下拉菜单让用户选择时间单位（毫秒/ms 或 秒/s），并在后端做相应转换：
unit = os.getenv("TIME_UNIT", "second") # 或 "millisecond" if unit == "millisecond": start_sec = seg[0] # 原始毫秒值 else: start_sec = round(seg[0] / 1000.0, 3)5.2 支持批量处理与文件导出
扩展功能以支持 ZIP 压缩包上传，自动遍历内部所有音频文件，并输出汇总报告（JSONL 或 CSV）。
5.3 增加错误码与状态字段
改进返回结构，加入status,error_code,message等字段，便于客户端判断执行状态：
{ "status": "success", "data": { "segments": [...], "total_count": 2 } }6. 总结
通过对 FSMN-VAD 项目的输出模块进行重构，我们成功实现了结构化数据输出与多格式适配能力。本次二次开发的核心价值在于：
- 解耦了数据生成与展示逻辑，提升了代码可维护性；
- 支持 JSON、CSV、Markdown 多种输出格式，满足不同应用场景需求；
- 为后续构建 API 服务打下基础，具备良好的工程延展性；
- 保留原有 Web 交互体验的同时增强了实用性，兼顾开发者与终端用户。
这一改造不仅适用于 FSMN-VAD 模型，也可推广至其他语音处理工具链的设计中，推动 AI 模型从“能用”向“好用”演进。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
