gihakkk/ani-multimodal-v2

담화 표지어 '아니' 멀티모달 분류기 (ver2)

한국어 담화 표지어 '아니' 가 발화에서 어떤 화용 기능으로 쓰였는지 7가지로 분류합니다. 문장(텍스트)과 말투(음성)를 함께 입력받는 멀티모달 분류기입니다.

• 텍스트 인코더: klue/roberta-large · beomi/KcELECTRA-base-v2022
• 음성 인코더: microsoft/wavlm-base-plus
• 데모: 👉 [Space 링크를 여기에 넣으세요]

분류 체계

id	분류	뜻	예
0	강조/강한 긍정	자기 말을 힘주어 세움	아니 좋은 점도 많지.
1	놀람/감탄	예상 밖이라 놀람	아니 이게 왜 9점대 일까...;;;
2	방어/합리화	상대 비난을 받아 넘기며 변호	아니 자기들도 고충이 있을텐데 그럴수도 있지
3	부연/상세화	앞말에 설명을 덧붙임	아니 저 오늘 학교 내려가다가 붕어빵 보이길래
4	부정/반박	상대 말이나 상황을 부정	아니 왜 아들한테 난리?
5	즉각 수정	방금 한 말을 곧바로 고침	행복... 아니 오래 사세요
6	화제 시작/전환	새 이야기를 꺼내거나 돌림	아니 근데 긴 생머리에 몸매좋으면 동안 인건가요??

성능

5-fold 교차검증으로 10개 모델(5 fold × 2 텍스트 백본)을 학습하고, 확률 평균으로 앙상블했습니다.

평가	표본	정확도	macro-F1	weighted-F1
교차검증 (out-of-fold)	1,846	0.6018	0.5507	0.5956
테스트 (앙상블)	206	0.5825	0.5303	0.5780
테스트 (단일 최고 모델)	206	—	0.5233	—

교차검증 수치가 표본이 9배 많아 더 안정적입니다. 무작위 추측의 macro-F1 은 약 0.14 입니다.

클래스별 (테스트 206건, 앙상블)

분류	precision	recall	F1	표본
강조/강한 긍정	0.417	0.455	0.435	11
놀람/감탄	0.537	0.550	0.543	40
방어/합리화	0.588	0.435	0.500	23
부연/상세화	0.333	0.182	0.235	11
부정/반박	0.556	0.682	0.612	66
즉각 수정	0.739	0.680	0.708	25
화제 시작/전환	0.731	0.633	0.679	30

모달리티 기여도 (테스트)

같은 모델에서 한쪽 벡터를 0으로 만들어 측정했습니다.

입력	정확도	macro-F1
텍스트 + 음성	0.5825	0.5303
텍스트만	0.5194	0.4874
음성만	0.5000	0.3649

음성만으로도 무작위(0.14)를 크게 웃돌고, 텍스트에 음성을 더하면 macro-F1 이 4.3점 오릅니다.

텍스트 백본 비교

백본	교차검증 macro-F1	테스트 macro-F1
klue/roberta-large (5 fold)	0.5485	0.5317
beomi/KcELECTRA-base-v2022 (5 fold)	0.5337	0.5023
둘을 합친 10모델 앙상블	0.5507	0.5303

저장소 파일

파일	내용
best_model.pt	단일 최고 모델 (fold5, klue/roberta-large 기반, fp16, 약 864MB)
config.py model.py data.py audio_utils.py inference.py	추론에 필요한 코드 전부
use_model.py	내려받아 바로 돌려 보는 예제
model_config.json label_map.json	구조·하이퍼파라미터 요약, 라벨 매핑
metrics.json summary.md classification_report.txt confusion_matrix.png	전체 평가 결과
predictions.csv	테스트 206건의 샘플별 정답·예측·확률

앙상블 전체(10개 체크포인트, 6.2GB)를 올렸다면 fold*_*.pt 파일도 함께 있습니다.

사용법

pip install torch transformers librosa soundfile huggingface_hub

from huggingface_hub import hf_hub_download, snapshot_download

REPO = "<사용자명>/<모델저장소이름>"

# 코드 + 체크포인트 내려받기
snapshot_download(repo_id=REPO, local_dir="ani_model",
                  allow_patterns=["*.py", "*.json", "best_model.pt"])

import sys; sys.path.insert(0, "ani_model")
from inference import Predictor

p = Predictor("ani_model/best_model.pt")

# 텍스트 + 음성
res = p.predict(text="아니 이게 왜 9점대 일까...;;;", audio="sample.wav")
print(res["label"], round(res["confidence"], 3))

# 음성 없이 텍스트만 (음성 벡터를 0으로)
import numpy as np
res = p.predict(text="행복... 아니 오래 사세요", audio=np.zeros(16000, dtype="float32"), drop_audio=True)
print(res["label"], res["probs"])

앙상블로 쓰려면 체크포인트 경로 리스트를 넘깁니다. 모델 1개당 램 약 1.8GB(roberta) / 0.9GB(KcELECTRA)가 듭니다.

p = Predictor(["ani_model/fold1_roberta.pt", "ani_model/fold2_roberta.pt"])

입력 형식

• text: '아니'가 포함된 한국어 문장. 최대 192 토큰.
• audio: wav/mp3/m4a 등 어떤 포맷·샘플레이트든 됩니다(내부에서 16kHz 모노로 변환). 또는 16kHz float32 numpy 배열. 10초보다 길면 텍스트상 '아니' 위치를 추정해 그 주변 10초만 씁니다.

모델 구조

텍스트 ─► RoBERTa/ELECTRA ─► [CLS] ⊕ '아니' 토큰 평균 ─► Linear+LayerNorm 512 ─┐
                                                                            ├─ concat ─► Dropout ─► Linear 512 ─► GELU ─► Dropout ─► Linear 7
음성  ─► WavLM ─► 13개 층 가중합 ─► attention pooling ─► Linear+LayerNorm 512 ─┘

문장 전체가 아니라 '아니' 토큰 위치의 표현을 따로 뽑아 [CLS]에 이어 붙이는 것이 핵심입니다. 음성 쪽은 마지막 층만 쓰지 않고 13개 층을 학습 가중치로 합친 뒤, 프레임별 attention 으로 풀링합니다.

학습 방법

항목	값
분할	층화 5-fold 교차검증 (1,846) + 고정 테스트셋 (206)
최적화	AdamW, cosine + warmup 10%, 층별 학습률 감쇠 0.9
학습률	텍스트 2e-5 / 음성 5e-5 / 헤드 5e-4 (인코더는 맨 위층 기준)
유효 배치	16 (2 × 누적 8), bf16 혼합정밀도
정규화	R-Drop α=1, manifold mixup α=0.2, modality dropout 0.15, label smoothing 0.05, weight decay 0.05
기타	가중치 EMA 0.99, 클래스 가중(sqrt), macro-F1 기준 best 선택, patience 6
오디오	16kHz 모노, '아니' 추정 위치 중심 10초 창, 게인·노이즈·창 위치 증강
시간	RTX 5060 Ti 16GB 에서 10개 모델 약 4.9시간

데이터

• 한국어 댓글·발화 2,052건. 국어 언어학 전공 연구자가 '아니'의 화용 기능을 직접 분류했습니다.
• 각 문장을 한 명의 화자가 낭독해 녹음했습니다(평균 10.5초).
• 클래스 분포가 불균형합니다: 부정/반박 655, 놀람/감탄 392, 화제 시작/전환 298, 즉각 수정 245, 방어/합리화 236, 부연/상세화 117, 강조/강한 긍정 109.
• 음성 원본과 텍스트 원본은 이 저장소에 포함되어 있지 않습니다. 모델 가중치만 공개합니다.

한계

• 화자 일반화 미검증: 음성이 한 사람의 낭독이라 다른 목소리·실제 대화에서는 성능이 떨어질 수 있습니다. 이 데이터로는 측정 자체가 불가능합니다.
• 낭독체: 자연 발화가 아니라 텍스트를 보고 읽은 음성이므로, 실제 대화의 운율과 다를 수 있습니다.
• 소수 클래스 약세: 부연/상세화(F1 0.235), 강조/강한 긍정(0.435)은 학습 표본이 각각 117건, 109건으로 적습니다.
• 인접 기능 혼동: 놀람/감탄 ↔ 부정/반박 사이 혼동이 가장 많습니다. 사람도 판단이 갈리는 경계가 있습니다.
• 원 데이터가 온라인 댓글이라 공격적·비속한 표현이 포함되어 있고, 모델은 그 분포를 학습했습니다.
• 연구용 모델입니다. 상업적 이용이나 사람에 대한 판단 근거로 쓰지 마십시오.

인용

@misc{ani_discourse_marker_2026,
  title  = {담화 표지어 '아니' 멀티모달 분류기},
  author = {<저자 이름>},
  year   = {2026},
  howpublished = {\url{https://huggingface.co/<사용자명>/<모델저장소이름>}}
}