Skip to content

README_ko.md

Latest commit

 

History

History
184 lines (132 loc) · 7.45 KB

README_ko.md

File metadata and controls

184 lines (132 loc) · 7.45 KB

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

FunASR OpenAI 호환 API 서버

FunASR OpenAI 호환 API는 /v1/audio/transcriptions를 제공합니다. OpenAI 스타일 SDK, 에이전트 프레임워크, Dify, n8n, HTTP 노드, 내부 업무 시스템에서 프라이빗 음성 인식 서비스로 사용할 수 있습니다.

빠른 시작

pip install funasr fastapi uvicorn python-multipart
python server.py --model sensevoice --device cuda --port 8000

모델 로드가 끝나면 서비스가 시작됩니다. 헬스 체크는 GET /health입니다.

바로 복사해서 쓸 수 있는 연동 예제가 필요하면 클라이언트 레시피, JavaScript/TypeScript 레시피, Gradio 브라우저 데모, 워크플로 레시피, Postman 컬렉션, OpenAPI 명세, 보안 및 게이트웨이 가이드, Kubernetes 배포 템플릿을 참고하세요.

엔드투엔드 smoke test

다른 터미널에서 실행합니다.

bash smoke_test.sh
# curl/bash가 없는 환경을 위한 크로스 플랫폼 방식:
python smoke_test.py

동일한 수동 명령:

curl -L https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/BAC009S0764W0121.wav -o sample.wav
curl http://localhost:8000/health
curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@sample.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

Gradio 브라우저 데모

로컬 브라우저에서 파일 업로드나 마이크 입력을 테스트하려면 먼저 API 서버를 시작한 뒤 선택 사항인 Gradio 프런트엔드를 실행합니다.

pip install gradio
python gradio_app.py --base-url http://localhost:8000

이 브라우저 데모는 smoke test와 동일한 OpenAI 호환 API 엔드포인트를 호출합니다. Docker, Kubernetes, 프로덕션 참고 사항은 Gradio 브라우저 데모를 확인하세요.

OpenAI SDK로 사용하기

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

result = client.audio.transcriptions.create(
    model="sensevoice",  # "paraformer", "paraformer-en", "fun-asr-nano"도 사용할 수 있습니다
    file=open("meeting.wav", "rb"),
)
print(result.text)

verbose = client.audio.transcriptions.create(
    model="sensevoice",
    file=open("meeting.wav", "rb"),
    response_format="verbose_json",
)
print(verbose.segments)

curl로 사용하기

curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@audio.wav \
  -F model=sensevoice

curl http://localhost:8000/v1/audio/transcriptions \
  -F file=@audio.wav \
  -F model=sensevoice \
  -F response_format=verbose_json

사용 가능한 모델

Model GPU 속도 CPU 속도 언어 특징
sensevoice 170x realtime 17x realtime zh/en/ja/ko/yue 감정 및 이벤트 태그
paraformer 120x realtime 15x realtime zh/en 문장부호 복원
paraformer-en 120x realtime 15x realtime en 영어 인식
fun-asr-nano 17x realtime 3.6x realtime 31 languages LLM-based, 타임스탬프

API 엔드포인트

Endpoint Method 설명
/v1/audio/transcriptions POST OpenAI 호환 음성 전사
/v1/models GET 모델 별칭 목록
/health GET 헬스 체크, 로드된 모델, 사용 가능한 모델
/docs GET FastAPI Swagger 문서

코드 작성 없이 확인하려면 Gradio 브라우저 데모로 로컬 업로드나 마이크 테스트를 진행하거나 Postman 컬렉션을 가져오세요. API 게이트웨이, 개발자 포털, 내부 클라이언트 생성을 위해서는 OpenAPI 명세를 사용할 수 있습니다.

에이전트 및 로우코드 워크플로

LangChain, LlamaIndex, AutoGen, CrewAI, Semantic Kernel, Dify, n8n, OpenAI audio API 또는 multipart HTTP를 지원하는 모든 시스템에서 사용할 수 있습니다.

Docker 배포

기본 이미지는 CPU 모드로 시작하므로 재현 가능한 smoke test로 사용할 수 있습니다.

cd examples/openai_api
cp .env.example .env

docker compose up --build

동일한 docker run 명령:

docker build -t funasr-api .

docker run --rm -p 8000:8000 \
  -e FUNASR_DEVICE=cpu \
  -e FUNASR_MODEL=sensevoice \
  funasr-api

GPU 호스트에서는 NVIDIA Container Toolkit과 CUDA 지원 PyTorch/FunASR 이미지가 필요합니다. CUDA 의존성에 맞게 이미지를 조정한 뒤 다음처럼 실행할 수 있습니다.

docker run --rm --gpus all -p 8000:8000 \
  -e FUNASR_DEVICE=cuda \
  -e FUNASR_MODEL=sensevoice \
  funasr-api

컨테이너 검증:

BASE_URL=http://localhost:8000 bash smoke_test.sh
python smoke_test.py --base-url http://localhost:8000

Kubernetes 배포

팀에서 공유하거나 게이트웨이를 통해 노출하기 전에 보안 및 게이트웨이 가이드를 검토하고 TLS, 인증, 업로드 제한, 속도 제한, 로그 정책을 준비하세요.

영구 모델 캐시, 헬스 프로브, 프라이빗 ClusterIP를 갖춘 내부 클러스터 서비스가 필요하다면 Kubernetes 배포 템플릿에서 시작하세요. 예제 이미지를 빌드하고 push한 뒤 manifests를 적용하고, kubectl port-forward와 python smoke_test.py --base-url http://localhost:8000으로 검증합니다.

CUDA 지원 이미지와 GPU 스케줄링 설정이 준비되기 전까지는 기본 CPU 모드를 유지하세요.

설정

인자 기본값 설명
--host 0.0.0.0 바인드 주소
--port 8000 포트
--device cuda cuda, cpu, mps
--model sensevoice 시작 시 미리 로드할 모델

Docker 환경 변수:

Env 기본값 설명
FUNASR_PORT 8000 server.py로 전달되는 컨테이너 포트
FUNASR_DEVICE cpu 컨테이너 디바이스 모드. CUDA 지원 의존성이 포함된 이미지에서만 cuda로 설정하세요
FUNASR_MODEL sensevoice 컨테이너 시작 시 로드할 모델 별칭

문제 해결

증상 해결 방법
CUDA를 사용할 수 없음 먼저 --device cpu로 smoke test를 통과시키세요.
8000 포트가 사용 중 --port 9000으로 바꾸고 BASE_URL=http://localhost:9000 bash smoke_test.sh 또는 python smoke_test.py --base-url http://localhost:9000을 실행하세요.
모델 다운로드가 느림 안정적인 네트워크에서 다시 시도하거나 ModelScope/Hugging Face에서 모델을 미리 다운로드하세요.
Dify/n8n 컨테이너에서 localhost 접속 실패 워크플로 런타임에서 접근 가능한 호스트명, Compose service name 또는 Kubernetes service name을 사용하세요.
응답에 segments가 없음 response_format=verbose_json를 설정하세요.