6. 개발 환경 준비: whisper.cpp, ONNX Runtime, 모바일 빌드 도구
개발 환경 준비: whisper.cpp, ONNX Runtime, 모바일 빌드 도구
이번 장의 목표
이 장의 목표는 아주 단순합니다. 초보자도 오늘 바로 실습을 시작할 수 있는 최소 환경을 만드는 것입니다. 아직 성능 튜닝, 양자화, 스트리밍, 가속 백엔드까지 한꺼번에 욕심내지 않습니다. 먼저 작게 성공하는 환경을 만드는 것이 더 중요합니다.
온디바이스 ASR를 처음 시작할 때 가장 좋은 전략은 보통 이렇습니다.
데스크톱에서 음성 파일 하나를 정확히 읽히게 만든다.
같은 모델을 안드로이드 예제 앱에 올려 본다.
그다음 ONNX Runtime 같은 다른 런타임 경로를 열어 둔다.
이 순서로 가면 어디서 문제가 생겼는지 추적하기가 훨씬 쉽습니다.
이 장에서는 특히 Whisper Tiny 또는 Base 모델을 기준으로 설명합니다. 이유도 간단합니다. 처음부터 큰 모델을 잡으면, 환경 문제인지 모델이 무거운 것인지조차 헷갈리기 쉽기 때문입니다.1
왜 CPU 기반으로 먼저 세팅하나
온디바이스 ASR를 처음 구현할 때는 화려한 가속기보다 재현성이 더 중요합니다. whisper.cpp는 의존성이 비교적 단순하고, CPU에서 시작하기 쉬우며, 안드로이드 예제 프로젝트도 함께 제공합니다.23
ONNX Runtime도 모바일에서 처음 붙일 때는 보통 CPU 경로부터 보는 편이 안전합니다. 공식 문서에는 Android용 onnxruntime-android 패키지와 모바일 배포 가이드가 정리되어 있고, XNNPACK 실행 공급자도 Android/iOS에서 CPU 최적화를 위해 제공됩니다.456
여기서 중요한 현실 하나가 있습니다.
안드로이드 가속은 생각보다 단순하지 않습니다.
기기마다 드라이버와 런타임 편차가 크고, Android 공식 문서 기준으로 NNAPI도 Android 15에서 지원 중단(deprecated) 되었기 때문에, 적어도 지금 시점의 입문 단계에서는 CPU 기준선이 더 중요합니다.78
즉, 이 책은 이렇게 갑니다.
먼저 CPU에서 확실히 돌아가게 만든다. 그다음에야 다른 가속 경로를 검토한다.
먼저 큰 그림을 잡자: 어떤 도구를 왜 쓰는가
이번 장에서 준비할 도구는 세 갈래입니다.
whisper.cpp: Whisper Tiny/Base를 가장 빠르게 시험해 볼 수 있는 경량 C/C++ 런타임
ONNX Runtime: ONNX 형식 모델을 앱에 붙일 때 유용한 범용 추론 엔진
모바일 빌드 도구: Android Studio, SDK, NDK, CMake, JDK, ffmpeg 같은 실습 기반 도구
초보자라면 우선순위를 이렇게 잡으면 됩니다.
먼저 whisper.cpp로 파일 기반 오프라인 인식을 성공시킵니다. 그다음 Android Studio에서 공식 예제 앱을 실행해 봅니다. 마지막으로 ONNX Runtime 경로를 추가해 두면, 이후 다른 모델로 확장할 때 훨씬 유연해집니다.
Step 1. Whisper Tiny 또는 Base 모델부터 고르기
처음 실습에서는 큰 모델보다 Tiny 또는 Base가 훨씬 낫습니다. 속도가 빠르고, 실패했을 때 원인도 추적하기 쉽기 때문입니다. 영어만 다룬다면 .en 모델이 더 효율적일 수 있고, 한국어를 포함한 다국어를 다루려면 tiny 또는 base 같은 multilingual 모델을 고르면 됩니다.1
아주 단순하게 정리하면 이렇습니다.
tiny: 가장 가볍고 빠릅니다. 환경 확인용 첫 테스트에 좋습니다.base: tiny보다 조금 무겁지만 결과가 더 안정적인 편입니다..en버전: 영어 전용일 때 유리합니다. 한국어 실습에는 보통 쓰지 않습니다.
이 장의 추천 시작점은 다음 둘 중 하나입니다.
한국어까지 포함한 일반 실습:
tiny또는base영어만 테스트:
tiny.en또는base.en
Step 2. 데스크톱에서 whisper.cpp를 먼저 확인하기
안드로이드로 바로 들어가지 말고, 먼저 데스크톱에서 모델과 오디오가 정상 동작하는지 확인하세요. 이 단계를 건너뛰면 나중에 문제를 만났을 때 모델 문제인지, 빌드 문제인지, 안드로이드 자산 복사 문제인지 구분하기가 어려워집니다.
2-1. 준비물 설치
아래 도구를 먼저 준비합니다.
Git
CMake
C/C++ 빌드 도구
ffmpeg
터미널
macOS나 Linux에서는 비교적 간단하고, Windows라면 WSL 또는 적절한 빌드 환경을 함께 준비해 두면 편합니다.
2-2. 저장소 가져오기와 모델 다운로드
가장 먼저 whisper.cpp 저장소를 가져오고, 작은 모델 하나를 받습니다.
git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
sh ./models/download-ggml-model.sh tiny
# 또는
sh ./models/download-ggml-model.sh base영어 전용 테스트라면 tiny.en, base.en도 좋습니다.2
2-3. 빌드하기
버전에 따라 예제 바이너리 이름은 조금 달라질 수 있지만, 공식 저장소 기준으로 CLI 도구를 빌드해 바로 시험할 수 있습니다.
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j2-4. 샘플 파일로 첫 실행
일단 샘플 오디오 하나를 돌려 보세요.
./build/bin/whisper-cli -m models/ggml-tiny.bin -f samples/jfk.wav핵심은 단순합니다. 모델 파일 하나와 WAV 파일 하나를 넣고 텍스트가 나오면 성공입니다.2
2-5. 오디오 포맷 맞추기
초보자가 가장 자주 막히는 지점이 여기입니다. 음성 파일 포맷이 제각각이면 실습이 꼬입니다. 첫 실습에서는 입력을 16kHz, 모노, 16-bit PCM WAV로 통일하는 편이 가장 안전합니다.
ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav이 명령은 오디오를 16kHz, 모노, 16-bit PCM WAV로 바꿉니다. 온디바이스 ASR 실습에서 거의 만능 열쇠처럼 쓸 수 있는 조합입니다.
Step 3. Android Studio와 모바일 빌드 도구 준비하기
이제 안드로이드 쪽 기본 공구함을 챙길 차례입니다. 여기서는 복잡한 최적화보다, 예제 앱을 띄우고 추후 네이티브 라이브러리를 붙일 수 있는 상태를 만드는 데 집중합니다.
3-1. 기본 설치 목록
초보자 기준으로 다음 정도면 충분합니다.
Android Studio
Android SDK
Android NDK
CMake
JDK
ffmpeg
Git
Android Studio를 설치하면 SDK, NDK, CMake를 한곳에서 관리할 수 있어 훨씬 편합니다. ONNX Runtime을 직접 Android용으로 빌드할 경우에는 JAVA_HOME 설정과, 환경에 따라 Ninja가 추가로 필요할 수 있습니다.9
3-2. 왜 NDK가 필요한가
whisper.cpp는 C/C++ 기반입니다. 즉, 안드로이드 앱에 붙일 때는 결국 네이티브 라이브러리를 다루게 됩니다. 그래서 Kotlin이나 Java만 하던 사람도 NDK를 피하기 어렵습니다.
처음에는 이게 무섭게 느껴질 수 있지만, 지금 단계에서는 "NDK는 네이티브 코드용 공구 상자" 정도로 이해하면 충분합니다.
3-3. 실기기를 추천하는 이유
가능하면 에뮬레이터보다 ARM64 실기기를 추천합니다. 이유는 간단합니다. 실제 배포 대상이 대부분 ARM 계열이고, 성능과 발열, 스레드 수, 추론 속도가 실기기에서 훨씬 현실적으로 보이기 때문입니다.
Step 4. 바로 실행해 볼 수 있는 앱: whisper.cpp 공식 Android 예제
초보자에게 가장 좋은 길은 "내 앱을 처음부터 다 만들기"가 아니라, 이미 돌아가는 예제를 먼저 실행해 보는 것입니다. whisper.cpp 저장소에는 안드로이드 예제 프로젝트가 있으며, 공식 README에도 모델과 샘플을 assets에 넣어 실행하는 방법이 정리돼 있습니다.3
4-1. 예제 앱 실행 흐름
진행 순서는 매우 단순합니다.
whisper.cpp저장소를 Android Studio로 엽니다.examples/whisper.android프로젝트를 확인합니다.모델 파일을
app/src/main/assets/models아래에 복사합니다.샘플 오디오를
app/src/main/assets/samples아래에 복사합니다.release빌드 변형을 선택하고 실행합니다.3
예를 들어 tiny 모델을 처음 시험할 때는 이런 흐름입니다.
sh ./models/download-ggml-model.sh tiny.en
mkdir -p examples/whisper.android/app/src/main/assets/models
cp models/ggml-tiny.en.bin examples/whisper.android/app/src/main/assets/models/
mkdir -p examples/whisper.android/app/src/main/assets/samples
cp samples/jfk.wav examples/whisper.android/app/src/main/assets/samples/그다음 Android Studio에서 프로젝트를 열고 실행하면 됩니다.
4-2. 이 예제가 왜 중요한가
이 예제를 한 번 성공시키면, 이후에는 다음이 한꺼번에 정리됩니다.
모델을 앱 자산에 어떻게 넣는지
샘플 오디오를 어떻게 읽는지
네이티브 추론 결과를 UI에 어떻게 연결하는지
즉, "온디바이스 ASR 앱의 최소 골격"이 눈에 보이기 시작합니다.
Step 5. ONNX Runtime 경로도 함께 열어 두기
Whisper 계열을 바로 올릴 때는 whisper.cpp가 빠른 출발점이지만, 프로젝트가 커지면 ONNX Runtime도 아주 중요한 선택지가 됩니다. 이미 ONNX 형식으로 변환된 모델을 쓰거나, 추후 다른 ASR 모델까지 염두에 둔다면 ONNX Runtime이 훨씬 범용적입니다.4
5-1. 가장 쉬운 시작법
안드로이드 앱에 ONNX Runtime을 가장 쉽게 붙이는 방법은 미리 빌드된 Android 패키지를 쓰는 것입니다. 보통은 onnxruntime-android를 먼저 붙이고, 모바일 패키지 크기 최적화가 중요해지면 ONNX Runtime mobile 경로를 검토합니다.4
Gradle에는 보통 이런 식으로 추가합니다.
dependencies {
implementation("com.microsoft.onnxruntime:onnxruntime-android:<version>")
}처음부터 커스텀 빌드, ORT 포맷 변환, 연산자 최소화까지 한꺼번에 들어가면 금방 지칩니다. 처음엔 호환성이 넓은 패키지로 시작하는 편이 낫습니다.
5-2. CPU 기준 세션부터 만들기
ONNX Runtime에서도 첫 목표는 같습니다. 모델이 로드되고, 입력 텐서를 넣고, 출력이 나온다는 사실을 확인하는 것입니다.
그다음에야 XNNPACK이나 다른 실행 공급자를 고민할 수 있습니다. 공식 문서 기준으로 XNNPACK은 Android/iOS에서 CPU 성능을 높이는 중요한 선택지이고, 사용 시에는 ORT 스레드풀과 XNNPACK 내부 스레드풀이 겹치지 않도록 설정을 조정하는 것이 권장됩니다.5
즉, 처음 순서는 보통 이렇게 잡으면 됩니다.
먼저 기본 세션으로 정상 동작 확인
그다음 XNNPACK 적용 검토
마지막에 기기별 추가 가속을 검토
5-3. 나중에 직접 AAR를 빌드해야 할 때
대부분의 초보자는 여기까지 가지 않아도 됩니다. 하지만 앱 크기, ABI, 연산자 집합 때문에 직접 ONNX Runtime을 Android용으로 빌드해야 할 수도 있습니다. 공식 문서에는 --android_sdk_path, --android_ndk_path, --android_abi, --android_api, --build_java 옵션으로 AAR를 만드는 방법이 정리되어 있습니다.9
예시는 이런 느낌입니다.
./build.sh --android \
--android_sdk_path <android sdk path> \
--android_ndk_path <android ndk path> \
--android_abi arm64-v8a \
--android_api 27 \
--build_java이렇게 빌드하면 안드로이드 프로젝트에 넣을 수 있는 AAR 산출물을 만들 수 있습니다.
Step 6. 초보자를 위한 최소 권장 환경
처음 실습이라면 아래 조합이 가장 무난합니다.
권장 조합 A: 가장 빠른 출발
런타임: whisper.cpp
모델:
tiny또는base대상: 데스크톱 CLI + 안드로이드 공식 예제 앱
추론 장치: CPU
이 조합은 "정말로 돌아가는지"를 확인하기 가장 좋습니다.
권장 조합 B: 앱 구조를 조금 더 일반화하고 싶을 때
런타임: ONNX Runtime
모델 형식: ONNX
대상: Android 앱
추론 장치: CPU부터 시작, 필요 시 XNNPACK 검토
이 조합은 Whisper만이 아니라 다른 모델까지 시야에 넣고 싶을 때 좋습니다.
Step 7. 폴더 구조를 이렇게 잡으면 덜 헷갈린다
실습용 프로젝트는 폴더 구조를 단순하게 두는 편이 좋습니다.
project-root/
├─ models/
│ ├─ ggml-tiny.bin
│ └─ ggml-base.bin
├─ audio/
│ ├─ sample1.wav
│ └─ sample2.wav
├─ tools/
│ └─ convert.sh
└─ android-app/
└─ app/src/main/assets/
├─ models/
└─ samples/핵심은 두 가지입니다. 모델 폴더와 오디오 폴더를 분리하고, 안드로이드 assets 안에도 같은 구조를 최대한 유지하는 것입니다. 이렇게 해 두면 데스크톱과 모바일 사이를 오갈 때 머리가 덜 아픕니다.
자주 막히는 지점
환경 세팅은 작은 실수 하나가 크게 돌아옵니다. 아래는 초보자가 특히 자주 만나는 문제입니다.
모델은 맞는데 결과가 이상할 때
가장 먼저 오디오 포맷을 의심하세요. 샘플레이트, 채널 수, PCM 형식이 안 맞으면 모델이 멀쩡해도 결과가 망가집니다. 먼저 16kHz 모노 WAV로 변환해 두면 문제를 많이 줄일 수 있습니다.
한국어인데 .en 모델을 썼을 때
영어 전용 모델은 영어에 최적화되어 있습니다. 한국어 실습이라면 tiny.en, base.en이 아니라 tiny, base 같은 다국어 모델을 써야 합니다.1
앱이 실행은 되는데 너무 느릴 때
정상입니다. 지금은 CPU 기반 최소 환경을 만드는 단계입니다. 아직 양자화도 안 했고, 스트리밍도 안 했고, 가속 백엔드별 최적화도 하지 않았습니다. 느린 것이 이상한 게 아니라, 돌아가는 것이 먼저입니다.
GPU 가속을 당장 붙이고 싶을 때
조금만 참는 편이 낫습니다. 안드로이드에서는 GPU 경로가 기기와 드라이버, 런타임 조합에 따라 편차가 큽니다. 입문 단계에서는 CPU 기준선이 훨씬 중요합니다.78
이 장을 마치면 확인해야 할 체크리스트
아래 다섯 가지가 되면, 다음 장으로 넘어갈 준비가 끝난 것입니다.
데스크톱에서
whisper.cppCLI가 실행된다.tiny또는base모델 하나가 정상 로드된다.WAV 샘플 하나를 텍스트로 변환할 수 있다.
안드로이드 공식 예제 앱이 기기에서 뜬다.
ONNX Runtime을 쓸 경우 Gradle 의존성이 정상 동작한다.
여기까지 왔다면, 이제 진짜 구현을 시작할 준비가 된 것입니다. 다음 장에서는 이 환경을 바탕으로 파일 기반 오프라인 음성 인식을 직접 만들어 보겠습니다. 복잡한 최적화보다 먼저, 음성이 텍스트가 되는 첫 순간부터 손에 넣어 봅시다.
참고
3whisper.cpp Android example README
4Deploy on mobile | ONNX Runtime
5XNNPACK Execution Provider | ONNX Runtime
7Neural Networks API | Android Developers
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.