test(melo): add Dockerfile and document native-build failures
User hit "Failed building wheel for tokenizers / fugashi / mecab-python3" on first install. Root cause is missing prebuilt wheels (typically Python 3.12+) and missing MeCab/Rust system tools. - Dockerfile: python:3.11-slim + MeCab + Rust, one-shot path that bypasses host setup entirely. - README: explicit "Python 3.10/3.11 OR Docker" guidance, per-error troubleshooting, OS-specific system-package commands. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Claude Owner
35
melo-test/Dockerfile
Normal file
35
melo-test/Dockerfile
Normal file
@@ -0,0 +1,35 @@
|
||||
# MeloTTS-Korean 테스트 서버 컨테이너.
|
||||
# 호스트에 Python/MeCab/Rust 안 깔고 싶을 때 사용.
|
||||
#
|
||||
# 빌드: docker build -t melo-test .
|
||||
# 실행: docker run --rm -p 7860:7860 melo-test
|
||||
# (가중치 캐시 유지하려면: -v melo-cache:/root/.cache/huggingface)
|
||||
FROM python:3.11-slim
|
||||
|
||||
# fugashi/mecab-python3 빌드용 MeCab + tokenizers 빌드용 Rust + 기본 빌드 툴
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
build-essential \
|
||||
git \
|
||||
curl \
|
||||
ca-certificates \
|
||||
mecab \
|
||||
libmecab-dev \
|
||||
mecab-ipadic-utf8 \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Rust (tokenizers 소스 빌드 fallback 대비)
|
||||
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
|
||||
| sh -s -- -y --default-toolchain stable --profile minimal
|
||||
ENV PATH="/root/.cargo/bin:${PATH}"
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY requirements.txt .
|
||||
RUN pip install --upgrade pip setuptools wheel \
|
||||
&& pip install -r requirements.txt
|
||||
|
||||
COPY . .
|
||||
|
||||
EXPOSE 7860
|
||||
ENV PORT=7860
|
||||
CMD ["python", "server.py"]
|
||||
@@ -7,39 +7,67 @@
|
||||
- `server.py` — FastAPI 서버 (`POST /tts` → wav 반환, `/` → 정적 페이지)
|
||||
- `index.html` — 텍스트 입력 + 합성 + 재생 UI
|
||||
- `requirements.txt` — Python 의존성
|
||||
- `Dockerfile` — 호스트 셋업 없이 한 번에 돌리고 싶을 때 사용
|
||||
|
||||
## 사전 요구
|
||||
## ⚠️ 설치 전 체크
|
||||
|
||||
- Python 3.9 ~ 3.11 (MeloTTS 권장 범위)
|
||||
- ffmpeg 불필요 (테스트는 wav 그대로 재생)
|
||||
- 첫 실행 시 모델 가중치(수백 MB) 다운로드. 시간/디스크 여유 확인
|
||||
- CPU 만으로 동작. GPU 있으면 자동으로 사용 (`MELO_DEVICE=cuda` 명시 가능)
|
||||
MeloTTS 의존성(`fugashi`, `mecab-python3`, `tokenizers`)이 네이티브 빌드를 요구합니다.
|
||||
사전 빌드 wheel 이 없는 환경(특히 **Python 3.12+**)에서는
|
||||
`ERROR: Failed building wheel for tokenizers` / `fugashi` / `mecab-python3` 가 발생합니다.
|
||||
|
||||
## 설치 & 실행
|
||||
가장 빠른 해결은 둘 중 하나:
|
||||
|
||||
1. **Python 을 3.10 또는 3.11 로 맞추기** (권장, 기존 wheel 활용)
|
||||
2. **Docker 사용** (호스트에 아무것도 설치하지 않음, 아래 "방법 B" 참조)
|
||||
|
||||
소스 빌드를 굳이 하고 싶으면 OS 별 시스템 패키지 설치 필요:
|
||||
|
||||
- Ubuntu/Debian: `sudo apt install build-essential mecab libmecab-dev mecab-ipadic-utf8 cargo`
|
||||
- macOS: `brew install mecab rust` (그리고 Xcode CLT)
|
||||
- Windows: WSL2 또는 Docker 권장 (네이티브에서는 MeCab 빌드가 까다로움)
|
||||
|
||||
## 방법 A — 로컬 Python (3.10 또는 3.11)
|
||||
|
||||
```bash
|
||||
# 1. 가상환경 (권장)
|
||||
# 0. Python 버전 확인 — 반드시 3.10.x 또는 3.11.x
|
||||
python --version
|
||||
|
||||
# 1. 가상환경
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
|
||||
# 2. 의존성
|
||||
pip install --upgrade pip
|
||||
pip install --upgrade pip setuptools wheel
|
||||
pip install -r requirements.txt
|
||||
|
||||
# (선택) 일본어 모델을 함께 쓸 경우에만 필요
|
||||
# python -m unidic download
|
||||
|
||||
# 3. 서버 실행
|
||||
# 3. 실행
|
||||
python server.py
|
||||
# 또는 포트 변경: PORT=8000 python server.py
|
||||
# 포트 변경: PORT=8000 python server.py
|
||||
```
|
||||
|
||||
서버가 뜨면 브라우저에서 다음 주소 열기:
|
||||
> Python 3.12+ 에서 위 단계가 깨지면 → 3.11 설치 후 재시도하거나 방법 B 로 넘어가세요.
|
||||
> pyenv 사용 예: `pyenv install 3.11.9 && pyenv local 3.11.9`
|
||||
|
||||
```
|
||||
http://localhost:7860
|
||||
## 방법 B — Docker (호스트 셋업 0, Python 버전 신경 X)
|
||||
|
||||
```bash
|
||||
# 빌드 (한 번만, MeCab/Rust/Python 모두 포함, 3~5분)
|
||||
docker build -t melo-test .
|
||||
|
||||
# 실행
|
||||
docker run --rm -p 7860:7860 melo-test
|
||||
|
||||
# 모델 가중치 캐시 유지 (다음 실행부터 다운로드 생략)
|
||||
docker run --rm -p 7860:7860 \
|
||||
-v melo-cache:/root/.cache/huggingface \
|
||||
melo-test
|
||||
```
|
||||
|
||||
브라우저에서 `http://localhost:7860`.
|
||||
|
||||
## 사용
|
||||
|
||||
서버가 뜨면 브라우저에서 `http://localhost:7860` 열기.
|
||||
텍스트 입력 → `합성` 클릭 → 오디오 플레이어에서 즉시 재생.
|
||||
응답 헤더 `X-Synth-Ms` 로 합성 소요 시간(ms) 확인 가능.
|
||||
|
||||
@@ -61,12 +89,30 @@ Content-Type: application/json
|
||||
| `PORT` | `7860` | 바인드 포트 |
|
||||
| `MELO_DEVICE` | `auto` | `cpu` / `cuda` / `mps` / `auto` |
|
||||
|
||||
## 문제 해결
|
||||
## 자주 발생하는 오류
|
||||
|
||||
- 첫 합성이 30초 이상 걸리면 정상 (모델 로딩 + JIT 워밍업). 두 번째부터 ms 단위.
|
||||
- `ModuleNotFoundError: melo` → `pip install -r requirements.txt` 가 실패한 경우. 가상환경 활성화 여부 확인.
|
||||
- 한국어 발음이 깨질 때 → 입력에 영문/이모지가 섞이면 운율이 어색해질 수 있음. 디스코드 봇 통합 단계에서 `TTSClient.textReplace` 와 같은 사전 치환을 그대로 활용.
|
||||
- 디스코드에 붙이려면: MeloTTS 컨테이너를 LAN(예: 시그니처 서버 옆)에 띄우고, `src/utils/tts/Chzzk.ts` 와 같은 시그니처의 `textToSpeech(text): Promise<Buffer>` 어댑터(`src/utils/tts/Melo.ts`)를 추가한 뒤 `src/classes/TTSClient.ts` 의 import 만 교체.
|
||||
`ERROR: Failed building wheel for tokenizers`
|
||||
→ Python 3.12+ 에서 대부분 발생. 3.10/3.11 로 낮추거나 Docker 사용.
|
||||
소스 빌드를 강행하려면 Rust 설치: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
|
||||
|
||||
`ERROR: Failed building wheel for fugashi / mecab-python3`
|
||||
→ MeCab 시스템 라이브러리 부재. Ubuntu `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`, macOS `brew install mecab`.
|
||||
Korean 만 쓰지만 MeloTTS 설치 시 일본어 의존성이 같이 끌려옵니다(런타임엔 사용 안 됨).
|
||||
|
||||
`ModuleNotFoundError: melo`
|
||||
→ `pip install -r requirements.txt` 가 실제로 끝까지 성공했는지 확인. 위 빌드 에러가 있으면 melo 가 설치되지 않은 상태.
|
||||
|
||||
첫 합성이 30초 이상 걸림
|
||||
→ 정상 (모델 가중치 다운로드 + 워밍업). 두 번째 호출부터 ms 단위.
|
||||
|
||||
한국어 발음이 깨짐
|
||||
→ 입력에 영문/이모지가 섞이면 운율이 어색해질 수 있음. 디스코드 봇 통합 단계에서 `TTSClient.textReplace` 같은 사전 치환을 그대로 활용.
|
||||
|
||||
## 디스코드 봇 연동 (테스트 성공 후)
|
||||
|
||||
MeloTTS 서버를 LAN(예: 시그니처 서버 옆)에 띄우고,
|
||||
`src/utils/tts/Chzzk.ts` 와 같은 시그니처의 `textToSpeech(text): Promise<Buffer>` 어댑터
|
||||
(`src/utils/tts/Melo.ts`)를 추가한 뒤 `src/classes/TTSClient.ts` 의 import 만 교체.
|
||||
|
||||
## 참고
|
||||
|
||||
|
||||
Reference in New Issue
Block a user