Nlptutti 한국어 STT 평가 매뉴얼

세 함수는 기본적으로 문장부호를 제거한다. 문장부호도 오류로 평가하려면 rm_punctuation=False를 지정한다. 여러 문장은 evaluate_corpus의 micro와 macro를 목적에 맞게 사용한다.

pip install -U nlptutti

import nlptutti as nt

reference = "오늘 날씨가 맑습니다"
hypothesis = "오늘 날씨는 맑습니다"

cer = nt.get_cer(reference, hypothesis, rate_mode="standard")
wer = nt.get_wer(reference, hypothesis, rate_mode="standard")
crr = nt.get_crr(reference, hypothesis, rate_mode="standard")

print(round(cer["cer"], 4), cer["substitutions"])  # 0.1111 1
print(round(wer["wer"], 4), wer["substitutions"])  # 0.3333 1
print(crr["crr"], crr["substitutions"])            # 0.89 1

CER·WER는 낮을수록, CRR는 높을수록 좋다. 완전 일치는 각각 0.0, 0.0, 1.0이며 상세 편집 횟수는 같은 결과 딕셔너리에서 확인한다.

import nlptutti as nt

report = nt.compare_systems(
    ["오늘 날씨가 맑습니다", "서울은 따뜻합니다"],
    {
        "baseline": [
            "오늘 날씨는 맑습니다",
            "서울은 춥습니다",
        ],
        "candidate": [
            "오늘 날씨가 맑습니다",
            "서울은 따뜻합니다",
        ],
    },
    rate_mode="standard",
)

for system in report["systems"]:
    metrics = system["metrics"]
    print(
        system["id"],
        round(metrics["cer"]["micro"], 4),
        round(metrics["wer"]["micro"], 4),
    )

# baseline 0.2353 0.4
# candidate 0.0 0.0

이 예제는 패키지 저장소의 고정 예제 데이터와 같다. 문서와 CI에서도 같은 기대값을 검사한다.

JSON과 Markdown 결과 저장

0.0.0.24부터 예제가 설치본에 포함된다. 설치 후에는 GitHub 파일이나 모델을 내려받지 않고 실행한다.

nlptutti sample --output comparison_input.json
nlptutti compare comparison_input.json \
  --rate-mode standard \
  --output-dir comparison-report

comparison-report/report.json
comparison-report/report.md

• micro: corpus 전체의 편집 횟수를 합산한 점수다.
• macro: 문장별 점수의 단순 평균이다.
• delta: candidate 점수에서 baseline 점수를 뺀 값이다. CER·WER는 음수, CRR은 양수일수록 candidate가 좋다.
• 기본값: 기존 결과와 호환되도록 rate_mode="normalized"를 유지한다. 공식 비교에서는 "standard"를 직접 적는다.
• ID mapping: ID 문자열을 정렬한 순서로 계산하므로 mapping에 넣은 순서가 fingerprint나 bootstrap 결과를 바꾸지 않는다.
• 선택 평가 설정: 키워드·개체명·별칭을 사용하면 설정 전체의 SHA-256을 결과에 남긴다.
• 원문: 문장 전체를 담는 raw_inputs는 include_transcripts=True일 때만 추가한다. 개체명 오류 구간이나 진단 토큰은 별개다.

외부에 공유할 보고서: 0.0.0.23부터

기존 결과와 호환되도록 기본값은 privacy_mode="detailed"다. 이 모드에는 사전 이름·라벨, 개체명 오류 구간, 진단 토큰이 남을 수 있다. include_transcripts=False만으로 모든 텍스트가 숨겨지는 것은 아니다.

report = nt.compare_systems(
    ["김민수"],
    {
        "baseline": ["김민서"],
        "candidate": ["김민수"],
    },
    entities=["김민수"],
    privacy_mode="aggregate",
)
systems = report["systems"]
print([system["id"] for system in systems])
# ['system-1', 'system-2']
summary = systems[1]["entities"]["summary"]
print(summary["f1"])  # 1.0

집계 모드는 점수와 fingerprint를 유지하고 사전별·라벨별 상세와 오류 텍스트를 제외한다. 시스템 이름은 입력 순서대로 바꾸며 진단 토큰은 [redacted]로 표시한다. CLI에서는 --privacy-mode aggregate를 지정한다. 원문 포함 옵션과 함께 쓸 수 없으며, 해시와 집계값도 익명성을 보장하지 않는다.

파일·문장별 비교와 CI 판정: 0.0.0.24부터

저장된 STT 파일은 --input-format manifest로 연결한다. 파일마다 ID, 경로, 형식을 적고 공급자 응답에는 provider와 schema도 명시한다. 경로는 목록 파일이 있는 폴더 기준이며, 보고서에는 경로 대신 파일 해시와 형식만 남긴다. 파일 목록 예제에서 시작할 수 있다.

nlptutti compare manifest.json \
  --input-format manifest \
  --rate-mode standard \
  --output-dir comparison-report

include_items=True는 문장별 점수와 상위 악화·개선 ID를 추가한다. labels는 사용자가 붙인 도메인·잡음 등의 조건별 집계다. 음성을 분석해 라벨을 추정하지 않으며, 표본 수가 작은 조건은 따로 해석해야 한다. ID와 라벨도 민감할 수 있어 집계 전용 모드에서는 두 옵션을 거부한다. 숫자·띄어쓰기·이름 예제로 결과를 읽어 보자.

nlptutti gate \
  comparison-report/report.json \
  --policy examples/gate_policy.json \
  --output decision.json

gate는 직접 정한 허용치를 검사한다. 종료 코드 0은 통과, 3은 품질 기준 미달, 2는 입력이나 설정 오류다. 2%p는 0.02로 적는다. 정책 파일과 CI 예제를 참고하자. 이 판정은 통계적 유의성 검정이 아니다.

JSON과 Markdown은 같은 보고서 검증을 거친다. 필수 필드나 숫자가 잘못되면 필드 경로를 포함한 오류가 난다. Bootstrap은 여전히 문장 단위이며 같은 화자의 여러 문장은 독립 표본이 아닐 수 있다. 소표본·낮은 재표집 횟수·폭이 0인 구간은 해석 안내를 함께 확인한다.

입력 ID 규칙, paired bootstrap, 한국어 진단과 결과 schema는 패키지 비교 매뉴얼에 정리되어 있다.

1. 일반 텍스트

import nlptutti as nt

transcript = nt.parse_transcript(
    "오늘 날씨는 맑습니다",
    "text",
)

입력 문자열을 바꾸지 않고 가설문장으로 사용한다. txt도 같은 형식 이름으로 사용할 수 있다.

2. JSON

transcript = nt.parse_transcript(
    {
        "text": "오늘 날씨는 맑습니다",
        "segments": [
            {"start": 0, "end": 1200, "text": "오늘 날씨는"},
            {"start": 1200, "end": 2500, "text": "맑습니다"},
        ],
        "model": "example-model",
        "language": "ko",
    },
    "json",
)

기본값은 최상위 text만 평가 문장으로 사용한다. file, model, language, duration_s가 실제로 있으면 provenance에 보존한다. JSON 타임스탬프의 단위는 추정하지 않는다.

# 최상위 text가 없을 때만 직접 선택한다.
transcript = nt.parse_transcript(
    {
        "segments": [
            {"text": "오늘 날씨는"},
            {"text": "맑습니다"},
        ]
    },
    "json",
    json_text_policy="segments_fallback",
)

3. SRT

srt = """1
00:00:00,000 --> 00:00:01,200
오늘 날씨는

2
00:00:01,200 --> 00:00:02,500
맑습니다
"""

transcript = nt.parse_transcript(srt, "srt")

cue 텍스트를 순서대로 ASCII 공백 하나로 연결한다. 타임코드는 점수에서 빼고 provenance에만 남긴다.

4. TSV

tsv = """start\tend\ttext
0.0\t1.2\t오늘 날씨는
1.2\t2.5\t맑습니다
"""

transcript = nt.parse_transcript(tsv, "tsv")

start, end, text 헤더가 필요하다. 시간 값은 초 단위의 유한한 숫자로 검증하고 text 열만 평가 문장으로 사용한다.

평가 여권 만들기

report = nt.evaluate_transcript(
    "오늘 날씨가 맑습니다",
    transcript,
    rate_mode="standard",
)

print(round(report["metrics"]["cer"]["value"], 4))  # 0.1111
print(round(report["metrics"]["wer"]["value"], 4))  # 0.3333
print(report["schema_version"])                      # 1.0
print(report["options"]["rate_mode"])               # standard

• evaluator: 실제 평가에 사용한 nlptutti 버전을 기록한다.
• options: rate_mode, 문장부호 제거, 유니코드 정규화 설정을 기록한다.
• metrics: CER·WER·CRR 값과 각 치환·삭제·삽입 횟수를 기록한다.
• provenance: 입력 형식, 선택한 JSON 정책, 구간 수, 제공된 메타데이터와 시간 정보를 기록한다.
• 원문 보호: reference와 hypothesis 원문 대신 SHA-256, 문자 수, UTF-8 byte 수를 기록한다. 해시는 익명화 수단이 아니므로 민감한 짧은 문장의 접근 권한은 별도로 관리한다.

JSON 문법 오류, 필수 필드 누락, 잘못된 SRT 타임코드, TSV 헤더 누락은 TranscriptFormatError로 알린다. 잘못된 입력을 빈 가설문장으로 조용히 바꾸지 않는다. 0.0.0.23부터 중복 JSON 키와 NaN/Infinity·범위를 넘는 실수도 거부한다. 이미 dict로 변환하면서 사라진 중복 키는 확인할 수 없으므로 원본 문자열을 전달한다.

지원 형식은 FunASR 고정 커밋 d1007c3의 CLI 출력 문서를 참고하되 특정 공급자에 종속되지 않도록 직접 구현했다. FunASR 모델이나 런타임은 패키지 의존성에 포함하지 않는다.

같은 입력 비교

import nlptutti as nt

default_result = nt.get_cer("STEAM", "STREAM")
standard_result = nt.get_cer(
    "STEAM",
    "STREAM",
    rate_mode="standard",
)

print(default_result["cer"])   # 0.16666666666666666
print(standard_result["cer"])  # 0.2

기존 코드는 수정할 필요가 없다. 옵션을 생략한 호출은 계속 normalized로 계산된다. 한 프로젝트 안에서는 두 방식을 섞지 말고 결과와 함께 rate_mode를 기록한다.

import nlptutti as nt

result = nt.get_cer(
    "제이 차 세계 대전",
    "제이차 세계대전",
)

print(result)
# {"cer": 0.0, "substitutions": 0, "deletions": 0, "insertions": 0}

띄어쓰기 자체도 오류로 평가해야 한다면 CER보다 별도 전처리 정책이나 WER를 함께 검토한다.

import nlptutti as nt

result = nt.get_wer(
    "오늘 날씨가 좋습니다",
    "오늘 정말 날씨가 좋습니다",
)

print(result["wer"])         # 0.25
print(result["insertions"])  # 1

표준 WER가 필요하면 같은 호출에 rate_mode="standard"를 추가한다.

import nlptutti as nt

result = nt.get_crr("아키택트", "아키택쳐")

print(result["crr"])           # 0.75
print(result["substitutions"]) # 1

standard 모드에서는 CER가 1을 넘을 수 있으므로 CRR가 0보다 작아질 수도 있다. 0과 1 사이의 정답률이 필요하면 기본 normalized 모드를 사용한다.

import nlptutti as nt

pattern = nt.make_keyword_pattern("메리츠 화재")

print(bool(pattern.search("메리츠화재의 주가")))  # True
print(bool(pattern.search("메리츠 화재는 상승"))) # True
print(bool(pattern.search("비메리츠화재상품")))    # False

조사 목록을 생략하면 COMPLEX_JOSA가 사용된다. 직접 제어하려면 두 번째 인자에 조사 목록을, 세 번째 인자에 어미 목록을 전달한다.

import nlptutti as nt

report = nt.evaluate_corpus(
    ["가나", "다라"],
    ["가마", "다라바"],
)

print(report["rate_mode"])          # normalized
print(report["cer"]["micro"])       # 0.4
print(report["cer"]["macro"])       # 0.41666666666666663
print(report["perfect_sentences"])  # 0
print(report["sentence_error_rate"]) # 1.0

• micro: 모든 문장의 편집 횟수를 합친 뒤 한 번 계산한다.
• macro: 문장별 오류율을 동일한 가중치로 평균한다.
• sentence_error_rate: CER 전처리 후 하나라도 문자 오류가 있는 문장의 비율이다.

띄어쓰기만 다르면 왜 문장 오류율이 0일까?

기존 문장 오류율은 공백을 제거하는 문자 기준이다. 그 의미는 유지하고, 0.0.0.24부터 공백으로 나눈 어절 기준을 별도 필드로 제공한다.

import nlptutti as nt

result = nt.evaluate_corpus(
    ["가 나"], ["가나"],
)
# 문자 기준: 0.0, 1
print(result["sentence_error_rate"])
print(result["perfect_sentences"])
# 어절 기준: 1.0, 0
print(result["word_sentence_error_rate"])
print(result["word_perfect_sentences"])

sentence_error_unit은 character로 기록한다. 구두점만 다르면 기본 설정에서는 두 기준 모두 일치다. rate_mode="normalized"는 분모 선택이며 Unicode 문자열 변환과는 다르다. 두 예제의 출력은 패키지 docs/manual-examples.json의 공통 기대값으로 검사한다.

import nlptutti as nt

report = nt.evaluate_entities(
    ["삼성전자의 갤럭시 S26 발표"],
    ["삼성전다의 갤럭시 에스 이십육 발표와 애플"],
    {
        "ORG": ["삼성전자", "애플"],
        "PRODUCT": ["갤럭시 S26"],
    },
    aliases={
        "갤럭시 S26": ["갤럭시 에스 이십육"],
    },
)

print(report["entity_cer"]["micro"])  # 0.1
print(report["summary"]["f1"])  # 0.5
print(report["labels"]["PRODUCT"]["f1"])  # 1.0
print([(e["type"], e["entity"]) for e in report["errors"]])
# [("misrecognition", "삼성전자"), ("addition", "애플")]

결과 읽기

• entity_cer.micro: 모든 참조 개체명 span의 편집 횟수를 합쳐 계산한다.
• entity_cer.macro: 참조 개체명 언급별 CER를 동일한 가중치로 평균한다.
• 계산식 선택: 기본 normalized는 기존 패키지 호환용이다. 논문의 NE-WER처럼 참조 개체명 문자 수를 분모로 보고할 때는 rate_mode="standard"를 지정한다.
• summary: 개체명 언급의 precision, recall, F1과 false positive, false negative를 담는다.
• labels: ORG, PERSON, PRODUCT처럼 사용자가 지정한 유형별로 결과를 나눈다.
• errors: omission, addition, misrecognition과 해당 문장 인덱스 및 편집 횟수를 보여준다.

한국어와 별칭 정책

• 개체명 내부 띄어쓰기와 기본 조사·어미 결합을 허용하며, 조사는 개체명 span에 포함하지 않는다.
• aliases를 생략하면 정확한 개체명 표기만 인정한다. 발음 유사도나 퍼지 매칭은 적용하지 않는다.
• 숫자 읽기나 영문 표기의 허용 가능한 전사형처럼 실제로 같은 개체인 경우에만 별칭을 등록한다.
• 별칭은 문자 정렬 전에 대표 개체명으로 바뀌므로 등록된 별칭의 Entity CER는 0.0이다.
• 참조에 없는 개체명 추가는 Entity CER가 아니라 precision/F1과 addition 오류로 확인한다.

왜 두 점수를 함께 보나

LREC 2016의 NE-WER 연구는 전체 WER 대신 참조 개체명 span에 속한 오류를 따로 계산한다. Nlptutti는 한국어의 불안정한 단어 경계를 줄이기 위해 이 개념을 문자 단위 Entity CER로 독립 구현했다. 이는 특정 논문이나 공개 구현을 그대로 포팅한 지표가 아니며, 다른 구현과 점수가 같다는 의미도 아니다. 다만 참조 span 밖에 새로 생긴 개체명은 이 CER에 포함되지 않으므로 언급 precision/F1을 함께 반환한다.

NAACL 2025의 Spoken NER 연구도 개체명 오류율을 전체 WER의 대체제가 아닌 보완 지표로 설명한다. 따라서 보고서에는 전체 CER, Entity CER, 개체명 F1과 평가 정책을 함께 기록하는 것이 좋다.

• ContextASR-Bench 평가 코드: 개체명 목록을 이용해 WER, 퍼지 매칭 기반 NE-WER, 정확 일치 기반 NE-FNR을 계산한다. NVIDIA NeMo-Skills에도 같은 벤치마크 평가 구현이 있다. Nlptutti는 퍼지 매칭을 기본으로 사용하지 않고 한국어 문자 span과 사용자가 등록한 aliases를 평가한다.
• Teklia ie-eval: BIO 형식의 정답·예측 파일을 입력받아 ECER/EWER와 유형별·순서 독립 점수를 계산한다. Nlptutti는 이미 태깅된 NER 출력 대신 원문 reference/hypothesis와 개체명 사전을 입력받으며 NER 모델을 실행하지 않는다.
• PIER: 전체 문장을 먼저 정렬하고 참조에서 지정한 관심 단어 위치의 편집만 단어 단위로 센다. Nlptutti Entity CER는 같은 관심 구간 평가 원칙을 한국어 문자 단위로 적용한다.

공통으로 지키는 규칙과 의도한 차이는 교차 검증 테스트와 고정 upstream 결과에 기록한다. CI에서는 외부 저장소를 내려받지 않고 검증한 커밋과 결과를 fixture로 고정한다.

import nlptutti as nt

report = nt.evaluate_keywords(
    [
        "삼성전자와 삼성전자가 협력했다.",
        "애플이 발표했다.",
    ],
    [
        "삼성전자가 협력했다.",
        "애플과 삼성전자가 발표했다.",
    ],
    {"ORG": ["삼성전자", "애플"]},
)

samsung = report["keywords"]["삼성전자"]
print(samsung["true_positives"])   # 1
print(samsung["false_negatives"])  # 1
print(samsung["false_positives"])  # 1
print(samsung["f1"])               # 0.5
print(report["labels"]["ORG"]["f1"])  # 0.6666666666666666

0.0.0.23부터 unicode_normalization="NFC"를 지정하면 문장·키워드·조사·어미에 같은 Unicode 정규화를 적용한다. 기본값은 여전히 None이며 반환 키는 입력한 키워드 표기를 유지한다. 키워드 매칭에서는 구두점을 제거하지 않으므로 C++와 C는 다르다.

import nlptutti as nt

detail = nt.explain_errors(
    "아키택트",
    "아키택쳐",
)

print(detail["rate"])   # 0.25
print(detail["counts"])
# {"hits": 3, "substitutions": 1, "deletions": 0, "insertions": 0}

print(detail["error_frequencies"]["substitutions"])
# [{"reference": "트", "hypothesis": "쳐", "count": 1}]

단어 단위 분석은 unit="word"를 지정한다. 반환되는 alignment에는 equal, substitute, delete, insert가 순서대로 담긴다.

import nlptutti as nt

result = nt.calculate_keyword_error_rate_with_pattern(
    ["삼성전자가 발표했다."],
    ["삼성전자가 발표했다."],
    ["삼성전자"],
    nt.COMPLEX_JOSA,
)

print(result["keywords"]["삼성전자"]["accuracy"]) # 1.0

이 함수는 한 문장에 같은 키워드가 여러 번 나와도 1회로 집계하며, hypothesis에만 등장한 키워드는 false positive로 세지 않는다. 새 코드에서는 evaluate_keywords를 권장한다.

문장부호

result = nt.get_wer(
    "안녕하세요!",
    "안녕하세요",
    rm_punctuation=True,  # 기본값
)

유니코드 NFC

result = nt.get_cer(
    reference,
    hypothesis,
    unicode_normalization="NFC",
)

• unicode_normalization=None이 기본값이며 과거 결과를 그대로 보존한다.
• NFC/NFD/NFKC/NFKD를 선택할 수 있다. 일반적인 한글 조합형 차이에는 NFC가 적합하다.
• 0.0.0.23부터 비교 API의 정규화 설정은 키워드·개체명 사전과 접미사에도 적용된다. NFD에서도 서울대학교를 서울로 세지 않고, 허용 조사인 서울은은 1회로 센다.
• CER와 CRR은 공백을 항상 제거한다. WER는 공백을 단어 경계로 사용한다.
• 코퍼스, 키워드, 개체명 평가의 reference/hypothesis 문장 수가 다르면 ValueError가 발생한다.

• Galibert et al., LREC 2016: NE-WER를 참조 개체명 span에 제한된 WER로 설명한다.
• Le-Duc et al., NAACL 2025: WER·KER를 보완하는 Named-Entity-Error-Rate를 논의한다.
• Szymański et al., ACL 2023: ASR 오류와 개체명 인식 오류의 관계 및 오류 유형을 분석한다.
• Gong et al., Interspeech 2025: 일반 WER와 별도로 bias word 성능을 보고한다.
• K et al., NAACL 2025 Findings: 단어 경계와 형태가 다양한 다국어 ASR에서 CER 병행의 근거를 제시한다.