bytedance/Sa2VA · 上手攻略

• 仓库：bytedance/Sa2VA
• 链接：https://github.com/bytedance/Sa2VA
• 分类：多模态 / 像素级 grounding（Pixel LLM）
• 作者：spark
• 更新：2026-09-08

1. 是什么

Sa2VA 是字节跳动 Seed 团队联合 UC Merced / WHU / PKU 在 2026 年开源的 Pixel LLM 系列旗舰仓库，核心论文《Sa2VA: Marrying SAM2 with MLLM for Dense Grounded Understanding of Images and Videos》已被 IEEE TPAMI 2026 接收（DOI: 1109/TPAMI.2025.11640960）。仓库本身是一个 mono-repo，把四个研究项目收在一棵树下：

• Sa2VA：把 SAM-2 与多模态大模型（InternVL2.5/3、Qwen2.5-VL、Qwen3-VL）结合的 统一基础模型。
• VRT（Visual Reasoning Tracer）：对象级 grounded reasoning，配套 VRT-Bench 评测与 VRT-80k 训练数据。
• SAMTok（CVPR-26）：统一的 mask-token 接口，让任意 MLLM 都能生成并理解 mask。
• SaSaSa2VA：在 ICCV 2025 LSVOS Challenge RVOS Track 拿到 第一名 的扩展方案。
• Pixel-SAIL：单 transformer 的像素级 grounding 实验。

一句话：Sa2VA = 「SAM-2 负责像素级 mask，MLLM 负责语言理解，两者用一个 [SEG] token 接通」，是当前「dense grounded MLLM」这条赛道上最早开源且论文进入 TPAMI 的代表性工作。

2. 解决什么问题

现有 MLLM 普遍只能「看到图像、回答文字」，做不到「看到图像、回答文字、并在像素上把答案对应的对象框出 / 抠出」。Sa2VA 用一个非常干净的统一接口解决这个问题：

• MLLM 在生成时遇到「需要给像素答案」就 emit 一个特殊 token [SEG]；
• 该 token 的 hidden state 经一个轻量投影头映射到 SAM-2 的 prompt space；
• SAM-2 解码器把投影向量解成 mask（图像或视频帧级）。

由此，一个模型同时支持：

任务	触发方式
Referring segmentation（图 / 视频）	自然语言描述 → mask
Grounded conversation generation	生成带 inline [SEG] 的描述
Visual prompting	用户指定区域提问
通用图 / 视频 chat	MLLM 自身能力

对标数据集覆盖 RefCOCO/+/g、ReVOS、MeViS、DAVIS、Ref-SAV，训练数据放在 HuggingFace Dense-World/Sa2VA-Training。

3. 快速安装

仓库用 uv 锁环境，依赖由 pyproject.toml + uv.lock 完整声明。

# 1) 装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) clone + 走 helper 脚本（推荐，会把 venv 放 /tmp 再软链回项目）
git clone https://github.com/bytedance/Sa2VA.git
cd Sa2VA
bash setup_env.sh sa2va latest      # 最新模型：Qwen3-VL / Qwen2.5-VL / InternVL3
# 或
bash setup_env.sh sa2va legacy     # 老模型：InternVL2.5 及之前

# 3) 复制 token 模板（如要拉 gated 资源）
cp .env.example .env && vim .env

激活：

source projects/sa2va/.venv/bin/activate

显存与硬件底线：README 明确要求 8× A100 起步做完整训练；单卡 / 少卡只能做推理与 LoRA 微调。⚠️ 这点 README 没把卡数写粗体，但配置脚本 tools/dist.sh 默认 8 卡，老老实实按 8 卡准备。

4. 核心用法

4.1 用预训练权重跑 demo

下载 HuggingFace 模型（建议先确认 HF_TOKEN 已写在 .env）：

huggingface-cli download ByteDance/Sa2VA-4B --local-dir ./pretrained/Sa2VA-4B
huggingface-cli download facebook/sam2-hiera-large --local-dir ./pretrained/sam2_hiera_large.pt

视频帧级 chat + segmentation demo：

PYTHONPATH=. python projects/sa2va/demo/demo.py \
  PATH_TO_VIDEO_FRAMES_FOLDER \
  --model_path ByteDance/Sa2VA-8B \
  --work-dir ./outputs \
  --text "<image>Please describe the video content."

Gradio 交互界面（本地聊天 + 出 mask）：

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

4.2 数据准备

训练数据托管在 HuggingFace：

mkdir -p data
# 把 zip 放到 data/ 后就地解压
unzip data/video_datas_mevis.zip -d data/

约定目录结构（节选）：

data/
├── video_datas/
│   ├── revos/  mevis/  davis17/  chat_univi/
│   └── sam_v_full/        # ⚠️ 来自 Meta SA-V，需自取
├── ref_seg/{refcoco,refcoco+,refcocog}
├── glamm_data/{images,annotations}
├── osprey-724k/...
└── llava_data/...

4.3 训练（8 卡 A100）

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

其他 backbone 的 config 在 projects/sa2va/configs/：InternVL3 用 sa2va_in30_*.py、Qwen2.5-VL 用 sa2va_qwenvl25/、Qwen3-VL 用 sa2va_qwenvl3/。完整训练非常吃资源，新模型发布时一般建议用 LoRA 微调走 projects/sa2va/configs/sa2va_finetune.py。

4.4 评测

# 跑全套分割 benchmark
python projects/sa2va/evaluation/run_all_evals.py /path/to/model --gpus 8

# 跑单个，例如 ReVOS
./projects/sa2va/evaluation/dist_test.sh \
  projects/sa2va/evaluation/sa2va_eval_ref_vos.py \
  path-to-hf-model 8 --work_dir ./eval_out

QA 类 benchmark（图像 / 视频 chat）走兄弟仓库 zhang-tao-whu/sa2va_eval（改自 VLMEvalKit）：

python run.py --data MMBench_DEV_EN SEEDBench_IMG MMStar \
  --model Sa2VA-4B --verbose

4.5 转 HuggingFace 格式

训完的 .pth 一键转回 HF 权重：

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

5. 典型适用场景

• 视频 referring segmentation：给定一句「segment the girl wearing the yellow dress」，跨帧稳定抠出目标。README 自带的 La La Land demo 就是这种用法。
• 可视化标注 / 数据工厂：用 SaSaSa2VA 把视频 / 图集自动切成带 mask 的对话样本，做下游训练集。
• 视觉问答 + 区域解释：在 GUI agent、机器人、AR 场景里让模型既能说话又能「圈出」它说的是哪块区域。
• 学术复现 / benchmark：Sa2VA 是 dense grounded MLLM 的标杆之一，做对比实验或审稿时复用其权重 + 评测管线非常方便。
• CVPR-26 / TPAMI 投稿基线：SAMTok 给出 mask-as-token 的统一抽象，适合做多模态 token 设计的上游基线。

6. 坑与注意

1. 完整训练门槛高：8× A100 是 README 推荐的最小配置，普通实验室先做 LoRA。⚠️ 不要被「1B 模型」误导，推理阶段显存占用主要看 MLLM backbone，4B/8B 仍然需要 ≥24 GB 显存才能舒服地跑视频。
2. SAM 权重必须单独下：sam2_hiera_large.pt 不在 HuggingFace model card 里自动 download，需要手动从 facebook/sam2-hiera-large 拉，README 在「Pretrained Model Preparation」一节写得偏隐晦。
3. SA-V 数据集许可：训练用的 sam_v_full（SA-V 视频数据）来自 Meta 的 Segment Anything Video 仓库，不在 HuggingFace 一键包内，需自行去 Meta 站点下载并遵守其许可。不要假定「HuggingFace zip 包 = 完整可商用」。
4. [SEG] token 兼容性：不同 MLLM backbone 的 tokenizer 对特殊 token 的行为不一致，README 提到 setup_env.sh sa2va latest 走 Qwen3-VL/InternVL3，legacy 走 InternVL2.5；切换 backbone 一定要选对 --extra，否则会出现「训出来 mask 完全不可用」这类隐蔽 bug。⚠️
5. 路径与 import：训练 / 评测命令必须在 仓库根目录 跑，README 反复强调 code uses repo-root-relative imports such as projects.sa2va, third_parts, vlm；一旦 cd projects/sa2va 再跑就会出现 ModuleNotFoundError。
6. 评测仓库是独立的：sa2va_eval 不是 Git submodule，需要单独 clone。如果只在主仓跑 python run.py 找不到 --model Sa2VA-* 选项，就是漏了这一步。
7. 公开模型命名漂移：2026-06 月连续发布了 Sa2VA-Qwen3-VL-4B-SAM3（用 SAM3）、Sa2VA-LLaVA-1.5-7B，引入新 grounding encoder / 老 backbone。线上 demo 选择具体权重时务必检查权重卡片的 backbone + SAM 版本。⚠️
8. TPAMI 论文 vs arXiv v1：arXiv 2501.04001 与 TPAMI 终稿会有小差异（如消融实验补充），引用务必以 IEEE 链接为准；引用 BibTeX 仓库已给好，直接用即可。

7. 与同类对比

项目	核心思路	与 Sa2VA 的差异
LISA / PixelLLM	在 MLLM 里加一个 mask decoder	早期工作，通常只支持 InternVL 系列；Sa2VA 把 grounding 完全外包给 SAM-2，MLLM 只负责吐 [SEG] token，更干净
GLaMM / GHOST	把像素级 grounding 做成大规模视觉 grounding pretrain	数据规模更大，但缺乏视频能力；Sa2VA 把视频 referring（ReVOS / MeViS / DAVIS / Ref-SAV）作为一等公民
SAM 2 / SAM 3	纯分割模型，需手动 prompt	不能「对话」，要外面套一层 LLM；Sa2VA 是把这件事直接内化进 MLLM
GroundingDINO / Grounded-SAM	detect-then-segment 范式	视觉模型管线，需要文本编码器；Sa2VA 在 MLLM token 空间里解决，pipeline 更短
VLM-R1 / Seg-Zero	RL 思路训 segmentation	多数仍在图像级 / 单轮，Sa2VA 已经覆盖视频 + GCG + 多 backbone

如果你的场景是「我要给一段对话里的对象打 mask，且最好直接复用一个 MLLM 别堆一坨模型」——Sa2VA 是目前 TPAMI 这条线最直接的选择。

8. 一句话推荐结论

「一个 MLLM、emit 一个 [SEG] token、让 SAM-2 解码成 mask」——这就是 Sa2VA 的全部秘诀；想跑视频 referring segmentation 或 grounded chat 又不想堆 detect-then-segment pipeline 的团队，优先 fork 这棵 mono-repo。

---

⚠️ 待核验事项： - 截至 2026-09-08，Sa2VA-Qwen3-VL-4B-SAM3 与 Sa2VA-LLaVA-1.5-7B 是否都已上传完整权重，以 HuggingFace ByteDance 主页为准。 - 训练硬件建议「8× A100 起步」源自 README Section "Training Script"，未做实测；用 H100 / H200 是否能压缩训练时间，未在仓库文档中给出。

字数：约 2,250 CJK · 私域污染 SUM=0 · 边界：仅写 guides/bytedance-sa2va.md