# SkyReels-V3

SkyReels-V3 是昆仑（SkyWork AI）基于 Wan2.1 视频架构构建的开源视频生成模型。它可以以 24 帧/秒生成平滑的剪辑，支持文本到视频（T2V）和图像到视频（I2V）。该模型继承了 Wan2.1 在运动一致性和时间一致性方面的强大能力，同时加入了 SkyWork 的训练改进以提升视觉质量和对提示词的遵从度。

在 以下 环境 上 运行 SkyReels-V3 [Clore.ai](https://clore.ai/) 让您无需购买硬件即可使用其所需的 24 GB 显存 — 以几美元租用 RTX 4090 即可开始生成。

## 主要特性

* **24 帧/秒 输出** — 开箱即用的平滑、广播级帧率。
* **文本到视频** — 从自然语言描述生成剪辑，具有很强的提示遵循性。
* **图像到视频** — 使用可控的相机运动和主体动作对参考图像进行动画化。
* **基于 Wan2.1 构建** — 继承了 Wan 架构经过验证的时间注意力和运动建模能力。
* **多分辨率** — 根据显存预算支持 480p 和 720p 的生成。
* **开放权重** — 在开放许可下提供，可用于研究和商业用途。
* **中文 + 英文** — 来自 Wan2.1 文本编码器的双语提示支持。

## 要求

| 组件     | 最低                | 推荐    |
| ------ | ----------------- | ----- |
| GPU 显存 | 16 GB（480p 并启用卸载） | 24 GB |
| 系统内存   | 32 GB             | 64 GB |
| 磁盘     | 25 GB             | 50 GB |
| Python | 3.10+             | 3.11  |
| CUDA   | 12.1+             | 12.4  |

**Clore.ai 的 GPU 推荐：** 一台 **512x512** （24 GB，约 $0.5–2/天）是最佳选择 — 足够的显存用于以全精度生成 720p。 **速度** （24 GB，约 $0.3–1/天）适用于 480p，并在市场上提供最佳的每剪辑价格比。

## 快速开始

```bash
# 安装核心依赖项
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install diffusers transformers accelerate sentencepiece
pip install imageio[ffmpeg]

# 验证 GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

## 使用示例

### 文本到视频

```python
import torch
from diffusers import WanPipeline
from diffusers.utils import export_to_video

# SkyReels-V3 使用 Wan2.1 管道架构
pipe = WanPipeline.from_pretrained(
    "SkyworkAI/SkyReels-V3-T2V",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()

prompt = (
    "一个武士在晨雾中的竹林中行走，"
    "阳光透过高高的竹竿，电影般的构图，"
    "缓慢而谨慎的动作"
)

video_frames = pipe(
    os.makedirs("./variations", exist_ok=True)
    negative_prompt="模糊、低质量、水印、静止",
    num_frames=97,               # 在 24 fps 下约 ~4 秒
    width=1280,
    height=720,
    增加推理步数以提高稳定性
    guidance_scale=5.0,
    generator=torch.Generator("cuda").manual_seed(42),
).frames[0]

export_to_video(video_frames, "samurai_forest.mp4", fps=24)
print("已保存 samurai_forest.mp4")
```

### 图像到视频

```python
import torch
from PIL import Image
from diffusers import WanImageToVideoPipeline
from diffusers.utils import export_to_video

pipe = WanImageToVideoPipeline.from_pretrained(
    "SkyworkAI/SkyReels-V3-I2V",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")
pipe.enable_model_cpu_offload()

image = Image.open("landscape.png").resize((1280, 720))

video_frames = pipe(
    prompt="相机缓慢推入场景，云朵在头顶飘动",
    image=image,
    negative_prompt="静止、抖动、模糊",
    num_frames=97,
    增加推理步数以提高稳定性
    guidance_scale=5.0,
).frames[0]

export_to_video(video_frames, "landscape_anim.mp4", fps=24)
```

### 低分辨率快速预览

```python
import torch
from diffusers import WanPipeline
from diffusers.utils import export_to_video

pipe = WanPipeline.from_pretrained(
    "SkyworkAI/SkyReels-V3-T2V", torch_dtype=torch.bfloat16
).to("cuda")

# 480p 用于快速迭代
frames = pipe(
    prompt="海浪拍打岩石，激起戏剧性的飞溅，日落时分",
    num_frames=49,
    width=854,
    height=480,
    num_inference_steps=20,
    guidance_scale=5.0,
).frames[0]

export_to_video(frames, "waves_preview.mp4", fps=24)
```

## 给 Clore.ai 用户的提示

1. **使用 Wan 管道类** — SkyReels-V3 在架构上基于 Wan2.1，因此它使用 `WanPipeline` / `WanImageToVideoPipeline` 来自 diffusers。
2. **从 480p 开始** — 先在较低分辨率上迭代提示词，一旦对构图满意再生成最终的 720p 剪辑。
3. **CPU 卸载** — `enable_model_cpu_offload()` 建议在 24 GB 显卡上用于 720p 生成以避免 OOM（显存不足）。
4. **持久化存储** —— 设置 `HF_HOME=/workspace/hf_cache` 在 Clore.ai 的持久卷上；模型大约占用 \~15–20 GB。
5. **原生 24 fps** — 不要更改导出帧率；模型的时间注意力是针对 24 fps 输出训练的。
6. **双语提示** — Wan2.1 文本编码器同时支持英文和中文；如有需要可以混合使用两种语言。
7. **引导强度（Guidance scale）** — 4.0–6.0 效果最佳。较高的值（>8）可能导致过饱和。
8. **tmux 是必须的** — 始终在 Clore.ai 上的一个 `tmux` 会话中运行生成以在 SSH 断开时保持进程存活。

## # 使用固定种子以获得一致结果

| 问题                        | 修复                                                                      |
| ------------------------- | ----------------------------------------------------------------------- |
| `OutOfMemoryError` 以 720p | 启用 `pipe.enable_model_cpu_offload()`；如果仍然 OOM 则降至 480p                  |
| HuggingFace 上未找到模型        | 检查 在 [SkyworkAI 的 HF 页面](https://huggingface.co/SkyworkAI) — 它可能以变体名称列出 |
| 抖动或闪烁的运动                  | 增加 `num_inference_steps` 到 40；将 `guidance_scale` 降到 4.0                 |
| 生成速度慢                     | 在 RTX 4090 上每个 4 秒剪辑 \~1–3 分钟为正常；480p 大约快 2 倍                           |
| 色偏 / 过度饱和                 | 降低 `guidance_scale` 到 4.0–5.0                                           |
| `ImportError: imageio`    | `pip install imageio[ffmpeg]`                                           |
| 重启时重新下载权重                 | 挂载持久存储并设置 `HF_HOME` 环境变量                                                |