AI 바이브 코딩 · 가이드 · 2026-05-07 · 조회 238

Whisper.cpp설치 가이드

강의 녹화용 실시간 자막 시스템에 Whisper를 도입하려는 사용자

# Whisper.cpp 강의용 설치 가이드

> **대상 독자**: 강의 녹화용 실시간 자막 시스템에 Whisper를 도입하려는 사용자
> **환경 전제**: Windows + Python 3.13 + venv
> **목표**: 본인 PC 사양에 맞는 Whisper 모델을 골라 설치하고 동작 확인까지

---

## 0. 빠른 결정 가이드

PC 사양에 따라 어느 모델을 쓸지 먼저 결정합니다.

```text
┌────────────────────────────────────────────────────────────────┐
│  GPU 없음 (CPU만)                                              │
│  ├─ 일반 노트북/구형 PC          → tiny 또는 base              │
│  ├─ 일반 데스크톱 (4코어 이상)   → base 또는 small             │
│  └─ 고성능 CPU (8코어 이상)      → small + chunk_ms 3000ms     │
│                                                                │
│  GPU 있음 (NVIDIA)                                             │
│  ├─ GTX 1060 / RTX 3050          → small 또는 medium           │
│  ├─ RTX 3060 / 4060              → medium 또는 large-v3-turbo  │
│  └─ RTX 3080+ / 4070+            → large-v3 또는 large-v3-turbo│
└────────────────────────────────────────────────────────────────┘
```

GPU 유무 확인:

```powershell
nvidia-smi
```

명령어가 동작하지 않으면 GPU 없음 = CPU 빌드.

---

## 1. 모델별 비교표

### 1.1 한 눈에 보기

| 모델 | 파일 | 용량 | 한국어 품질 | CPU 5초 처리 시간 (참고) | 메모리 |
|---|---|---:|---|---:|---:|
| tiny | `ggml-tiny.bin` | 75MB | ★☆☆☆☆ | ~2초 | ~400MB |
| base | `ggml-base.bin` | 142MB | ★★☆☆☆ | ~3.5초 | ~600MB |
| small | `ggml-small.bin` | 466MB | ★★★★☆ | **~10초** | ~1GB |
| medium | `ggml-medium.bin` | 1.5GB | ★★★★★ | ~30초 (CPU 비실용) | ~3GB |
| large-v3 | `ggml-large-v3.bin` | 3GB | ★★★★★ | CPU 불가 (GPU 전제) | ~5GB |
| large-v3-turbo | `ggml-large-v3-turbo.bin` | 1.5GB | ★★★★★ | GPU 전제 | ~3GB |

> 처리 시간은 일반 데스크톱 CPU 4스레드 기준 추정치. 환경에 따라 ±50% 차이 가능.
> 5초 오디오 처리 시간이 5초를 넘으면 실시간 처리 불가 (또는 chunk_ms 재조정 필요).

### 1.2 한국어 인식 품질 체감

같은 발화 *"오늘은 바이브 코딩으로 만든 프로그램을 소개해보겠습니다"* 기준 (참고용):

| 모델 | 인식 결과 예시 |
|---|---|
| tiny | 오늘은 바이브 코딩으로 만든 프로글램을 소개해 보겠습니다 |
| base | 오늘은 바이브 코딩으로 만든 프로그램을 소개해 보겠습니다 |
| small | 오늘은 바이브 코딩으로 만든 프로그램을 소개해보겠습니다. |
| medium 이상 | 오늘은 바이브 코딩으로 만든 프로그램을 소개해보겠습니다. |

> Vosk small 한국어 모델은 같은 발화에서 조사/받침이 자주 흔들립니다.
> Whisper `base` 이상이면 Vosk small보다 명확히 좋습니다.

### 1.3 영어 전용 모델 주의

Hugging Face에 `.en` 접미사 붙은 파일이 따로 있습니다.

```text
ggml-small.bin     ← 다국어 (한국어 OK)        ✅ 받기
ggml-small.en.bin  ← 영어 전용 (한국어 안 됨) ❌ 받지 말 것
```

한국어 강의용으로는 **반드시 `.en` 없는 버전**을 받아야 합니다.

---

## 2. 모델 추천

### 2.1 케이스별 추천

#### A. CPU만, 발표 녹화 용도 (지연 허용)
**추천: `small`** (chunk_ms = 3000ms 설정)
- 자막이 약 3초 늦게 따라오지만 인식 품질이 압도적
- 강의 후 편집 시 자막을 미세 조정하면 됨

#### B. CPU만, 실시간 화면 송출 (지연 최소화)
**추천: `base`** (chunk_ms = 1500ms 설정)
- 자막이 약 1.5초 지연으로 따라옴
- 인식 품질은 Vosk보다 명확히 좋고 small보다는 살짝 떨어짐

#### C. CPU만, 노트북에서 발열 걱정
**추천: `base`** + n_threads = 코어 수의 절반
- CPU 사용률을 50%로 제한해서 발열 억제
- 처리 시간은 길어지지만 chunk_ms를 늘려 보완

#### D. NVIDIA GPU 있음
**추천: `large-v3-turbo`**
- 정확도 최상, 처리 시간 매우 짧음
- GPU 빌드 환경 구축 필요 (§5 참고)

---

## 3. 공통 설치 절차

모든 모델에 공통으로 필요한 단계입니다.

### 3.1 가상환경 준비

```powershell
cd C:\Subtitle

# venv 폴더가 없을 때만 생성
python -m venv venv

# 활성화
.\venv\Scripts\Activate.ps1
```

활성화되면 프롬프트 앞에 `(venv)`가 붙습니다:

```text
(venv) PS C:\Subtitle>
```

> **PowerShell 실행 정책 에러가 뜨면**:
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```

### 3.2 pywhispercpp 설치 (CPU 버전)

```powershell
python -m pip install --upgrade pip
pip install pywhispercpp
```

설치 확인:

```powershell
python -c "from pywhispercpp.model import Model; print('OK')"
```

`OK`가 나오면 성공.

### 3.3 모델 폴더 준비

```powershell
mkdir C:\Subtitle\models -Force
cd C:\Subtitle\models
```

여기에 ggml 모델 파일을 받습니다.

---

## 4. 모델별 다운로드 명령어

각 모델 다운로드 명령어입니다. **모델 폴더(`C:\Subtitle\models`)에서 실행**하세요.

### 4.1 tiny (75MB)

```powershell
curl.exe -L -o "ggml-tiny.bin" "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin"
```

### 4.2 base (142MB)

```powershell
curl.exe -L -o "ggml-base.bin" "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin"
```

### 4.3 small (466MB)

```powershell
curl.exe -L -o "ggml-small.bin" "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"
```

### 4.4 medium (1.5GB)

```powershell
curl.exe -L -o "ggml-medium.bin" "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin"
```

### 4.5 large-v3 (3GB)

```powershell
curl.exe -L -o "ggml-large-v3.bin" "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin"
```

### 4.6 large-v3-turbo (1.5GB)

```powershell
curl.exe -L -o "ggml-large-v3-turbo.bin" "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin"
```

### 4.7 다운로드 확인

```powershell
ls *.bin
```

`Length` 컬럼의 바이트 크기가 표 §1.1과 일치해야 합니다.

> **다운로드가 너무 느리거나 멈출 때**: `Start-BitsTransfer` 사용
> ```powershell
> Start-BitsTransfer -Source "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin" -Destination "C:\Subtitle\models\ggml-small.bin"
> ```
> 또는 브라우저로 직접 받아서 폴더에 옮기기.

---

## 5. GPU 빌드 (선택, NVIDIA GPU가 있을 때만)

### 5.1 사전 요구사항

- NVIDIA GPU (CUDA 지원)
- CUDA Toolkit 11.8 이상 설치 (`nvcc --version`으로 확인)
- Visual Studio Build Tools (C++ 컴파일러)

CUDA 설치 확인:

```powershell
nvcc --version
```

버전 정보가 나오면 OK.

### 5.2 CUDA 빌드 설치

CPU 버전을 이미 설치했다면 먼저 제거:

```powershell
pip uninstall -y pywhispercpp
```

CUDA 옵션으로 재설치:

```powershell
$env:GGML_CUDA="1"
pip install --no-cache-dir --force-reinstall git+https://github.com/absadiki/pywhispercpp
```

빌드에 5~15분 걸립니다.

### 5.3 GPU 동작 확인

```powershell
python -c "from pywhispercpp.model import Model; m = Model(r'C:\Subtitle\models\ggml-small.bin'); print('GPU loaded')"
```

콘솔 로그에 `CUDA` 또는 `GPU` 관련 메시지가 보이면 성공.

---

## 6. 동작 확인 테스트

설치 후 모델이 실제로 한국어를 잘 인식하는지 확인합니다.

### 6.1 테스트 스크립트

`C:\Subtitle\test_whisper.py` 파일을 만들고 다음 내용 저장:

```python
"""Whisper.cpp 한국어 인식 동작 확인용 스크립트."""

import sys
import time
import numpy as np
import sounddevice as sd
from pywhispercpp.model import Model

# === 여기서 모델 경로만 바꾸면 다른 모델로 테스트 가능 ===
MODEL_PATH = r"C:\Subtitle\models\ggml-small.bin"
SAMPLE_RATE = 16000
DURATION_SEC = 5

def record_audio(duration_sec: int, sample_rate: int) -> np.ndarray:
    print(f"\n[녹음 시작] {duration_sec}초간 한국어로 말해주세요...")
    print("예: '오늘은 바이브 코딩으로 만든 프로그램을 소개해보겠습니다'")
    print()
    for i in range(3, 0, -1):
        print(f"  {i}...")
        time.sleep(1)
    print("  >>> 지금 말하세요 <<<")
    audio = sd.rec(
        int(duration_sec * sample_rate),
        samplerate=sample_rate,
        channels=1,
        dtype="float32",
    )
    sd.wait()
    print("[녹음 완료]\n")
    return audio.flatten()

def main():
    print("=" * 60)
    print("Whisper 한국어 인식 테스트")
    print("=" * 60)
    print(f"모델 경로: {MODEL_PATH}")
    print()

print("[모델 로딩 중...]")
    t0 = time.time()
    model = Model(
        MODEL_PATH,
        n_threads=4,
        language="ko",
        print_realtime=False,
        print_progress=False,
    )
    print(f"[모델 로드 완료] {time.time() - t0:.1f}초\n")

try:
        default_in = sd.query_devices(kind="input")
        print(f"[입력 장치] {default_in['name']}")
    except Exception as e:
        print(f"[경고] {e}")

audio = record_audio(DURATION_SEC, SAMPLE_RATE)

print("[인식 중...]")
    t0 = time.time()
    segments = model.transcribe(audio)
    elapsed = time.time() - t0

print()
    print("=" * 60)
    print("인식 결과")
    print("=" * 60)
    for i, seg in enumerate(segments):
        print(f"  [{i}] {seg.text}")
    print()
    print(f"처리 시간: {elapsed:.2f}초 (오디오 {DURATION_SEC}초)")
    print(f"실시간 배수: {DURATION_SEC / elapsed:.2f}x")
    print()
    if elapsed > DURATION_SEC:
        print("[주의] 처리 시간이 오디오 길이보다 깁니다.")
        print("       실시간 처리에는 더 작은 모델 또는 chunk_ms 증가 필요.")
    else:
        print("[OK] 실시간 처리 가능한 속도입니다.")

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\n[중단됨]")
        sys.exit(1)
    except Exception as e:
        print(f"\n[에러] {type(e).__name__}: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)
```

### 6.2 실행

venv 활성화 상태에서:

```powershell
python test_whisper.py
```

5초 녹음 후 인식 결과와 처리 시간이 출력됩니다.

### 6.3 결과 해석

```text
실시간 배수 1.0x 이상  → 실시간 처리 가능, 그대로 사용
실시간 배수 0.5~1.0x   → chunk_ms를 3000ms 이상으로 늘려야 따라감
실시간 배수 0.5x 미만  → 한 단계 작은 모델로 다운그레이드 권장
```

### 6.4 다른 모델 테스트

`test_whisper.py`의 `MODEL_PATH` 한 줄만 바꿔서 다시 실행:

```python
# small에서 base로 바꾸려면
MODEL_PATH = r"C:\Subtitle\models\ggml-base.bin"
```

여러 모델을 받아두고 본인 환경에서 가장 잘 맞는 걸 고르는 방식이 가장 확실합니다.

---

## 7. 모델별 권장 chunk_ms 설정

`speech_whisper.py` 또는 `config.py`에서 설정할 chunk_ms 값.

| 모델 | CPU 권장 chunk_ms | GPU 권장 chunk_ms |
|---|---:|---:|
| tiny | 1000 | 500 |
| base | 1500 | 800 |
| small | **3000** | 1500 |
| medium | (CPU 비권장) | 2000 |
| large-v3 | (CPU 불가) | 2500 |
| large-v3-turbo | (CPU 불가) | 1500 |

**원칙**: chunk_ms는 "5초 오디오 처리 시간 / 5 × 1000 × 1.5" 정도로 잡으면 안전 마진 있음.

예: small 모델이 5초 오디오를 10초에 처리한다면
→ `(10/5) × 1000 × 1.5 = 3000ms` 권장

---

## 8. 트러블슈팅

### 8.1 `pywhispercpp` import 에러

```text
ImportError: DLL load failed
```

→ Visual C++ Redistributable 누락. [Microsoft 공식 사이트](https://aka.ms/vs/17/release/vc_redist.x64.exe)에서 설치.

### 8.2 모델 로드 시 멈춤

```text
[모델 로딩 중...] (응답 없음)
```

→ 모델 파일 손상. 크기를 §1.1 표와 비교, 다르면 다시 다운로드.

```powershell
ls C:\Subtitle\models\ggml-small.bin
```

### 8.3 인식 결과가 영어로 나옴

→ `language="ko"` 파라미터 누락. `Model()` 호출 시 명시:

```python
model = Model(MODEL_PATH, language="ko")
```

### 8.4 인식 결과가 빈 문자열

→ 마이크 입력이 너무 작음. Windows 사운드 설정에서 입력 레벨 확인.
→ 또는 잘못된 입력 장치 선택. `sd.query_devices()`로 장치 목록 확인.

### 8.5 처리 중 CPU 100% 지속, 노트북 발열

→ `n_threads`를 줄이기:

```python
model = Model(MODEL_PATH, n_threads=2)  # 4 → 2
```

처리 시간은 늘어나지만 발열 억제됨.

### 8.6 메모리 부족 에러

→ 더 작은 모델로 교체. 또는 다른 프로그램 닫고 재시도.
→ medium 이상은 RAM 8GB 이하 환경에서 비권장.

---

## 9. 한 줄 요약

```text
GPU 없으면 base나 small 받아서 §6 테스트 돌리고
실시간 배수 1.0x 넘으면 그 모델로 가고,
넘지 않으면 chunk_ms를 3000ms로 잡거나 한 단계 작은 모델로 내리기.
한국어는 반드시 .en 없는 모델 + language="ko".
```

---

## 부록 A. 파일 위치 정리

```text
C:\Subtitle\
├── venv\                          (가상환경)
├── models\
│   ├── ggml-small.bin             (Whisper 모델)
│   └── vosk-model-small-ko-0.22\  (기존 Vosk, 롤백용 유지)
├── test_whisper.py                (§6.1 테스트 스크립트)
└── ...
```

## 부록 B. 모델 한 번에 다 받기 (참고)

여러 모델을 모두 받아두고 비교하고 싶을 때:

```powershell
cd C:\Subtitle\models
@(
    "ggml-tiny.bin",
    "ggml-base.bin",
    "ggml-small.bin"
) | ForEach-Object {
    Write-Host "Downloading $_..."
    curl.exe -L -o $_ "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/$_"
}
```

총 약 700MB.

## 부록 C. 모델 삭제

쓰지 않는 모델 삭제로 디스크 확보:

```powershell
Remove-Item C:\Subtitle\models\ggml-tiny.bin
Remove-Item C:\Subtitle\models\ggml-medium.bin
```

같은 카테고리 자료

RAG 시스템 구축 가이드 AI Agent 설계 원칙 Prompt Engineering 실전 패턴 MCP 서버 만들기

← AI 바이브 코딩 목록 기술 자료 전체

Whisper.cpp설치 가이드

같은 카테고리 자료

이런 기술을 우리 회사에 적용하려면?

회원 전용 기능입니다