prama 0.1.1

Sclite-backed WER/CER evaluation engine for ASR outputs.

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。