English | 简体中文 | 繁體中文 | Русский

ScribeCrate

오픈소스, 자체 호스팅 전사 API.

Docker Pulls

License: MIT

Open In Colab

ScribeCrate는 오디오를 전사하고, 자막을 생성하며, 음성을 영어로 번역하기 위한 자체 호스팅(self-hosted) 음성-텍스트 API입니다. Whisper 모델을 기반으로 하며, faster-whisper를 통해 구동되는 OpenAI와 호환되는 전사 및 번역 엔드포인트를 제공합니다. Docker를 사용하여 CPU 또는 NVIDIA GPU에서 배포할 수 있습니다.

이전에는 docker-whisper로 알려졌으며, hwdsl2가 유지 관리하고 있습니다. Docker 이미지는 여전히 hwdsl2/whisper-server입니다.

주요 기능:

• OpenAI와 호환되는 API: OpenAI Whisper API를 지원하는 클라이언트와의 통합을 위해 POST /v1/audio/transcriptions 및 POST /v1/audio/translations 엔드포인트를 제공합니다.

• 개인적이고 로컬한 처리: 오디오는 서버에 남아 있으며 전사를 위해 제3자에게 전송되지 않습니다.

• 화자 분리(Speaker diarization): 선택적 로컬 sherpa-onnx 확장을 사용하여 각 세그먼트에서 누가 말하고 있는지 식별할 수 있습니다.

• 스트리밍 결과: stream=true를 추가하여 전체 업로드 파일 처리가 완료될 때까지 기다릴 필요 없이, 디코딩되는 즉시 Server-Sent Events(SSE)를 통해 전사 세그먼트를 받을 수 있습니다.

• Whisper 모델 지원: tiny, base, small, medium, large-v3, large-v3-turbo 등 다양한 모델을 선택할 수 있습니다.

• CPU 및 GPU 지원: CPU에서 실행하거나, :cuda 이미지를 사용하여 NVIDIA GPU로 추론 속도를 높일 수 있습니다.

• 광범위한 오디오 형식 지원: MP3, M4A, WAV, WebM, OGG, FLAC 등 FFmpeg이 지원하는 다른 오디오 형식을 지원합니다.

• 유연한 출력: JSON, 일반 텍스트(plain text), 상세 JSON(verbose JSON), SRT 자막, WebVTT 자막을 지원합니다.

• 오프라인 작동: 사전 캐시된 모델과 WHISPER_LOCAL_ONLY를 사용하여 인터넷 연결 없이 실행할 수 있습니다.

• 자동 빌드: 이미지는 GitHub Actions을 통해 자동으로 빌드 및 게시되며, 공개적으로 접근 가능한 빌드 워크플로우가 제공됩니다.

또한 단일 명령어로 완전한 자체 호스팅 AI 스택을 배포하는 Self-Hosted AI Stack의 일부로도 사용할 수 있습니다.

📘 The Self-Hosted AI Builder’s Guide는 자체 프라이빗(private) AI 스택을 구축, 보안 및 운영하기 위한 실용적인 가이드입니다.

추가 이용 가능:

• 온라인으로 사용해 보기: Colab에서 열기 — Docker나 설치가 필요 없습니다
• 관련 AI 서비스: ScribeCrate Live, SpeakCrate, EmbedCrate, GatewayCrate, InferCrate, ParseCrate, UplinkCrate

빠른 시작 (Quick start)

다음 명령어를 사용하여 ScribeCrate를 시작하세요:

docker run \
    --name whisper \
    --restart=always \
...

NVIDIA GPU가 있는 경우, 하드웨어 가속 추론(hardware-accelerated inference)을 위해 :cuda 이미지를 사용하세요:

docker run \
    --name whisper \
    --restart=always \
...

필수 조건: NVIDIA GPU, NVIDIA 드라이버 575.57.08+ (Linux) 또는 576.57+ (Windows), 그리고 호스트에 NVIDIA Container Toolkit이 설치되어 있어야 합니다. :cuda 이미지는 linux/amd64 전용입니다.

중요: 이 이미지는 기본 base 모델의 경우 최소 700MB의 사용 가능한 RAM을 필요로 합니다. RAM이 512MB 이하인 시스템은 지원되지 않습니다.

[!NOTE]
인터넷에 노출되는 배포의 경우 HTTPS를 추가하기 위해 리버스 프록시 (reverse proxy)를 사용하세요. 또한, 암호화되지 않은 포트로의 직접적인 접근을 방지하려면 위의 docker run 명령어에서 -p 9000:9000을 -p 127.0.0.1:9000:9000으로 교체하세요.

Whisper의 base 모델(~145 MB)은 첫 시작 시 다운로드되어 캐시됩니다. 서버가 준비되었는지 확인하려면 로그를 확인하세요:

docker logs whisper

"ScribeCrate transcription server is ready" 메시지가 표시되면, 위에 표시된 영구 볼륨(persistent volume)을 사용하여 새로 설치된 API 키를 검색하세요:

scribe_api_key="$(docker exec whisper whisper_manage --getkey)"

서버 주소로 your_server_ip를, 오디오 파일로 audio.mp3을 대체하여 첫 번째 오디오 파일을 전사하세요:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer $scribe_api_key" \
    -F [email protected] \
...

응답:

{"text": "Your transcribed text appears here."}

팁: 테스트에 사용할 샘플 오디오 파일이 필요합니까? Azure Samples 리포지토리에서 이 영어 음성 샘플(WAV, MIT License)을 다운로드하세요:

curl -L -o sample_speech.wav \
    "https://github.com/Azure-Samples/cognitive-services-speech-sdk/raw/master/sampledata/audiofiles/katiesteve.wav"

...

또는, Docker 없이 Whisper를 설정할 수도 있습니다. 이 이미지를 사용하는 방법에 대해 더 자세히 알아보려면 아래 섹션을 읽어보세요.

ScribeCrate 대 ScribeCrate Live

ScribeCrate Live는 WhisperLive를 기반으로 별도로 배포된 서버입니다.

커뮤니티

• 💬 토론 및 전시를 위해 r/selfhostedstack 커뮤니티에 참여하세요.
• ⭐ 유용하다고 생각되면 저장소(repository)에 별표(Star)를 눌러주세요. 다른 사람들이 발견하는 데 도움이 됩니다.

• IPsec VPN 설정
• Docker용 IPsec VPN 서버
• WireGuard
• OpenVPN
• Headscale

요구 사항 (Requirements)

• Docker가 설치된 Linux 서버 (로컬 또는 클라우드)
• 지원되는 아키텍처: amd64 (x86_64), arm64 (예: Raspberry Pi 4/5, AWS Graviton)
• 최소 RAM: 기본 base 모델의 경우 약 700 MB 여유 공간 필요 (모델 테이블 model table 참조)
• 초기 모델 다운로드를 위한 인터넷 접속 (이후 모델은 로컬에 캐시됨). 사전 캐시된 모델을 사용하고 WHISPER_LOCAL_ONLY=true를 사용하는 경우 필수는 아닙니다.

GPU 가속화를 위해 (:cuda 이미지):

• CUDA 지원 NVIDIA GPU (Compute Capability 6.0 이상)
• 호스트에 NVIDIA 드라이버 575.57.08+ (Linux) 또는 576.57+ (Windows) 설치
• NVIDIA Container Toolkit 설치
• :cuda 이미지는 linux/amd64만 지원합니다.

인터넷에 노출되는 배포의 경우, HTTPS를 추가하려면 리버스 프록시 사용하기를 참조하세요.

다운로드 (Download)

Docker Hub 레지스트리에서 신뢰할 수 있는 빌드를 받으세요:

docker pull hwdsl2/whisper-server

NVIDIA GPU 가속화를 위해서는 대신 :cuda 태그를 풀(pull)하세요:

docker pull hwdsl2/whisper-server:cuda

대안으로, Quay.io에서 다운로드할 수 있습니다:

docker pull quay.io/hwdsl2/whisper-server
docker image tag quay.io/hwdsl2/whisper-server hwdsl2/whisper-server

CPU 이미지는 linux/amd64 및 linux/arm64를 지원합니다. :cuda 태그는 linux/amd64만 지원합니다.

환경 변수 (Environment variables)

모든 변수는 선택 사항입니다. /var/lib/whisper 볼륨이 마운트된 초기 설치(Fresh installs)에서는 Bearer 토큰이 자동으로 생성됩니다. 키가 없는 기존 설치는 하위 호환성을 위해 열려 있습니다.

이 Docker 이미지는 다음 변수들을 사용하며, 이들은 env 파일에 선언할 수 있습니다 (예시 example 참조):

env 파일을 사용하는 예시:

cp whisper.env.example whisper.env
# 설정을 위해 whisper.env를 편집한 후 다음을 실행합니다:
docker run \
...

이 env 파일은 컨테이너 내부로 바인드 마운트(bind-mounted)되므로, 컨테이너를 재생성하지 않고도 재시작 시 변경 사항이 반영됩니다.

docker run \
    --name whisper \
    --restart=always \
...

docker-compose 사용하기 (Using docker-compose)

cp whisper.env.example whisper.env
# 필요한 경우 whisper.env를 편집한 후 다음을 실행합니다:
docker compose up -d
...

예시 docker-compose.yml (이미 포함됨):

services:
  whisper:
    image: hwdsl2/whisper-server
...

⚠️ [참고] 인터넷에 노출되는 배포 환경에서는 HTTPS를 추가하기 위해 리버스 프록시를 사용하세요. 또한, 암호화되지 않은 포트로의 직접적인 접근을 방지하려면 docker-compose.yml 파일에서 "9000:9000/tcp"를 "127.0.0.1:9000:9000/tcp"로 변경하세요.

GPU 배포 환경을 위해 별도의 docker-compose.cuda.yml 파일이 제공됩니다:

cp whisper.env.example whisper.env
# 필요에 따라 whisper.env를 편집한 후 다음 명령어를 실행하세요:
docker compose -f docker-compose.cuda.yml up -d
...

예시 docker-compose.cuda.yml (이미 포함됨):

services:
  whisper:
    image: hwdsl2/whisper-server:cuda
...

API 참조

ScribeCrate는 OpenAI의 오디오 전사(audio transcription) 및 오디오 번역(audio translation) 인터페이스와 호환되는 엔드포인트를 제공합니다. OpenAI SDK를 사용하는 클라이언트는 기본 URL을 구성하고 ScribeCrate API 키를 사용하세요:

인증: 신규 영구 설치에는 API 키가 필요합니다. 아래의 SDK 구성 및 curl 예제에서 이 키를 가져오세요:

scribe_api_key="$(docker exec whisper whisper_manage --getkey)"

export OPENAI_BASE_URL="http://your_server_ip:9000/v1"
...

API 키 인증이 비활성화된 경우, curl 예제에서 Authorization 헤더를 생략하세요. OpenAI SDK 클라이언트도 여전히 비어있지 않은 키가 필요하므로, OPENAI_API_KEY=unused로 설정하세요.

스피커 화자 분리(Speaker diarization)는 활성화할 경우 로컬 sherpa-onnx 확장 기능이며, OpenAI의 화자 분리 모델과 동등하지 않습니다. gpt-4o-transcribe-diarize, response_format=diarized_json, include=logprobs, chunking_strategy, known_speaker_names, known_speaker_references와 같은 OpenAI 전용 전사 옵션은 지원되지 않으며 400 에러를 반환합니다.

오디오 전사(Transcribe audio)

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

매개변수(Parameters):

예시: