LTX-2
- 추천0
- GitHub 별10K
- 영상라이선스Apache-2.0
Lightricks의 오픈소스 음성·영상 동시 생성 모델 LTX-2의 추론·LoRA 학습 패키지. 텍스트·이미지·음성으로 영상을 만들어요(코드 Apache-2.0)
요약
Lightricks의 오픈소스 음성·영상 동시 생성 모델 LTX-2의 추론·LoRA 학습 패키지. 텍스트·이미지·음성으로 영상을 만들어요(코드 Apache-2.0)
설명
LTX-2
LTX-2는 DiT 기반으로는 처음 나온 음성·영상 기반 모델로, 요즘 영상 생성에 필요한 핵심 기능을 한 모델에 담았습니다. 싱크가 맞는 음성과 영상, 높은 화질, 여러 성능 모드, 제작용 결과물, API 접근, 열린 공개가 그것입니다.
🚀 빠른 시작
저장소를 받습니다.
git clone https://github.com/Lightricks/LTX-2.git
cd LTX-2
의존성을 설치합니다. natten 추가 옵션은 아래 영상 VAE에서 가장 빠른 백엔드이며 Linux + CUDA에서만 쓰입니다. Windows와 macOS에서는 자동으로 건너뛰고 Triton 또는 기본(eager) 구현으로 대신하니, 같은 명령을 어디서나 쓸 수 있습니다(neighborhood attention 백엔드 참고).
uv sync --extra natten
모델을 내려받거나 Hugging Face CLI를 씁니다.
hf auth login
hf download Lightricks/LTX-2.5 \
diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
vae/ltx-2.5-video-vae-bf16.safetensors \
vae/ltx-2.5-audio-vae-bf16.safetensors \
latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
--local-dir models/ltx-2.5
용량은 약 66 GiB입니다. CLI는 --local-dir 아래에 저장소의 폴더 구조를 그대로 둡니다. 아래 경로에 diffusion_models/, vae/ 같은 폴더가 들어 있는 이유입니다.
401/403이 나오면 Hugging Face에서 모델 약관에 동의하고 Read 토큰으로 로그인하세요(세분화 토큰은 "read gated repos" 권한을 켜야 합니다).
생성합니다.
uv run python -m ltx_pipelines.distilled \
--transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
--text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
--video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
--audio-vae-path models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
--spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
--num-frames 121 \
--seed 42 \
--output-path output.mp4 \
--prompt "A medium close-up shot features a Caucasian man with a beard, wearing a green and white baseball cap without any letters on the front, and a light blue shirt over a white t-shirt. He is positioned in the center of the frame, looking intently directly at the camera, his eyes focused on camera. His facial expression is one of deep concentration, with his brow slightly raised. As he looks straight at the camera, a quick sniff sound is heard, and then he speaks with a deep male voice and a satisfied tone, saying, 'I think it's so good.' The camera remains static throughout, maintaining a shallow depth of field, which keeps the man in sharp focus while the background is softly blurred, showing a beige wall behind him. After a brief pause, another short, audible sniff is heard. The man then continues to speak, his voice maintaining the same quality, as he states, 'So good. So good.' He elaborates further, emphasizing his point with a final statement, 'This got to be, it's got to be the best tool I've ever seen.'"
GPU 메모리가 부족하면 --quantization fp8-cast --offload {cpu, disk}를 고려하세요. 추가 플래그도 참고하세요.
이것은 DistilledPipeline으로, 가장 빠른 시작점입니다. 제작용 품질(더 느리고 VRAM을 더 씁니다)이 필요하면 아래 DFR을 쓰세요. 다른 기능은 모델과 파이프라인을 보세요.
DFR (제작용 품질)
DFR(Diffusion Fidelity Rendering)은 제작용 품질의 텍스트·이미지→영상 경로입니다. 위 명령과 같은 증류 transformer에 디테일 IC-LoRA를 더하고, 키프레임을 추가로 생성하고 공간 디테일 보정 단계를 거칩니다. 프롬프트 작성 방식이 달라지는 것이 아니라 실행 시간이 늘고 VRAM이 더 필요합니다. 전체(dev) transformer를 넣지 마세요.
텍스트 인코더, VAE, 공간 업스케일러, 증류 transformer는 첫 번째 다운로드에서 받은 것을 그대로 쓰고, 디테일 IC-LoRA(별도 저장소)를 추가로 받습니다.
hf download Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler \
ltx-2.5-22b-ic-lora-pixel-spatial-upscaler-x2-1.0.safetensors \
--local-dir models/ltx-2.5/loras
uv run python -m ltx_pipelines.dfr_pipeline \
--transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
--text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
--video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
--audio-vae-path models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
--detailing-lora models/ltx-2.5/loras/ltx-2.5-22b-ic-lora-pixel-spatial-upscaler-x2-1.0.safetensors \
--spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
--num-frames 121 \
--seed 42 \
--output-path output_dfr.mp4 \
--prompt "YOUR_PROMPT"
기본값은 1024×1536, 24fps(--temporal-upscalings 0)입니다. UHD 4K는 --width 3840 --height 2176(2160이 아닙니다)입니다. --temporal-upscalings 1 또는 2에는 시간 업스케일러가 필요합니다. 크기·fps·메모리 참고는 DFR 실행에 있습니다.
전체 모델 목록
이 저장소의 코드는 Apache License 2.0의 오픈소스입니다. LTX 모델은 여기에 포함되지 않습니다. 모델은 위에 적힌 별도 라이선스로 공개되며, 이 코드와 함께 쓸 때도 그 라이선스가 적용됩니다.
LTX-2.5가 권장 모델이고 빠른 시작에서도 이 모델을 씁니다. 가중치는 구성 요소별로 파일 하나씩 올라가 있어서, 쓰는 파이프라인에 필요한 부분만 내려받으면 됩니다.
LTX-2.5 HuggingFace 저장소에서 받습니다.
Transformer (아래 중 하나를 골라 받습니다)
ltx-2.5-22b-dev-transformer-bf16.safetensors- 전체 모델. 안내식 2단계 파이프라인(TI2Vid, Keyframe, A2Vid)에서 씁니다ltx-2.5-22b-distilled-transformer-bf16.safetensors- 훨씬 적은 스텝으로 돌아갑니다.DistilledPipeline,DFRPipeline,ICLoraPipeline,DubItPipeline이 이것을 요구합니다
텍스트 인코더 - LTX용으로 파인튜닝한 Gemma 4 12B이며 텍스트 프로젝션이 함께 들어 있습니다. 모든 파이프라인에 필요합니다. 모델에 포함돼 있어 Gemma를 따로 받지 않아도 됩니다. Google의 기본 Gemma 4 릴리스로는 대신할 수 없습니다. 불러올 때 체크포인트가 학습된 버전(gemma4-12b-ltx-v1)과 인코더 버전을 확인하기 때문입니다.
영상 VAE (아래 중 하나를 골라 받습니다)
ltx-2.5-video-vae-bf16.safetensors- 확산 디코더(NADiffusionDecoder). 화질이 좋아지는 대신 디코딩 시간이 길고 VRAM을 더 씁니다.natten추가 옵션이 있을 때 가장 빠르고, 없으면 Triton 또는 기본 neighborhood attention으로 대신합니다ltx-2.5-video-vae-conv-bf16.safetensors- 합성곱 디코더. 가볍고 추가 의존성이 필요 없습니다
오디오 VAE - 오디오를 생성하거나 디코딩하는 파이프라인에 필요합니다.
공간 업스케일러 - 이 저장소의 2단계 파이프라인 구현에 필요합니다.
시간 업스케일러 - DFRPipeline이 시간 보정 라운드(--temporal-upscalings)를 돌 때 필요합니다.
증류 LoRA - 1단계에서 전체 모델을 돌리는 2단계 파이프라인 구현(TI2Vid 2단계 / HQ, Keyframe, A2Vid)에 필요합니다. DistilledPipeline, DFRPipeline, ICLoraPipeline, DubItPipeline에는 필요 없습니다.
디테일 IC-LoRA - DFRPipeline의 보정 단계(--detailing-lora)에 필요합니다. 별도 저장소 LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler에 있습니다.
길이 예측 헤드 - 선택 사항입니다. --num-frames를 생략하면 프롬프트에서 클립 길이를 예측합니다.
이전 버전: LTX-2.3
이 저장소의 모든 파이프라인은 LTX-2.3에서도 돌아갑니다. LTX-2.3 체크포인트는 transformer, VAE, 텍스트 프로젝션을 하나로 묶은 단일 파일이고 LTX-2 Community License를 따릅니다. Gemma 3 텍스트 인코더는 따로 받으며 Google의 라이선스를 따릅니다. 두 모델의 파일은 서로 바꿔 쓸 수 없고, LoRA는 학습한 모델에서만 동작합니다.
전체 목록은 LTX-2.3 모델 문서를 보세요.
제공하는 파이프라인
- DistilledPipeline - 가장 빠른 텍스트·이미지→영상(시작점)
- DFRPipeline - 제작용 품질의 텍스트·이미지→영상(더 느리고 VRAM을 더 씁니다). 같은 증류 transformer, 생성 키프레임, 공간 디테일 보정, 선택 사항인 2배/4배 fps. 실행법은 위 DFR와 DFR 실행을 보세요
- TI2VidTwoStagesPipeline - CFG/STG와 2배 업샘플링을 쓰는 안내식 2단계 텍스트·이미지→영상 및 키프레임 보간
- TI2VidTwoStagesHQPipeline - 같은 안내식 2단계 흐름에 res_2s 샘플러를 써서 스텝이 더 적습니다
- TI2VidOneStagePipeline - 빠른 시제품용 1단계 생성
- ICLoraPipeline - 영상→영상, 이미지→영상 변환(증류 모델 사용)
- A2VidPipelineTwoStage - 입력 오디오 파일을 조건으로 하는 음성→영상 생성
- RetakePipeline - 기존 영상의 특정 시간 구간만 다시 생성
- HDRICLoraPipeline - HDR IC-LoRA로 하는 SDR→HDR 영상→영상 변환. BT.2020/HLG 마스터와 EXR 내보내기·색보정용 ACEScct EXR 시퀀스를 만듭니다
- DubItPipeline - Dub-It: 화자 정체성과 입 모양을 맞추면서 말을 바꿔 줍니다(증류 모델, IC-LoRA 하나, 2단계)
- 기본 HDR / EXR - 표준 파이프라인은 EXR 정지 이미지와 EXR 프레임 폴더를 받아
--hdr {SRGB_LINEAR,ACESCG,ACESCCT,ACES2065_1}을 쓰고, 16비트 EXR 프레임과 BT.2020/HLG 마스터를 씁니다. HDR 지원을 보세요
⚡ 최적화 팁
- 속도는 DistilledPipeline - 미리 정한 시그마 8개(1단계 8스텝, 2단계 4스텝)로 가장 빠르게 추론합니다. 제작용 품질은 DFR을 쓰세요.
- FP8 양자화 - 메모리 사용량을 줄입니다.
--quantization fp8-cast(CLI) 또는quantization=QuantizationPolicy.fp8_cast()(Python). Fp8-cast는 bf16 체크포인트와 함께 쓰며 즉석에서 다운캐스트합니다. 네이티브 FP8을 지원하는 Hopper 이상 GPU에서는 FP8 스케일 행렬곱을 위해--quantization fp8-scaled-mm을 쓰고, 이것은 fp8 체크포인트와 함께 씁니다. - 어텐션 최적화 설치 - 데이터센터급 Blackwell GPU(B200)에서는 FlashAttention 4를 직접 설치합니다:
uv pip install 'flash-attn-4==4.0.0b9'(torch 2.9.1+cu128에서 검증한 리비전이며, 더 새 베타에는 소비자용 Blackwell에서 알려진 문제가 있습니다). Hopper GPU에서는 FlashAttention 3 휠을 설치합니다. 그 밖의 CUDA GPU에서는 PyTorch SDPA를 자동으로 씁니다. 설치된 백엔드는 실행 시 자동으로 선택되며, 특정 백엔드를 강제하는 것은 CLI 플래그가 아니라 Python API 옵션(AttentionFunction.FLASH_ATTENTION_3/FLASH_ATTENTION_4)입니다. - 그래디언트 추정 사용 - 품질을 유지하면서 추론 스텝을 40에서 20~30으로 줄입니다(파이프라인 문서 참고).
- 메모리 정리 건너뛰기 - VRAM이 충분하면 단계 사이의 자동 메모리 정리를 꺼서 더 빠르게 처리합니다.
- 1단계 파이프라인 선택 - 고해상도가 필요 없으면
TI2VidOneStagePipeline으로 더 빠르게 생성합니다.
✍️ LTX-2 프롬프트 쓰기
프롬프트는 동작과 장면을 시간 순서대로 자세히 적는 데 집중하세요. 구체적인 움직임, 모습, 카메라 각도, 환경 묘사를 하나의 흐르는 문단에 담습니다. 동작으로 바로 시작하고 묘사는 문자 그대로 정확하게 씁니다. 촬영 감독이 샷 리스트를 설명한다고 생각하세요. 200단어 안으로 씁니다. 가장 좋은 결과를 얻으려면 다음 구조로 만드세요.
- 핵심 동작을 한 문장으로 시작합니다
- 움직임과 몸짓을 구체적으로 더합니다
- 인물·사물의 모습을 정확히 묘사합니다
- 배경과 환경 묘사를 넣습니다
- 카메라 각도와 움직임을 지정합니다
- 조명과 색을 묘사합니다
- 변화나 갑작스러운 사건을 적습니다
프롬프트 작성 안내는 https://ltx.io/blog/prompting-guide-for-ltx-2를 참고하세요.
자동 프롬프트 개선
LTX-2 파이프라인은 enhance_prompt 파라미터로 프롬프트 자동 개선을 지원합니다.
🔌 ComfyUI 연동
ComfyUI에서 이 모델을 쓰려면 https://github.com/Lightricks/ComfyUI-LTXVideo/의 안내를 따르세요.
📦 패키지
이 저장소는 세 개의 주요 패키지로 이뤄진 모노레포입니다.
- ltx-core - 핵심 모델 구현, 추론 스택, 유틸리티
- ltx-pipelines - 텍스트→영상, 이미지→영상 등 생성 모드의 고수준 파이프라인 구현
- ltx-trainer - LoRA, 전체 파인튜닝, IC-LoRA 학습 도구
각 패키지에 자체 README와 문서가 있습니다.
📚 문서
- LTX-Core README - 핵심 모델 구현, 추론 스택, 유틸리티
- LTX-Pipelines README - 고수준 파이프라인 구현과 사용 가이드
- LTX-Trainer README - 학습·파인튜닝 문서와 자세한 가이드
라이선스: 코드 Apache-2.0(모델은 별도 라이선스) · 저장소: Lightricks/LTX-2
평점
- 5점
- 0
- 4점
- 0
- 3점
- 0
- 2점
- 0
- 1점
- 0