음성과 영상이 동기화된 영상을 로컬에서 생성하고 모델에 맞춰 튜닝하는 도구
텍스트를 입력하면 인물의 입모아와 목소리가 자연스럽게 맞춰진 영상이 만들어지는 장면을 떠올려 보세요. 이 저장소는 LTX-2 모델의 추론과 LoRA 학습을 위한 공식 Python 패키지입니다. 복잡한 서버 설정 없이 로컬 환경에서 영상 생성 파이프라인을 직접 실행하고, 원하는 스타일에 맞게 모델을 미세 조정할 수 있게 해줍니다.
한 모델로 처리하는 영상과 음성
LTX-2는 DiT 아키텍처 기반의 오디오-비디오 파운데이션 모델입니다. 현대 영상 생성의 핵심 기능인 동기화된 음성과 영상, 다양한 성능 모드, API 접근성을 하나의 모델에 담았습니다. 이 저장소는 해당 모델을 Python으로 추론하고 LoRA를 통해 미세 조정하는 데 필요한 코드를 제공합니다. 사용자가 직접 모델을 다운로드하고 파이프라인을 구성하여 원하는 영상과 음성을 생성할 수 있습니다.
속도와 품질을 고르는 두 가지 경로
모델 실행 방식은 목적에 따라 두 가지로 나뉩니다.
- DistilledPipeline 가장 빠른 텍스트/이미지-영상 변환 경로입니다. 1단계 8스텝, 2단계 4스텝으로 빠르게 동작하며 초기 테스트에 적합합니다.
- DFRPipeline 프로덕션 품질을 위한 경로입니다. 디테일링 IC-LoRA와 공간 디테일링 패스를 적용하며, 2배 또는 4배의 fps 업스케일링도 지원합니다.
필요한 부분만 고르는 모델 구성
LTX-2.5 모델은 컴포넌트별로 파일이 분리되어 있어 필요한 부분만 다운로드할 수 있습니다.
- 트랜스포머 디스틸드 버전은 빠른 추론을 위해 사용되며, 개발용 풀 모델은 가이드된 2단계 파이프라인에 사용됩니다.
- VAE 비디오와 오디오를 각각 처리하는 VAE가 있으며, 비디오 VAE는 디퓨전 디코더와 컨볼루션 디코더 중 선택 가능합니다.
- 업스케일러 공간 업스케일러는 해상도를 높이는 데 사용되며, 시간 업스케일러는 DFR 파이프라인의 시간 정제 라운드 실행 시 필요합니다.
실행 환경과 최적화
저장소는 uv를 사용하여 의존성을 관리합니다. Linux와 CUDA 환경에서 natten 추가 패키지를 설치하면 디퓨전 비디오 VAE 디코딩이 가장 빠릅니다. Windows와 macOS에서는 자동으로 Triton 또는 eager 구현으로 폴백되어 동일한 명령어로 실행할 수 있습니다. 데이터센터 Blackwell GPU(B200)에서는 FlashAttention 4를 수동으로 설치하여 성능을 최적화할 수 있으며, Hopper GPU에서는 FlashAttention 3 휠을 사용합니다. 그 외 CUDA GPU에서는 PyTorch SDPA가 자동으로 사용됩니다. 프롬프트 작성 시에는 시나리오를 마치 촬영감독이 숏 리스트를 설명하듯 구체적이고 시간 순서대로 기술하는 것이 좋습니다.
실행 전 확인 사항
모델 파일만 약 66 GiB가 필요하며, DFR 파이프라인 실행 시에는 더 많은 VRAM이 요구됩니다. GPU 메모리가 제한적인 환경에서는 --quantization fp8-cast 옵션을 활용하거나, 메모리 클리닝을 비활성화하지 않는 것이 좋습니다. 또한, Hugging Face에서 모델 조건을 수락하고 읽기 권한이 있는 토큰으로 로그인해야 모델 다운로드가 가능합니다. LoRA는 학습된 모델과만 호환되므로, LTX-2.3과 LTX-2.5의 체크포인트는 서로 교환할 수 없습니다.
