Sa2VA：将SAM2与LLaVA结合，实现对图像和视频的密集接地理解

[🏠 Sa2VA] [📜 arXiv] [🤗 HuggingFace] [Gradio Demo (我们内部：Sa2VA-4B)] [Gradio Demo (由HuggingFace官方提供)] [🤖 Replicate Demo]

Haobo Yuan^1* · Xiangtai Li^2*† · Tao Zhang^2,3* · Yueyi Sun⁴ · Zilong Huang² · Shilin Xu⁴ ·Shunping Ji³ ·Yunhai Tong⁴ · Lu Qi³ · Jiashi Feng² · Ming-Hsuan Yang¹

¹加州大学默塞德分校    ²字节跳动Seed    ³武汉大学    ⁴北京大学

† 项目负责人 * 前三位作者对本工作贡献相等。

新闻

• 🚀 视觉推理追踪器（VRT） 已发布！
• 🏅 SaSaSa2VA 在ICCV 2025 LSVOS挑战赛RVOS赛道中荣获第一名！🎉🎉🎉

开源进展

• 发布Qwen3-VL相关模型。
• 发布InternVL-3-VL相关模型。
• 发布Qwen2.5-VL相关模型。
• 发布开源训练数据集。
• 发布Ref-SAM-v数据集。
• 发布各数据集的评估代码。
• 发布1B、4B、8B、26B模型。
• 发布1B、4B、8B模型的训练代码。
• 发布推理与测试代码。
• 发布演示代码。

概述

本仓库包含论文“Sa2VA：将SAM2与LLaVA结合，实现对图像和视频的密集接地理解”的代码。

Sa2VA是首个用于图像和视频密集接地理解的统一模型。与现有的多模态大型语言模型不同，后者往往局限于特定模态和任务，Sa2VA则支持广泛的图像和视频任务，包括指代分割和对话，且只需极少的一次性指令微调。Sa2VA将基础视频分割模型SAM-2与先进的视觉-语言模型LLaVA相结合，将文本、图像和视频统一到一个共享的LLM标记空间中。

模型库

我们提供以下模型：

🤗 Gradio演示

我们提供了一个使用Gradio实现交互式聊天的脚本，需要安装gradio。你可以尝试快速搭建本地聊天界面。

PYTHONPATH=. python projects/sa2va/gradio/app.py ByteDance/Sa2VA-4B

环境

使用uv来管理依赖。运行uv sync即可安装所有内容，根据你的模型系列选择额外选项：

• uv sync --extra=legacy 适用于InternVL2.5或更早版本的模型（旧版Transformers）。
• uv sync --extra=latest 适用于较新的模型（最新版Transformers）。

🚀 快速入门

我们的Sa2VA模型已在🤗HuggingFace上发布。只需几个步骤，你就可以用自己的数据进行试用。你可以安装demo/requirements.txt以避免安装仅用于训练的包。

选项1 - 脚本：

假设你有一个文件夹（PATH_TO_FOLDER），其中包含一段视频的图片，你可以使用以下脚本与Sa2VA模型进行对话或对视频中的物体进行分割。

python demo/demo.py PATH_TO_FOLDER --model_path ByteDance/Sa2VA-8B --work-dir OUTPUT_DIR --text "<image>请描述视频内容。"

如果输出包含分割结果，结果将被保存到OUTPUT_DIR。

选项2 - Jupter Notebook：

请参考demo.ipynb。

🎥 演示

训练

curl -LsSf https://astral.sh/uv/install.sh | sh

uv sync --extra=latest # 或 uv sync --extra=legacy 用于基于 InternVL2/2.5 的 Sa2VA
source .venv/bin/activate

./ # 项目根目录
pretrained/
├── sam2_hiera_large.pt
├── InternVL2_5-1B
├── InternVL2_5-4B

unzip video_datas_mevis.zip

data/
├── video_datas
|   ├── revos
|   ├── mevis
|   └── davis17
|   └── chat_univi
|   └── sam_v_full # [!重要] 请直接从 sam-2 下载。
|   └── Ref-SAV.json
├── ref_seg
|   ├── refclef
|   ├── refcoco
|   ├── refcoco+
|   ├── refcocog
|   ├── 
├── glamm_data
|   ├── images
|   ├── annotations
├── osprey-724k
|   ├── Osprey-724K
|   ├── coco
├── llava_data
|   ├── llava_images
|   ├── LLaVA-Instruct-150K
|   ├── LLaVA-Pretrain

bash tools/dist.sh train projects/sa2va/configs/sa2va_in30_8b.py 8

python tools/convert_to_hf.py projects/sa2va/configs/sa2va_in30_8b.py --pth-model PATH_TO_PTH_MODEL --save-path PATH_TO_SAVE_FOLDER

评估

您可以从 这里🤗 下载 Ref-SAV 评估集。

python projects/sa2va/evaluation/run_all_evals.py /path/to/SA2VA/model --gpus 8

./projects/llava_sam2/evaluation/dist_test.sh projects/llava_sam2/evaluation/ref_vos_eval.py path-to-hf-model 8 --work-dir path-to-output

python run.py --data MMBench_DEV_EN MME SEEDBench_IMG --model Sa2VA-1B --verbose

torchrun --nproc-per-node=8 run.py --data MMBench_DEV_EN SEEDBench_IMG MMStar AI2D_TEST MMMU_DEV_VAL ScienceQA_TEST --model Sa2VA-4B Sa2VA-8B --verbose

参考文献

如果您觉得本仓库有用，请考虑引用以下论文：

@article{sa2va,
  title={Sa2VA: 将 SAM2 与 LLaVA 结合，实现对图像和视频的密集接地理解},
  author={Yuan, Haobo and Li, Xiangtai and Zhang, Tao and Sun, Yueyi and Huang, Zilong and Xu, Shilin and Ji, Shunping and Tong, Yunhai and Qi, Lu and Feng, Jiashi and Yang, Ming-Hsuan},
  journal={arXiv 预印本},
  year={2025}
}

Sa2VA 快速上手指南

Sa2VA 是首个统一图像和视频密集接地理解（Dense Grounded Understanding）的模型。它结合了 SAM-2（视频分割基础模型）与 LLaVA（先进视觉语言模型），支持指代分割、多轮对话等多种任务。

1. 环境准备

系统要求

• GPU: 推理建议至少 16GB 显存（如 RTX 3090/4090 或 A10/A100）。训练建议至少 8 张 A100 GPU。
• Python: 推荐 Python 3.10+
• 包管理工具: 强烈推荐使用 uv 进行依赖管理（比 pip/conda 更快更稳定）。

前置依赖

确保已安装 Git 和 CUDA 驱动。

2. 安装步骤

第一步：安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

第二步：克隆代码并同步依赖

根据你要使用的模型版本选择对应的依赖环境：

方案 A：使用新版模型（推荐，基于 InternVL3 或 Qwen2.5-VL/Qwen3-VL）

git clone https://github.com/ByteDance/Sa2VA.git
cd Sa2VA
uv sync --extra=latest
source .venv/bin/activate

方案 B：使用旧版模型（基于 InternVL2.5）

git clone https://github.com/ByteDance/Sa2VA.git
cd Sa2VA
uv sync --extra=legacy
source .venv/bin/activate

注意：如果下载速度慢，可尝试配置国内镜像源（如清华源）加速 uv 或后续 HuggingFace 模型的下载。

3. 基本使用

方式一：命令行脚本推理（推荐）

假设你有一个包含视频帧图像的文件夹 PATH_TO_FOLDER，可以使用以下命令与模型交互或进行视频物体分割。

示例：描述视频内容

python demo/demo.py PATH_TO_FOLDER --model_path ByteDance/Sa2VA-8B --work-dir OUTPUT_DIR --text "<image>Please describe the video content."

示例：指代分割（Segmentation） 如果提示词中包含分割指令（如 "segment the girl..."），结果掩码将自动保存至 OUTPUT_DIR。

python demo/demo.py PATH_TO_FOLDER --model_path ByteDance/Sa2VA-8B --work-dir OUTPUT_DIR --text "<image>Please segment the girl wearing the yellow dress."

参数说明：

• PATH_TO_FOLDER: 存放视频拆解后的图片文件夹路径。
• --model_path: 模型名称（如 ByteDance/Sa2VA-4B, ByteDance/Sa2VA-8B 等），首次运行会自动从 HuggingFace 下载。
• --work-dir: 输出结果保存目录。

方式二：Gradio 本地演示界面

如果你想构建一个本地的聊天交互界面，可以运行以下命令：

PYTHONPATH=. python projects/sa2va/gradio/app.py ByteDance/Sa2VA-4B

运行后在浏览器访问显示的本地地址即可体验。

方式三：Jupyter Notebook

项目根目录下提供了 demo.ipynb，适合开发者在 Notebook 环境中逐步调试和测试代码逻辑。

模型选择参考：

• Sa2VA-4B: 平衡速度与性能，适合大多数消费级显卡。
• Sa2VA-8B/26B: 性能更强，适合高精度任务或多卡环境。
• Qwen3-VL 系列: 基于最新 Qwen3 架构，语言能力更强。