시스템 요구사항 및 준비 작업
고효율 음성 인식 서비스를 구축하려면 안정적인 컴퓨팅 리소스가 필요합니다. Qwen3-ASR-1.7B 모델의 안정적 실행을 위해 권장되는 하드웨어 사양과 소프트웨어 구성 요소는 다음과 같습니다.
하드웨어 사양
- 그래픽 처리 장치: NVIDIA GPU가 필수입니다. 최소 8GB VRAM (RTX 3070 급 이상 권장) 을 확보해야 합니다. CPU 모드에서도 구동 가능하지만 추론 속도가 현저히 저하됩니다.
- 메모리: 시스템 메모리는 16GB 이상을 추천합니다.
- 저장 공간: 모델 가중치와 라이브러리 파일을 저장할 최소 10GB 의 여유 공간이 필요합니다.
소프트웨어 환경
다음 버전 이상의 패키지가 설치되어 있어야 합니다. 다른 배포판의 경우 명령어가 일부 다를 수 있으므로 주의하세요.
- OS: Ubuntu 18.04 또는 최신 버전
- Python: 3.8+
- CUDA Toolkit: 11.7+ (GPU 활용 시)
- cuDNN: CUDA 와 호환되는 버전
CUDA 설치가 완료되었는지 확인하려면 다음 명령어를 터미널에 입력하여 출력된 버전을比对하면 됩니다:
nvcc --version
개발 환경 설정
시스템 전체 Python 환경과의 충돌을 방지하기 위해 Conda 를 활용한 격리 환경을 생성하는 것이 좋습니다.
가상 환경 구축
전용 네임페이스를 가진 환경에서 작업을 수행합니다:
# conda 프로젝트 생성 (파이썬 3.10 기준)
conda create -n qwen_speech python=3.10 -y
# 환경 활성화
conda activate qwen_speech
핵심 라이브러리 설치
모델 추론 및 데이터 전처리를 위한 모듈들을 설치합니다. Torch 라이브러리는 사용 중인 CUDA 버전에 맞춰서 선택해야 합니다.
# pytorch 및 관련 라이브러리
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# 모델 관리 도구 설치
pip install modelscope
# 멀티미디어 처리 도구
pip install soundfile librosa
추론 엔진 설정
vLLM 은 대규모 언어 모델 기반 추론을 가속화하는 백엔드입니다. 이는 해당 환경에서만 정상 작동하므로 확인이 필요합니다.
pip install vllm
pip install 'qwen-asr[vllm]'
모델 다운로드 및 경로 설정
모델 체크포인트 파일의 크기는 약 7GB 수준입니다. 로컬 디스크 경로를 명시적으로 설정하여 다운로드 위치를 제어할 수 있습니다.
캐시 디렉토리 지정
echo 'export MODELSCOPE_CACHE=/home/user/models_cache' >> ~/.bashrc
source ~/.bashrc
모델 획득 과정
modelscope download --model Qwen/Qwen3-ASR-1.7B
모델 위치 검증
import os
cache_root = os.environ.get("MODELSCOPE_CACHE")
base_path = os.path.join(cache_root, "models", "Qwen", "Qwen3-ASR-1.7B")
print(f"체크포인트 위치: {base_path}")
음성 추론 예제 구현
준비된 모델을 활용해 오디오 데이터를 텍스트로 변환하는 로직을 구현한 샘플 코드입니다.
기본 처리 플로우
import torch
from transformers import pipeline
# 모델 인스턴스 초기화
asr_processor = pipeline(
"automatic-speech-recognition",
model=base_path,
torch_dtype=torch.bfloat16,
device=0,
max_new_tokens=256
)
# 외부 URL 오디오 파일 분석
audio_input_url = "https://example.com/sample_audio.wav"
output_data = asr_processor(audio_input_url)
print(f"언어 식별: {output_data[0].get('lang_code')}")
print(f"변환 결과: {output_data[0]['text']}")
로컬 파일 처리
# 로컬 저장된 웨이브 파일 처리
local_audio_path = "./data/input_recording.wav"
result_batch = asr_processor(local_audio_path, batch_size=8)
print(result_batch[0]["text"])
RESTful 서비스 배포 전략
클라이언트 요청을 받는 HTTP 서버 형태로 서비스를 제공하려면 내장 유틸리티를 사용합니다.
백엔드 구동 명령
qwen-asr-serve Qwen/Qwen3-ASR-1.7B \
--gpu-mem-util 0.8 \
--bind-address 0.0.0.0 \
--listen-port 9000
API 요청 패턴
import requests
endpoint = "http://localhost:9000/v1/transcribe"
payload = {
"audio_source": "https://example.com/stream.mp3"
}
headers = {"Authorization": "Bearer TOKEN"}
try:
resp = requests.post(endpoint, json=payload, headers=headers, timeout=120)
print(resp.json()["text_result"])
except Exception as e:
print(f"통신 오류 발생: {e}")
운영 중 발생할 수 있는 이슈 대응
VRAM 부족 에러
추론 중 메모리 초과가 발생하면 배치 크기나 토큰 제한을 축소해야 합니다.
asr_processor = pipeline(
...,
max_new_tokens=128, # 토큰 수 감소
batch_size=4 # 병렬 처리 단위 축소
)
오디오 포맷 호환성
MP3 등의 포맷이 지원되지 않을 경우 추가 코덱을 설치합니다.
pip install ffmpeg-python
초기 로드 지연
모델 히터를 첫 번에 불러올 때 시간이 소요되지만, 그 이후에는 성능이 최적화됩니다. 응답 속도가 중요한 경우 경량화된 0.6B 버전을 고려할 수 있습니다.