Ruyi：CreateAI推出的开源图像转视频大模型，支持768分辨率与多维度视频控制

一、Ruyi是什么？

Ruyi是Ruyi-Models项目的核心图像到视频（Image-to-Video, i2v）生成模型，由CreateAI团队开发并开源，旨在为用户提供“低门槛、高性能、高自由度”的视频生成解决方案。不同于传统图像转视频工具的低分辨率、弱控制问题，Ruyi专注于“电影级画质”输出，核心能力是将单张静态图像转化为连贯、清晰、富有动态感的视频内容。

其核心技术指标如下：

• 基础输出规格：分辨率768px、帧率24帧/秒（fps）、总时长5秒（120帧）；

• 硬件适配：在RTX 3090或RTX 4090显卡上，可无损生成512分辨率120帧视频，或768分辨率约72帧视频；

• 核心定位：开源免费、支持本地化部署、兼容ComfyUI工作流、提供多维度视频控制能力，兼顾个人用户与开发者需求。

Ruyi-Models项目则是该模型的开源载体，包含完整的部署脚本、ComfyUI集成节点、GPU优化方案、模型文件说明及使用文档，用户可通过简单步骤完成安装与运行，无需复杂的技术储备。

二、功能特色

Ruyi-Models的核心优势在于“画质、控制、易用性、兼容性”四大维度的平衡，具体功能特色如下：

1. 电影级画质输出，高分辨率+高帧率双保障

Ruyi突破了传统i2v模型“低分辨率模糊”“帧率不足导致卡顿”的痛点，默认输出768分辨率视频（主流短视频平台高清规格），24帧/秒的帧率符合人眼视觉流畅标准，5秒120帧的时长足以承载完整的动态场景（如产品旋转、风景过渡、人物动作预览等）。生成的视频色彩还原度高、细节保留完整，无明显噪点或画面撕裂，可直接用于商业宣传、自媒体发布等专业场景。

2. 多维度视频控制，自由度拉满

区别于“一键生成不可调”的工具，Ruyi提供两大核心控制能力，让用户精准掌控视频动态效果：

• 镜头控制：支持5种镜头方向调节，包括“向左移动（left）、向右移动（right）、静态（static）、向上移动（up）、向下移动（down）”，可模拟真实拍摄中的运镜效果（如推拉摇移），让静态图像转化为“有视角变化”的视频；

• 运动幅度控制：提供4级运动强度调节（motion 1-4），从“轻微微动”（适合产品展示）到“大幅动态”（适合特效场景），满足不同场景下的动态需求。

3. ComfyUI深度集成，可视化工作流高效创作

针对AI绘画/视频创作者常用的ComfyUI工具，Ruyi-Models提供专用节点支持，无需手动编写代码，通过拖拽节点即可完成视频生成：

• 核心节点：集成TeaCache（加速生成）、Enhance-A-Video（提升画质）、Ruyi原生生成节点，可直接嵌入现有ComfyUI工作流；

• 操作便捷：节点逻辑清晰，只需将TeaCache、Enhance-A-Video节点链接在采样器节点前，即可启用加速与画质增强功能；

• 依赖兼容：配套需要ComfyUI-VideoHelperSuite节点（用于视频输出显示），安装后可直接预览生成结果。

4. 灵活的GPU内存优化，适配不同硬件配置

考虑到用户硬件差异，Ruyi提供多重GPU内存优化方案，低配置显卡也能运行高分辨率视频生成：

• FP8量化模式：支持4级FP8模式（lite/strong/extreme），内存占用依次降低（bf16 default > fp8 lite > fp8 strong > fp8 extreme），RTX 3090/4090用户可通过该模式生成更长帧数视频；

• 双GPU模式：提供normal_mode（常规模式）和low_gpu_mode（低内存模式），后者可大幅降低显存占用（如A100在512分辨率120帧下，low_gpu_mode仅需11430MiB，而normal_mode需25238MiB）；

• 显存卸载参数：支持GPU_offload_steps参数调节，通过牺牲少量生成时间换取显存占用降低，用户可根据自身显卡显存（8GB/12GB/24GB）灵活配置。

5. 持续迭代优化，修复痛点+新增功能

项目保持高频更新，不断解决用户使用中的核心问题：

• 2024年12月24日：修复3:4/4:5比例视频生成时的黑边问题；

• 2025年1月6日：新增FP8模式，进一步降低GPU内存占用；

• 2025年1月14日：新增TeaCache和Enhance-A-Video节点，生成速度与画质双重提升；

• 模型自动更新：支持模型文件自动下载与更新，无需手动替换文件。

三、技术细节

Ruyi-Models的技术设计围绕“高性能、低显存、易集成”三大目标，核心技术细节如下：

1. 核心模型架构

Ruyi基于扩散模型（Diffusion Model）开发，专注于图像到视频的时序连贯性与空间分辨率平衡：

• 生成逻辑：通过对输入图像进行时序扩展，基于扩散过程逐步生成连续帧，确保帧间过渡自然，无跳变或模糊；

• 模型规格：当前核心模型为Ruyi-Mini-7B，总存储占用17GB，包含transformers（transformer层权重）、vae（变分自编码器，负责图像/视频编码解码）等核心模块；

• 支持比例：兼容16:9（常规视频）、3:4（竖屏短视频）、4:5（社交媒体视频）等主流比例，解决传统模型比例适配性差的问题。

2. GPU优化核心技术

为适配不同硬件，Ruyi采用多重显存优化技术，下表为核心优化方案的效果对比（以512分辨率、120帧为例）：

注：显存占用为PyTorch的max_memory_allocated()值，nvidia-smi显示值会更高（CUDA占用500-800MiB+PyTorch缓存）。

3. 关键参数说明

Ruyi提供可配置参数，用户可根据需求调整生成效果与性能，核心参数如下：

• resolution：视频分辨率，支持512或768，越高画质越清晰，显存占用越高；

• num_frames：生成帧数，最大120帧（5秒），支持自定义帧数（如24帧=1秒）；

• fps：帧率，默认24帧/秒，不可修改（保证视频流畅度）；

• camera_control：镜头控制，可选left/right/static/up/down；

• motion_amplitude：运动幅度，可选1-4（数值越大，动态越强）；

• GPU_memory_mode：GPU内存模式，可选normal/low_gpu；

• GPU_offload_steps：显存卸载步数，可选0-10（数值越大，显存占用越低，生成时间越长）；

• fp8_mode：FP8量化模式，可选none/lite/strong/extreme（仅ComfyUI支持）。

4. 技术依赖栈

项目基于Python生态开发，核心依赖如下：

• 深度学习框架：PyTorch（负责模型推理）；

• 视频处理：ComfyUI-VideoHelperSuite（视频输出与预览）；

• 加速模块：TeaCache（生成加速）、Enhance-A-Video（画质增强）；

• 其他依赖：可通过requirements.txt安装，包含transformers、accelerate、numpy等常用库。

四、应用场景

Ruyi-Models的高画质、强控制特性使其适用于多个实际场景，覆盖个人创作、商业生产、开发者集成等多个维度：

1. 内容创作（自媒体/短视频）

• 适用人群：博主、短视频创作者、自媒体人；

• 核心用途：将封面图、产品图转化为动态视频（如美食博主的菜品图转制作过程预览、穿搭博主的穿搭图转动态展示）；

• 优势：无需拍摄实景，仅需一张高质量图片即可生成5秒高清视频，搭配镜头控制可模拟“多角度展示”，提升内容丰富度。

2. 商业广告与营销素材

• 适用人群：广告策划、电商运营、品牌营销人员；

• 核心用途：生成产品演示视频（如电子产品旋转展示、服装面料动态效果）、广告片片段（如海报图转15秒宣传视频）；

• 优势：768分辨率满足广告投放标准，运动幅度控制可突出产品核心卖点（如珠宝的光泽动态、家具的空间展示），降低拍摄成本。

3. 设计可视化（建筑/产品设计）

• 适用人群：建筑设计师、产品设计师、UI/UX设计师；

• 核心用途：将设计图转化为动态演示视频（如建筑效果图转建筑漫游视频、产品设计图转360°旋转展示）；

• 优势：镜头控制功能可模拟“实地考察”视角，帮助客户更直观理解设计方案，无需复杂的3D建模渲染。

4. 创意艺术创作

• 适用人群：数字艺术家、插画师、创意设计师；

• 核心用途：将静态艺术作品转化为动态艺术视频（如插画转梦幻动态效果、数字绘画转镜头移动式展示）；

• 优势：运动幅度调节可实现“抽象动态”或“写实动态”，搭配高分辨率输出，满足艺术展示需求。

5. AI工具集成与二次开发

• 适用人群：开发者、AI工具厂商；

• 核心用途：将Ruyi集成到自有AI平台（如设计工具、视频编辑软件），提供图像转视频功能；

• 优势：开源Apache 2.0许可证支持商业使用，ComfyUI节点与Python脚本双重调用方式，适配不同集成场景。

五、使用方法

Ruyi-Models提供三种主流使用方式（普通Python运行、ComfyUI集成、Windows便携版适配），步骤详细且易操作，以下为完整指南：

1. 前置准备

• 硬件要求：GPU需支持CUDA（NVIDIA显卡），推荐RTX 3090/4090（24GB显存）或A100（40GB显存），最低支持RTX 3080（10GB显存，需开启low_gpu_mode+FP8）；

• 系统要求：Windows、Linux均可（Windows需注意Python环境配置）；

• 依赖环境：Python 3.8+，PyTorch 2.0+（需支持CUDA）。

2. 普通用户使用（Python脚本运行）

步骤1：克隆仓库与安装依赖

# 克隆项目仓库
git clone https://github.com/IamCreateAI/Ruyi-Models
cd Ruyi-Models

# 安装依赖（确保已激活Python环境）
pip install -r requirements.txt

步骤2：下载模型（可选）

• 自动下载：运行脚本时会自动下载Ruyi-Mini-7B模型到Ruyi-Models/models/目录；

• 手动下载：若自动下载慢，可从Hugging Face（https://huggingface.co/IamCreateAI/Ruyi-Mini-7B）下载，解压后放入`Ruyi-Models/models/Ruyi-Mini-7B/`，目录结构如下：

📦 Ruyi-Models/models/
├── 📂 Ruyi-Mini-7B/
│  ├── 📂 transformers/
│  ├── 📂 vae/
│  └── 📂 ...（其他模型文件）

步骤3：运行生成脚本

• 基础运行（适用于24GB显存以下显卡）：

  python3 predict_i2v.py

• 高速运行（适用于24GB+显存显卡，如RTX 4090/A100）：

  python3 predict_i2v_80g.py

• 自定义参数：修改脚本中的input_image（输入图像路径）、resolution（分辨率）、num_frames（帧数）、camera_control（镜头控制）等变量，即可调整生成效果。

3. ComfyUI用户使用（推荐创作者）

ComfyUI用户可通过两种方式安装，推荐使用ComfyUI-Manager一键安装：

方法1：ComfyUI-Manager一键安装

步骤1：安装ComfyUI-Manager

cd ComfyUI/custom_nodes/
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
pip install -r ComfyUI-Manager/requirements.txt

步骤2：安装Ruyi与依赖节点

1. 启动ComfyUI，打开左侧“Manager”面板；

2. 选择“Custom Nodes Manager”，搜索“Ruyi”，找到“ComfyUI-Ruyi”点击“Install”；

3. 搜索“ComfyUI-VideoHelperSuite”，点击“Install”（用于视频输出显示）；

4. 重启ComfyUI，即可在“Add Node → Ruyi”菜单中找到3个核心节点。

步骤3：使用ComfyUI节点生成视频

1. 拖拽“Ruyi Image to Video”节点到工作流；

2. 拖拽“TeaCache”和“Enhance-A-Video”节点，链接在采样器节点前（顺序：输入图像 → TeaCache → Enhance-A-Video → 采样器 → Ruyi生成节点 → 视频输出）；

3. 配置参数（分辨率、帧数、镜头控制等），点击“Queue Prompt”运行，生成的视频可通过ComfyUI预览窗口查看。

方法2：手动安装（适用于无法使用Manager的用户）

# 安装Ruyi节点
cd ComfyUI/custom_nodes/
git clone https://github.com/IamCreateAI/Ruyi-Models.git
pip install -r Ruyi-Models/requirements.txt

# 安装依赖节点ComfyUI-VideoHelperSuite
git clone https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite.git
pip install -r ComfyUI-VideoHelperSuite/requirements.txt

安装后重启ComfyUI，即可使用节点（同方法1步骤3）。

4. Windows用户特殊说明（便携版ComfyUI）

若使用Windows便携版ComfyUI（如ComfyUI_windows_portable_nvidia），需使用嵌入式Python环境安装：

# 进入ComfyUI自定义节点目录
cd ComfyUI_windows_portable\ComfyUI\custom_nodes

# 克隆Ruyi仓库
git clone https://github.com/IamCreateAI/Ruyi-Models.git

# 使用嵌入式Python安装依赖
..\..\python_embeded\python.exe -m pip install -r Ruyi-Models\requirements.txt

# 安装ComfyUI-VideoHelperSuite（同上述步骤）
git clone https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite.git
..\..\python_embeded\python.exe -m pip install -r ComfyUI-VideoHelperSuite\requirements.txt

六、常见问题解答（FAQ）

1. 模型下载慢或下载失败怎么办？

• 解决方案1：手动下载Hugging Face模型（链接见“官方链接”部分），解压后放入指定目录；

• 解决方案2：使用代理工具加速下载，或通过国内镜像源（如阿里云、清华镜像）下载依赖包；

• 解决方案3：检查网络连接，确保GitHub与Hugging Face可访问，若仍失败可加入官方社区获取离线模型包。

2. 运行时提示“GPU内存不足（OOM）”如何解决？

• 方案1：降低分辨率（从768改为512），减少帧数（如从120帧改为72帧）；

• 方案2：开启low_gpu_mode，修改脚本中GPU_memory_mode = "low_gpu"；

• 方案3：增加GPU_offload_steps参数（如设置为10），牺牲生成时间换取显存；

• 方案4：在ComfyUI中启用FP8模式（选择fp8 strong/extreme），进一步降低显存占用；

• 方案5：更换更高显存显卡（如RTX 4090→A100）。

3. 生成的视频有黑边或比例异常怎么办？

• 原因：未更新到2024年12月24日后的版本，旧版本不支持3:4/4:5比例；

• 解决方案：拉取最新代码（git pull），更新模型文件，确保使用最新版本的扩散模型。

4. ComfyUI中找不到Ruyi节点怎么办？

• 检查1：确认Ruyi-Models已克隆到ComfyUI/custom_nodes/目录；

• 检查2：已安装ComfyUI-VideoHelperSuite依赖节点；

• 检查3：重启ComfyUI，若仍未找到，重新运行依赖安装命令（pip install -r requirements.txt）；

• 检查4：Windows用户需确认使用嵌入式Python安装依赖，而非系统Python。

5. 生成速度太慢，如何加速？

• 方案1：使用predict_i2v_80g.py脚本（仅24GB+显存可用）；

• 方案2：开启TeaCache节点（ComfyUI），可显著提升生成速度；

• 方案3：降低GPU_offload_steps参数（如设置为0-5），减少显存卸载耗时；

• 方案4：使用更高性能显卡（RTX 4090比RTX 3090快约30%，A100比RTX 4090快约50%）。

6. 生成的视频动态效果不符合预期（如镜头移动过度/不足）怎么办？

• 调整镜头控制参数：若移动过度，选择“static”（静态）或降低运动幅度（motion 1）；

• 若移动不足，提高运动幅度（motion 3-4），或更换镜头方向（如left→right组合）；

• 调整帧数：帧数越多，动态过渡越自然（如24帧→120帧）。

7. Windows系统下运行run_nvidia_gpu.bat后，依赖安装失败怎么办？

• 原因：未使用ComfyUI便携版的嵌入式Python；

• 解决方案：严格按照“Windows用户特殊说明”步骤，使用..\..\python_embeded\python.exe执行pip安装命令，避免使用系统自带Python。

七、相关链接

• 项目GitHub仓库：https://github.com/IamCreateAI/Ruyi-Models

• 模型下载（Hugging Face）：https://huggingface.co/IamCreateAI/Ruyi-Mini-7B

• ComfyUI-Manager下载：https://github.com/ltdrdata/ComfyUI-Manager

• ComfyUI-VideoHelperSuite下载：https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite

• TeaCache项目地址：https://github.com/ali-vilab/TeaCache

• Enhance-A-Video项目地址：https://github.com/NUS-HPC-AI-Lab/Enhance-A-Video

八、总结

Ruyi-Models是一款兼顾高性能、易用性与灵活性的开源图像到视频生成项目，核心模型Ruyi能够基于单张图像生成768分辨率、24帧/秒的电影级视频，支持镜头控制与运动幅度调节，适配RTX 3090/4090等主流GPU，通过FP8量化、显存卸载等优化方案降低硬件门槛。项目提供Python脚本与ComfyUI节点两种使用方式，集成TeaCache加速与Enhance-A-Video画质增强模块，同时保持高频更新修复核心问题，适用于内容创作、商业广告、设计可视化等多个场景。其Apache 2.0开源许可证支持商业使用与二次开发，配套完善的文档与社区支持，无论是个人创作者还是开发者，都能快速上手并实现高质量视频生成，是当前图像到视频领域极具实用性的开源解决方案。