VILA-U 复现 - TechBlog

Paper: arXiv: 2409.04429
Model: huggingface: mit-han-lab/vila-u
Code: Github: mit-han-lab/vila-u
Project: hanlab.mit.edu/projects/vila-u

本文档记录了在 AutoDL 云平台从零开始复现 VILA-U 多模态模型的完整过程，包括环境配置、存储优化、模型下载、推理验证及常见问题处理。

1. 环境初始化

git clone https://github.com/mit-han-lab/vila-u
cd vila-u

1.1 问题：安装脚本因磁盘空间不足失败

直接运行 ./environment_setup.sh vila-u 时，conda 安装包和 pip 缓存会写入系统盘，而 AutoDL 系统盘通常只有 30 GB，极易写满。

1.2 解决方案：将缓存路径重定向到数据盘

在运行安装脚本前，先执行以下配置：

# 1. 设置 conda 环境到数据盘
mkdir -p /root/autodl-tmp/conda/pkgs
mkdir -p /root/autodl-tmp/conda/envs
conda config --add pkgs_dirs /root/autodl-tmp/conda/pkgs
conda config --add envs_dirs /root/autodl-tmp/conda/envs

# 2. 设置 pip 缓存到数据盘
export PIP_CACHE_DIR=/root/autodl-tmp/.pip_cache
mkdir -p $PIP_CACHE_DIR

# 3. 验证配置
cat ~/.condarc

预期 ~/.condarc 内容包含自定义路径：

channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/
  - defaults
show_channel_urls: true
pkgs_dirs:
  - /root/autodl-tmp/conda/pkgs
envs_dirs:
  - /root/autodl-tmp/conda/envs

1.3 保持配置持久化

环境变量 PIP_CACHE_DIR 仅在当前终端有效，关闭终端会丢失。将其与 Hugging Face 缓存路径一并写入 ~/.bashrc：

echo '' >> ~/.bashrc
echo '# === VILA-U 环境配置 ===' >> ~/.bashrc
echo 'export PIP_CACHE_DIR=/root/autodl-tmp/.pip_cache' >> ~/.bashrc
echo 'export HF_HOME=/root/autodl-tmp/.cache/huggingface' >> ~/.bashrc
echo 'export TMPDIR=/root/autodl-tmp/tmp' >> ~/.bashrc

source ~/.bashrc

验证持久化：

# 新开终端或模拟
bash -l -c 'echo "PIP_CACHE_DIR in new shell: $PIP_CACHE_DIR"'
conda config --show pkgs_dirs
cat ~/.condarc | grep pkgs_dirs

若输出为数据盘路径，说明配置已持久生效。

完成以上步骤后，再执行安装脚本：

./environment_setup.sh vila-u

2. 模型权重下载

VILA-U 官方权重 vila-u-7b-256 约 12.7 GB，存放在 Hugging Face。国内直接 git clone 极易超时或 LFS 断连。

2.1 下载方案（推荐）

使用 huggingface_hub 提供的 hf download 命令，配合国内镜像。

安装 hf 工具（如果尚未安装）：

pip install huggingface_hub

设置镜像并下载到数据盘：

export HF_ENDPOINT=https://hf-mirror.com

cd /root/autodl-tmp

hf download mit-han-lab/vila-u-7b-256 \
  --local-dir /root/autodl-tmp/vila-u-7b-256 \
  --max-workers 1

参数说明：

参数	作用
`mit-han-lab/vila-u-7b-256`	Hugging Face 模型 ID
`--local-dir`	指定本地存放目录（直接落在此处）
`--max-workers 1`	单线程下载，减少大文件断连风险

2.2 断点续传

若下载中断，无需删库重来。可指定缺少的文件单独下载：

# 单文件下载
hf download mit-han-lab/vila-u-7b-256 \
  llm/model-00003-of-00003.safetensors \
  --local-dir /root/autodl-tmp/vila-u-7b-256 \
  --max-workers 1

# 如果某文件不完整，先删除再重下
rm -f /root/autodl-tmp/vila-u-7b-256/llm/model-00001-of-00003.safetensors
hf download mit-han-lab/vila-u-7b-256 \
  llm/model-00001-of-00003.safetensors \
  --local-dir /root/autodl-tmp/vila-u-7b-256 \
  --max-workers 1

2.3 校验权重完整性

import os
from huggingface_hub import hf_hub_url, get_hf_file_metadata

repo = "mit-han-lab/vila-u-7b-256"
base = "/root/autodl-tmp/vila-u-7b-256"
files = [
    "llm/model-00001-of-00003.safetensors",
    "llm/model-00002-of-00003.safetensors",
    "llm/model-00003-of-00003.safetensors",
    "vision_tower/model.safetensors",
    "mm_projector/model.safetensors",
]

for f in files:
    remote_size = get_hf_file_metadata(hf_hub_url(repo, f)).size
    local_path = os.path.join(base, f)
    local_size = os.path.getsize(local_path) if os.path.exists(local_path) else -1
    print(f"{f}: {'OK' if remote_size == local_size else f'错误 (本地{local_size} vs 远端{remote_size})'}")

全部输出 OK 即完整。

2.4 目录结构

/root/autodl-tmp/vila-u-7b-256/
├── config.json
├── README.md
├── llm/                # 主语言模型权重（3 个 safetensors 分片）
├── vision_tower/       # 视觉编码器权重
└── mm_projector/       # 多模态投影层权重

3. 推理环境确认与基本命令

推理使用已配置的 vila-u conda 环境，依赖 transformers 4.36.2 及官方提供的 transformers_replace 补丁。不必重装任何包，冲突的库（如 lmms-eval）不影响推理。

3.1 激活环境

conda activate vila-u
cd /root/autodl-tmp/vila-u

3.2 图像理解（看图问答）

CUDA_VISIBLE_DEVICES=0 python inference.py \
  --model_path /root/autodl-tmp/vila-u-7b-256 \
  --image_path /path/to/your_image.jpg \
  --query "Describe this image in detail."

3.3 视频理解（对视频提问）

CUDA_VISIBLE_DEVICES=0 python inference.py \
  --model_path /root/autodl-tmp/vila-u-7b-256 \
  --video_path /path/to/your_video.mp4 \
  --query "Summarize the video content."

3.4 文生图

CUDA_VISIBLE_DEVICES=0 python inference.py \
  --model_path /root/autodl-tmp/vila-u-7b-256 \
  --prompt "A snowy mountain at sunset." \
  --save_path /root/autodl-tmp/outputs/images \
  --generation_nums 4

图 0	图 1	图 2	图 3

3.5 文生视频

CUDA_VISIBLE_DEVICES=0 python inference.py \
  --model_path /root/autodl-tmp/vila-u-7b-256 \
  --prompt "Fireworks bursting in the night sky." \
  --video_generation True \
  --save_path /root/autodl-tmp/outputs/videos

注意：该命令生成 8 帧图像，拼接为一张横向长图 video_0.png，不会直接输出 .mp4（详见第 4 节）。

3.6 Gradio 网页演示（可选）

CUDA_VISIBLE_DEVICES=0 python app.py --model_path /root/autodl-tmp/vila-u-7b-256

4. 关于文生视频输出的说明

4.1 输出形式

VILA‑U 的视频生成为 固定 8 帧 的序列图像。代码中的 save_video 函数将这 8 帧横向拼接，保存为一张 .png 图片（例如 video_0.png），不是 .mp4 等视频文件。

4.2 时序性分析

模型内部按 因果自回归 顺序生成 2048 个视觉 token（每帧 256 token，共 8 帧），因此序列具有 帧顺序（第 1 帧→第 2 帧→…→第 8 帧），但没有显式时间戳、帧率或运动矢量。这种设计可看作“按顺序生成多帧图像”，适用于有限长度的简单动态。

4.3 导出 MP4（可选）

若需合成标准视频文件，可使用 ffmpeg 将长图裁剪为帧后合并（假设长图总宽 2048 像素，每帧 256×256）：

ffmpeg -i /root/autodl-tmp/outputs/videos/video_0.png \
  -vf "crop=256:256:'mod(n,8)*256':0" -r 8 \
  /root/autodl-tmp/outputs/videos/output.mp4

或在 inference.py 中自定义 save_video，用 cv2.VideoWriter 直接写入 mp4。

5. 硬件资源建议

显存需求：VILA‑U 7B 全量加载约需 16 GB 以上显存，推荐 24 GB 及以上 GPU（如 A10、3090、4090）。
系统盘空间：已通过配置将缓存、权重全部置于 /root/autodl-tmp（数据盘），安装后系统盘占用很低。

6. 常见问题速查

问题	原因	解决
环境安装时磁盘满	conda/pip 缓存写系统盘	按第 1.2 节重定向缓存到数据盘
`git clone` 权重失败	直连 Hugging Face 超时/LFS 断连	使用 `hf download` + 国内镜像（第 2 节）
`PIP_CACHE_DIR` 终端关闭后丢失	环境变量仅临时生效	将变量写入 `~/.bashrc`（第 1.3 节）
下载中断	网络波动	单文件续传（第 2.2 节）
生成视频为 PNG 而非 MP4	官方设计如此（拼接帧）	参考第 4.3 节合成视频或自行修改保存函数
推理时 `import vila_u` 失败	未激活 vila-u 环境或路径不对	`conda activate vila-u` 且确保在仓库目录下