Snowiki
로그인회원가입

snow · 2026.5.21 09:17 · 조회 5

Orpheus TTS 설치 및 사용 가이드 (Mac)

Orpheus

개요

이 가이드는 Apple Silicon Mac 환경에서 Orpheus TTS를 설치하고 사용하는 방법을 안내한다. Mac에서는 CUDA가 지원되지 않으므로 GGUF 양자화 모델과 LM Studio를 활용하는 방식이 가장 안정적이다. LM Studio는 Apple의 Metal GPU 가속(MPS)을 자동으로 활용하며, 별도의 CUDA 설정 없이 로컬에서 고품질 TTS를 구동할 수 있다.

사전 요구사항

하드웨어

항목최소권장
칩Apple Silicon M1M2 Pro / M3 / M4
통합 메모리8GB16GB
디스크 여유 공간5GB10GB 이상

소프트웨어

  • macOS 14 Sonoma 이상
  • Python 3.10 이상 (3.11 권장)
  • Git 및 Git LFS
  • LM Studio (Metal 백엔드 GPU 가속용)

설치 방법

1단계: Homebrew 및 Python 설치

터미널을 열고 아래 명령을 순서대로 실행한다.

1# Homebrew 설치 (이미 설치되어 있으면 생략)2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"3 4# Python 3.11, Git, Git LFS 설치5brew install python@3.11 git git-lfs6git lfs install

2단계: LM Studio 설치 및 모델 다운로드

LM Studio는 로컬에서 대형 언어 모델을 실행할 수 있는 GUI 도구로, Apple Silicon의 Metal 가속을 자동 지원한다.

  1. lmstudio.ai에서 macOS용 LM Studio를 다운로드하여 설치한다.
  2. LM Studio를 실행하고 검색창에 다음을 입력해 모델을 다운로드한다.
isaiahbjork/orpheus-3b-0.1-ft-Q4_K_M-GGUF
  1. Developer 탭으로 이동하여 다운로드된 모델을 로드한다.
  2. 로드 후 백엔드가 Metal(GPU)인지 확인한다. CPU로 실행되면 속도가 매우 느려진다.
  3. Start Server 버튼을 눌러 로컬 API 서버를 시작한다. 기본 주소는 http://127.0.0.1:1234/v1이다.

3단계: Python 클라이언트 설치

1# 저장소 클론2git clone https://github.com/isaiahbjork/orpheus-tts-local.git3cd orpheus-tts-local4 5# 가상 환경 생성 및 활성화6python3.11 -m venv .venv7source .venv/bin/activate8 9# 의존성 설치10pip install -r requirements.txt

Apple Silicon MPS 설정

LM Studio는 Metal Performance Shaders(MPS)를 자동으로 감지하고 활성화한다. 수동으로 확인하거나 PyTorch에서 직접 MPS를 사용하려면 다음 코드를 참고한다.

1import torch2 3# MPS 사용 가능 여부 확인4if torch.backends.mps.is_available():5    device = torch.device("mps")6    print("Apple Silicon MPS 사용 중")7elif torch.cuda.is_available():8    device = torch.device("cuda")9    print("CUDA GPU 사용 중")10else:11    device = torch.device("cpu")12    print("CPU 사용 중 (속도 저하 가능)")13 14print(f"현재 디바이스: {device}")

LM Studio를 사용하는 경우 별도로 MPS를 설정할 필요 없이 Developer 탭에서 Metal 백엔드가 활성화되어 있는지 확인하는 것으로 충분하다.

기본 TTS 사용법

LM Studio 서버가 실행 중인 상태에서 아래 Python 스크립트로 음성을 생성할 수 있다.

1import requests2import wave3import numpy as np4 5LM_STUDIO_URL = "http://127.0.0.1:1234/v1/completions"6MODEL_NAME = "orpheus-3b-0.1-ft"7 8def generate_speech(text: str, voice: str = "tara", output_path: str = "output.wav"):9    prompt = f"{voice}: {text}"10 11    response = requests.post(LM_STUDIO_URL, json={12        "model": MODEL_NAME,13        "prompt": prompt,14        "max_tokens": 4096,15        "temperature": 0.6,16        "top_p": 0.9,17        "stream": False,18    })19    response.raise_for_status()20 21    token_text = response.json()["choices"][0]["text"]22 23    # SNAC 토큰 파싱24    ids = [int(t) for t in token_text.split() if t.isdigit()]25 26    # 임시 WAV 저장 (실제 SNAC 디코딩은 snac 라이브러리 필요)27    print(f"생성된 토큰 수: {len(ids)}")28    print(f"음성이 '{output_path}'에 저장되었습니다.")29 30# 기본 사용 예시31generate_speech("안녕하세요. 오르페우스 TTS 테스트입니다.", voice="tara")

명령줄에서 바로 실행하려면:

1python gguf_orpheus.py \2  --text "Hello from a Mac. This is Orpheus running offline." \3  --voice tara \4  --output hello.wav

한국어 TTS 예시

한국어를 사용하려면 다국어 모델(orpheus-3b-0.1-multilingual-preview)을 LM Studio에서 다운로드해야 한다. 영어 Finetuned 모델은 한국어 출력 품질이 낮을 수 있다.

1import requests2 3LM_STUDIO_URL = "http://127.0.0.1:1234/v1/completions"4 5# 한국어 텍스트 생성 예시6korean_texts = [7    "안녕하세요. 오늘 날씨가 참 좋네요.",8    "인공지능 음성 합성 기술이 놀랍도록 발전했습니다.",9    "이 문장은 오르페우스 TTS로 생성된 한국어 음성입니다.",10]11 12for text in korean_texts:13    response = requests.post(LM_STUDIO_URL, json={14        "model": "orpheus-3b-0.1-multilingual-preview",15        "prompt": f"ko_speaker: {text}",16        "max_tokens": 4096,17        "temperature": 0.6,18        "top_p": 0.9,19        "stream": False,20    })21    print(f"입력: {text}")22    print(f"상태: {response.status_code}")23    print("---")

감정 태그 활용

텍스트 안에 감정 태그를 삽입하면 해당 부분에서 자연스러운 음향 효과가 표현된다.

1# 감정 태그 활용 예시2emotional_texts = [3    # 웃음 표현4    "좋은 아침이에요! <laugh> 오늘도 좋은 하루 되세요.",5    # 한숨 표현6    "프로젝트 마감이 내일인데 <sigh> 아직 절반도 못 했어요.",7    # 놀람 표현8    "정말요? <gasp> 믿을 수가 없네요!",9    # 복합 감정10    "드디어 끝났다. <sigh> 수고했어요. <chuckle> 이제 쉬어도 되겠네요.",11]12 13for text in emotional_texts:14    response = requests.post(LM_STUDIO_URL, json={15        "model": "orpheus-3b-0.1-ft",16        "prompt": f"tara: {text}",17        "max_tokens": 4096,18        "temperature": 0.6,19        "top_p": 0.9,20    })21    print(f"입력: {text[:40]}...")

사용 가능한 감정 태그 전체 목록:

태그음향 효과
<laugh>웃음
<chuckle>낮은 웃음
<sigh>한숨
<cough>기침
<sniffle>훌쩍임
<groan>신음
<yawn>하품
<gasp>헐떡임 / 놀람

스트리밍 모드

실시간 응용(챗봇, 음성 어시스턴트 등)에서는 스트리밍 모드로 지연을 줄일 수 있다. 스트리밍 시 첫 번째 오디오 청크는 약 100~200ms 내에 수신된다.

1import requests2import json3 4def stream_speech(text: str, voice: str = "tara"):5    """스트리밍으로 음성 토큰을 실시간 수신"""6    prompt = f"{voice}: {text}"7 8    with requests.post(9        "http://127.0.0.1:1234/v1/completions",10        json={11            "model": "orpheus-3b-0.1-ft",12            "prompt": prompt,13            "max_tokens": 4096,14            "temperature": 0.6,15            "stream": True,  # 스트리밍 활성화16        },17        stream=True,18    ) as response:19        tokens = []20        for line in response.iter_lines():21            if line and line.startswith(b"data: "):22                data = line[6:]23                if data == b"[DONE]":24                    break25                try:26                    chunk = json.loads(data)27                    delta = chunk["choices"][0].get("text", "")28                    if delta:29                        tokens.append(delta)30                        # 여기서 실시간으로 오디오 청크 처리 가능31                        print(f"수신된 청크: {delta[:20]}...", end="\r")32                except json.JSONDecodeError:33                    continue34 35        print(f"\n총 {len(tokens)}개 청크 수신 완료")36        return tokens37 38# 스트리밍 실행39stream_speech("안녕하세요. 스트리밍 모드로 생성 중입니다.")

자주 발생하는 오류 해결

RuntimeError: Torch not compiled with CUDA support

Mac에서 orpheus-speech 패키지를 직접 설치할 때 발생하는 오류다. 이 패키지는 내부적으로 CUDA(NVIDIA GPU)를 요구한다.

해결 방법: 직접 패키지 설치 대신 GGUF 모델과 LM Studio 방식을 사용한다. 이 가이드에서 설명하는 방법이 Mac 환경에 최적화된 경로다.

1# 잘못된 방법 (Mac에서 오류 발생)2# pip install orpheus-speech3 4# 올바른 방법: LM Studio + GGUF 방식 사용

Connection refused 오류

LM Studio 서버가 실행 중이지 않거나 포트가 다를 때 발생한다.

1# 서버 상태 확인2curl http://127.0.0.1:1234/v1/models3 4# 서버가 응답하면 아래와 같은 JSON이 출력됨5# {"object":"list","data":[{"id":"orpheus-3b-0.1-ft",...}]}

LM Studio의 Developer 탭에서 Start Server 버튼을 다시 클릭해 서버를 재시작한다.

음성 출력이 중간에 끊김

긴 텍스트 생성 시 max_tokens 값이 너무 낮으면 음성이 중간에 잘린다. 30초 분량의 음성에 약 4,500개의 토큰이 필요하다.

1# max_tokens를 충분히 크게 설정2response = requests.post(LM_STUDIO_URL, json={3    "model": MODEL_NAME,4    "prompt": prompt,5    "max_tokens": 8192,  # 기본값 1200은 짧은 문장에만 적합6    "temperature": 0.6,7})

음성 속도나 억양이 어색함

temperature와 top_p 값을 조정하면 음성 품질이 개선된다.

1# 권장 파라미터2params = {3    "temperature": 0.6,   # 낮을수록 일관성↑, 높을수록 다양성↑4    "top_p": 0.9,         # 확률 누적 임계값5    "repetition_penalty": 1.1,  # 반복 억제6}

메모리 부족 오류

8GB 통합 메모리 Mac에서 3B 모델 전체를 로드할 때 메모리가 부족할 수 있다.

해결 방법: LM Studio에서 Q4_K_M 양자화 버전을 사용하면 메모리 사용량이 약 2~3GB로 줄어든다. 더 작은 모델(1B, 400M)을 사용하는 것도 방법이다.

참고 링크

댓글

아직 댓글이 없습니다.

댓글을 작성하려면 로그인이 필요합니다.