适用场景
这套方案面向只有一张消费级显卡（24GB 显存这一档，如 RTX 3090/4090 系列）的开发者，目标是在本地跑通一个能对输入做出即时响应的世界模型 demo：给出画面或控制信号，模型在几百毫秒内吐出下一段 720P 视频。适合做产品预研、内容创作试验、教学演示，不适合直接当生产服务——单卡单实例没有冗余，一旦显存吃满就会中断。
环境与前置条件
硬件底线
- 显卡：显存建议 24GB 起步。720P 实时推理的显存大头在 KV 缓存和 VAE 解码，16GB 卡能跑起来，但通常要把分辨率降到 960×540 或者把帧率压到 12～16 FPS。
- 内存：32GB 以上。权重加载、视频帧在内存里排队都会吃内存，16GB 机器容易在加载阶段被 OOM Killer 干掉。
- 磁盘：预留 100GB 以上 SSD。开源权重加上依赖包体积不小，机械盘加载权重会明显拖慢启动。
- CPU：6 核以上。实时链路里编码、推流、前后处理都在 CPU 侧，CPU 打满时 GPU 会空转等数据。
软件环境
- 操作系统：Ubuntu 22.04 LTS 是阻力最小的选择。WSL2 可以跑，但 PCIe 转发和视频编码会有额外开销，实时性会打折；Windows 原生环境依赖编译问题较多。
- 显卡驱动：装与 CUDA 运行时匹配的官方驱动，
nvidia-smi右上角显示的 CUDA Version 要不低于框架要求。 - Python 3.10 或 3.11，用 conda 或 venv 做隔离。
- ffmpeg（带 NVENC 支持更好），用于视频读写和推流。
EdenLive 的具体脚本入口、参数名、配置字段以官方仓库 README 和示例配置为准。下面给的是一套通用骨架，字段名对不上时按语义映射即可，思路是完全一致的。
分步骤部署
第 1 步：体检显卡与驱动
先确认卡被正确识别、驱动版本够用、没有其他进程占着显存。
```bash
nvidia-smi
nvidia-smi --query-gpu=name,memory.total,memory.used,driver_version --format=csv
```
预期输出里能看到你的显卡型号、memory.total 接近标称值（比如 24564 MiB）、memory.used 只有几百 MiB。如果 nvidia-smi 报 “Failed to initialize NVML”，先解决驱动问题，后面所有步骤都跑不通。
再看 CUDA 编译工具链：
```bash
nvcc --version
```
如果没有 nvcc 也不用慌——很多项目只需要 PyTorch 自带的 CUDA 运行时，编译扩展时再用 conda 装对应版本的 cudatoolkit-dev 即可。
第 2 步：创建隔离环境
实时推理对版本极其敏感，务必单独开一个环境，不要和别的项目共用。
```bash
conda create -n edenlive python=3.11 -y
conda activate edenlive
python -V
```
看到 Python 3.11.x 即成功。后续所有命令都在这个环境里执行。
第 3 步：拉取代码与安装依赖
```bash
git clone <官方仓库地址> edenlive
cd edenlive
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
```
这一步在装 PyTorch、transformers、diffusers、视频编解码库等。耗时几分钟到十几分钟，取决于网络。装完后验证核心库能正确识别显卡：
```bash
python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
```
预期输出 True 和你的显卡型号。如果是 False，说明装的是 CPU 版 PyTorch，需要按官方文档用带 CUDA 标识的源重装。
如果项目用到了 AI 词典：FlashAttention">FlashAttention，单独装：
```bash
pip install flash-attn --no-build-isolation
```
这一步可能要编译十几分钟。装不上不影响先跑通，配置里把 attention 后端换成 sdpa 即可。
第 4 步：下载开源权重
权重通常放在 Hugging Face 上。用官方 CLI 下载并指定本地目录：
```bash
pip install -U "huggingface_hub[cli]"
网络受限时可设置镜像端点，具体地址以镜像站当前说明为准
export HF_ENDPOINT=<镜像站地址>
hf download <组织名>/<模型仓库名> --local-dir ./weights/edenlive
```
如果仓库需要授权，先 hf auth login 填入 access token。下载完成后核对体积：
```bash
du -sh ./weights/edenlive
ls -lh ./weights/edenlive
```
预期能看到多个 .safetensors 分片和 config.json、分词器文件。体积明显小于官方标注时，说明下载中断了，删掉目录重下。
第 5 步：写实时推理配置
新建 configs/realtime_720p.yaml。每一条都对应一个真实的显存/延迟取舍：
```yaml
model:
weights: ./weights/edenlive
dtype: bfloat16 # Ampere 及以上用 bf16 更稳；老卡或出现 NaN 时改 float16
device: cuda:0
attention: flash_attention_2 # 装不上改 sdpa
enable_torch_compile: true # 首次启动慢，之后每帧更快
runtime:
resolution: [1280, 720]
fps: 24
frame_chunk: 3 # 每次前向生成的帧数，实时链路取 2~4
steps: 4 # 采样步数，配合蒸馏权重可再降
guidance: 1.5
vae_tiling: true # 显存吃紧时开启，省显存但解码稍慢
cpu_offload: false # 实时场景必须关闭，开了延迟会翻倍
keep_kv_cache: true # 保留历史上下文，减少画面跳变
server:
host: 0.0.0.0
port: 8000
protocol: webrtc # 或 websocket
max_queue: 1 # 只处理最新一帧，旧帧直接丢弃
```
max_queue: 1 这条容易被忽略但很关键：队列长度大于 1 时，模型会老老实实把积压的旧帧算完，表现出来就是“操作已经停了，画面还在动”。
第 6 步：先跑离线，确认模型本身没问题
不要一上来就开实时服务。先用离线模式跑一小段，把权重、精度、显存这些基础问题排干净。
```bash
python scripts/infer.py \
--config configs/realtime_720p.yaml \
--mode offline \
--prompt "<你的场景描述>" \
--frames 48 \
--out out/test.mp4
```
成功标志：进程正常结束，out/test.mp4 生成。用 ffprobe 核对规格：
```bash
ffprobe -v error -show_entries stream=width,height,r_frame_rate,nb_frames \
-of default=nw=1 out/test.mp4
```
预期 width=1280、height=720、r_frame_rate=24/1。同时另开一个终端盯显存：
```bash
watch -n 0.5 nvidia-smi --query-gpu=memory.used,utilization.gpu,temperature.gpu --format=csv
```
显存占用要留出至少 1～2GB 余量，贴着上限跑在实时模式下很容易崩。
第 7 步：启动实时服务
```bash
python scripts/serve.py --config configs/realtime_720p.yaml
```
启动日志里会打印监听地址和实际生效的推理参数。浏览器打开 http://<机器IP>:8000，应该能看到实时画面。首次启动因为 torch.compile 要编译图，会卡顿几十秒到几分钟，属于正常现象，第二次启动会快很多。
如果项目提供预热参数，建议加上，让模型在接收第一个请求前就把显存池和编译缓存准备好。
第 8 步：接入交互输入
把键盘、鼠标或摄像头的输入接到服务端，让画面随操作变化。常见的做法是客户端通过 WebSocket 上报事件，服务端把它转成条件向量送进模型。注意两点：
- 输入要做节流，按 24 FPS 的节奏采样，别把每秒上百次的鼠标事件全塞进去。
- 服务端对输入做“取最新值”处理，中间态直接丢弃，和
max_queue: 1是同一个道理。
第 9 步：延迟调优
先量再调。在链路里打点，把端到端延迟拆成四段记录：输入编码、模型前向、VAE 解码、编码传输。哪一段占比大就调哪一段。
几个见效比较快的方向：
- 降采样步数：
steps从 8 降到 4 通常延迟减半，画质损失在实时预览里往往可以接受；如果官方提供蒸馏权重，优先换用。 - 缩小 frame_chunk：从 4 降到 2，单次前向更快，但每次生成的时间跨度变短，画面连贯性要靠 KV 缓存补。
- VAE 解码分块：
vae_tiling: true能省显存，但解码时间会增加；显存够就关掉。 - 编码走硬件：用 NVENC 代替 CPU 软编，
ffmpeg -c:v h264_nvenc，能省下可观的 CPU 时间和延迟。 - 异步流水线：让“生成下一块”和“编码发送当前块”并行，GPU 和编码器不互相等。
验证部署是否成功
1. 服务可用性
```bash
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/
```
预期返回 200。
2. 输出规格
用前面的 ffprobe 命令确认分辨率是 1280×720、帧率是 24/1。
3. 实时性
在浏览器端或用脚本记录从“发出输入”到“画面更新”的时间戳差值，连续采样 100 次取中位数。720P 场景下，中位数能稳定在数百毫秒量级，就可以认为链路是通的；如果持续超过 1 秒且 GPU 利用率不高，问题多半在 CPU 侧或队列堆积。
4. 稳定性
挂机跑 30 分钟，期间观察：
```bash
nvidia-smi --query-gpu=memory.used,utilization.gpu,temperature.gpu,clocks_throttle_reasons.active --format=csv -l 2
```
重点看显存是否随时间缓慢上涨（有上涨就是有地方在攒缓存），以及有没有触发 HW Slowdown 之类的降频原因。消费级卡长时间高负载会撞温度墙降频，帧率随之抖动。
常见报错与解决
报错：torch.OutOfMemoryError: CUDA out of memory. Tried to allocate ...
原因：显存不足。常见于分辨率开太高、frame_chunk 太大、或者 cpu_offload 关着但显存余量本来就少。
解决：按顺序试——先降 frame_chunk 到 2，再开 vae_tiling: true，再把分辨率降到 960×540；同时加上内存分配器优化参数：
```bash
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
python scripts/serve.py --config configs/realtime_720p.yaml
```
另外确认没有别的进程占着显存：nvidia-smi 看进程列表，或 sudo fuser -v /dev/nvidia*。
报错：ImportError: ... flash_attn_2_cuda ... undefined symbol
原因：FlashAttention 的预编译包和当前 PyTorch / CUDA 版本 ABI 不匹配，通常是先装了别的版本 torch 又升级导致的。
解决：卸载后重装，或者干脆换后端。
```bash
pip uninstall -y flash-attn
pip install flash-attn --no-build-isolation
```
装不上就把配置里的 attention 改成 sdpa，功能不受影响，只是显存和速度略差。
报错：RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu
原因：部分模块被 offload 到 CPU 了，或者配置里 cpu_offload 和 device: cuda:0 冲突。
解决：实时模式下确认 cpu_offload: false，并检查有没有设 CUDA_VISIBLE_DEVICES 导致设备编号错位。
```bash
echo $CUDA_VISIBLE_DEVICES
CUDA_VISIBLE_DEVICES=0 python scripts/serve.py --config configs/realtime_720p.yaml
```
报错：401 Client Error / 403 Forbidden / 下载卡在 0%
原因：权重仓库需要授权但没登录，或者网络到 Hugging Face 不通。
解决：
```bash
hf auth login # 粘贴 access token
export HF_ENDPOINT=<镜像站地址> # 地址以镜像站当前说明为准
hf download <组织名>/<模型仓库名> --local-dir ./weights/edenlive
```
现象：GPU 利用率只有 30%，帧率上不去
原因：不是算力瓶颈，是 CPU 侧跟不上——软编码、逐帧写盘、同步等待都在拖后腿。
解决：改用 NVENC 硬编，把日志和落盘改成异步线程，检查 top 里是不是某个 Python 进程单核跑满。
```bash
ffmpeg -hwaccels # 确认列表里有 cuda / nvenc
```
现象：画面闪烁、物体前后不一致
原因：每次生成的 chunk 太短又没有复用上下文。
解决：打开 keep_kv_cache，把 frame_chunk 调回 3～4，或者适当提高 guidance 让条件约束更强。
后续维护
备份
需要备份的只有三样：配置文件、环境依赖清单、权重文件校验值。前两样很小，建议纳入 Git：
```bash
pip freeze > requirements.lock.txt
sha256sum weights/edenlive/*.safetensors > weights.sha256
```
权重本身不用进版本库，但哈希清单要留，方便换机器时校验下载是否完整。
升级
项目和框架都在快速迭代，升级前一定做好两件事：一是新建独立环境验证，别在原地 pip install -U；二是锁定版本，requirements.lock.txt 就是为此存在。升级后跑一遍前面的验证清单，重点看输出规格和延迟中位数有没有变化。
日志
给每帧记一行 JSON：时间戳、输入摘要、前向耗时、解码耗时、显存占用。出问题时能直接定位是哪个环节退化。
```bash
tail -f logs/infer.jsonl | jq '.forward_ms'
```
监控
日常挂机推荐两条命令：
```bash
nvidia-smi dmon -s pucvmet -d 5 # 功耗、利用率、温度、显存、降频原因
df -h . # 输出目录容易悄悄吃满磁盘
```
有条件的话接 DCGM exporter + Prometheus，把显存占用和温度做成曲线，比事后翻日志直观得多。
清理
长时间运行会积累临时文件和编译缓存，定期清理：
```bash
du -sh ~/.cache/huggingface ~/.cache/torch
rm -rf out/*.mp4 # 确认不需要再删
```
最后提醒一句：单卡实时世界模型目前仍在“能演示”和“能稳定服务”之间，调参时优先保证不崩、延迟可预期，画质精修放到第二步。参数细节以 EdenLive 官方文档当前版本为准，各字段的实际名称和取值范围可能随版本调整，照抄前先对一遍示例配置。