multimodal-serving-lab

생성·멀티모달 AI 모델을 로컬 환경에서 직접 실행·서빙·최적화해 본 기록을 정리한 저장소입니다.

이미지/비디오에서 시작해 음성(TTS/STT), LLM, 토킹헤드 아바타까지 모달리티를 넓히며, 각 모델을 서빙 프레임워크(BentoML / Triton / vLLM) 로 패키징·최적화·배포하는 0→1 과정을 실험합니다. 별도의 serve/는 서빙 런타임의 내부 동작(동적 배칭·큐·지연/처리량)을 직접 구현해 이해하기 위한 학습용 baseline이며, 프레임워크 결과와 나란히 비교하는 기준선으로 씁니다. Apple Silicon/MPS를 기본으로 하고, 무거운 실험은 클라우드 GPU에서 진행합니다. 완성된 제품이 아니라 "무엇이 가능했고 어떤 한계가 있었는지"를 남기는 실험 아카이브입니다.

모델 파일, 가상환경, 생성 결과물(이미지/영상/오디오/모션)은 저장소에 포함하지 않습니다.

구성

• serve/: 서빙 내부 원리 학습용 baseline + 벤치마크 하니스 — 직접 구현한 큐·동적 배칭·메트릭(프레임워크 비교 기준선). 실제 서빙은 BentoML/Triton/vLLM 사용
• sd-gen/: Stable Diffusion 기반 이미지 생성, ComfyUI 연동, 단발 생성, 업스케일
• video-gen/: AnimateDiff, Zeroscope, LTX 계열 비디오 생성
• tts-gen/: 음성 합성(Piper) 서빙·최적화 — BentoML 패키징, RTF·동시성 벤치
• stt-gen/: 음성 인식(faster-whisper) 서빙·최적화 — int8 양자화 RTF/WER/메모리, TTS↔STT 왕복
• llm-serve/: LLM 서빙·양자화 최적화 — 로컬 Ollama(OpenAI 호환)↔클라우드 vLLM 전환 구조, 양자화/배칭 벤치
• voice-agent/: STT→LLM→TTS 음성 에이전트 — 대화 턴 end-to-end 지연 예산 측정(병목: warm=STT, cold=LLM)
• s2s-gen/: 음성 대화 파이프라인 비교 — cascade(STT→LLM→TTS) vs csm(TTS만 Sesame CSM 표현형, MPS) vs moshi(full-duplex 라이브, lab-ui 런처). 같은 축에서 TTFA·E2E·RTF 측정. CSM 은 로드가 무거워 csm-tts BentoML 상주 서비스(stt-gen/tts-gen 와 동일 패턴)로 띄워 저지연 합성하고, "인프로세스 vs 서빙" 지연 트레이드오프를 실측
• avatar-gen/: 토킹헤드·립싱크 아바타 파이프라인(text→LLM→TTS→lip-sync) — 사전 스캐폴드, static 백엔드로 지금 동작·립싱크 모델 교체형(wav2lip/musetalk)
• lab-ui/: 위 실험들을 브라우저에서 실행·확인하는 랩 대시보드(FastAPI) — 각 CLI를 allowlist 인자로 subprocess 실행, preflight로 준비 상태 안내
• docs/project-flow-and-terms.md: 흐름·용어·실험 기록 문서 안내
• docs/project-flow.md: 전체 실험 흐름·서브 프로젝트별 로직 해설
• docs/glossary.md: 멀티모달·서빙·최적화 핵심 용어 사전
• docs/experiments.md: 시도한 내용·결과·한계, 벤치 수치 기록

의존성 관리 (uv)

모든 서브 프로젝트는 uv 기반입니다(각 디렉터리에 pyproject.toml + .python-version). 준비는 한 줄:

cd <서브프로젝트>
uv sync            # .venv 생성 + 의존성 설치 (Python 3.11 은 uv 가 자동 확보)
uv run python <script> ...

uv sync 없이 uv run 으로 바로 실행해도 첫 회에 자동으로 동기화됩니다. GPU(NVIDIA) 사용자는 uv sync --extra gpu(sd-gen·tts-gen).

실행 환경 (device 이식성)

모든 서브 프로젝트는 device 파라미터화(Apple Silicon/MPS·CPU 기본, NVIDIA/CUDA 전환 가능):

• TTS(Piper): --cuda 또는 PIPER_CUDA=1 + uv sync --extra gpu(onnxruntime-gpu)
• STT(faster-whisper): device: auto|cuda (GPU는 compute_type: float16|int8_float16)
• LLM: OpenAI 호환 base_url 교체(로컬 Ollama ↔ 클라우드 vLLM)
• avatar: device: auto(cuda→mps→cpu) 자동 감지

실행 예시

이미지 생성:

cd sd-gen
uv sync
uv run python generate.py -p "a cinematic mountain landscape at sunset"

비디오 생성:

cd video-gen
uv sync
uv run python generate.py -p "a cat walking in a garden"

전체 테스트 대시보드 (lab-ui):

cd lab-ui
uv run python app.py
# http://127.0.0.1:7860

• 카드별로 serve/이미지/비디오/TTS/STT/LLM/voice-agent/avatar 실행 폼을 제공하고, 로그·산출물을 보여줍니다.
• 각 카드는 uv run으로 해당 서브 프로젝트를 실행합니다. 첫 실행 시 uv가 그 디렉터리의 .venv를 자동 동기화하므로 별도 준비가 필요 없습니다(무거운 타깃은 첫 회 설치에 시간이 걸립니다).
• 무거운 모델/런타임(모델 다운로드, Ollama, ffmpeg)은 자동 설치하지 않습니다. 각 카드의 preflight 배지가 준비 상태(uv·동기화·외부 런타임)와 다음에 할 일을 안내합니다.

정리

• 모델 캐시는 각 디렉터리의 models/ 아래에 생성되며 Git에 포함하지 않습니다.
• 생성된 이미지와 영상은 outputs/ 아래에 저장되며 Git에 포함하지 않습니다.
• Apple Silicon MPS에서는 float32가 더 안정적이었습니다. fp16은 검은 이미지나 불안정한 결과가 나오는 경우가 있었습니다.
• 이미지 생성은 로컬 실험용으로 충분히 쓸 만했지만, 비디오 생성은 메모리, 해상도, 프레임 수, 모델 성숙도 때문에 품질 한계가 컸습니다.
• img2img로 프레임을 이어 붙이는 방식은 작은 카메라 움직임에는 쓸 수 있지만, 걷기 같은 실제 동작을 만들기에는 한계가 있었습니다.