VideoLLaMA 3：面向视频理解的前沿多模态基础模型

如果我们的项目对您有所帮助，请在 GitHub 上给我们点个赞 ⭐，以支持我们。🙏🙏

📰 新闻

• [2025.02.07] 🔥🔥 发布我们重新标注的高质量图文数据集 VL3-Syn7M。
• [2025.01.26] 🔥🔥 截至1月26日，VideoLLaMA3-7B是Hugging Face空间上的LVBench排行榜上表现最好的7B参数量模型。
• [2025.01.24] 🔥🔥 截至1月24日，VideoLLaMA3-7B是VideoMME排行榜上表现最好的7B参数量模型。
• [2025.01.22] 👋👋 发布VideoLLaMA 3的技术报告。如果您有与VideoLLaMA 3密切相关但未在论文中提及的工作，欢迎随时告知我们。
• [2025.01.21] 发布VideoLLaMA 3的模型及推理代码。

🌟 简介

VideoLLaMA 3是一系列具有前沿图像和视频理解能力的多模态基础模型。

💡点击此处查看视频基准测试的详细性能

💡点击此处查看图像基准测试的详细性能

🛠️ 需求与安装

基本依赖：

• Python >= 3.10
• PyTorch >= 2.4.0
• CUDA 版本 >= 11.8
• transformers >= 4.46.3

安装所需软件包：

[仅推理]

为确保稳定的推理效果，建议安装以下版本的软件包：

# 用于 CUDA 11.8 的 PyTorch 和 torchvision
pip install torch==2.4.0 torchvision==0.19.0 --extra-index-url https://download.pytorch.org/whl/cu118

# 将 flash-attn 锁定到兼容版本
pip install flash-attn==2.7.3 --no-build-isolation --upgrade

# Transformers 和 accelerate
pip install transformers==4.46.3 accelerate==1.0.1

# 视频处理依赖项
pip install decord ffmpeg-python imageio opencv-python

⚠ 注意: 对于使用 torch==2.4.0 和 torchvision==0.19.0 的 CUDA 11.8，请使用 flash-attn==2.7.3。
如果您使用的是其他 Python 或 CUDA 版本，请查看 flash-attn 发布页面 以选择兼容的轮子文件。使用不兼容的版本可能会导致设置失败。

[训练]

git clone https://github.com/DAMO-NLP-SG/VideoLLaMA3
cd VideoLLaMA3
pip install -r requirements.txt
pip install flash-attn --no-build-isolation

:earth_americas: 模型库

我们还上传了 VideoLLaMA3-7B 的微调视觉编码器，以便更广泛的应用：

🤖 推理

import torch
from transformers import AutoModelForCausalLM, AutoProcessor

device = "cuda:0"
model_path = "DAMO-NLP-SG/VideoLLaMA3-7B"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    trust_remote_code=True,
    device_map={"": device},
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)

conversation = [
    {"role": "system", "content": "You are a helpful assistant."},
    {
        "role": "user",
        "content": [
            {"type": "video", "video": {"video_path": "./assets/cat_and_chicken.mp4", "fps": 1, "max_frames": 180}},
            {"type": "text", "text": "What is the cat doing?"},
        ]
    },
]

inputs = processor(
    conversation=conversation,
    add_system_prompt=True,
    add_generation_prompt=True,
    return_tensors="pt"
)
inputs = {k: v.to(device) if isinstance(v, torch.Tensor) else v for k, v in inputs.items()}
if "pixel_values" in inputs:
    inputs["pixel_values"] = inputs["pixel_values"].to(torch.bfloat16)
output_ids = model.generate(**inputs, max_new_tokens=1024)
response = processor.batch_decode(output_ids, skip_special_tokens=True)[0].strip()
print(response)

更多案例请参考 示例。

烹饪书

查看 推理笔记本，它们展示了如何在各种应用中使用 VideoLLaMA3，例如单张图像理解、多张图像理解、视觉引用与定位、视频理解等。

🤗 演示

强烈建议先尝试我们的 在线演示。

或者，您也可以在本地启动一个 Gradio 应用程序：

python inference/launch_gradio_demo.py --model-path DAMO-NLP-SG/VideoLLaMA3-7B

选项：
  --model-path MODEL_PATH, --model_path MODEL_PATH
  --server-port SERVER_PORT, --server_port SERVER_PORT
  	可选。模型服务器的端口。
  --interface-port INTERFACE_PORT, --interface_port INTERFACE_PORT
  	可选。Gradio 界面的端口。
  --nproc NPROC
  	可选。模型进程的数量。

🗝️ 训练

第一步：准备训练数据

要使用我们的训练代码，请在 data_root 目录下按您喜欢的方式组织图像和视频数据，然后使用一个或多个注释文件来记录每段对话数据及其对应的图像/视频路径。例如：

data_root
├── LLaVA-Video-178K
│   ├── video_1.mp4
│   └── ...
├── LLaVA-OneVision-Data
│   ├── image_1.jpg
│   └── ...
├── annotations_video.jsonl
├── annotations_image.jsonl
└── ...

注释文件由一系列字典组成，每个条目遵循以下格式：

[
    {
        "image": ["images/xxx.jpg"],
        "conversations": [
            {
                "from": "human",
                "value": "<image>\n图中公交车有哪些颜色？"
            },
            {
                "from": "gpt",
                "value": "图中的公交车是白色和红色的。"
            },
            ...
        ]
    },
    {
        "video": ["videos/xxx.mp4"],
        "conversations": [
            {
                "from": "human",
                "value": "<video>\n视频中主要发生了哪些活动？"
            },
            {
                "from": "gpt",
                "value": "视频中主要发生的活动包括一名男子在准备摄像设备、一群男子乘坐直升机以及一名男子驾船在水中航行。"
            },
            ...
        ]
    },
    ...
]

为了加载效率和内存优化，我们建议使用符合 huggingface datasets 格式的 .jsonl 文件。

第二步：（可选）转换 HF 检查点

如果您想使用本代码库在自己的数据上微调 VideoLLaMA3，请先将 Hugging Face 上的检查点转换为本地格式。例如：

python scripts/convert_hf_checkpoint.py --model_path DAMO-NLP-SG/VideoLLaMA3-7B --save_path weights/videollama3_7b_local

第三步：准备训练脚本

我们在 scripts/train 中提供了一些适用于各个阶段的模板。您可以根据这些模板修改变量，以适应您的数据和模型设置。例如：

  --data_folder ./datasets \
  --data_path ./datasets/annotations_video.jsonl ./datasets/annotations_image.jsonl \
  --model_path Qwen/Qwen2.5-1.5B-Instruct \
  --vision_encoder DAMO-NLP-SG/SigLIP-NaViT \

对于微调，--model_path 是第 2 步中所述的已转换检查点的路径。

第四步：开始训练

现在您可以使用自己的训练脚本开始训练：

# VideoLLaMA3 第一阶段
bash scripts/train/stage1_2b.sh
# VideoLLaMA3 第二阶段
bash scripts/train/stage2_2b.sh

关于 CUDA OOM 错误的一些提示：

• 请尝试使用最新的主分支，我们在 此提交 中优化了内存消耗。
• 可以通过传递 --deepspeed scripts/zero2.json / zero3.json 来尝试 DeepSpeed 的 ZeRO-2/3。
• 通过分别设置 --mm_max_length 和 --model_max_length，减少视觉 token 的最大数量（高分辨率图像和视频会自动降采样以适应该长度）以及序列的最大长度（超过该长度的序列会被截断）。
• 减少本地批次大小，即训练脚本中的 LOCAL_BATCH_SIZE。 您可以根据可用的 GPU 内存和 GPU 数量调整上述超参数，使训练适配您的硬件。
• （新！） 如果在使用上述方法后仍然遇到内存问题，您可以在训练脚本中设置 --use_flash_loss True 来尝试一项 实验性 功能。具体来说，它使用 Inf-CL 中提出的基于分块的交叉熵实现来降低内存消耗，这在训练具有长上下文或大词汇量的模型时非常有帮助！

✅ 评估

第一步：准备评估数据

首先，请根据官方说明下载相应数据，并将其组织成以下格式：

benchmarks
└── video
│   ├── activitynet_qa
│   │   ├── all_test
│   │   ├── test_a.json
│   │   └── test_q.json
│   ├── charades
│   │   ├── Charades_v1
│   │   └── charades_annotations_test-random_prompt.json
│   ├── egoschema
│   │   ├── good_clips_git
│   │   └── questions.json
│   ├── longvideobench
│   │   ├── lvb_val.json
│   │   ├── 字幕
│   │   └── 视频
│   ├── lvbench
│   │   ├── 视频
│   │   └── video_info.meta.jsonl
│   ├── mlvu
│   │   ├── json
│   │   └── 视频
│   ├── mvbench
│   │   ├── json
│   │   └── 视频
│   ├── nextqa
│   │   ├── map_vid_vidorID.json
│   │   ├── NExTVideo
│   │   └── test.csv
│   ├── perception_test
│   │   ├── mc_question_test.json
│   │   └── 视频
│   ├── tempcompass
│   │   ├── captioning
│   │   ├── caption_matching
│   │   ├── 多选题
│   │   ├── 视频
│   │   └── 是/否
│   ├── videomme
│   │   ├── 字幕
│   │   ├── test-00000-of-00001.parquet
│   │   └── 视频

第二步：开始评估

bash scripts/eval/eval_video.sh ${MODEL_PATH} ${BENCHMARKS} ${NUM_NODES} ${NUM_GPUS}

您可以通过评估脚本中的 DATA_ROOT 和 SAVE_DIR 来更改基准测试和输出的目录。更多详细用法请参阅相关脚本。

第三步：添加新的基准测试

即将推出...

📑 引用

如果您发现 VideoLLaMA 对您的研究和应用有所帮助，请使用以下 BibTeX 格式引用：

@article{damonlpsg2025videollama3,
  title={VideoLLaMA 3: 面向图像和视频理解的前沿多模态基础模型},
  author={张博强、李科涵、程泽森、胡志强、袁宇谦、陈冠政、冷思聪、蒋宇明、张航、李欣、金鹏、张文琪、王凡、邴立东、赵德利},
  journal={arXiv 预印本 arXiv:2501.13106},
  year={2025},
  url = {https://arxiv.org/abs/2501.13106}
}

@article{damonlpsg2024videollama2,
  title={VideoLLaMA 2: 推进视频大模型中的时空建模与音频理解},
  author={程泽森、冷思聪、张航、辛义飞、李欣、陈冠政、朱永鑫、张文琪、罗子阳、赵德利、邴立东},
  journal={arXiv 预印本 arXiv:2406.07476},
  year={2024},
  url = {https://arxiv.org/abs/2406.07476}
}

@article{damonlpsg2023videollama,
  title = {Video-LLaMA：面向视频理解的指令微调视听语言模型},
  author = {张航、李欣、邴立东},
  journal = {arXiv 预印本 arXiv:2306.02858},
  year = {2023},
  url = {https://arxiv.org/abs/2306.02858}
}

👍 致谢

我们的 VideoLLaMA3 基于 SigLip 和 Qwen2.5 构建。我们还从 LLaVA-OneVision、InternVL2 和 Qwen2VL 的实现中学习了很多。此外，VideoLLaMA3 还受益于大量开源项目的工作。我们由衷感谢这些贡献，并在 ACKNOWLEDGEMENT.md 中列出了相关名单以表达我们的谢意。如果您的工作被用于 VideoLLaMA3 但未在此仓库或技术报告中提及，请随时告知我们 :heart:。

🔒 许可协议

本项目采用 Apache 2.0 许可协议发布，具体许可信息请参阅 LICENSE 文件。 该服务为研究预览版，仅限 非商业用途，并受 Qwen 模型许可协议、OpenAI 和 Gemini 生成数据的使用条款以及 ShareGPT 隐私政策的约束。如您发现任何潜在违规行为，请与我们联系。

VideoLLaMA3 快速上手指南

VideoLLaMA 3 是阿里达摩院（DAMO-NLP-SG）推出的前沿多模态基础模型系列，具备卓越的图像和视频理解能力。本指南将帮助你快速配置环境并运行推理。

1. 环境准备

在开始之前，请确保你的系统满足以下基本要求：

• Python: >= 3.10
• PyTorch: >= 2.4.0
• CUDA: >= 11.8
• Transformers: >= 4.46.3

注意：为了获得稳定的推理性能，建议严格使用下文指定的库版本，特别是 flash-attn 与 PyTorch/CUDA 版本的兼容性至关重要。

2. 安装步骤

仅用于推理（Inference-only）的用户，请按顺序执行以下命令安装依赖：

# 1. 安装 PyTorch 和 torchvision (针对 CUDA 11.8)
pip install torch==2.4.0 torchvision==0.19.0 --extra-index-url https://download.pytorch.org/whl/cu118

# 2. 安装 Flash-Attention (需指定兼容版本 2.7.3)
pip install flash-attn==2.7.3 --no-build-isolation --upgrade

# 3. 安装 Transformers 和 Accelerate
pip install transformers==4.46.3 accelerate==1.0.1

# 4. 安装视频处理相关依赖
pip install decord ffmpeg-python imageio opencv-python

⚠️ 重要提示：如果你使用的 Python 或 CUDA 版本不同，请务必查阅 flash-attn releases 以选择对应的 wheel 包，版本不匹配可能导致安装失败或运行时错误。

3. 基本使用

以下是一个最简单的视频问答推理示例。该代码加载 VideoLLaMA3-7B 模型，并对输入视频内容进行提问。

import torch
from transformers import AutoModelForCausalLM, AutoProcessor

# 设置设备
device = "cuda:0"
# 模型路径，也可替换为 DAMO-NLP-SG/VideoLLaMA3-2B 等其它版本
model_path = "DAMO-NLP-SG/VideoLLaMA3-7B"

# 加载模型
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    trust_remote_code=True,
    device_map={"": device},
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

# 加载处理器
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)

# 构建对话内容
conversation = [
    {"role": "system", "content": "You are a helpful assistant."},
    {
        "role": "user",
        "content": [
            # 视频输入配置：路径、帧率(fps)、最大帧数(max_frames)
            {"type": "video", "video": {"video_path": "./assets/cat_and_chicken.mp4", "fps": 1, "max_frames": 180}},
            {"type": "text", "text": "What is the cat doing?"},
        ]
    },
]

# 预处理输入
inputs = processor(
    conversation=conversation,
    add_system_prompt=True,
    add_generation_prompt=True,
    return_tensors="pt"
)

# 将输入移至 GPU 并转换数据类型
inputs = {k: v.to(device) if isinstance(v, torch.Tensor) else v for k, v in inputs.items()}
if "pixel_values" in inputs:
    inputs["pixel_values"] = inputs["pixel_values"].to(torch.bfloat16)

# 生成回答
output_ids = model.generate(**inputs, max_new_tokens=1024)
response = processor.batch_decode(output_ids, skip_special_tokens=True)[0].strip()

print(response)

更多资源

• 模型仓库：可在 Hugging Face 获取 VideoLLaMA3-7B 和 VideoLLaMA3-2B 等模型权重。
• 进阶示例：更多应用场景（如单图/多图理解、视觉定位、长视频理解等）请参考官方提供的 Jupyter Notebooks。