ASR 全链路质量评估平台

一、立项背景与目标
随着语音交互在智能客服、车载、医疗记录等场景广泛落地，ASR 模型质量直接决定下游业务可用性。但业内存在两个痛点：一是模型评测常依赖厂商宣传数字，缺乏独立、可复现的客观评估手段；二是选型时面对百度、讯飞、阿里等多家厂商，难以在相同测试集上横向比较真实能力、错误类型与服务性能。本项目"ASR 全链路质量评估平台"即针对上述背景立项，目标是搭建一套端到端、可扩展、可复现的 ASR 自动化质量评估工具：输入一批待测音频及对应标准答案，平台自动调用被测 ASR 接口完成转写，基于编辑距离计算 CER 与 WER，细分替换/删除/插入三类错误，挖掘高频错误模式与场景短板，输出含 Bad Case 与优化建议的评估报告。项目既可作为个人测试工程能力的综合实战，也可作为团队 ASR 选型与回归测试的基础设施。

二、软件功能
平台提供命令行一体化入口，功能包括：测试数据生成（正弦波合成与 Windows TTS 真人发音两条路径）、批量调用真实 ASR 接口、文本归一化、多维度指标计算、错误画像分析、并发压测、Markdown 与交互式 HTML 双格式报告生成。所有第三方凭证均通过环境变量注入，仓库零明文敏感信息。

三、核心功能模块
1) 指标计算模块（metrics.py）：基于 Levenshtein 编辑距离的动态规划实现，对参考文本与识别结果做字符级与词级双向对齐，输出命中、替换、删除、插入四类计数及派生比率，并以 jiwer 库做数值交叉校验。
2) 文本归一化模块（textnorm.py）：依次执行去标点、NFKC 全角转半角、中文数字转阿拉伯数字、合并被空格分隔的单字母序列、统一小写，专用于消除"表示形式不同"导致的虚假错误。
3) ASR 客户端层（asr_client.py）：以 typing.Protocol 定义统一 transcribe 接口，实现 Mock、通用 HTTP、百度（HTTP+token 两步鉴权）、讯飞（WebSocket+HMAC-SHA256 签名+流式分帧）四类客户端，由工厂函数按配置返回。
4) 错误分析模块（error_analysis.py）：聚合字符级与词级错误构成、按场景标签分组画像、用 Counter 挖掘高频替换对/漏识字/多识字，并基于启发式规则自动生成优化建议。
5) 并发压测模块（benchmark.py）：基于 ThreadPoolExecutor 线程池对真实接口压测，统计 QPS、延迟 P50/P90/P99、成功率与错误分类，自动解读百度业务错误码。
6) 报告生成模块（report.py / report_html.py）：Jinja2 渲染 Markdown 与离线 HTML 报告，后者使用本地 vendor 的 ECharts + echarts-wordcloud

一、整体架构与设计思路
平台采用"配置驱动 + 接口抽象 + 分层解耦"的总体架构，自下而上分为四层：基础设施层（config.py 集中管理路径、厂商参数与凭证，全部凭证从环境变量读取，符合 12-factor 规范）、ASR 接入层（以 typing.Protocol 定义统一 transcribe 接口，Mock/HTTP/百度/讯飞四类客户端各自实现，由工厂函数按 mode 字段返回，新增厂商只需加一个类与一个工厂分支，业务代码零改动，体现开放-封闭原则）、评估核心层（metrics 计算指标、textnorm 归一化、error_analysis 聚合分析三者解耦，归一化默认开启但可通过参数关闭，兼顾生产评测与单元测试）、表现与输出层（report 与 report_html 平行实现，复用同一份 ErrorProfile 数据）。整体设计强调"评估方法本身的可信度"，通过 34 个单元测试与边界测试覆盖核心算法 96% 的代码路径，确保"尺子是准的"，模型评估结果才有意义。

二、各模块技术栈
核心语言为 Python 3.10，大量使用类型提示（PEP 604 的 X|Y 联合类型）、@dataclass、@property、Protocol 与工厂模式。指标计算使用自研 Levenshtein DP 配合 jiwer 交叉校验。文本归一化使用 re 正则（含零宽断言）与 unicodedata 的 NFKC。百度客户端用 requests 实现 HTTP 调用与 token 缓存；讯飞客户端用 websockets 实现 WebSocket 流式协议，鉴权用 hashlib + hmac 完成 HMAC-SHA256 签名，响应解析处理嵌套的 ws/cw/w 结构。压测用 concurrent.futures.ThreadPoolExecutor 配合 as_completed 与 time.perf_counter 高精度计时。报告渲染用 Jinja2 模板引擎，离线可视化用 ECharts + echarts-wordcloud（本地 vendor，断网可用）。CLI 用 typer 声明式注册子命令，终端美化用 rich。测试用 pytest + coverage，核心模块覆盖率 96%。

三、开发难点与解决方案
难点一：评估方法学的虚假错误。首版评测百度 CER 高达 10.98%，深入 Bad Case 发现绝大多数是"中文数字 一三八 vs 阿拉伯数字 138""全角字母 vs 半角""逐字母读法 A B C vs 连写 ABC"等表示形式差异，并非模型真实错误。解决方案是自研文本归一化模块，使 CER 校准至 0.88%，并补充专项单元测试防止回归，深刻体现"评估方法决定评估结论可信度"。