TheStageAI/TheWhisper

📚 빠른 개요

TheWhisper는 OpenAI의 Whisper 모델을 기반으로 구축된 오픈소스 음성-텍스트 변환 시스템입니다. 이 프로젝트는 다음을 제공합니다:

원래의 고정된 30초 윈도우 대신 짧은 오디오 청크(10~30초)를 받아들이는 파인튜닝된 Whisper 체크포인트.
두 가지 주요 하드웨어 제품군을 위한 고성능 추론 엔진:
- NVIDIA GPU(RTX 4090, L40s, H100, A100, Jetson-Thor): 맞춤형 TheStage AI "ElasticModels" 엔진을 통해, 그리고 표준 Hugging Face Transformers를 통해서도.
- Apple Silicon / macOS: CoreML(및 MLX) 엔진을 통해 약 2 W 전력과 약 2 GB RAM으로 실행.
마이크나 파일에서 오디오를 지속적으로 입력하고 단어 수준 타임스탬프를 받을 수 있는 스트리밍 API.
간단한 Python 래퍼(ASRPipeline, StreamingPipeline)와 JavaScript/Electron으로 작성된 예제 프런트엔드.
실시간 전사를 시연하는 macOS용 사전 빌드 데스크톱 앱 TheNotes.
바닐라 Whisper와 비교한 벤치마크(지연, 메모리, 전력, WER)가 benchmark/ 폴더에 게시됨.

이 저장소는 온프레미스, 클라우드 또는 온디바이스에서 저지연, 저전력 ASR 서비스를 자체 호스팅하려는 개발자를 대상으로 합니다.

🛠️ 핵심 구성 요소

구성 요소	기능	핵심 기술
모델 가중치	유연한 청크 크기를 가진 파인튜닝된 Whisper-large-v3(및 "turbo" 변형).	Hugging Face 🤗 hub
추론 엔진	NVIDIA(TensorRT 기반 ElasticModels) 및 Apple Silicon(CoreML/MLX)용 최적화 런타임.	TheStage AI, NVIDIA, Apple
Python API	단일 파일 전사용 `ASRPipeline`; 연속 오디오용 `StreamingPipeline`.	PyTorch, Torch-Audio, 맞춤형 래퍼
스트리밍 유틸리티	오디오 청크를 입력하고 결과를 출력하는 `MicStream`, `FileStream`, `StdoutStream`.	순수 Python
프런트엔드 데모	라이브 자막을 보여주는 Electron 앱과 React 예제.	Electron, ReactJS

🚀 시작하기(일반적인 흐름)

설치 – 하드웨어 대상 선택:

# Apple Silicon
pip install .[apple]

# NVIDIA GPU
pip install .[nvidia]
# (optional) TheStage AI optimized engine
pip install 'thestage-elastic-models[nvidia]==0.2.4.post0' ...

구성 – TheStage AI 엔진의 경우 TheStage AI 플랫폼에서 API 토큰을 받아 실행:
```
thestage config set -t <YOUR_API_TOKEN>
```

빠른 전사 실행(단일 파일):

from thestage_speechkit.nvidia import ASRPipeline
model = ASRPipeline(model='TheStageAI/thewhisper-large-v3-turbo',
                    chunk_length_s=10, device='cuda')
result = model('speech.wav')
print(result['text'])

스트리밍 예제 – 마이크 오디오를 캡처하고 라이브 자막을 출력:

from thestage_speechkit.streaming import StreamingPipeline, MicStream, StdoutStream
pipe = StreamingPipeline(model='TheStageAI/thewhisper-large-v3-turbo',
                         chunk_length_s=10, platform='apple')
mic = MicStream(step_size_s=0.5)
out = StdoutStream()
while (chunk := mic.next_chunk()) is not None:
    txt, _ = pipe(chunk)
    out.write(txt, None)

데스크톱 앱 – 사전 빌드된 macOS TheNotes 패키지를 다운로드하거나 React/Electron 튜토리얼을 따라 직접 빌드.

📊 성능 하이라이트

NVIDIA L40s: whisper-large-v3 모델에서 약 220 tokens/초(10초 청크에서 약 0.5초 지연).
Apple Silicon: 약 2 W 전력 소비, 약 2 GB RAM, M2/M3 칩에서 실시간 스트리밍.
정확도: Open ASR 다국어 리더보드에서 평가; WER은 바닐라 Whisper와 비슷하면서 더 낮은 지연을 제공.
다양한 청크 크기(10초, 15초, 20초, 30초)에 대한 벤치마크는 benchmark/README.md에 있습니다.

📦 저장소 내용

thestage_speechkit/ – Apple 및 NVIDIA 파이프라인, VAD, 스트리밍 헬퍼가 포함된 Python 패키지.
electron_app/ – Electron 프런트엔드 소스와 빌드 지침.
benchmark/ – 지연, 메모리, 전력, WER을 요약한 스크립트와 표.
README.md – 이 문서, 빠른 시작, 사용 예제.
Hugging Face의 thewhisper-large-v3 및 thewhisper-large-v3-turbo 모델 카드.

🛡️ 라이선스 및 상업적 사용

코드는 MIT License로 배포됩니다(LICENSE 참조).
모델 가중치는 Hugging Face에서 오픈소스입니다.
TheStage AI 최적화 엔진을 연간 4개 GPU 이상 필요로 하는 기업은 TheStage AI 연락 페이지를 통해 상업적 라이선스를 요청할 수 있습니다.

🎯 누가 사용해야 하는가

실시간 자막, 음성 비서, 회의 전사 서비스를 구축하는 개발자.
Jetson 장치나 Apple Silicon 노트북에 ASR을 배포하는 엣지/IoT 팀.
예측 가능한 지연과 비용으로 클라우드 STT API에 대한 자체 호스팅 대안을 원하는 기업.

📚 추가 자료 및 리소스

모델 허브: https://huggingface.co/TheStageAI/thewhisper-large-v3-turbo/
TheStage AI ElasticModels 문서: https://docs.thestage.ai/elastic_models/docs/source/index.html
튜토리얼(macOS 노트 앱): https://app.thestage.ai/blog/Building-a-macOS-Note-Taker-app-on-Electron-with-TheWhisper?id=6
Open ASR 리더보드: https://github.com/huggingface/open_asr_leaderboard

TheWhisper는 연구 등급 Whisper 모델과 실제 하드웨어 성능 제약 사이의 간극을 메우는 실용적이고 프로덕션 준비된 음성-텍스트 스택입니다.