배포 선택표
제품, 데모, 벤치마크, 내부 워크플로에 가장 짧은 FunASR 배포 경로를 고릅니다. 먼저 목적을 만족하는 가장 작은 구성을 선택하고, 처리량, 지연 시간, 연동 요구가 명확해질 때 더 무거운 runtime으로 이동합니다.
빠른 결정표
| 경로 | 적합한 상황 | 시작 위치 | 운영 메모 |
|---|---|---|---|
| Colab notebook | 브라우저 smoke test, 첫 평가, 공유 가능한 데모 | Colab quickstart | 로컬 환경이 필요 없습니다. 첫 실행은 모델을 내려받으며 GPU runtime이 더 빠릅니다. |
| Python API | Notebook, 오프라인 작업, 첫 모델 평가 | README quickstart | 가장 단순한 시작점입니다. batching, retry, 파일 관리는 호출자가 담당합니다. |
| OpenAI 호환 API | 사내 음성 API, Agent, Dify/LangChain/AutoGen/n8n 스타일 클라이언트 | OpenAI API · 한국어 quickstart · Python smoke test · JS/TS recipes · Workflow recipes · Gradio demo · Security guide · Postman collection · OpenAPI spec | OpenAI audio API나 multipart HTTP node를 이미 지원하는 앱과 workflow engine에 가장 쉽게 붙습니다. |
| Docker Compose API | 재현 가능한 로컬 smoke test, 작은 사내 서비스 | OpenAI API Docker docs · Python smoke test | 기본은 CPU입니다. 컨테이너에서 CUDA를 쓰기 전 CUDA 지원 PyTorch/FunASR image를 확인합니다. |
| Kubernetes API | 클러스터 내부 사내 음성 API | Kubernetes template · Python smoke test | 기본은 private ClusterIP입니다. 넓게 노출하기 전 auth, TLS, network policy, GPU scheduling을 추가합니다. |
| Runtime WebSocket service | 실시간 자막, 회의, 콜센터 스트리밍 음성 | Runtime docs | partial result, endpointing, 긴 오디오 스트림이 중요할 때 선택합니다. |
| vLLM acceleration | Fun-ASR-Nano 같은 LLM-based ASR의 고처리량 추론 | vLLM guide | LLM decoder 처리량을 높이는 경로입니다. non-autoregressive Paraformer에는 적용하지 않습니다. |
| MCP server | Claude/Cursor/desktop agent 음성 도구 | MCP example | ASR 결과를 로컬 tool로 노출하고 싶을 때 적합합니다. |
| Subtitle generator | 긴 오디오나 비디오에서 SRT/VTT 생성 | Subtitle generator | 가독성이 중요하면 verbose segments와 speaker label을 사용합니다. |
| Batch ASR script | 아카이브, 회의록, 데이터셋, 반복 오프라인 처리 | Batch example | 운영 환경에서는 queue, manifest, retry log를 추가합니다. |
| Triton runtime | 전용 고성능 serving | Triton runtime docs | 설정이 무겁습니다. 이미 Triton/GPU serving을 운영하는 팀에 적합합니다. |
자주 고르는 경로
5분 안에 FunASR 시험하기
브라우저만으로 smoke test를 하려면 Colab quickstart를 사용합니다. 로컬 작업은 README의 Python API가 가장 짧습니다. 설치, 모델 다운로드, 장치 선택, 출력 형식을 빠르게 확인할 수 있습니다. 어떤 모델부터 쓸지 모르겠다면 모델 선택 가이드를 보세요.
클라우드 전사를 로컬 API로 대체하기
OpenAI 호환 API를 사용합니다. 먼저 sensevoice로 bash smoke test나 Python smoke test를 통과시키고, 기존 SDK 또는 HTTP 클라이언트를 연결합니다. 클러스터 배포는 Kubernetes template에서 시작합니다. Dify, n8n, webhook worker에는 workflow recipes를, GUI API 확인에는 Postman collection 또는 Gradio demo를 사용할 수 있습니다. gateway와 developer portal에는 OpenAPI spec과 security guide를 참고합니다.
재현 가능한 container demo
cd examples/openai_api
cp .env.example .env
docker compose up --buildCUDA 지원 PyTorch/FunASR image를 확정하기 전에는 CPU mode로 검증합니다.
실시간 음성 서비스
Runtime WebSocket service를 사용합니다. 운영 전에 실제 오디오로 chunk size, VAD, endpointing, punctuation, speaker diarization, reconnect, client backpressure를 검증하세요.
운영 전 체크리스트
- 사용할 model alias를 정하고 deployment note에 고정합니다.
- FunASR version, model version, device, CUDA/PyTorch version, Docker image tag, 시작 명령을 기록합니다.
- 짧은 공개 오디오로 Python smoke test를 실행하고, 실제 private sample도 최소 1개 확인합니다. Kubernetes는 deployment template를 사용해 먼저
kubectl port-forward로 검증합니다. - 각 request에서 audio duration, model, device, latency, response format, error type을 기록합니다.
- 신뢰 네트워크 밖으로 API를 노출하기 전 upload size limit, authentication, TLS, rate limit을 추가합니다. 경계 설계는 security guide를 사용합니다.
- Streaming은 silence, noise, overlapping speakers, long sessions, reconnect, slow clients를 테스트합니다.
issue를 열 때
Runtime, Docker, vLLM, Triton, Android, browser, agent integration 문제는 Deployment Help를 사용하세요. deployment path, 정확한 command/config, logs, model, device, audio characteristics를 포함하면 재현이 쉬워집니다.