remsky/Kokoro-FastAPI

Kokoro-FastAPI – Docker 기반 OpenAI 호환 TTS 서비스

개요 – Kokoro-82M 텍스트 음성 변환 모델(8,200만 파라미터 다국어 TTS 모델)을 래핑한 즉시 실행 가능한 FastAPI 서버입니다. 이 서버는 OpenAI의 audio/speech 엔드포인트를 모방하므로 기존 OpenAI 클라이언트 라이브러리를 수정 없이 사용할 수 있습니다. 멀티 아키텍처 Docker 이미지(CPU, NVIDIA-CUDA, AMD-ROCm, Apple-Silicon)로 제공되며 uv를 사용하여 직접 시작할 수도 있습니다.

주요 기능

• OpenAI 호환 음성 API – POST /v1/audio/speech는 OpenAI와 동일한 JSON 필드(model, voice, input, response_format, speed 등)를 허용하며 mp3, wav, opus, flac, aac 또는 raw PCM 형식으로 오디오를 반환합니다.
• 스트리밍 – OpenAI 클라이언트와 표준 requests 모두에서 오디오를 청크 단위로 수신할 수 있어 낮은 첫 토큰 지연 시간(GPU에서 약 300ms, 최신 M 시리즈 CPU에서 약 1초)으로 실시간 재생이 가능합니다.
• 다국어 음성 – 영어(미국/영국), 스페인어, 프랑스어, 힌디어, 이탈리아어, 일본어, 브라질 포르투갈어, 중국어(표준어).
• 음성 믹싱 및 별칭 – 여러 보이스팩을 가중치 비율로 결합(af_bella(2)+af_sky(1))하거나 복잡한 믹스에 대한 짧은 별칭을 정의할 수 있습니다.
• 인라인 SSML 스타일 태그 – [voice:…], [pause:1.5s], [rate:1.5] 및 IPA 발음 태그를 텍스트에 직접 삽입할 수 있습니다.
• 다중 화자 대화 – 음성 태그나 전용 /dev/dialogue 엔드포인트를 사용하여 각 턴마다 고유한 음성을 가진 대화 스크립트를 작성할 수 있습니다.
• 사용자 지정 보이스팩 생성 – Inno-Clone-Tuner (/dev/tune)를 통해 짧은 참조 클립을 기반으로 음성을 미세 조정하고 결과물인 .pt 보이스팩을 저장할 수 있습니다.
• 타임스탬프 자막 – 자막 생성을 위해 단어별 또는 청크별 타임스탬프를 선택적으로 제공합니다.
• 웹 UI – 테스트, 음성 믹스 미리보기 및 긴 텍스트 읽기를 위한 내장 브라우저 UI (/web)가 포함되어 있습니다.
• Kubernetes / DigitalOcean 배포 – Helm 차트와 배포 문서가 제공됩니다.

실행 방법

1. Docker – 적절한 이미지(예: ghcr.io/remsky/kokoro-fastapi-gpu:latest)를 가져오고 8880 포트를 노출합니다.
2. Docker-Compose – 저장소를 복제하고 docker/gpu(또는 cpu/rocm) 폴더를 선택한 후 docker compose up --build를 실행합니다.
3. 직접 실행 – uv와 시스템 종속성을 설치한 후 ./start-gpu.sh 또는 ./start-cpu.sh를 실행합니다.

모든 이미지에는 모델이 포함되어 있습니다. 수동으로 다운로드해야 하는 경우 도우미 스크립트가 제공됩니다.

일반적인 사용 예시 (Python)

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")
resp = client.audio.speech.create(
    model="kokoro",
    voice="af_bella+af_sky",
    input="Hello world!",
    response_format="mp3",
)
resp.stream_to_file("out.mp3")

원시 HTTP를 선호하는 경우 requests에서도 동일한 호출 방식을 사용할 수 있습니다.

이 프로젝트의 중요성

• 자체 호스팅 가능한 OpenAI 호환 TTS 백엔드를 제공하여 외부 유료 API에 대한 의존성을 제거합니다.
• Kokoro-82M 모델은 소비자용 GPU나 CPU에서도 실행될 만큼 가볍지만, 오픈소스 TTS 스택에서 보기 드문 다국어 지원 및 음성 믹싱 기능을 갖추고 있습니다.
• 풍부한 API(스트리밍, 음성 태그, 튜닝, 타임스탬프) 덕분에 음성 비서, 오디오북, 인터랙티브 게임 등 빠르고 제어 가능한 음성 합성이 필요한 모든 애플리케이션에 적합합니다.

---

링크

• 모델 저장소: https://huggingface.co/hexgrad/Kokoro-82M
• Demo Space: https://huggingface.co/spaces/Remsky/FastKoko
• Helm 차트: docs/deployment/kubernetes.md
• 통합 가이드: Home Assistant, SillyTavern, OpenWebUI 등.