Next.js + FastAPI + PostgreSQL + Redis 기반 작사 서비스 초기 세팅입니다.
pmtm-fe: Next.js 프론트엔드pmtm-be: FastAPI 백엔드pmtm-ai: 가사 생성 AI 학습/추론 코드 영역pmtm-svs: 8마디 DiffSinger 가이드 랩 추론 런타임docker-compose.yml: 로컬 인프라 실행
cd pmtm-fe
npm install
npm run dev기본 주소: http://localhost:3100
백엔드는 로컬에서 실행합니다. 가사 생성은 업로드한 비트 파일을 librosa로 분석해 BPM을 추정한 뒤,
pmtm-ai/venv의 Qwen/Qwen2.5-3B-Instruct 추론 CLI를 호출합니다.
LLM 선택값 qwen-exp-005-sft는 pmtm-ai/models/exp-005/sft_rap_qwen, qwen-exp-005-grpo는 pmtm-ai/models/exp-005/grpo_rap_qwen LoRA 어댑터를 적용합니다.
OpenAI 선택지를 사용하려면 OPENAI_API_KEY를 설정합니다.
cd pmtm-be
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8100기본 주소: http://localhost:8100
비트 기반 생성 API는 POST /api/v1/lyrics/generate-from-beat를 사용합니다.
요청 형식은 multipart/form-data이며 beat 오디오 파일과 llm 값을 보냅니다.
지원 형식은 MP3, WAV, M4A/MP4, AAC, FLAC이고 파일은 임시 분석 후 저장하지 않습니다.
편집된 가사로 DiffSinger 가이드 랩을 만드는 API는 POST /api/v1/guide-demos를 사용합니다.
요청 형식은 multipart/form-data이며 beat, lyrics, bpm, firstBarStartSec, voicebank 값을 보냅니다.
가사는 비어 있지 않은 정확히 8줄이어야 하며 1줄을 1마디로 렌더링합니다.
응답의 jobId로 GET /api/v1/demos/{jobId}를 polling하고, 완료 후 GET /api/v1/demos/{jobId}/audio에서 데모 오디오를 받을 수 있습니다.
드라이 보컬은 GET /api/v1/demos/{jobId}/vocal, FlowPlan은 GET /api/v1/demos/{jobId}/flow-plan에서 받습니다.
데모 생성은 Redis + RQ 비동기 작업이므로 백엔드와 별도로 워커를 실행해야 합니다.
cd pmtm-be
source .venv/bin/activate
PYTHONPATH=. rq worker demo-generation --worker-class rq.SimpleWorker --url redis://localhost:6380/0로컬 macOS 개발에서는 기본 RQ worker의 fork 방식이 librosa/오디오 분석 단계에서 멈출 수 있어 rq.SimpleWorker를 사용합니다.
SVS는 pmtm-svs의 별도 Python 3.8 환경과 사용자가 직접 준비한 OpenUtau DiffSinger 보이스뱅크가 필요합니다.
설치 및 potg, kitane, rang, lunar 디렉터리 구성은 pmtm-svs/README.md를 따릅니다.
보이스뱅크 파일은 저장소에 포함하거나 재배포하지 않습니다.
MP3/M4A 등 비-WAV 비트 처리와 MP3 데모 출력을 위해 로컬 ffmpeg 설치가 필요합니다.
Docker Compose로 PostgreSQL, Redis만 실행합니다. 프론트엔드와 백엔드는 로컬에서 직접 실행합니다.
docker compose up서비스:
- postgres:
localhost:5433 - redis:
localhost:6380
OpenAI 선택지를 사용하려면 pmtm-be/.env 또는 pmtm-be/.env.local에 키를 넣습니다.
OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-5-miniQwen 로컬 추론은 pmtm-ai의 별도 Python 환경과 모델 캐시가 필요합니다. 로컬 개발에서는 백엔드도 로컬 Python 환경에서 실행합니다.
pmtm-ai는 모델 학습, 추론, 데이터셋, 체크포인트 자산을 분리해서 다루는 디렉터리입니다.
cd pmtm-ai
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt현재 로컬 기본 추론 모델은 Qwen/Qwen2.5-3B-Instruct입니다. 모델 파일은 Hugging Face 캐시에 있어야 하며, 백엔드 기본 설정은 pmtm-ai/.venv/bin/python을 호출합니다.
exp-005 시연 모델은 llm=qwen-exp-005-sft 또는 llm=qwen-exp-005-grpo로 호출하며, 어댑터 파일은 각각 pmtm-ai/models/exp-005/sft_rap_qwen, pmtm-ai/models/exp-005/grpo_rap_qwen에 있어야 합니다.
OpenAI 선택지의 기본 모델은 gpt-5-mini입니다.