🧭 核心特点与能力

JoyAI-Echo 是一款专注于长视频生成的研究模型，其核心能力包括：

  • 分钟级多镜头故事生成：能根据一个包含多个镜头描述的 JSON 提示文件，生成一个连贯、多镜头的长视频。
  • 音视频联合生成：单个模型可同时生成同步的视频和音频。
  • 跨镜头记忆一致性：通过“跨模态记忆库”将前一个镜头的视觉特征和声音音色传递给后续镜头，确保角色和场景在长视频中保持一致。
  • 快速推理：采用 DMD 蒸馏技术，推理速度比原始流程快约 7.5 倍。
  • 交互式编辑（规划中）：未来计划支持通过对话指令进行实时编辑。

重要限制：

  • 仅支持文本生成视频（T2V）：当前版本不支持图像生成视频（I2V）。
  • 高硬件要求：默认设置下，峰值显存占用约 46-50 GB，需要 H100/A100（80 GB）或 48 GB 显存的 GPU。
  • 学术研究用途：项目声明仅限学术研究和非商业用途，并基于 LTX-2 社区许可协议。

📦 部署与安装

1. 环境要求

  • 操作系统：Linux (推荐) 或 macOS。
  • Python 版本：Python 3.11。
  • PyTorch 环境：PyTorch 2.8 及 CUDA 12.8。
  • GPU：显存 ≥ 48GB（如 A100 80GB、H100 80GB、RTX A6000 等）。
  • 其他工具：ffmpeg（用于镜头拼接）。

2. 安装步骤

第一步：克隆仓库

1
2
git clone https://github.com/jd-opensource/JoyAI-Echo.git
cd JoyAI-Echo

第二步：创建 Python 环境（推荐使用 conda）

1
2
3
# 使用 conda（推荐，会自动安装 ffmpeg）
conda env create -f environment.yml
conda activate echo-long

或使用 uv：

1
2
3
4
5
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install --extra-index-url https://download.pytorch.org/whl/cu128 -r requirements.txt
# 并手动安装 ffmpeg
sudo apt install ffmpeg  # Ubuntu/Debian

第三步：下载模型权重
需要下载两个权重文件（总计约 70 GB），并放置在 checkpoints/ 目录下：

  1. 主模型：echo-longvideo-release.safetensors (~46 GB)，从 Hugging Face 仓库 下载。
  2. 文本编码器：gemma-3-12b/ 目录 (~24 GB)，下载 Google 的 gemma-3-12b-it 模型。

最终目录结构应为：

1
2
3
checkpoints/
├── echo-longvideo-release.safetensors
└── gemma-3-12b/

🚀 使用指南

1. 准备故事提示（Prompt）

  • 强烈建议使用官方提示增强器：项目提供了两个系统提示文件（prompts/long_story_writer_system_prompt.md 用于多镜头长视频，prompts/short_story_writer_system_prompt.md 用于单镜头短视频）。将你的粗略想法输入增强器，以获得结构良好的分镜头描述。

  • 创建 JSON 提示文件：在 prompts/ 目录下创建一个 .json 文件。格式为包含 prompts 列表的单个对象，每个字符串代表一个镜头。一个字符串生成一个镜头，多个字符串生成多镜头故事。

  • 镜头描述结构：每个字符串应包含以下部分（按顺序）：

    1. 角色与主体：描述外貌（年龄、体型、发型、着装）、说话音色。
    2. 动作与对话：主体的行为和台词。
    3. 风格：整体视觉和情感美学（如“写实赛车电影风格”）。
    4. 运镜：镜头类型和构图（如“面部特写”、“腰部以上中景”）。
    5. 背景：场景细节。
    6. 音效与背景音乐：环境音和配乐。

    示例可参考 prompts/example_multi_shot.json。

2. 运行推理

1
python inference.py

此命令会加载模型，并处理 prompts/ 目录下的所有 JSON 文件。输出结果将保存在 inference_result/outputs/<prompt-name>/ 下。

3. 高级配置

所有推理参数在 configs/inference.yaml 中管理。你可以：

  • 通过命令行覆盖参数：例如 python inference.py --seed 42 --num-frames 121（减少帧数以适配更小的 GPU）。
  • 使用自定义配置文件：python inference.py --config configs/my_experiment.yaml。
  • 查看所有可配置项：python inference.py --help。

⚙️ 硬件适配建议

  • 默认设置（25fps x 241帧 x 1280x736）需要约 46-50 GB 显存。
  • 显存不足时：可以通过减少帧数（--num-frames）来降低显存消耗，例如 --num-frames 121 可显著降低需求，但会缩短生成视频时长。

❓ 常见注意事项

  • I2V 支持：当前版本不支持图像生成视频。项目计划在未来版本中支持。
  • 许可证：严格限制于学术研究和非商业用途。商业使用需联系原项目（Lightricks Ltd.）获取授权。
  • 结果复现：为确保结果一致性，可通过 --seed 固定随机种子。

总结

JoyAI-Echo 是一个面向长视频生成前沿研究的强大模型。部署的核心是满足其苛刻的硬件要求（48GB+ 显存），并严格按照文档准备环境、下载权重。使用时要善用其提供的提示增强器来构建结构化 JSON 输入。请务必注意其仅限学术研究的许可证限制。对于普通用户或硬件不足的开发者，当前版本可能不适合直接运行，建议关注其官方项目页面和未来更新。