Quantatirsk/qwen3-asr

Qwen3‑ASR — 로컬 음성 인식 API 서비스

무엇인가요 – 오픈소스 Qwen3‑ASR 음성-텍스트 모델(0.6 B 및 1.7 B)을 래핑하여 익숙한 OpenAI 호환 및 Alibaba 클라우드 호환 HTTP 및 WebSocket 엔드포인트를 통해 제공하는 즉시 실행 가능한 서버입니다. GPU에서는 공식 vLLM 백엔드, CPU/macOS에서는 번들된 Rust 백엔드로 실행되며, 호스트 환경에 따라 최적의 런타임을 자동으로 선택합니다.

주요 기능

• 하이브리드 런타임 – GPU → vLLM, CPU/macOS → Rust 기반 QwenASR.
• 화자 분리 – 다중 화자 감지(CAM++ 모델) 및 자동 화자 라벨링 지원.
• 실시간 스트리밍 – 저지연 번역을 위한 WebSocket API(Paraformer + Qwen3‑ASR).
• 스마트 오디오 처리 – VAD 기반 세그멘테이션, 원거리 음성 노이즈 필터링, 배치 추론(GPU에서 2~3배 속도 향상).
• API 호환성 – OpenAI /v1/audio/transcriptions 엔드포인트 및 Alibaba Cloud Speech REST/WebSocket 프로토콜과 호환되어 기존 클라이언트 코드를 로컬 서버로 바로 연결 가능.
• 자원 기반 모델 선택 – VRAM에 따라 0.6 B 또는 1.7 B 모델을 자동 선택 가능. QWEN3_ASR_MODEL로 오버라이드 가능.

실행 방법

1. Docker(권장) – .env.example을 .env로 복사하고, API 키가 필요하면 편집 후 다음 명령 실행:

   docker-compose up -d               # GPU 이미지(기본)
   # 또는 CPU 전용
   docker-compose -f docker-compose-cpu.yml up -d
   

   서비스는 http://localhost:17003에서 접근 가능하며, Swagger 문서는 /docs에 있습니다.
2. 커스텀 GPU 빌드 – 리포지토리는 CUDA 12.6, 12.8(기본), 13.0을 타겟으로 하는 Dockerfile.gpu 및 빌드 인자를 제공합니다.
3. 오프라인 배포 – 인터넷이 연결된 머신에서 ./scripts/prepare-models.sh 실행 후 생성된 qwen3-asr-models-*.tar.gz를 tar로 압축. 타겟 호스트로 복사하여 추출 후 Docker Compose로 시작.
4. 로컬 개발 – Python 3.10+ 설치 후 다음 실행:

   uv sync                     # GPU 스택 (CPU용은 ./scripts/sync_cpu_env.sh)
   source .venv/bin/activate
   python start.py
   

   macOS/Apple Silicon은 자동으로 Rust 백엔드 사용.

API 사용법

• OpenAI 스타일 (POST /v1/audio/transcriptions):

  from openai import OpenAI
  client = OpenAI(base_url="http://localhost:8000/v1", api_key="my_key")
  with open("audio.wav", "rb") as f:
      resp = client.audio.transcriptions.create(file=f, response_format="verbose_json")
  print(resp.text)
  

• Alibaba Cloud 스타일 (POST /stream/v1/asr 또는 WebSocket /ws/v1/asr/qwen).
• 지원되는 응답 형식: json, text, srt, vtt, verbose_json.
• 파라미터로 화자 분리 활성/비활성, 단어 수준 타임스탬프 요청(오프라인 엔드포인트에서만 가능), 언어 힌트 제공 가능.

지원되는 모델

모델 ID	크기	일반적인 VRAM 필요량	비고
qwen3-asr-1.7b	1.7 B	≥ 32 GB	높은 정확도, 다국어(52개 이상 방언 포함)
qwen3-asr-0.6b	0.6 B	< 32 GB	가벼운 크기, Rust를 통해 CPU/macOS에서 실행

라이선스 – MIT (LICENSE 참조).

누가 사용할까 – OpenAI 또는 Alibaba Cloud 음성 API와 동일한 코드로 호출할 수 있는 자체 호스팅형, 프라이버시 중심의 음성-텍스트 서비스가 필요한 개발자. 외부 클라우드 제공업체에 의존하지 않고도 선택적 화자 분리 및 실시간 스트리밍 기능을 원하는 사람.