Update README.md repository tree

030e472 verified 3 days ago

13.8 kB

---
language:
- ko
license: apache-2.0
tags:
- audio
- speech-recognition
- automatic-speech-recognition
- apple-silicon
- on-device
- korean
- embeddinggemma-2
- notesoop
pipeline_tag: automatic-speech-recognition
metrics:
- cer
- wer
library_name: pytorch
---
# Notesoop-STT-Ko-v1

<p align="center">
  <img src="https://img.shields.io/badge/Language-Korean%20(한국어)-blue" alt="Language" />
  <img src="https://img.shields.io/badge/Speedup-39.9x%20Real--time-green" alt="Speedup" />
  <img src="https://img.shields.io/badge/Audio%20Encoder-EmbeddingGemma--2-orange" alt="Audio Encoder" />
  <img src="https://img.shields.io/badge/VRAM-1.2GB%20~%201.5GB-purple" alt="VRAM" />
  <img src="https://img.shields.io/badge/Platform-Apple%20Silicon%20(PyTorch%20MPS)-black" alt="Platform" />
  <img src="https://img.shields.io/badge/License-Apache%202.0-lightgrey" alt="License" />
</p>

<p align="center">
  <a href="https://apps.apple.com/kr/app/notesoop/id6760303593" target="_blank"><img src="https://img.shields.io/badge/App_Store-%EB%85%B8%ED%8A%B8%EC%88%B2_%EB%8B%A4%EC%9A%B4%EB%A1%9C%EB%93%9C-0D96F6?style=for-the-badge&logo=apple&logoColor=white" alt="Download on the App Store" /></a>&nbsp;&nbsp;<a href="https://play.google.com/store/apps/details?id=com.phsoft.notesoop&utm_source=ig&utm_medium=social&utm_content=link_in_bio&fbclid=PAdGRleAS711NwZG9mAmV4dG4DYWVtAjExAHNydGMGYXBwX2lkDzEyNDAyNDU3NDI4NzQxNAABpxFu1PSQrzp-9WgAihbuFrY4gre7MP6MH5Xx4lfKa9FjndnyVoMXb8awipoa_aem_5ccpc4qbd5STxaPUlQif3g" target="_blank"><img src="https://img.shields.io/badge/Google_Play-%EB%85%B8%ED%8A%B8%EC%88%B2_%EB%8B%A4%EC%9A%B4%EB%A1%9C%EB%93%9C-01875F?style=for-the-badge&logo=googleplay&logoColor=white" alt="Get it on Google Play" /></a>
</p>

**Notesoop-STT-Ko-v1**은 노트숲(Notesoop)에서 개발한 Apple Silicon(PyTorch MPS) 가속 한국어 온디바이스 음성인식(ASR) 모델입니다.

Google의 `EmbeddingGemma-2` 오디오 인코더를 기반으로 온디바이스 환경에 최적화된 경량 음향 리더와 언어 디코더를 결합하여 설계되었습니다. 약 1.2~1.5GB 수준의 낮은 메모리 점유율로 **실시간 대비 약 40배속(`RTF 0.0251`, 41분 분량 음성을 약 63초에 처리)**의 빠른 온디바이스 추론 성능을 제공합니다.

> 본 모델(Notesoop-STT-Ko-v1)은 올해 안에 노트숲(Notesoop) 앱에서도 만나보실 수 있습니다.

---

## Background & Design Goals

노트숲은 **"학습의 비효율을 줄여, 사용자가 도구가 아닌 배움에 집중할 수 있는 경험을 만든다"**는 미션 아래 흩어진 학습 도구와 AI를 자연스럽게 연결하는 기술을 연구하고 있습니다.

실제 학습 환경에서는 수십 분에서 수 시간 분량의 강의 및 학습 음성을 다루게 됩니다. 이때 네트워크 상태에 의존하거나 긴 변환 시간을 기다려야 하고, 무거운 모델 때문에 기기 리소스가 잠식되어 정작 PDF 열람이나 필기 같은 본연의 학습 활동이 방해받는 것은 큰 비효율입니다. **Notesoop-STT-Ko-v1**은 기술적 복잡함은 모델 내부로 숨기고 사용자에게는 끊김 없는 학습 환경을 제공하기 위해 다음 세 가지 목표를 중심으로 설계되었습니다.

* **실질적인 학습 효율 (Practicality & Speed):** 긴 녹음 파일도 대기 시간 없이 즉시 복습과 정리에 활용할 수 있도록, 비자기회귀(Non-Autoregressive) 단일 패스 구조와 고속 병렬 처리 파이프라인을 적용했습니다.
* **모바일 및 온디바이스 최적화 (Simplicity & Accessibility):** 별도의 서버나 고사양 장비 없이 태블릿·스마트폰 등 제한된 연산 자원을 가진 모바일 디바이스에서도 충분한 추론 속도를 제공할 수 있도록, 음향 리더 모델을 온디바이스에 맞게 초경량화하고 메모리 점유율을 최소화했습니다.
* **열린 기술 실험 (Open Ecosystem):** 누구나 온디바이스 환경에서 한국어 음성인식 기술을 부담 없이 실험하고 더 나은 학습 경험을 만드는 데 활용할 수 있도록, 모델 가중치와 PyTorch MPS 고속 추론 파이프라인 전체를 Apache-2.0 라이선스로 공개합니다.

---

## Model Specifications

| 항목 | 상세 사양 |
| :--- | :--- |
| **Audio Encoder** | `google/embeddinggemma-2` (Audio Tower, 16kHz Mono, 128-Mel) |
| **Acoustic Decoder** | Lightweight Korean Acoustic Reader |
| **Vocabulary** | 25,000 한국어 형태소 및 음절 어휘집 |
| **Language Rescoring** | KenLM 3-Gram 한국어 언어 모델 |
| **Supported Backends** | PyTorch MPS (`bfloat16`), CUDA / CPU |
| **Training Data** | AI Hub 한국어 강의 음성 데이터 (약 300GB) |
| **License** | Apache-2.0 |

---

## Overview

Notesoop-STT-Ko-v1은 Google의 `embeddinggemma-2` 오디오 인코더가 추출한 고밀도 음향 표현을 바탕으로, 온디바이스 환경에서 지연 없이 빠르게 동작할 수 있도록 최적화된 경량 음향 리더를 통해 한국어 음성을 텍스트로 고속 복원합니다.

* **Google EmbeddingGemma-2 오디오 인코더 기반:** 사전 학습된 대규모 멀티모달 오디오 인코더의 풍부한 음향 특징을 활용하여 배경 소음과 다양한 음질 조건에서도 견고한 음향 표현을 포착합니다.
* **초경량 온디바이스 리더:** 메모리 대역폭이 제한된 모바일 및 랩톱 디바이스에서도 부담 없이 구동될 수 있도록 파라미터 크기와 메모리 사용량을 최소화했습니다.
* **Apple Silicon MPS 고속 가속:** PyTorch MPS 환경에서 불필요한 형변환 오버헤드를 줄인 `bfloat16` 텐서 연산을 통해 실시간 대비 약 40배속의 빠른 추론 성능을 제공합니다.
* **GPU-CPU 비동기 파이프라이닝:** GPU가 오디오 청크를 처리하는 동안 CPU 스레드에서 언어 모델 빔 서치와 텍스트 중복 제거를 병렬로 수행하여 체감 지연 시간을 극대화했습니다.

---

## Data

**Notesoop-STT-Ko-v1**은 실제 학습 및 교육 현장의 음향·언어적 특성을 반영하기 위해 **AI Hub의 약 300GB 분량 한국어 강의 음성 데이터**로 학습되었습니다.

* **실전 강의 도메인 특화:** 약 300GB 규모의 방대한 실제 강의 음성을 학습에 활용하여, 정제된 낭독체뿐만 아니라 강의 현장의 발화 속도 변화, 설명조 어투, 학술·전공 용어, 장시간 연속 발화 환경에서도 안정적인 인식 성능을 제공합니다.
* **형태소·음절 하이브리드 토크나이징:** 한국어 교착어 특성에 맞춰 자주 쓰이는 표면 형태소(Surface Morpheme)와 음절 단위 Fallback을 결합한 25,000개 어휘 사전을 구축하여 미등록 어휘(OOV) 손실을 최소화했습니다.

---

## Benchmark

`Notesoop-STT-Ko-v1`의 성능을 **(1) 공인 표준 한국어 학술 벤치마크**와 **(2) 실제 대학 전공 강의 롱폼 음성** 두 가지 환경에서 실측한 결과입니다. (Apple M1 Pro 16GB 기준)

### 1. 표준 한국어 STT 벤치마크 (Zeroth-Korean Test Set, 457개 문장)
한국어 음성인식 학술 평가의 공식 표준 데이터셋인 `Bingsu/zeroth-korean` 테스트 분할(총 457개 발화 문장, 1시간 11분 27초 분량)에 대한 전수 평가 결과입니다.

| 데이터셋 | 총 오디오 길이 | 전체 전사 시간 ⏱️ | 체감 속도 ⚡ | RTF | 초당 처리량 (Throughput) | 음절 오차율 (CER) 🎯 | 단어 오차율 (WER) |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| **Zeroth-Korean Test (457문장)** | **1시간 11분 (4,287초)** | **2분 30초 (150.7초)** | **28.45배속** | **0.0352** | **3.03 문장/초** | **16.21%** | 45.40% |

* **초당 3문장 이상의 초고속 전사**: 1시간 11분 분량의 방대한 오디오를 단 2분 30초 만에 완주하며, 낭독체 음성 환경에서 **16.21%의 준수한 음절 오차율(CER)**을 달성합니다.
* **실제 전사 샘플 예시**:
  * **정답 (REF)**: *"한 잔의 커피가 소비자에게 전해지기 위해선 여러 차례의 공정을 거쳐야 한다"*
  * **예측 (HYP)**: *"한 잔의 커피가 소비자에게 전해지기 위해선 여러 차례의 공정을 거쳐야 한다"* (CER: **0.00%**)
  * **정답 (REF)**: *"또한 박 전 대통령 측은 앞으로 검찰 수사와 관련해 수사 내용에 대한 입장뿐 아니라 변호인단의 활동 상황 등도 소상하게 공개한다는 방침이다"*
  * **예측 (HYP)**: *"또한 박 전 대통령 주변에 앞으로 검찰수사와 관련된 수사 내용에 대한 입장뿐 아니라 변호인단의 활동 상황 등도 소상하게 공개한다는 방식이다"* (CER: **10.39%**)

---

### 2. 실전 전공 강의 녹음 (41분 43초, Field Test)
대학 강의 환경(배경 잡음, 반향, 말더듬 등이 포함된 실제 41분 43초 녹음 음성)을 **Apple M1 Pro (16GB RAM)** 모델에서 직접 구동하며 글로벌 표준 ASR 모델들과 비교 측정한 실측 결과입니다.

| Model | Backend / Device | Processing Time | Speedup | RTF | CER (%) 🎯 | WER (%) | Host RAM | GPU Memory (VRAM) 🖥️ |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| **Notesoop-STT-Ko-v1** | **PyTorch MPS (`bf16`)** | **1분 2초 (62.7s)** | **39.9x** | **0.0251** | **22.46** | 39.25 | **1,076 MB** | 1,537 MB |
| Whisper-medium | MPS | 4분 11초 (251.5s) | 10.0x | 0.1005 | 26.68 | 45.82 | 1,050 MB | 3,467 MB |
| Whisper-large-v3 | MPS | 11분 45초 (704.9s) | 3.6x | 0.2816 | 25.55 | 42.10 | 1,243 MB | 6,325 MB |

* **`Whisper-large-v3` 대비 11.2배 고속 & 더 우수한 정확도:** Whisper-large-v3(11분 45초, CER 25.55%) 대비 **약 11.2배 빠른 속도(1분 2초)**와 **더 낮은 음절 오차율(CER 22.46%, 3.09%p 향상)**을 동시에 제공합니다.
* **1/4 수준의 경량 VRAM (1.2~1.5GB):** Whisper-large-v3(6.3GB)의 1/4도 안 되는 가벼운 메모리 점유율 덕분에, 기본형 맥북 에어/프로(8GB/16GB)에서도 발열과 팬 소음 없이 다른 학습 앱과 동시에 쾌적하게 구동됩니다.
* **비자기회귀(Non-Autoregressive) 구조의 강점:** 문장을 한 토큰씩 순차 생성하는 Whisper와 달리, 비자기회귀 구조로 오디오 전체 음향 특징을 단일 패스($O(T)$)로 병렬 처리하여 장시간 음성에서도 처리 속도가 기하급수적으로 빨라집니다.

---

## Quickstart

### 1. Installation

macOS (Apple Silicon M1 이상 권장) 및 Python 3.10+ 환경을 권장합니다. 오디오 디코딩을 위해 시스템에 `ffmpeg`가 설치되어 있어야 합니다(`brew install ffmpeg`).

```bash
git clone https://huggingface.co/Phsoft-ai/Notesoop-STT-Ko-v1
cd Notesoop-STT-Ko-v1
# 의존성 패키지 설치
pip install -r requirements.txt
# KenLM 3-Gram 디코더 설치
pip install https://github.com/kpu/kenlm/archive/master.zip
```

### 2. CLI Usage

`transcribe.py`를 통해 단일 명령어로 오디오 파일을 전사할 수 있습니다. (`.wav`, `.m4a`, `.mp3`, `.flac` 지원)

```bash
# 기본 실행 (PyTorch MPS 백엔드, batch_size=4)
python transcribe.py sample_audio.wav
# 장시간 강의 오디오 전사 및 결과 파일 저장
python transcribe.py my_lecture.m4a --batch-size 4 --chunk-sec 16.0 --output transcript.txt
# KenLM 빔 서치 비활성화 (Greedy CTC 디코딩)
python transcribe.py sample_audio.wav --no-kenlm
```

### 3. Python API

```python
from run_inference import EmbeddingGemmaSTT
stt = EmbeddingGemmaSTT(
    device="mps",
    use_kenlm=True,
    lm_alpha=0.12,
    lm_beta=0.40,
)
transcript, rtf = stt.transcribe(
    "sample_audio.wav",
    chunk_sec=16.0,
    overlap_sec=1.0,
    batch_size=4,
)
print(f"RTF: {rtf:.4f} ({1/rtf:.1f}x real-time)")
print(transcript)
```

---

## Repository Structure

```text
Notesoop-STT-Ko-v1/
├── README.md                        # Model Card 및 사용 안내
├── checkpoints/
│   └── best_reader_inference.pt     # 음향 리더 모델 가중치 (137MB)
├── data/
│   └── vocab/
│       ├── vocab_25k.json           # 25,000 한국어 형태소/음절 어휘 사전
│       ├── vector_bank_25k.pt       # 어휘 매칭 벡터 뱅크
│       └── korean_lm.bin            # KenLM 3-Gram 한국어 언어 모델 (82.7MB)
├── src/
│   ├── model.py                     # 음향 리더 모델 구현
│   ├── dataset.py                   # 한국어 형태소 토크나이저 및 정규화
│   ├── decoder.py                   # KenLM 빔 서치 디코더 래퍼
│   └── step2_extract_features.py    # EmbeddingGemma-2 오디오 특징 추출기
├── run_inference.py                 # 추론 파이프라인 및 Python API
├── transcribe.py                    # CLI 실행 스크립트
└── sample_audio.wav                 # 테스트용 샘플 오디오
```

---

## License & Citation

본 모델과 코드는 **[Apache License 2.0](LICENSE)** 하에 공개되어 연구 및 상업적 용도로 자유롭게 활용할 수 있습니다.

```bibtex
@misc{notesoop2026sttkov1,
  author = {Notesoop AI Team},
  title = {Notesoop-STT-Ko-v1: Lightweight Korean On-Device Speech Recognition},
  year = {2026},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/Phsoft-ai/Notesoop-STT-Ko-v1}},
  note = {Apple Silicon MPS Accelerated Korean ASR}
}
```

---

<p align="center">
  <b>Notesoop (노트숲)</b> — 학습의 비효율을 줄여, 도구가 아닌 배움에 집중할 수 있는 경험을 만듭니다.<br>
  음성 기록과 PDF 필기 연동, 핵심 정리, 복습 문제 생성까지 하나로 연결된 학습 환경을 노트숲 앱에서 만나보세요.
</p>

	---
	language:
	- ko
	license: apache-2.0
	tags:
	- audio
	- speech-recognition
	- automatic-speech-recognition
	- apple-silicon
	- on-device
	- korean
	- embeddinggemma-2
	- notesoop
	pipeline_tag: automatic-speech-recognition
	metrics:
	- cer
	- wer
	library_name: pytorch
	---

	# Notesoop-STT-Ko-v1

	<p align="center">
	<img src="https://img.shields.io/badge/Language-Korean%20(한국어)-blue" alt="Language" />
	<img src="https://img.shields.io/badge/Speedup-39.9x%20Real--time-green" alt="Speedup" />
	<img src="https://img.shields.io/badge/Audio%20Encoder-EmbeddingGemma--2-orange" alt="Audio Encoder" />
	<img src="https://img.shields.io/badge/VRAM-1.2GB%20~%201.5GB-purple" alt="VRAM" />
	<img src="https://img.shields.io/badge/Platform-Apple%20Silicon%20(PyTorch%20MPS)-black" alt="Platform" />
	<img src="https://img.shields.io/badge/License-Apache%202.0-lightgrey" alt="License" />
	</p>

	<p align="center">
	<a href="https://apps.apple.com/kr/app/notesoop/id6760303593" target="_blank"><img src="https://img.shields.io/badge/App_Store-%EB%85%B8%ED%8A%B8%EC%88%B2_%EB%8B%A4%EC%9A%B4%EB%A1%9C%EB%93%9C-0D96F6?style=for-the-badge&logo=apple&logoColor=white" alt="Download on the App Store" /></a>  <a href="https://play.google.com/store/apps/details?id=com.phsoft.notesoop&utm_source=ig&utm_medium=social&utm_content=link_in_bio&fbclid=PAdGRleAS711NwZG9mAmV4dG4DYWVtAjExAHNydGMGYXBwX2lkDzEyNDAyNDU3NDI4NzQxNAABpxFu1PSQrzp-9WgAihbuFrY4gre7MP6MH5Xx4lfKa9FjndnyVoMXb8awipoa_aem_5ccpc4qbd5STxaPUlQif3g" target="_blank"><img src="https://img.shields.io/badge/Google_Play-%EB%85%B8%ED%8A%B8%EC%88%B2_%EB%8B%A4%EC%9A%B4%EB%A1%9C%EB%93%9C-01875F?style=for-the-badge&logo=googleplay&logoColor=white" alt="Get it on Google Play" /></a>
	</p>

	Notesoop-STT-Ko-v1은 노트숲(Notesoop)에서 개발한 Apple Silicon(PyTorch MPS) 가속 한국어 온디바이스 음성인식(ASR) 모델입니다.

	Google의 `EmbeddingGemma-2` 오디오 인코더를 기반으로 온디바이스 환경에 최적화된 경량 음향 리더와 언어 디코더를 결합하여 설계되었습니다. 약 1.2~1.5GB 수준의 낮은 메모리 점유율로 실시간 대비 약 40배속(`RTF 0.0251`, 41분 분량 음성을 약 63초에 처리)의 빠른 온디바이스 추론 성능을 제공합니다.

	> 본 모델(Notesoop-STT-Ko-v1)은 올해 안에 노트숲(Notesoop) 앱에서도 만나보실 수 있습니다.

	---

	## Background & Design Goals

	노트숲은 "학습의 비효율을 줄여, 사용자가 도구가 아닌 배움에 집중할 수 있는 경험을 만든다"는 미션 아래 흩어진 학습 도구와 AI를 자연스럽게 연결하는 기술을 연구하고 있습니다.

	실제 학습 환경에서는 수십 분에서 수 시간 분량의 강의 및 학습 음성을 다루게 됩니다. 이때 네트워크 상태에 의존하거나 긴 변환 시간을 기다려야 하고, 무거운 모델 때문에 기기 리소스가 잠식되어 정작 PDF 열람이나 필기 같은 본연의 학습 활동이 방해받는 것은 큰 비효율입니다. Notesoop-STT-Ko-v1은 기술적 복잡함은 모델 내부로 숨기고 사용자에게는 끊김 없는 학습 환경을 제공하기 위해 다음 세 가지 목표를 중심으로 설계되었습니다.

	* 실질적인 학습 효율 (Practicality & Speed): 긴 녹음 파일도 대기 시간 없이 즉시 복습과 정리에 활용할 수 있도록, 비자기회귀(Non-Autoregressive) 단일 패스 구조와 고속 병렬 처리 파이프라인을 적용했습니다.
	* 모바일 및 온디바이스 최적화 (Simplicity & Accessibility): 별도의 서버나 고사양 장비 없이 태블릿·스마트폰 등 제한된 연산 자원을 가진 모바일 디바이스에서도 충분한 추론 속도를 제공할 수 있도록, 음향 리더 모델을 온디바이스에 맞게 초경량화하고 메모리 점유율을 최소화했습니다.
	* 열린 기술 실험 (Open Ecosystem): 누구나 온디바이스 환경에서 한국어 음성인식 기술을 부담 없이 실험하고 더 나은 학습 경험을 만드는 데 활용할 수 있도록, 모델 가중치와 PyTorch MPS 고속 추론 파이프라인 전체를 Apache-2.0 라이선스로 공개합니다.

	---

	## Model Specifications

	\| 항목 \| 상세 사양 \|
	\| :--- \| :--- \|
	\| Audio Encoder \| `google/embeddinggemma-2` (Audio Tower, 16kHz Mono, 128-Mel) \|
	\| Acoustic Decoder \| Lightweight Korean Acoustic Reader \|
	\| Vocabulary \| 25,000 한국어 형태소 및 음절 어휘집 \|
	\| Language Rescoring \| KenLM 3-Gram 한국어 언어 모델 \|
	\| Supported Backends \| PyTorch MPS (`bfloat16`), CUDA / CPU \|
	\| Training Data \| AI Hub 한국어 강의 음성 데이터 (약 300GB) \|
	\| License \| Apache-2.0 \|

	---

	## Overview

	Notesoop-STT-Ko-v1은 Google의 `embeddinggemma-2` 오디오 인코더가 추출한 고밀도 음향 표현을 바탕으로, 온디바이스 환경에서 지연 없이 빠르게 동작할 수 있도록 최적화된 경량 음향 리더를 통해 한국어 음성을 텍스트로 고속 복원합니다.

	* Google EmbeddingGemma-2 오디오 인코더 기반: 사전 학습된 대규모 멀티모달 오디오 인코더의 풍부한 음향 특징을 활용하여 배경 소음과 다양한 음질 조건에서도 견고한 음향 표현을 포착합니다.
	* 초경량 온디바이스 리더: 메모리 대역폭이 제한된 모바일 및 랩톱 디바이스에서도 부담 없이 구동될 수 있도록 파라미터 크기와 메모리 사용량을 최소화했습니다.
	* Apple Silicon MPS 고속 가속: PyTorch MPS 환경에서 불필요한 형변환 오버헤드를 줄인 `bfloat16` 텐서 연산을 통해 실시간 대비 약 40배속의 빠른 추론 성능을 제공합니다.
	* GPU-CPU 비동기 파이프라이닝: GPU가 오디오 청크를 처리하는 동안 CPU 스레드에서 언어 모델 빔 서치와 텍스트 중복 제거를 병렬로 수행하여 체감 지연 시간을 극대화했습니다.

	---

	## Data

	Notesoop-STT-Ko-v1은 실제 학습 및 교육 현장의 음향·언어적 특성을 반영하기 위해 AI Hub의 약 300GB 분량 한국어 강의 음성 데이터로 학습되었습니다.

	* 실전 강의 도메인 특화: 약 300GB 규모의 방대한 실제 강의 음성을 학습에 활용하여, 정제된 낭독체뿐만 아니라 강의 현장의 발화 속도 변화, 설명조 어투, 학술·전공 용어, 장시간 연속 발화 환경에서도 안정적인 인식 성능을 제공합니다.
	* 형태소·음절 하이브리드 토크나이징: 한국어 교착어 특성에 맞춰 자주 쓰이는 표면 형태소(Surface Morpheme)와 음절 단위 Fallback을 결합한 25,000개 어휘 사전을 구축하여 미등록 어휘(OOV) 손실을 최소화했습니다.

	---

	## Benchmark

	`Notesoop-STT-Ko-v1`의 성능을 (1) 공인 표준 한국어 학술 벤치마크와 (2) 실제 대학 전공 강의 롱폼 음성 두 가지 환경에서 실측한 결과입니다. (Apple M1 Pro 16GB 기준)

	### 1. 표준 한국어 STT 벤치마크 (Zeroth-Korean Test Set, 457개 문장)
	한국어 음성인식 학술 평가의 공식 표준 데이터셋인 `Bingsu/zeroth-korean` 테스트 분할(총 457개 발화 문장, 1시간 11분 27초 분량)에 대한 전수 평가 결과입니다.

	\| 데이터셋 \| 총 오디오 길이 \| 전체 전사 시간 ⏱️ \| 체감 속도 ⚡ \| RTF \| 초당 처리량 (Throughput) \| 음절 오차율 (CER) 🎯 \| 단어 오차율 (WER) \|
	\| :--- \| :---: \| :---: \| :---: \| :---: \| :---: \| :---: \| :---: \|
	\| Zeroth-Korean Test (457문장) \| 1시간 11분 (4,287초) \| 2분 30초 (150.7초) \| 28.45배속 \| 0.0352 \| 3.03 문장/초 \| 16.21% \| 45.40% \|

	* 초당 3문장 이상의 초고속 전사: 1시간 11분 분량의 방대한 오디오를 단 2분 30초 만에 완주하며, 낭독체 음성 환경에서 16.21%의 준수한 음절 오차율(CER)을 달성합니다.
	* 실제 전사 샘플 예시:
	* 정답 (REF): "한 잔의 커피가 소비자에게 전해지기 위해선 여러 차례의 공정을 거쳐야 한다"
	* 예측 (HYP): "한 잔의 커피가 소비자에게 전해지기 위해선 여러 차례의 공정을 거쳐야 한다" (CER: 0.00%)
	* 정답 (REF): "또한 박 전 대통령 측은 앞으로 검찰 수사와 관련해 수사 내용에 대한 입장뿐 아니라 변호인단의 활동 상황 등도 소상하게 공개한다는 방침이다"
	* 예측 (HYP): "또한 박 전 대통령 주변에 앞으로 검찰수사와 관련된 수사 내용에 대한 입장뿐 아니라 변호인단의 활동 상황 등도 소상하게 공개한다는 방식이다" (CER: 10.39%)

	---

	### 2. 실전 전공 강의 녹음 (41분 43초, Field Test)
	대학 강의 환경(배경 잡음, 반향, 말더듬 등이 포함된 실제 41분 43초 녹음 음성)을 Apple M1 Pro (16GB RAM) 모델에서 직접 구동하며 글로벌 표준 ASR 모델들과 비교 측정한 실측 결과입니다.

	\| Model \| Backend / Device \| Processing Time \| Speedup \| RTF \| CER (%) 🎯 \| WER (%) \| Host RAM \| GPU Memory (VRAM) 🖥️ \|
	\| :--- \| :---: \| :---: \| :---: \| :---: \| :---: \| :---: \| :---: \| :---: \|
	\| Notesoop-STT-Ko-v1 \| PyTorch MPS (`bf16`) \| 1분 2초 (62.7s) \| 39.9x \| 0.0251 \| 22.46 \| 39.25 \| 1,076 MB \| 1,537 MB \|
	\| Whisper-medium \| MPS \| 4분 11초 (251.5s) \| 10.0x \| 0.1005 \| 26.68 \| 45.82 \| 1,050 MB \| 3,467 MB \|
	\| Whisper-large-v3 \| MPS \| 11분 45초 (704.9s) \| 3.6x \| 0.2816 \| 25.55 \| 42.10 \| 1,243 MB \| 6,325 MB \|

	* `Whisper-large-v3` 대비 11.2배 고속 & 더 우수한 정확도: Whisper-large-v3(11분 45초, CER 25.55%) 대비 약 11.2배 빠른 속도(1분 2초)와 더 낮은 음절 오차율(CER 22.46%, 3.09%p 향상)을 동시에 제공합니다.
	* 1/4 수준의 경량 VRAM (1.2~1.5GB): Whisper-large-v3(6.3GB)의 1/4도 안 되는 가벼운 메모리 점유율 덕분에, 기본형 맥북 에어/프로(8GB/16GB)에서도 발열과 팬 소음 없이 다른 학습 앱과 동시에 쾌적하게 구동됩니다.
	* 비자기회귀(Non-Autoregressive) 구조의 강점: 문장을 한 토큰씩 순차 생성하는 Whisper와 달리, 비자기회귀 구조로 오디오 전체 음향 특징을 단일 패스($O(T)$)로 병렬 처리하여 장시간 음성에서도 처리 속도가 기하급수적으로 빨라집니다.

	---

	## Quickstart

	### 1. Installation

	macOS (Apple Silicon M1 이상 권장) 및 Python 3.10+ 환경을 권장합니다. 오디오 디코딩을 위해 시스템에 `ffmpeg`가 설치되어 있어야 합니다(`brew install ffmpeg`).

	```bash
	git clone https://huggingface.co/Phsoft-ai/Notesoop-STT-Ko-v1
	cd Notesoop-STT-Ko-v1

	# 의존성 패키지 설치
	pip install -r requirements.txt

	# KenLM 3-Gram 디코더 설치
	pip install https://github.com/kpu/kenlm/archive/master.zip
	```

	### 2. CLI Usage

	`transcribe.py`를 통해 단일 명령어로 오디오 파일을 전사할 수 있습니다. (`.wav`, `.m4a`, `.mp3`, `.flac` 지원)

	```bash
	# 기본 실행 (PyTorch MPS 백엔드, batch_size=4)
	python transcribe.py sample_audio.wav

	# 장시간 강의 오디오 전사 및 결과 파일 저장
	python transcribe.py my_lecture.m4a --batch-size 4 --chunk-sec 16.0 --output transcript.txt

	# KenLM 빔 서치 비활성화 (Greedy CTC 디코딩)
	python transcribe.py sample_audio.wav --no-kenlm
	```

	### 3. Python API

	```python
	from run_inference import EmbeddingGemmaSTT

	stt = EmbeddingGemmaSTT(
	device="mps",
	use_kenlm=True,
	lm_alpha=0.12,
	lm_beta=0.40,
	)

	transcript, rtf = stt.transcribe(
	"sample_audio.wav",
	chunk_sec=16.0,
	overlap_sec=1.0,
	batch_size=4,
	)

	print(f"RTF: {rtf:.4f} ({1/rtf:.1f}x real-time)")
	print(transcript)
	```

	---

	## Repository Structure

	```text
	Notesoop-STT-Ko-v1/
	├── README.md # Model Card 및 사용 안내
	├── checkpoints/
	│ └── best_reader_inference.pt # 음향 리더 모델 가중치 (137MB)
	├── data/
	│ └── vocab/
	│ ├── vocab_25k.json # 25,000 한국어 형태소/음절 어휘 사전
	│ ├── vector_bank_25k.pt # 어휘 매칭 벡터 뱅크
	│ └── korean_lm.bin # KenLM 3-Gram 한국어 언어 모델 (82.7MB)
	├── src/
	│ ├── model.py # 음향 리더 모델 구현
	│ ├── dataset.py # 한국어 형태소 토크나이저 및 정규화
	│ ├── decoder.py # KenLM 빔 서치 디코더 래퍼
	│ └── step2_extract_features.py # EmbeddingGemma-2 오디오 특징 추출기
	├── run_inference.py # 추론 파이프라인 및 Python API
	├── transcribe.py # CLI 실행 스크립트
	└── sample_audio.wav # 테스트용 샘플 오디오
	```

	---

	## License & Citation

	본 모델과 코드는 [Apache License 2.0](LICENSE) 하에 공개되어 연구 및 상업적 용도로 자유롭게 활용할 수 있습니다.

	```bibtex
	@misc{notesoop2026sttkov1,
	author = {Notesoop AI Team},
	title = {Notesoop-STT-Ko-v1: Lightweight Korean On-Device Speech Recognition},
	year = {2026},
	publisher = {Hugging Face},
	howpublished = {\url{https://huggingface.co/Phsoft-ai/Notesoop-STT-Ko-v1}},
	note = {Apple Silicon MPS Accelerated Korean ASR}
	}
	```

	---

	<p align="center">
	<b>Notesoop (노트숲)</b> — 학습의 비효율을 줄여, 도구가 아닌 배움에 집중할 수 있는 경험을 만듭니다.<br>
	음성 기록과 PDF 필기 연동, 핵심 정리, 복습 문제 생성까지 하나로 연결된 학습 환경을 노트숲 앱에서 만나보세요.
	</p>