企业官网建设流程全解析

LTX-2.3 模型下载与配套文件清单：LTX-2 仓库的完整取件指南

【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2

LTX-2.3 是 LTX-2 音频-视频生成模型的上一代权重版本，其 checkpoint 采用"单文件一体包"（monolith）形态：一个.safetensors文件同时打包 transformer、视频 VAE、音频 VAE 与文本投影层，仅 Gemma 文本编码器需要单独下载。本文以仓库根目录的 MODELS-LTX-2.3.md 为骨架，逐项拆解每个模型文件的用途、适用 pipeline、下载方式与配套 CLI 参数，并对照 ltx-pipelines 与 ltx-core 的源码实现，帮助你按需下载、正确配对并跑通 LTX-2.3 的完整推理链路。

LTX-2.3 权重布局：单文件一体包 + 独立文本编码器

LTX-2.3 的每个 checkpoint 都是单一文件，内部一次性捆绑了四个组件：

• transformer（22B 规模的 DiT 主干，负责音视频联合去噪）；
• video VAE（视频编解码）；
• audio VAE（音频编解码，含 vocoder）；
• text projection（文本投影层，将 Gemma 的文本表示映射为模型可用的条件向量）。

唯一的例外是Gemma 文本编码器：它需要从 Google 的 Hugging Face 仓库单独下载（详见下文第六节）。

这种布局在 ltx-pipelines 的路径解析层 中有明确建模：ModelPaths.from_monolith把 checkpoint 路径同时赋给transformer_path、video_vae_path、audio_vae_path与duration_head_path，仅text_encoder_path单独指向gemma_root目录；而ModelPaths.from_split则是 LTX-2.5 的"每组件一个文件"布局。二者通过mode字段区分，互不通用。

版本边界（务必先读）：本仓库中的所有 pipeline 都可以运行在 LTX-2.3 之上，但 LTX-2.3 与 LTX-2.5 的权重不可互换——如果你需要 LTX-2.5，请从 Quick Start 开始，其权重按组件拆分，与本页文件不兼容；本页列出的 LoRA 都是在 LTX-2.3 上训练的，只能搭配 LTX-2.3 checkpoint 使用。这一约束在仓库根 README.md 的 "Legacy: LTX-2.3" 一节中有明确说明。

模型版本信息还会被运行时自动读取：ltx_pipelines.utils.constants.detect_model_version从 safetensors 元数据的model_version字段解析版本号，detect_params据此为 2.3 代 checkpoint 选择 LTX_2_3_PARAMS（30 步推理、STG 扰动块为第 28 层），无需手工指定参数。

核心模型 checkpoint：dev 与 distilled 二选一

LTX-2.3 提供两个一体包 checkpoint，下载时任选其一，它们服务于不同的速度/质量取向：

蒸馏模型的速度优势来自其预定义 sigma 调度：在 constants.py 中，DISTILLED_SIGMA_VALUES定义了 9 个 sigma 值（等价于阶段一 8 步去噪），STAGE_2_DISTILLED_SIGMA_VALUES只保留 4 个值（阶段二 4 步精修）。对照 distilled.py 的注释，阶段一采用 ancestral（SDE）Euler 采样器，阶段二保持确定性采样——这套设计是 LTX-2.3 蒸馏 pipeline 无需 CFG 引导即可快速出片的原因。

空间上采样器：两阶段 pipeline 的必需品

仓库中所有两阶段 pipeline 实现都必须加载空间上采样器（spatial upscaler），用于将阶段一生成的半分辨率视频在潜空间中放大 2 倍，再交给阶段二做精修。可选文件：

• ltx-2.3-spatial-upscaler-x2-1.1.safetensors（2 倍放大）
• ltx-2.3-spatial-upscaler-x1.5-1.0.safetensors（1.5 倍放大）

在 CLI 中通过--spatial-upsampler-path传入。该参数在 args.py 的两阶段解析器 中被标记为required=True；对应地，distilled.py 与 ti2vid_two_stages.py 都通过VideoUpsampler在阶段一与阶段二之间调用self.upsampler(video_state.latent[:1])完成潜空间放大。

时间上采样器：模型已支持，留待未来 pipeline

ltx-2.3-temporal-upscaler-x2-1.0.safetensors（2 倍时间上采样）在 LTX-2.3 一代是**"模型已支持、未来 pipeline 实现将会需要"**的角色——当前仓库的两阶段实现尚不强制要求它，但与 LTX-2.5 中DFRPipeline的--temporal-upsample-rounds时间精修（见 README.md）属于同一类能力，建议提前下载备用。

蒸馏 LoRA：两阶段非蒸馏 pipeline 的"精修插件"

ltx-2.3-22b-distilled-lora-384-1.1.safetensors是两阶段 pipeline 实现（在完整 dev 模型上运行时）的阶段二精修所必需的 LoRA：

• 必需场景：所有两阶段 pipeline，除了DistilledPipeline、ICLoraPipeline与DubItPipeline三个（它们各自已经运行在蒸馏 checkpoint 上，无需再叠加蒸馏 LoRA）；
• 在 CLI 中用--distilled-lora PATH [STRENGTH]传入，例如--distilled-lora path/to/ltx-2.3-22b-distilled-lora-384-1.1.safetensors 0.8。

从源码看，它的作用是让阶段二用蒸馏化的少步数调度完成高分辨率精修：ti2vid_two_stages.py 中阶段二DiffusionStage.from_checkpoint的loras参数是(*tuple(loras), *distilled_lora)，即普通 LoRA 与蒸馏 LoRA 同时叠加，配合STAGE_2_DISTILLED_SIGMAS的四步调度工作；该参数的完整语义（"second stage upsamples the video by 2x resolution and refines it using a distilled denoising schedule, fewer steps, no CFG"）见 args.py 的--distilled-lora定义。

Gemma 3 文本编码器：需要单独下载的唯一组件

LTX-2.3 使用Gemma 3（google/gemma-3-12b-it-qat-q4_0-unquantized）作为文本编码器，需从该 Hugging Face 仓库下载全部资产（config、tokenizer、processor 等 sidecar 文件）。在 monolith（一体包）模式下，用--gemma-root指向本地解压后的 Gemma 目录：

--gemma-root path/to/gemma-3-12b-it-qat-q4_0-unquantized

如果下载或推理时报 401/403，通常是 HF 门控仓库的登录态问题：需要先hf auth login完成登录，并使用具备 "read gated repos" 权限的 Read token（细粒度 token 必须显式开启该 scope）。

LoRA 生态全景：IC-LoRA、相机控制、HDR 与 DubIt

LTX-2.3 的 LoRA 家族覆盖控制类 IC-LoRA、相机运动、HDR 与配音四条线，全部以--lora PATH [STRENGTH]方式叠加到 pipeline 上（可重复传参，默认强度 1.0，见 args.py 的--lora定义）。下表为全量清单：

其中两条 IC-LoRA 与对应 pipeline 的绑定关系在 pipelines.md 中有明确交代：

• HDR：HDRICLoraPipeline在蒸馏 checkpoint 上做两阶段视频到视频，解码潜变量后经 ARRI LogC3 逆变换得到线性 HDR 浮点张量[f, h, w, c]；它的文本嵌入是外部预计算的，以video_context/audio_context两个张量保存在.safetensors中，通过--text-embeddings传入——这正是 LTX-2.3-22b-IC-LoRA-HDR 仓库同时提供"LoRA + 预计算文本嵌入"两份资产的原因。该 pipeline 的模块级文档给出了完整示例命令（见 hdr_ic_lora.py 的 docstring）：

python -m ltx_pipelines.hdr_ic_lora \ --input ./videos/ \ --output-dir ./hdr-output \ --distilled-checkpoint-path /models/ltx-2.3-22b-distilled.safetensors \ --spatial-upsampler-path /models/ltx-2.3-spatial-upscaler-x2-1.0.safetensors \ --hdr-lora /path/to/hdr_lora.safetensors \ --text-embeddings /path/to/hdr_scene_emb.safetensors \ --num-frames 161

• DubIt：DubItPipeline只在蒸馏 checkpoint 上运行，且要求恰好一次--lora传入 DubIt IC-LoRA（参考视频的 VAE 潜变量作为冻结参考 token 拼接进目标音频序列），帧数与帧率取自参考视频容器，因此其 CLI 刻意不接受--num-frames/--frame-rate（见 pipelines.md 第 10 节）。

如果你需要训练自己的 IC-LoRA（而非直接使用官方 LoRA），仓库的 ltx-trainer 提供了完整的配置模板，例如 a2a_ic_lora.yaml（音频到音频 IC-LoRA：参考音频潜变量作为条件拼接、不参与噪声与损失、rank 32 / alpha 32、timestep_sampling_mode: shifted_logit_normal）。这些训练产物同样以--lora形式加载到 LTX-2.3 推理链路中。

实操：下载、登录与目录组织

推荐用 Hugging Face CLI 下载（与 README.md 的 Quick Start 保持一致的流程），先登录再取件：

# 1. 登录（接受模型条款，使用带 read gated repos 权限的 Read token） hf auth login # 2. 下载核心 checkpoint（二选一） hf download Lightricks/LTX-2.3 \ ltx-2.3-22b-distilled-1.1.safetensors \ --local-dir models/ltx-2.3 # 3. 下载空间上采样器与蒸馏 LoRA hf download Lightricks/LTX-2.3 \ ltx-2.3-spatial-upscaler-x2-1.1.safetensors \ ltx-2.3-22b-distilled-lora-384-1.1.safetensors \ --local-dir models/ltx-2.3 # 4. 按需下载 LoRA（以 Union-Control 为例） hf download Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control \ ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors \ --local-dir models/ltx-2.3/loras

Gemma 3 编码器同样用hf download google/gemma-3-12b-it-qat-q4_0-unquantized --local-dir models/gemma3取回全部 sidecar 文件。建议将下载结果组织为：

models/ltx-2.3/ ├── ltx-2.3-22b-distilled-1.1.safetensors # 或 ltx-2.3-22b-dev.safetensors ├── ltx-2.3-spatial-upscaler-x2-1.1.safetensors # 两阶段必选 ├── ltx-2.3-22b-distilled-lora-384-1.1.safetensors ├── loras/ └── models/gemma3/ # Gemma 3 编码器目录

用 LTX-2.3 跑通推理：两套典型 CLI

仓库根目录执行uv sync --frozen（依赖安装细节见 installation.md）后，即可直接运行各 pipeline 模块。以下是 LTX-2.3 文件配对的两种典型用法。

① 蒸馏快速路线（DistilledPipeline，最省步数）

python -m ltx_pipelines.distilled \ --distilled-checkpoint-path models/ltx-2.3/ltx-2.3-22b-distilled-1.1.safetensors \ --gemma-root models/gemma3 \ --spatial-upsampler-path models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \ --prompt "A cat walks across a sunlit wooden floor, whiskers twitching, soft purring audible" \ --num-frames 121 \ --seed 42 \ --output-path output.mp4

② 完整质量路线（TI2VidTwoStages，dev + 蒸馏 LoRA）

python -m ltx_pipelines.ti2vid_two_stages \ --checkpoint-path models/ltx-2.3/ltx-2.3-22b-dev.safetensors \ --gemma-root models/gemma3 \ --spatial-upsampler-path models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \ --distilled-lora models/ltx-2.3/ltx-2.3-22b-distilled-lora-384-1.1.safetensors 0.8 \ --lora models/ltx-2.3/loras/ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors 0.5 \ --prompt "A person walking on the street, following the guide lines" \ --output-path output.mp4

需要留意的通用约束与参数（完整清单可用任意模块的--help查看，亦见 installation.md 的 Common CLI flags）：

• 帧数必须满足num_frames = 8k + 1（如 1、9、17、…、121、161），分辨率为 32 的倍数；两阶段 pipeline 的输出宽高需能被 64 整除（args.py 中--height/--width的帮助文本）；
• 显存受限时组合使用--quantization fp8-cast（对 bf16 checkpoint 在线降精度）与--offload {cpu,disk}（权重按层流式加载，disk最省显存但最慢）——这是 README.md 的显存建议；
• 叠加多个 LoRA 可重复传--lora；--enhance-prompt会用内置增强器重写提示词。

版本与兼容性红线（总结）

1. LTX-2.3 ≠ LTX-2.5：LTX-2.3 是一体包 + 独立 Gemma 3，LTX-2.5 是按组件拆分 + 内置 Gemma 4 文本投影；两代文件绝不互换；
2. LoRA 绑定训练版本：本页 LoRA 全部训练自 LTX-2.3，只能搭配ltx-2.3-22b-dev或ltx-2.3-22b-distilled使用；
3. monolith 与 split 互斥：LTX-2.3 走 monolith（--checkpoint-path/--distilled-checkpoint-path+--gemma-root），LTX-2.5 走 split（--transformer-path等）；混用两种路径集是显式报错（见 model_paths.py 的model_paths_from_namespace）；
4. 空间上采样器两阶段必选、蒸馏 LoRA视 pipeline 而定：DistilledPipeline/ICLoraPipeline/DubItPipeline不需要蒸馏 LoRA，其余两阶段实现必须提供。

按本清单取件、配对并运行后，LTX-2.3 的全部 pipeline（文本/图像转视频、IC-LoRA 控制、HDR、DubIt 配音等，完整索引见 pipelines.md）即可在本地完整复现。若需升级到推荐的新一代模型，请回到 README.md 的 Quick Start 按 LTX-2.5 的分件清单重新下载。

【免费下载链接】LTX-2Official Python inference and LoRA trainer package for the LTX-2 audio–video generative model.项目地址: https://gitcode.com/GitHub_Trending/lt/LTX-2