prama

prama 是一个基于 sclite 的语音识别评估引擎，用于在 Python 中计算 ASR 结果的 WER（Word Error Rate）和 CER（Character Error Rate），默认返回轻量汇总统计，也可以按需返回可继续分析的对齐结果和 sclite 报告文本。

当前包的定位是轻量评估库：高层 API 面向文本列表评估，底层保留 ScliteClient 以便直接调用 sclite 对齐能力。

功能特性

• 计算 WER 和 CER。
• 支持多条 utterance 批量评估。
• 默认只返回总体统计，降低大批量评估时的内存占用。
• 可选返回分组统计、逐 token 对齐结果和 PRA 文本报告。
• 封装 libsclite.so，默认从包内 src/prama/lib/libsclite.so 查找动态库。
• 支持通过 SCLITE_LIB_PATH 或初始化参数指定自定义 libsclite.so 路径。

环境要求

• Python >=3.10, <3.13
• Linux 环境
• Poetry

安装依赖：

poetry install

运行测试：

poetry run pytest

快速开始

计算 WER：

from prama.evaluator import get_wer

result = get_wer(
    references=["the quick brown fox jumps over the lazy dog"],
    hypotheses=["the quick brown fox jumped over lazy dog"],
    utterance_ids=["sample-a"],
)

print(result.wer)
print(result.summary.substitutions)

如果需要逐 utterance 的 token 对齐结果和 PRA 报告，可以显式开启：

from prama.evaluator import get_wer

result = get_wer(
    references=["the quick brown fox jumps over the lazy dog"],
    hypotheses=["the quick brown fox jumped over lazy dog"],
    utterance_ids=["sample-a"],
    include_details=True,
    include_report=True,
)

print(result.utterances[0].tokens)
print(result.report)

计算 CER：

from prama.evaluator import get_cer

result = get_cer(
    references=["你好世界"],
    hypotheses=["你好世"],
)

print(result.cer)
print(result.summary.deletions)

复用评估器：

from prama.evaluator import Evaluator

with Evaluator() as evaluator:
    wer_result = evaluator.get_wer(["hello world"], ["hello word"])
    cer_result = evaluator.get_cer(["hello"], ["hallo"])

print(wer_result.wer)
print(cer_result.cer)

高层 API

get_wer

get_wer(
    references: list[str],
    hypotheses: list[str],
    utterance_ids: list[str] | None = None,
    *,
    include_details: bool = False,
    include_report: bool = False,
    batch_size: int | None = 1000,
) -> WerResult

get_cer

get_cer(
    references: list[str],
    hypotheses: list[str],
    utterance_ids: list[str] | None = None,
    *,
    include_details: bool = False,
    include_report: bool = False,
    batch_size: int | None = 1000,
) -> WerResult

参数说明：

• references：参考文本列表。
• hypotheses：识别结果文本列表。
• utterance_ids：可选的 utterance ID 列表。未传入时自动生成 utt0001、utt0002 等 ID。
• include_details：是否返回每个 utterance 的分组统计和 token 对齐结果。默认 False。
• include_report：是否生成 PRA 文本报告。默认 False。
• batch_size：轻量汇总模式下的自动分批大小，默认 1000。传入 None 时关闭分批，按整批调用 sclite。

当 include_details=False 且 include_report=False 时，高层 API 会按 batch_size 分批评估并累加汇总计数，以避免一次性生成所有样本的 native 对齐结果。开启明细或报告后会使用整批评估，以保持返回内容完整。

输入约束：

• references、hypotheses 和 utterance_ids 必须是 list[str]。
• references 和 hypotheses 允许长度不一致，缺失的一侧会按空文本参与评估。
• utterance_ids 如果传入，长度必须等于实际评估对数。
• utterance_ids 不能包含空字符串、括号或换行符。

返回结果

get_wer 和 get_cer 返回 WerResult：

@dataclass(frozen=True, slots=True)
class WerResult:
    summary: ScliteCounts
    groups: list[ScliteGroup]
    utterances: list[WerUtterance]
    report: str
    metric: str

常用字段：

• result.wer：WER 数值。
• result.cer：CER 数值。CER 复用 sclite 的错误率字段。
• result.accuracy：准确率。
• result.summary：总体统计，包含 correct、substitutions、deletions、insertions 等字段。
• result.groups：sclite 分组统计。仅在 include_details=True 时填充，否则为空列表。
• result.utterances：逐 utterance 的 token 对齐结果。仅在 include_details=True 时填充，否则为空列表。
• result.report：sclite 生成的 PRA 文本报告。仅在 include_report=True 时填充，否则为空字符串。

底层 sclite 封装

如果需要直接评估 TRN、STM、CTM 等格式文件，可以使用 ScliteClient：

from prama.sclite import Format, IdType, ScliteClient, ScliteOptions

with ScliteClient() as client:
    with client.align_files(
        "ref.trn",
        "hyp.trn",
        ref_format=Format.TRN,
        hyp_format=Format.TRN,
        options=ScliteOptions(id_type=IdType.SP),
    ) as result:
        print(result.summary().wer)
        print(result.report_text())

动态库查找顺序：

1. ScliteClient(lib_path=...) 显式传入的路径。
2. 环境变量 SCLITE_LIB_PATH。
3. 包内 prama/lib/libsclite.so。
4. 系统库搜索结果。

开发说明

本项目使用 Poetry 管理依赖和命令：

poetry install
poetry run pytest

测试用例位于 tests/test_sclite，覆盖高层评估 API 和底层 sclite wrapper。