Whisper ASR Webservice 中 Faster Whisper 引擎的 JSON 序列化问题解析

问题背景

在语音识别领域，Whisper ASR Webservice 是一个基于 OpenAI Whisper 模型的 Web 服务封装。该项目支持多种 Whisper 实现，包括原生的 Whisper 和 Faster Whisper 优化版本。在 v1.7.0 版本中，用户报告了一个关于 Faster Whisper 引擎输出 JSON 格式时出现的序列化问题。

技术细节

当用户将输出格式设置为 JSON 并使用 Faster Whisper 作为 ASR 引擎时，系统会抛出 TypeError 异常，提示 Segments 对象不可序列化。这是因为 Faster Whisper 在 v1.7.0 版本中修改了其响应对象的结构，导致原有的 JSON 序列化方法不再适用。

解决方案分析

社区用户提供了一个有效的解决方案：通过自定义 JSON 编码器来处理数据类对象。具体实现如下：

class JSONEncoder(json.JSONEncoder):
    def default(s, o):
        if dataclasses.is_dataclass(o):
            return dataclasses.asdict(o)
        return super().default(o)

class WriteJSON(ResultWriter):
    extension: str = "json"

    def write_result(self, result: dict, file: TextIO):
        json.dump(result, file, cls=JSONEncoder)

这种方法利用了 Python 的 dataclasses 模块，将数据类对象转换为字典后再进行序列化。相比 v1.6.0 版本中直接将数组索引值序列化的方式，新方法生成的 JSON 结构更加清晰，包含了字段名称（如 start、end、tokens 等），提高了可读性和易用性。

影响与考量

这种修改虽然解决了序列化问题，但也带来了输出格式的变化。开发者需要注意：

1. 向后兼容性问题：新格式与旧版本不兼容，可能需要更新依赖此输出的下游代码
2. 数据结构变化：从数组形式变为带有命名字段的对象，提高了数据结构的自描述性
3. 性能影响：额外的数据类转换可能会引入轻微的性能开销

最佳实践建议

对于使用 Whisper ASR Webservice 的开发者，建议：

1. 如果使用 Faster Whisper 引擎并需要 JSON 输出，可以采用上述自定义编码器方案
2. 在升级版本时，注意检查输出格式的变化，必要时调整解析逻辑
3. 考虑在项目文档中明确说明不同引擎的输出格式差异

总结

这个问题的出现反映了开源项目中依赖项更新带来的兼容性挑战。通过自定义 JSON 编码器，开发者可以灵活处理数据类对象的序列化需求，同时也展示了 Python 生态系统中 dataclasses 模块的强大功能。对于语音识别应用的开发者来说，理解这些底层技术细节有助于更好地构建稳定可靠的应用系统。