zenn
7101fdcd65
FastAPI backend, web UI, CosyVoice3/F5-TTS setup scripts, and handoff docs for GPU PC continuation. Co-authored-by: Cursor <cursoragent@cursor.com>
275 lines
6.9 KiB
Markdown
275 lines
6.9 KiB
Markdown
# 다음 작업자 인수인계 문서
|
|
|
|
이 문서는 한국어 보이스 클로닝 TTS 프로젝트를 다른 PC 또는 다음 AI가 이어받을 때 가장 먼저 읽어야 하는 문서입니다.
|
|
|
|
## 한 줄 요약
|
|
|
|
한국어 자연스러움과 본인 목소리 유사도를 우선하는 로컬 TTS 프로토타입입니다. 기본 모델은 `CosyVoice3`, 비교 모델은 `F5-TTS`이며, FastAPI 백엔드와 간단한 웹 UI까지 만들어져 있습니다.
|
|
|
|
## 현재 작업 상태
|
|
|
|
- 프로젝트 뼈대 생성 완료
|
|
- FastAPI 서버 구현 완료
|
|
- 웹 UI 구현 완료
|
|
- 한국어 텍스트 전처리 구현 완료
|
|
- 내 목소리 reference 녹음 가이드 작성 완료
|
|
- `CosyVoice3` / `F5-TTS` A/B 비교 스크립트 작성 완료
|
|
- 모델별 격리 venv 설치 스크립트 작성 완료
|
|
- 현재 Mac에서 API/UI smoke test 완료
|
|
- 실제 고품질 TTS 추론은 아직 NVIDIA GPU 환경에서 검증 필요
|
|
|
|
## 중요한 전제
|
|
|
|
현재 작업한 Mac은 Apple Silicon 환경이고 `nvidia-smi`가 없습니다. 따라서 여기서는 API/UI 구조 확인은 가능하지만, 계획한 고품질 보이스 클로닝 추론은 Windows 또는 Linux의 NVIDIA GPU PC에서 이어가는 것이 맞습니다.
|
|
|
|
메인 PC가 Windows + NVIDIA GPU라면 다음 순서로 진행하세요. 가능하면 WSL2 Ubuntu 환경을 권장합니다. Windows 네이티브도 가능할 수 있지만, `CosyVoice`는 Linux/WSL2 쪽이 문제 해결 자료가 많습니다.
|
|
|
|
## 깃에 올릴 때 주의
|
|
|
|
올리면 좋은 것:
|
|
|
|
- `README.md`
|
|
- `docs/HANDOFF.md`
|
|
- `backend/`
|
|
- `web/`
|
|
- `scripts/`
|
|
- `config/`
|
|
- `samples/README.md`
|
|
- `samples/my_voice_ref.txt`
|
|
- `.env.example`
|
|
- `.gitignore`
|
|
- `docker-compose.yml`
|
|
- `tests/`
|
|
|
|
올리지 말아야 할 것:
|
|
|
|
- `.venvs/`
|
|
- `models/`
|
|
- `outputs/`
|
|
- `external/CosyVoice/`
|
|
- 실제 내 목소리 WAV 파일
|
|
- `.env` 안에 개인 경로나 민감한 값이 들어간 경우
|
|
|
|
현재 `.gitignore`에는 `.venvs/`, `models/`, `outputs/`, `external/CosyVoice/`, `.env`, WAV 파일 등이 제외되도록 설정되어 있습니다.
|
|
|
|
## 메인 PC에서 처음 할 일
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd tts
|
|
|
|
chmod +x scripts/*.sh
|
|
./scripts/check_env.sh
|
|
```
|
|
|
|
Windows라면 WSL2 Ubuntu에서 실행하는 것을 권장합니다.
|
|
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y git python3 python3-venv python3-pip ffmpeg sox libsox-dev
|
|
```
|
|
|
|
NVIDIA GPU가 제대로 잡히는지 확인하세요.
|
|
|
|
```bash
|
|
nvidia-smi
|
|
```
|
|
|
|
## 환경 설치 순서
|
|
|
|
API 서버용 venv:
|
|
|
|
```bash
|
|
./scripts/setup_api.sh
|
|
```
|
|
|
|
F5-TTS 비교용 venv:
|
|
|
|
```bash
|
|
./scripts/setup_f5tts.sh
|
|
```
|
|
|
|
CosyVoice3 기본 모델용 venv:
|
|
|
|
```bash
|
|
./scripts/setup_cosyvoice.sh
|
|
```
|
|
|
|
`setup_cosyvoice.sh`는 `external/CosyVoice` 레포를 클론하고 `models/Fun-CosyVoice3-0.5B` 모델을 다운로드합니다. 시간이 오래 걸릴 수 있습니다.
|
|
|
|
## 현재 기본 모델
|
|
|
|
기본값은 `cosyvoice`입니다.
|
|
|
|
관련 파일:
|
|
|
|
- `.env.example`
|
|
- `.env`
|
|
- `config/settings.yaml`
|
|
- `config/model_choice.json`
|
|
|
|
모델 변경:
|
|
|
|
```bash
|
|
./scripts/select_model.sh cosyvoice
|
|
./scripts/select_model.sh f5_tts
|
|
```
|
|
|
|
또는 `.env`에서 직접 변경:
|
|
|
|
```env
|
|
TTS_MODEL=cosyvoice
|
|
```
|
|
|
|
## 내 목소리 샘플 준비
|
|
|
|
자세한 가이드는 `samples/README.md`에 있습니다.
|
|
|
|
권장 파일:
|
|
|
|
```text
|
|
samples/my_voice_30s.wav
|
|
samples/my_voice_1m.wav
|
|
samples/my_voice_3m.wav
|
|
samples/my_voice_ref.txt
|
|
```
|
|
|
|
중요:
|
|
|
|
- WAV는 mono, 24kHz 또는 16kHz 권장
|
|
- 녹음 대본과 `my_voice_ref.txt` 내용은 일치해야 함
|
|
- 조용한 환경에서 마이크 거리 일정하게 유지
|
|
- 30초, 1분, 3분 샘플을 각각 비교
|
|
|
|
reference WAV 전처리:
|
|
|
|
```bash
|
|
./scripts/prepare_reference.sh samples/my_voice_30s.wav
|
|
```
|
|
|
|
## 모델 A/B 비교
|
|
|
|
설치 검증용:
|
|
|
|
```bash
|
|
./scripts/run_ab_compare.py --ref-audio auto
|
|
```
|
|
|
|
본인 목소리 비교:
|
|
|
|
```bash
|
|
./scripts/run_ab_compare.py --ref-audio samples/my_voice_30s.wav
|
|
```
|
|
|
|
길이별 reference 비교:
|
|
|
|
```bash
|
|
./scripts/compare_voice_lengths.sh
|
|
```
|
|
|
|
결과는 보통 아래에 생성됩니다.
|
|
|
|
```text
|
|
outputs/ab_compare/
|
|
outputs/voice_length_compare/
|
|
```
|
|
|
|
평가 기준:
|
|
|
|
- 한국어 발음 정확도
|
|
- 조사/어미 자연스러움
|
|
- 억양과 호흡
|
|
- 내 목소리 유사도
|
|
- 긴 문장 안정성
|
|
- 숫자, 영어, 기호 포함 문장 처리
|
|
|
|
## 서버 실행
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
./scripts/run_server.sh
|
|
```
|
|
|
|
브라우저:
|
|
|
|
```text
|
|
http://localhost:8000
|
|
```
|
|
|
|
주요 API:
|
|
|
|
```text
|
|
GET /api/health
|
|
POST /api/tts
|
|
GET /api/audio/{job_id}
|
|
GET /api/voice-samples
|
|
POST /api/voice-sample
|
|
```
|
|
|
|
간단 테스트:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/tts \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"text":"안녕하세요. 한국어 음성 합성 테스트입니다."}'
|
|
```
|
|
|
|
## Mac에서 가능한 것과 불가능한 것
|
|
|
|
현재 Mac에서 가능한 것:
|
|
|
|
- FastAPI 서버 실행
|
|
- 웹 UI 확인
|
|
- `/api/health` 확인
|
|
- 샘플 업로드 UI 확인
|
|
- 텍스트 전처리 테스트
|
|
|
|
현재 Mac에서 어려운 것:
|
|
|
|
- `CosyVoice3` 고품질 추론
|
|
- `F5-TTS` CUDA 기반 추론
|
|
- 최종 품질 평가
|
|
|
|
즉, Mac은 개발/구조 확인용이고, 최종 모델 품질 검증은 NVIDIA GPU PC에서 해야 합니다.
|
|
|
|
## 다음 AI에게 요청할 때 권장 문장
|
|
|
|
다음 AI에게는 아래처럼 시작하면 됩니다.
|
|
|
|
```text
|
|
먼저 docs/HANDOFF.md를 읽고, 현재 한국어 보이스 클로닝 TTS 프로젝트 상태를 파악한 뒤 이어서 작업해줘.
|
|
목표는 Windows/NVIDIA GPU PC에서 CosyVoice3와 F5-TTS를 설치하고, 내 목소리 샘플로 A/B 비교 후 더 자연스러운 모델을 선택하는 거야.
|
|
```
|
|
|
|
## 다음 작업자가 우선 확인할 파일
|
|
|
|
1. `docs/HANDOFF.md`
|
|
2. `README.md`
|
|
3. `config/settings.yaml`
|
|
4. `config/model_choice.json`
|
|
5. `.env.example`
|
|
6. `samples/README.md`
|
|
7. `scripts/setup_cosyvoice.sh`
|
|
8. `scripts/setup_f5tts.sh`
|
|
9. `scripts/run_ab_compare.py`
|
|
10. `backend/app/main.py`
|
|
|
|
## 알려진 주의점
|
|
|
|
- `FastAPI TestClient`는 현재 API venv에서 `httpx` 계열 패키지가 없어 직접 테스트가 실패했습니다. 대신 실제 `uvicorn` 서버를 띄우고 `/api/health`와 웹 UI 200 응답은 확인했습니다.
|
|
- `scripts/setup_f5tts.sh`와 `scripts/setup_cosyvoice.sh`는 CUDA 12.4 PyTorch index를 사용합니다. 메인 PC CUDA 버전에 맞지 않으면 `cu124`를 `cu121`, `cu126`, `cu128` 등으로 조정해야 할 수 있습니다.
|
|
- `CosyVoice`는 `sox`, `libsox-dev`, `ffmpeg`가 필요할 수 있습니다.
|
|
- 실제 음성 파일은 개인정보성이 있으므로 깃에 올리지 않는 것을 권장합니다.
|
|
- `.env`도 깃에 올리지 말고 `.env.example`만 공유하세요.
|
|
|
|
## 완료 기준
|
|
|
|
이 프로젝트의 다음 큰 완료 기준은 다음과 같습니다.
|
|
|
|
- NVIDIA GPU PC에서 `./scripts/setup_cosyvoice.sh` 성공
|
|
- NVIDIA GPU PC에서 `./scripts/setup_f5tts.sh` 성공
|
|
- 본인 목소리 샘플로 `./scripts/run_ab_compare.py` 실행 성공
|
|
- `outputs/ab_compare/` 결과를 듣고 모델 선택
|
|
- 선택 모델로 `./scripts/run_server.sh` 실행
|
|
- 웹 UI에서 텍스트 입력 후 본인 목소리 WAV 재생 성공
|