LLaMA-VID：在大型语言模型中，一张图像值2个token

LLaMA-VID使现有框架能够支持长达一小时的视频，并通过额外的上下文token将其上限进一步提升。我们基于LLaVA构建了这个仓库。

发布

• [24/07/04] 🔥 我们的工作已被ECCV 2024接收！
• [23/12/05] 🔥 我们发布了完整的训练和评估模型、数据以及支持电影聊天的脚本！
• [23/11/29] 🔥 LLaMA-VID即将发布！我们发布了论文、代码、数据、模型和演示！

目录

• 演示
• 安装
• 模型
• 准备
• 训练
• 评估
• 示例
• 引用
• 致谢
• 许可证

演示

我们在这一部分提供了一些精选示例。更多示例请访问我们的项目页面。欢迎试用我们的在线演示！

安装

请按照以下步骤安装所需的软件包。

1. 克隆本仓库

git clone https://github.com/dvlab-research/LLaMA-VID.git

2. 安装软件包

conda create -n llamavid python=3.10 -y
conda activate llamavid
cd LLaMA-VID
pip install --upgrade pip  # 启用PEP 660支持
pip install -e .

3. 安装用于训练的附加软件包

pip install ninja
pip install flash-attn --no-build-isolation

模型

LLaMA-VID主要包含三个部分：编码器和解码器分别用于生成视觉嵌入和文本引导特征；上下文token和内容token则通过定制的token生成策略进行转换；指令微调旨在释放大型语言模型在图像和视频处理方面的潜力。

我们为LLaMA-VID提供了所有在阶段1和阶段2数据（长视频+阶段3）上完全微调过的模型：

类型	图像尺寸	最大token数	基础LLM	视觉编码器	微调数据	微调计划	下载
仅图像	224	4K	Vicuna-7B-v1.5	EVA-G	LLaVA1.5-Instruct	full_ft-1e	ckpt
仅图像	336	4K	Vicuna-7B-v1.5	EVA-G	LLaVA1.5-Instruct	full_ft-1e	ckpt
仅图像	336	4K	Vicuna-13B-v1.5	EVA-G	LLaVA1.5-Instruct	full_ft-1e	ckpt
短视频	224	4K	Vicuna-7B-v1.5	EVA-G	LLaVA1.5-VideoChatGPT-Instruct	full_ft-1e	ckpt
短视频	224	4K	Vicuna-13B-v1.5	EVA-G	LLaVA1.5-VideoChatGPT-Instruct	full_ft-1e	ckpt
长视频	224	64K	Vicuna-7B-v1.5	EVA-G	LLaVA1.5-VideoChatGPT-Instruct + LongVideoQA	full_ft-1e	ckpt

以下是仅在阶段1数据上预训练的权重（文本解码器+上下文注意力+投影器）：

类型	图像尺寸	最大token数	基础LLM	视觉编码器	预训练数据	预训练计划	下载
仅图像	224	4K	Vicuna-7B-v1.5	EVA-G	LCS-558K	1e	ckpt
仅图像	336	4K	Vicuna-7B-v1.5	EVA-G	LCS-558K	1e	ckpt
仅图像	336	4K	Vicuna-13B-v1.5	EVA-G	LCS-558K	1e	ckpt
短视频	224	4K	Vicuna-7B-v1.5	EVA-G	LCS-558K-WebVid-232K	1e	ckpt
短视频	224	4K	Vicuna-13B-v1.5	EVA-G	LCS-558K-WebVid-232K	1e	ckpt

准备

数据集

我们提供了用于 LLaMA-VID 训练的处理过的图像数据。数据格式按照 LLaVA 的标准组织，请按照 这篇文档 组织训练用的图像数据，并按照 这篇文档 组织评估用的图像数据。 请将预训练数据、微调数据和评估数据分别放入 LLaMA-VID-Pretrain、LLaMA-VID-Finetune 和 LLaMA-VID-Eval 子目录中，具体结构参考 结构。

对于视频数据集，请从 WebVid 下载 250 万条目的子集，并从 官方网站 或 video-chatgpt 下载 ActivityNet 数据集。 若需进行评估，还请从 这里 下载相应文件。MSVD-QA 可从 这里 下载，MSRVTT-QA 则可从 这里 获取。

关于长视频微调，请从 MovieNet 下载长视频数据，从 这里 下载镜头检测结果，并从 这里 下载我们构建的长视频问答对。在预处理之前，请将镜头检测结果放置于 LLaMA-VID-Finetune/movienet/files 目录下。

元信息方面，请下载以下文件，并按 结构 进行组织。

数据文件名	大小
blip_laion_cc_sbu_558k.json	181 MB
llava_v1_5_mix665k.json	1.03 GB
llava_558k_with_webvid.json	254 MB
llava_v1_5_mix665k_with_video_chatgpt.json	860 MB
llava_v1_5_mix665k_with_video_chatgpt_maxtime_5min.json	860 MB
long_videoqa.json	260 MB

预训练权重

我们建议用户从以下链接下载预训练权重：Vicuna-7b-v1.5、Vicuna-13b-v1.5、EVA-ViT-G、QFormer-7b、QFormer-13b，并将其放置在 model_zoo 目录中，具体结构参考 结构。

结构

在开始训练之前，文件夹结构应按如下方式组织：

LLaMA-VID
├── llamavid
├── scripts
├── work_dirs
│   ├── llama-vid
│   │   ├── llama-vid-13b-full-336
│   │   ├── ...
├── model_zoo
│   ├── LLM
│   │   ├── vicuna
│   │   │   ├── 7B-V1.5
│   │   │   ├── 13B-V1.5
│   ├── LAVIS
│   │   ├── eva_vit_g.pth
│   │   ├── instruct_blip_vicuna7b_trimmed.pth
│   │   ├── instruct_blip_vicuna13b_trimmed.pth
├── data
│   ├── LLaMA-VID-Pretrain
│   │   ├── blip_laion_cc_sbu_558k.json
│   │   ├── llava_558k_with_webvid.json
│   │   ├── images
│   │   ├── videos
│   ├── LLaMA-VID-Finetune
│   │   ├── llava_v1_5_mix665k.json
│   │   ├── llava_v1_5_mix665k_maxround_6_total_921k.json
│   │   ├── llava_v1_5_mix665k_maxround_12_total_714k.json
│   │   ├── llava_v1_5_mix665k_with_video_chatgpt.json
│   │   ├── llava_v1_5_mix665k_with_video_chatgpt_maxtime_5min.json
│   │   ├── long_videoqa.json
│   │   ├── movienet
│   │   ├── activitynet
│   │   ├── coco
│   │   ├── gqa
│   │   ├── ocr_vqa
│   │   ├── textvqa
│   │   ├── vg
│   ├── LLaMA-VID-Eval
│   │   ├── gqa
│   │   ├── ...

训练

LLaMA-VID 的训练分为三个阶段：(1) 特征对齐阶段：连接视觉和语言的标记；(2) 指令微调阶段：教会模型遵循多模态指令；(3) 长视频微调阶段：扩展位置嵌入，并教会模型理解长达数小时的视频指令。

LLaMA-VID 使用 8 块 80GB 显存的 A100 GPU 进行训练。若使用较少的 GPU，可以相应减少 per_device_train_batch_size 并增加 gradient_accumulation_steps。务必保持全局批次大小不变：per_device_train_batch_size × gradient_accumulation_steps × num_gpus。

请确保在训练前按照 准备工作 下载并整理好数据。

仅图像

若仅希望基于图像数据训练和微调 LLaMA-VID，请针对 Vicuna-7B（图像尺寸 336）运行以下命令：

bash scripts/image_only/train/stage_1_2_full_v7b_336.sh

或针对 Vicuna-13B（图像尺寸 336）：

bash scripts/image_only/train/stage_1_2_full_v13b_336.sh

您也可以尝试使用较小的图像尺寸 224 和更少的视觉标记：

bash scripts/image_only/train/stage_1_2_full_v7b_224_grid_4.sh

更多训练脚本可在 scripts/image_only/train 目录中找到。

短视频

若您对基于短视频数据训练和微调 LLaMA-VID 感兴趣，请针对 Vicuna-7B（图像尺寸 224）运行以下命令：

bash scripts/video/train/stage_1_2_full_v7b_224_fps_1.sh

或针对 Vicuna-13B（图像尺寸 224）：

bash scripts/video/train/stage_1_2_full_v13b_224_fps_1.sh

更多训练脚本可在 scripts/video/train 目录中找到。

长视频

我们提供了长视频训练的数据集和脚本。请按照 准备工作 下载长视频数据，并按 结构 进行组织。 在训练阶段，我们首先从长视频中提取所有帧，并将视觉特征本地保存，以提高训练效率。

python scripts/extra_tool/extract_movienet_features.py \
    --video_dir <movienet视频路径> \
    --files_dir <movienet文件路径> \ # 已下载的MovieNet.tar.gz中的文件
    --feat_dir <输出特征路径>

然后，针对 Vicuna-7B（图像尺寸 224）运行以下命令：

bash scripts/video/train/stage_3_full_v7b_224_longvid.sh

评估

我们在基于图像和基于视频的基准测试上进行了评估。请按照准备工作下载评估数据，并按照结构进行组织。

仅图像

LLM	分辨率	模型	GQA	MMB	MME	POPE	SEED	SQA-Image	VizWiz	VQA v2
Vicuna-7B	224	ckpt	63.0	65.3	1405.6	86.6	59.7	67.7	52.5	78.3
Vicuna-7B	336	ckpt	64.3	65.1	1521.4	86.0	59.9	68.3	54.2	79.3
Vicuna-13B	336	ckpt	65.0	66.6	1542.3	86.0	62.3	70.0	54.3	80.0

如果您想在基于图像的基准测试上评估模型，请使用scripts/image_only/eval中的脚本。 例如，运行以下命令进行GQA评估：

bash scripts/image_only/eval/gqa.sh

更多评估脚本请参见scripts/image_only/eval。

视频

LLM	分辨率	模型	MSVD-QA	MSRVTT-QA	ActivityNet-QA	正确性	细节	上下文	时间	一致性
Vicuna-7B	224	ckpt	69.7	57.7	47.4	2.96	3.00	3.53	2.46	2.51
Vicuna-13B	224	ckpt	70.0	58.9	47.5	3.07	3.05	3.60	2.58	2.63

如果您想在基于视频的基准测试上评估模型，请使用scripts/video/eval中的脚本。 例如，运行以下命令进行MSVD-QA评估：

bash scripts/video/eval/msvd_eval.sh

更多评估脚本请参见scripts/video/eval。

CLI 推理

无需Gradio界面即可使用LLaMA-VID与图像和视频进行对话。它还支持多GPU、4位和8位量化推理。采用4位量化时。 请尝试以下命令进行图像或视频推理：

python -m llamavid.serve.cli \
    --model-path work_dirs/llama-vid/llama-vid-7b-full-336 \
    --image-file <您的图像路径>

或者尝试以下命令进行视频推理：

python -m llamavid.serve.cli \
    --model-path work_dirs/llama-vid/llama-vid-7b-full-224-video-fps-1 \
    --image-file <您的视频路径> \
    --temperature 0.5

您也可以尝试4位或8位以实现高效推理：

python -m llamavid.serve.cli \
    --model-path work_dirs/llama-vid/llama-vid-7b-full-224-video-fps-1 \
    --image-file <您的视频路径>
    --temperature 0.5 \
    --load-4bit

长视频推理

对于长视频，如果您想对movienet中的视频进行推理，首先需要按如下方式处理视频数据和字幕：

python scripts/extra_tool/extract_movienet_features.py \
    --video_dir <movienet视频路径> \
    --files_dir <movienet文件路径> \ # 下载的MovieNet.tar.gz中的文件
    --feat_dir <输出特征路径>

如果您想对自己的自定义视频进行推理，也需先按如下方式处理视频数据和字幕：

python scripts/extra_tool/extract_video_features_subtitles.py \
    --video_file <自定义视频路径> \
    --feat_dir <输出特征路径>

然后，您可以尝试以下命令进行长视频推理：

python llamavid/serve/run_llamavid_movie.py \
    --model-path work_dirs/llama-vid/llama-vid-7b-full-224-long-video \
    --video-file <您已处理的视频文件路径> \
    --load-4bit

Gradio Web UI

在这里，我们采用了类似于 LLaVA 的 Gradio 界面，为 LLaMA-VID 提供一个用户友好的交互界面。要在本地启动 Gradio 演示，请依次运行以下命令。如果你计划启动多个模型工作进程以比较不同的检查点，只需仅需一次启动控制器和 Web 服务器即可。

启动控制器

python -m llamavid.serve.controller --host 0.0.0.0 --port 10000

启动 Gradio Web 服务器

python -m llamavid.serve.gradio_web_server --controller http://localhost:10000 --model-list-mode reload

现在你已经成功启动了 Gradio Web 界面。你可以通过屏幕上打印的 URL 打开该界面。你可能会注意到模型列表中还没有任何模型，这是因为我们尚未启动任何模型工作进程。当启动模型工作进程后，模型列表会自动更新。

启动模型工作进程

这是实际在 GPU 上执行推理的工作进程。每个工作进程负责 --model-path 中指定的单个模型。

python -m llamavid.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path work_dirs/llama-vid/llama-vid-vicuna-7b-short

等待进程完成模型加载，并看到“Uvicorn running on ...”的提示后，刷新你的 Gradio Web 界面，你就会在模型列表中看到刚刚启动的模型。

你可以根据需要启动任意数量的工作进程，并在同一 Gradio 界面中比较不同的模型。例如，这里有一个短视频模型。请确保 --controller 参数保持不变，而将 --port 和 --worker 分别设置为不同的端口号以区分各个工作进程。

python -m llamavid.serve.model_worker_short --host 0.0.0.0 --controller http://localhost:10000 --port <不同于40000，比如40001> --worker http://localhost:<相应地改为40001> --model-path work_dirs/llama-vid/llama-vid-7b-full-224-video-fps-1

如果你使用的是搭载 M1 或 M2 芯片的 Apple 设备，可以通过 --device 标志指定 MPS 设备：--device mps。

启动模型工作进程（多 GPU，当 GPU 显存 ≤ 24GB 时）

如果你的 GPU 显存小于 24GB（例如 RTX 3090、RTX 4090 等），可以尝试使用多 GPU 运行。我们最新的代码库会在你拥有多个 GPU 时自动尝试使用多 GPU。你可以通过 CUDA_VISIBLE_DEVICES 指定要使用的 GPU。下面是一个使用前两块 GPU 的示例：

CUDA_VISIBLE_DEVICES=0,1 python -m llamavid.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path work_dirs/llama-vid/llama-vid-7b-full-224-long-video

启动模型工作进程（4-bit、8-bit 推理，量化版本）

你可以启动使用量化位数（4-bit、8-bit）的模型工作进程，这样可以在降低 GPU 内存占用的同时进行推理。需要注意的是，量化位数的推理精度可能不如全精度模型高。只需在你要执行的模型工作进程命令中添加 --load-4bit 或 --load-8bit 即可。下面是一个使用 4-bit 量化运行的示例：

python -m llamavid.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path work_dirs/llama-vid/llama-vid-7b-full-224-long-video --load-4bit

示例

本节提供了一些示例。更多示例请参阅我们的项目页面。

引用

如果你发现本仓库对你的研究有所帮助，请考虑引用以下论文：

@inproceedings{li2024llamavid,
  title={LLaMA-VID: An Image is Worth 2 Tokens in Large Language Models},
  author={Li, Yanwei and Wang, Chengyao and Jia, Jiaya},
  journal={European Conference on Computer Vision},
  year={2024}
}

致谢

我们感谢以下项目组的杰出工作：

• 本工作基于 LLaVA 构建。
• 本工作使用了来自 Vicuna 的 LLM。
• 本工作使用了来自 InstructBLIP 的预训练权重。
• 我们参考了 Video-ChatGPT 的视频评估方法。

许可证

本项目的数据和检查点仅供研究使用，并受相关许可协议约束。它们同样受到 LLaVA、LLaMA、Vicuna 和 GPT-4 许可协议的限制。数据采用 CC BY NC 4.0 许可，仅允许非商业用途；使用该数据集训练的模型也不得用于研究以外的场景。

LLaMA-VID 快速上手指南

LLaMA-VID 是一个基于 LLaVA 架构的多模态大模型，专为处理长视频（长达数小时）而设计。它通过独特的令牌生成策略，将图像压缩为极少的上下文令牌，从而显著扩展了模型的视频理解能力。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• GPU: 建议至少 1 张 NVIDIA GPU (显存 >= 24GB，训练推荐 8x A100 80GB)
• CUDA: 已安装与 PyTorch 版本匹配的 CUDA 驱动
• 包管理器: Conda (推荐 Miniconda 或 Anaconda)
• Python: 3.10

2. 安装步骤

请按照以下步骤克隆代码并安装依赖。

2.1 克隆仓库

git clone https://github.com/dvlab-research/LLaMA-VID.git
cd LLaMA-VID

2.2 创建虚拟环境并安装基础包

conda create -n llamavid python=3.10 -y
conda activate llamavid
pip install --upgrade pip
pip install -e .

2.3 安装训练专用依赖

如果您计划进行模型训练或微调，需额外安装 ninja 和 flash-attn 以加速计算：

pip install ninja
pip install flash-attn --no-build-isolation

提示：国内用户若下载 flash-attn 较慢，可尝试使用清华源或阿里源加速 pip 安装，例如：pip install flash-attn --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple。

3. 基本使用

LLaMA-VID 的核心优势在于长视频理解。使用前需先下载预训练权重和数据集。

3.1 下载预训练权重与数据

根据您的需求（仅图像、短视频或长视频），从 Hugging Face 下载对应的模型权重。以下是长视频模型的示例：

• 模型权重: llama-vid-7b-full-224-long-video
• 数据集: LLaMA-VID-Data

请将下载的权重文件整理至项目根目录下的 model_zoo 文件夹，数据结构参考如下：

LLaMA-VID
├── model_zoo
│   ├── LLM
│   │   └── vicuna
│   │       └── 7B-V1.5  # 存放 Vicuna 权重
│   ├── LAVIS
│   │   ├── eva_vit_g.pth
│   │   └── instruct_blip_vicuna7b_trimmed.pth
├── data
│   ├── LLaMA-VID-Finetune
│   │   └── long_videoqa.json # 存放长视频问答数据
│   └── ...

(具体文件组织请严格参照官方 README 中的 "Structure" 章节)

3.2 运行推理/评估

项目提供了封装好的脚本用于不同场景。以下是运行长视频微调后模型进行评估的示例命令（需先配置好数据路径）：

# 示例：运行长视频评估脚本 (具体参数需根据实际下载的数据集路径调整)
python llamavid/eval/model_video_chatgpt.py \
    --model-path /path/to/llama-vid-7b-full-224-long-video \
    --video-dir /path/to/video/files \
    --conv-mode llama_vid

3.3 启动训练 (可选)

若您希望从头训练或微调模型，可使用提供的 Shell 脚本。以下是以 Vicuna-7B 为基础，针对长视频数据进行全量微调的示例：

1. 预处理长视频特征 (提取帧并保存视觉特征以加速训练):

   python scripts/extra_tool/extract_movienet_features.py \
       --video_dir <path to movienet video> \
       --files_dir <path to movienet files> \
       --feat_dir <path to output features>
   

2. 执行训练:

   # 运行长视频训练脚本 (需确保显存充足，默认配置针对多卡环境)
   bash scripts/video/train/stage_3_long_video_v7b_224.sh
   

   注：如果显存有限，请编辑脚本，减小 per_device_train_batch_size 并相应增加 gradient_accumulation_steps，保持全局 batch size 不变。

---

更多详细用法、Demo 演示及完整数据集说明，请访问 LLaMA-VID 项目主页。