VideoLLaMA3 使用指南

1. 项目介绍

VideoLLaMA3 是一系列具有前沿图像和视频理解能力的多模态基础模型。这些模型旨在通过先进的图像和视频处理技术，为用户提供卓越的多模态交互体验。

2. 项目快速启动

环境准备

在开始之前，请确保您的系统已安装以下依赖：

• Python >= 3.10
• Pytorch >= 2.4.0
• CUDA Version >= 11.8
• transformers >= 4.46.3

您可以通过以下命令安装所需的包：

pip install torch==2.4.0 torchvision==0.17.0 --extra-index-url https://download.pytorch.org/whl/cu118
pip install flash-attn --no-build-isolation
pip install transformers==4.46.3 accelerate==1.0.1
pip install decord ffmpeg-python imageio opencv-python

模型安装

从 GitHub 克隆 VideoLLaMA3 仓库：

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

运行示例

以下是一个简单的推理示例代码，用于与模型进行交互：

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": "你是一个有用的助手。"
    },
    {
        "role": "user",
        "content": [
            {
                "type": "video",
                "video": {
                    "video_path": "./assets/cat_and_chicken.mp4",
                    "fps": 1,
                    "max_frames": 180
                }
            },
            {
                "type": "text",
                "text": "猫在做什么？"
            }
        ]
    }
]

# 处理输入
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()
}

# 如果存在像素值，转换为 bfloat16
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)

3. 应用案例和最佳实践

以下是使用 VideoLLaMA3 的一些应用案例和最佳实践：

• 单图像理解：利用 VideoLLaMA3 进行一般图像理解、图表分析、表格理解、文档识别和视觉代码分析。
• 多图像理解：对多图像进行比较和理解，例如在不同图像之间寻找相似性或差异。
• 细粒度图像识别与理解：进行视觉引用和定位任务，例如识别图像中的特定对象并描述其属性。
• 视频理解：进行一般视频理解、长视频理解和时间定位任务。

4. 典型生态项目

VideoLLaMA3 的生态系统包括多个相关项目，例如：

• VideoLLaMA2：在 VideoLLaMA3 的基础上进一步提升了空间-时间建模和音频理解能力。
• VideoRefer Suite：通过视频 LLM 提升空间-时间对象理解。
• VCD：通过视觉对比解码减轻大型视觉-语言模型中的对象虚构成分。

这些项目共同构成了一个强大的多模态理解和生成工具集。