FunASR

( 简体中文 |English| 日本語 | 한국어 )

오프라인, 스트리밍, 엣지 배포를 위한 산업용 음성 인식 툴킷.

ASR · VAD · 문장 부호 · 화자 파이프라인 · 감정 및 오디오 이벤트 모델 · OpenAI 호환 서빙

빠른 시작 · 모델 선택 · 모델 · 배포 매트릭스 · 배포 허브 · 문서 · 벤치마크 · 기여하기

빠른 시작
네이티브 Transformers
Hugging Face API로 Fun-ASR-Nano 전사를 하려면 Transformers 5.17.0 CPU 빠른 시작 부터 시작하세요. FunASR 툴킷이나 원격 Python 코드는 필요하지 않습니다.

Space · Notebook · Python / 배치 예제

FunASR 툴킷 및 파이프라인

로컬 설정이 없으신가요? Colab 빠른 시작을 열어 공개 샘플을 전사하거나 브라우저에서 직접 오디오를 업로드하세요.

FunASR이 유용했다면 프로젝트에 Star를 눌러 더 많은 개발자가 찾을 수 있도록 도와주세요.

# CPU 전용 설치에서는 기본 PyPI 휠을 사용할 수 있습니다.
pip install torch torchaudio
pip install funasr
GPU 빠른 시작의 경우, FunASR을 설치하기 전에 pytorch.org 에서
NVIDIA 드라이버에 맞는 PyTorch 및 torchaudio 휠을 설치하세요. 설치 후 GPU가
인식되는지 확인하세요:

python - << ' PY '
import torch
print(torch.cuda.is_available())
PY
이 출력이 True 일 때만 device="cuda" 를 사용하세요. 그렇지 않으면 device="cpu" 를 사용하거나
올바른 CUDA 휠로 PyTorch를 재설치하세요.

FunASR 툴킷 GPU 예제: Fun-ASR-Nano (중국어, 영어, 일본어, 중국 방언군 및 지역 억양; 별도의 네이티브 Transformers CPU 경로는 위에 링크되어 있습니다):

from funasr import AutoModel

model = AutoModel ( model = "FunAudioLLM/Fun-ASR-Nano-2512" , device = "cuda" )
result = model . generate ( input = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav" )
print ( result [ 0 ][ "text" ])
별도의 31개 언어 체크포인트는
Fun-ASR-MLT-Nano-2512 를 사용하세요.
언어 지원 범위는 체크포인트별로 다르므로 Nano와 MLT-Nano는 서로 다른 모델 선택으로
취급해야 합니다.

5개 언어 ASR과 감정 및 오디오 이벤트 태그를 포함한 CPU 우선 예제는
SenseVoiceSmall 을 사용하세요. 아래 파이프라인은 이를 FSMN-VAD 및
CAM++와 결합하여 화자 인식 VAD 세그먼트를 생성합니다. 이는
SenseVoiceSmall 체크포인트의 네이티브 화자 출력이 아닙니다.
SenseVoice 논문 ,
Hugging Face 체크포인트 ,
및 GGUF 엣지 체크포인트 를 참조하세요.

from funasr import AutoModel
from funasr . utils . postprocess_utils import rich_transcription_postprocess

model = AutoModel ( model = "iic/SenseVoiceSmall" , vad_model = "fsmn-vad" , spk_model = "cam++" , device = "cpu" )
result = model . generate (
input = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav" ,
batch_size_s = 300 ,
)

# AutoModel 파이프라인은 화자 id와 타임스탬프가 포함된 VAD 세그먼트를 반환합니다:
for seg in result [ 0 ][ "sentence_info" ]:
print ( f"[ { seg [ 'start' ] / 1000 :.1f } s] Speaker { seg [ 'spk' ] } : { rich_transcription_postprocess ( seg [ 'sentence' ]) } " )
이 코드는 반환된 각 세그먼트의 시작 시간(초), 익명 화자
인덱스, 그리고 SenseVoice 태그가 제거된 텍스트를 출력합니다. 텍스트와 세그먼트 경계는
오디오와 체크포인트에 따라 달라지며, 여기서 고정된 전사 결과를 보장하지는 않습니다.

CAM++는 spk_embedding 벡터를 추출합니다. AutoModel은 해당 임베딩을 클러스터링하여
VAD 세그먼트에 화자 인덱스를 할당합니다. 인덱스는 녹음 내에서만 유효하며
알려진 인물의 신원이 아닙니다. 컴포넌트 및 결과 경계에 대해서는 SDK 계약 을
참조하세요. 위에서 설명한 대로 호환되는 GPU 환경을 확인한 후에만 device="cuda" 로
변경하세요.

플래그십 모델 확장 및 배포
대규모 환경에서는 vLLM으로 Fun-ASR-Nano를 가속하세요 (배치 처리):

from funasr . auto . auto_model_vllm import AutoModelVLLM

model = AutoModelVLLM ( model = "FunAudioLLM/Fun-ASR-Nano-2512" , tensor_parallel_size = 1 )
results = model . generate ([ "audio1.wav" , "audio2.wav" ], language = "auto" )

API 서버로 배포: 로컬 SenseVoice CPU 레시피 · Nano GPU 서빙 및 고정된 vLLM 설정

AI 에이전트와 함께 사용: Claude/Cursor용 MCP Server · LangChain/Dify/AutoGen용 OpenAI API

음성 에이전트와 함께 사용: 자체 호스팅 Talk 및 Voice Call 전사를 위한 OpenClaw 실시간 플러그인 · SenseVoice를 사용한 Hugging Face 음성 간 변환 (병합된 소스 체크아웃; v1.0.0에는 미포함)

FunASR을 선택하는 이유
FunASR은 툴킷입니다: 작업, 체크포인트, 런타임을 각각 선택하세요.
하나의 모델이나 어댑터에서의 지원이 모든 서빙 백엔드에서의 지원을 의미하지는 않습니다.

작업
체크포인트 또는 파이프라인
런타임 진입점
주요 제한 사항

감정/이벤트 태그를 포함한 파일 전사
SenseVoiceSmall
Python AutoModel , CPU 또는 GPU
5개 언어 체크포인트; 태그는 화자를 식별하지 않습니다.

LLM 기반 파일 전사
Fun-ASR-Nano
AutoModel ; 문서화된 GPU 경로용 분할 엔진 AutoModelVLLM
기본 Nano는 zh/en/ja 및 중국 방언/억양을 지원; 타임스탬프 지원은 체크포인트와 경로에 따라 다릅니다.

더 넓은 다국어 전사
Fun-ASR-MLT-Nano
Python AutoModel
별도의 31개 언어 체크포인트; 해당 지원 범위를 기본 Nano로 전용하지 마세요.

청크 기반 실시간 전사
Paraformer-zh-streaming
스트리밍 SDK 또는 런타임 WebSocket 서비스
오프라인 체크포인트가 아닌 스트리밍 체크포인트와 세션별 캐시를 사용하세요.

화자 인식 파일 전사
SenseVoiceSmall + FSMN-VAD + CAM++
VAD 및 임베딩 클러스터링을 포함한 AutoModel
녹음 내 익명 인덱스이며, 등록된 화자 식별이 아닙니다.

텍스트, 타임스탬프, 화자 통합
MOSS-Transcribe-Diarize, 서드파티 OpenMOSS
MOSS 가이드의 FunASR 어댑터 또는 업스트림 백엔드
오프라인, 녹음 로컬 익명 레이블; 통합 경로에는 외부 VAD/화자 파이프라인이 없습니다.

네이티브 CPU/엣지 전사
Fun-ASR-Nano 또는 SenseVoiceSmall GGUF
llama.cpp 런타임
일치하는 변환 가중치가 필요합니다; GGUF는 Python AutoModel 체크포인트가 아닙니다.

체크포인트, 인터페이스, 라이선스 경계에 대해서는 Model Zoo 및 배포 매트릭스 를
참조하세요. 런타임을 선택하기 전에 자체 오디오와
하드웨어에서 벤치마크하세요.

FunASR을 처음 사용하시나요? 로컬 환경을 설정하기 전에 Colab 빠른 시작을 사용하세요. 첫 모델을 선택하시나요? 모델 선택 가이드 부터 시작하세요. Whisper 또는 클라우드 ASR 제공업체에서 전환할 계획이신가요? 마이그레이션 가이드 와 벤치마크 예제를 사용하여 대표 오디오를 테스트하고, 기능을 매핑하고, 안전하게 롤아웃하세요.

설치
pip install funasr
소스에서 / 요구 사항
git clone https://github.com/modelscope/FunASR.git && cd FunASR
pip install -e ./
요구 사항: Python ≥ 3.8. 먼저 PyTorch + torchaudio를 설치한 후 ( pytorch.org ), pip install funasr 을 실행하세요.

Model Zoo
이 목록에는 서드파티 모델이 포함되어 있습니다. OpenMOSS는 MOSS-Transcribe-Diarize를 게시하며,
FunASR은 어댑터를 제공할 뿐 해당 가중치의 소유자가 아닙니다. 통합 경로는
오프라인이며, 익명 레이블은 각 녹음에 한정되며 실시간이나
알려진 인물 식별이 아닙니다. 모델 라이선스는 툴킷의 MIT 라이선스와 별개입니다.

모델
작업
언어
파라미터
링크

Fun-ASR-Nano
ASR
zh/en/ja + 중국 방언 및 억양
800M
⭐ HF / Transformers · HF / FunASR GGUF

Fun-ASR-MLT-Nano
ASR
31개 언어
800M
⭐ 🤗

SenseVoiceSmall
ASR + 감정 + 이벤트
zh/en/ja/ko/yue
234M
⭐ 🤗 GGUF 논문

MOSS-Transcribe-Diarize
서드파티 OpenMOSS: 오프라인 ASR + 타임스탬프 + 익명 화자
공식 카드 참조
공식 카드 참조
🤗 가이드

Paraformer-zh
ASR + 타임스탬프
zh/en
220M
⭐ 🤗

Paraformer-zh-streaming
스트리밍 ASR
zh/en
220M
⭐ 🤗

Qwen3-ASR
ASR, 52개 언어
다국어
1.7B
사용법

GLM-ASR-Nano
ASR, 17개 언어
다국어
1.5B
사용법

Whisper-large-v3
ASR + 번역
다국어
1550M
사용법

Whisper-large-v3-turbo
ASR + 번역
다국어
809M
사용법

ct-punc
문장 부호
zh/en
290M
⭐ 🤗

fsmn-vad
VAD
zh/en
0.4M
⭐ 🤗

cam++
화자 임베딩 (파이프라인 컴포넌트)
—
7.2M
⭐ 🤗

emotion2vec+large
감정 인식
—
300M
⭐ 🤗

사용법

Python 튜토리얼 · SDK 파라미터 및 출력 · 학습 · 모델 등록

from funasr import AutoModel

# 중국어 프로덕션 (VAD + ASR + 문장 부호 + 화자)
model = AutoModel ( model = "paraformer-zh" , vad_model = "fsmn-vad" , punc_model = "ct-punc" , spk_model = "cam++" , device = "cuda" )
result = model . generate ( input = "https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_example_zh.wav" , hotword = "关键词 20" )

# 선택적 Silero VAD (먼저 설치: python -m pip install "funasr[silero]")
model = AutoModel (
model = "paraformer-zh" , vad_model = "silero-vad" , device = "cuda" ,
vad_kwargs = { "silero_threshold" : 0.5 , "silero_min_silence_duration_ms" : 100 },
)
result = model . generate ( input = "audio.wav" )

# 스트리밍 실시간 (오디오를 청크 단위로 공급)
import soundfile as sf
model = AutoModel ( model = "paraformer-zh-streaming" , device = "cuda" )
audio , sr = sf . read ( "speech.wav" , dtype = "float32" ) # 16 kHz 모노
chunk_size = [ 0 , 10 , 5 ] # 600 ms 청크
chunk_stride = chunk_size [ 1 ] * 960
cache = {}
n_chunks = ( len ( audio ) - 1 ) // chunk_stride + 1
for i in range ( n_chunks ):
chunk = audio [ i * chunk_stride : ( i + 1 ) * chunk_stride ]
res = model . generate ( input = chunk , cache = cache , is_final = ( i == n_chunks - 1 ),
chunk_size = chunk_size , encoder_chunk_look_back = 4 , decoder_chunk_look_back = 1 )
if res [ 0 ][ "text" ]:
print ( res [ 0 ][ "text" ], end = "" , flush = True )

# 감정 인식
model = AutoModel ( model = "emotion2vec_plus_large" , device = "cuda" )
result = model . generate ( input = "audio.wav" , granularity = "utterance" )
CLI (에이전트 친화적)
# 오디오 전사 (가장 간단)
funasr audio.wav

# JSON 출력 (AI 에이전트용)
funasr audio.wav --output-format json

# SRT 자막
funasr audio.wav --output-format srt --output-dir ./subs

# 화자 분리 + 타임스탬프
funasr audio.wav --spk --timestamps -f json

# 모델 및 언어 선택
funasr audio.wav --model paraformer --language zh

# 배치 전사
funasr * .wav --output-format srt --output-dir ./output
사용 가능한 모델: sensevoice (기본값), paraformer , paraformer-en , fun-asr-nano

배포
POSIX 셸에서 Python 3.11로 새 디렉터리에서 로컬 SenseVoice CPU 서비스를
시작하세요. 이는 PyPI 릴리스를 별도 환경에 설치하며, 이
소스 체크아웃이 아닙니다. 인증되지 않은 서비스는 루프백에 유지하세요. 다른
클라이언트에 노출하기 전에 보안 가이드 를 사용하세요.

python3.11 -m venv .venv-funasr-http
. .venv-funasr-http/bin/activate
python -m pip install torch torchaudio
python -m pip install funasr fastapi uvicorn python-multipart
python -m pip check
funasr-server --host 127.0.0.1 --port 8000 --model sensevoice --device cpu
모델 다운로드와 서버 시작을 기다리세요. 두 번째 터미널에서 동일한
디렉터리와 curl 7.76+를 사용하여 공개 중국어 오디오 샘플을 다운로드하고 전사하세요.
요청은 사전 로드된 모델을 사용하며, 고정된 전사 결과나 화자 레이블을 보장하지 않습니다.

curl --fail --location https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav && \
curl --fail-with-body http://127.0.0.1:8000/v1/audio/transcriptions \
-F [email protected] \
-F model=sensevoice \
-F response_format=verbose_json
오프라인 통합 ASR 및 익명 화자 레이블( moss-transcribe-diarize )의 경우, MOSS 서비스, Docker, Kubernetes, vLLM, SGLang, LocalAI 및 FunClip 가이드 → 에서 별도 환경을
준비하세요. 이는 대체 서비스이며, CPU 환경의 또 다른 명령이 아닙니다. 포트 8000을 재사용하기 전에
CPU 서비스를 중지하세요. Nano GPU 서빙의 경우,
고정된 분할 엔진 가이드 를 따르고 실제 백엔드 로그를 확인하세요;
모델을 선택하는 것만으로는 vLLM이 로드되었음을 증명하지 않습니다.

# Docker 스트리밍 서비스
docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12
CPU / 엣지 — llama.cpp / GGUF (GPU 없음, Python 없음)
SenseVoice / Paraformer / Fun-ASR-Nano를 CPU 및 엣지 디바이스에서 단일 자체 포함 바이너리로 실행하세요 — 이는 FunASR에게 whisper.cpp가 Whisper에게 하는 것과 같지만, 중국어에서 whisper.cpp보다 CER이 약 3배 낮습니다 . 내장 FSMN-VAD, 런타임에 Python 불필요.

# Linux / macOS: 추출된 릴리스 디렉터리에서 실행
bash download-funasr-model.sh sensevoice ./gguf # 또는: paraformer | na…