MoE-LLaVA：面向大型视觉-语言模型的专家混合模型

如果您喜欢我们的项目，请在 GitHub 上为我们点亮星标 ⭐，以获取最新更新。


💡 我还有其他可能让您感兴趣的视觉-语言项目 ✨。

Open-Sora 计划：开源大型视频生成模型
林斌、葛云阳、程新华、李宗健、朱彬、王绍东、何先义、叶洋、袁圣海、陈刘汉、贾唐辉、张俊武、唐振宇、庞雅婷、佘彬、严岑、胡志恒、董晓艺、陈林、潘章、周兴、董绍玲、田永宏、袁力

Video-LLaVA：通过对齐后再投影学习统一的视觉表征
林斌、叶洋、朱彬、崔家熙、宁慕楠、金鹏、袁力

LanguageBind：通过基于语言的语义对齐将视频-语言预训练扩展至 N 模态
朱彬、林斌、宁慕楠、杨燕、崔家熙、王洪法、庞雅婷、蒋文浩、张俊武、李宗伟、张万才、李志峰、刘伟、袁力

📣 新闻

• [2025.07.15] 🔥🔥🔥 我们的 MoE-LLaVA 已被 IEEE 多媒体汇刊（TMM）接收！
• [2024.03.16] 🎉 我们发布了所有 stage2 模型，请查看我们的 模型库。
• [2024.02.03] 🎉 我们发布了一个更强大的 MoE-LLaVA-StableLM。该模型仅使用 2.0B 的稀疏激活参数，平均性能就接近 LLaVA-1.5-7B，请查看我们的 模型库。
• [2024.02.02] 🤝 您可以体验 和 ，这些内容由 @camenduru 制作，他慷慨地支持我们的研究！
• [2024.02.01] 🔥 对于无法访问 Hugging Face 的用户，现在可以通过 ModelScope 下载模型，请查看我们的 模型库。
• [2024.01.30] 🔥 我们发布了一个更强大的 MoE-LLaVA-Phi2。该模型仅使用 3.6B 的稀疏激活参数，平均性能就 超越了 LLaVA-1.5-7B，请查看我们的 模型库。
• [2024.01.27] 🤗 Hugging Face 演示以及 所有代码和数据集 现已可用！欢迎 关注 👀 此仓库，以获取最新动态。

😮 亮点

MoE-LLaVA 在多模态学习方面表现出色。

🔥 高性能，但参数量更少

• 仅需 3B 的稀疏激活参数，MoE-LLaVA 就能在多种视觉理解数据集上达到与 LLaVA-1.5-7B 相当的性能，甚至在物体幻觉基准测试中超越了 LLaVA-1.5-13B。

🚀 简单的基线，通过稀疏路径学习多模态交互。

• 通过增加 一个简单的 MoE 调优阶段，我们可以在 8 张 A100 GPU 上用不到 1 天的时间完成 MoE-LLaVA 的训练。

🤗 演示

Gradio Web UI

强烈推荐您通过以下命令试用我们的网页演示，它包含了 MoE-LLaVA 目前支持的所有功能。我们还在 Huggingface Spaces 中提供了 在线演示。

# 使用 phi2
deepspeed --include localhost:0 moellava/serve/gradio_web_server.py --model-path "LanguageBind/MoE-LLaVA-Phi2-2.7B-4e"

# 使用Qwen
deepspeed --include localhost:0 moellava/serve/gradio_web_server.py --model-path "LanguageBind/MoE-LLaVA-Qwen-1.8B-4e" 
# 使用StableLM
deepspeed --include localhost:0 moellava/serve/gradio_web_server.py --model-path "LanguageBind/MoE-LLaVA-StableLM-1.6B-4e" 

https://github.com/PKU-YuanGroup/MoE-LLaVA/assets/62638829/8541aac6-9ef6-4fde-aa94-80d0375b9bdb

命令行推理

# 使用Phi2
deepspeed --include localhost:0 moellava/serve/cli.py --model-path "LanguageBind/MoE-LLaVA-Phi2-2.7B-4e"  --image-file "image.jpg"
# 使用Qwen
deepspeed --include localhost:0 moellava/serve/cli.py --model-path "LanguageBind/MoE-LLaVA-Qwen-1.8B-4e"  --image-file "image.jpg"
# 使用StableLM
deepspeed --include localhost:0 moellava/serve/cli.py --model-path "LanguageBind/MoE-LLaVA-StableLM-1.6B-4e"  --image-file "image.jpg"

🐳 模型库

模型	激活参数	Transformers(HF)	ModelScope(HF)	平均	VQAv2	GQA	VizWiz	SQA-IMG	T-VQA	POPE	MME	MM-Bench	MM-Vet
MoE-LLaVA-1.6B×4-Top2	2.0B	🤗LanguageBind/MoE-LLaVA-StableLM-1.6B-4e	PKU-YuanLab/MoE-LLaVA-StableLM-1.6B-4e	57.3	76.7	60.3	36.2	62.6	50.1	85.7	1318.1	60.2	26.9
MoE-LLaVA-1.8B×4-Top2	2.2B	🤗LanguageBind/MoE-LLaVA-Qwen-1.8B-4e	PKU-YuanLab/MoE-LLaVA-Qwen-1.8B-4e	56.7	76.2	61.5	32.6	63.1	48.0	87.0	1291.6	59.6	25.3
MoE-LLaVA-2.7B×4-Top2	3.6B	🤗LanguageBind/MoE-LLaVA-Phi2-2.7B-4e	PKU-YuanLab/MoE-LLaVA-Phi2-2.7B-4e	61.1	77.6	61.4	43.9	68.5	51.4	86.3	1423.0	65.2	34.3
MoE-LLaVA-1.6B×4-Top2-384	2.0B	🤗LanguageBind/MoE-LLaVA-StableLM-1.6B-4e-384	PKU-YuanLab/MoE-LLaVA-StableLM-1.6B-4e-384	60.0	78.6	61.5	40.5	63.9	54.3	85.9	1335.7	63.3	32.3
MoE-LLaVA-2.7B×4-Top2-384	3.6B	🤗LanguageBind/MoE-LLaVA-Phi2-2.7B-4e-384	PKU-YuanLab/MoE-LLaVA-Phi2-2.7B-4e-384	62.9	79.9	62.6	43.7	70.3	57.0	85.7	1431.3	68.0	35.9
LLaVA-1.5	7B	🤗liuhaotian/llava-v1.5-7b	-	62.0	78.5	62.0	50.0	66.8	58.2	85.9	1510.7	64.3	30.5

🚨 请注意 https://github.com/PKU-YuanGroup/MoE-LLaVA/issues/27。

Stage2模型

模型	检查点
MoE-LLaVA-1.6B×4-Top2	LanguageBind/MoE-LLaVA-StableLM-Stage2
MoE-LLaVA-1.6B×4-Top2-384	LanguageBind/MoE-LLaVA-StableLM-Stage2-384
MoE-LLaVA-1.8B×4-Top2	LanguageBind/MoE-LLaVA-Qwen-Stage2
MoE-LLaVA-2.7B×4-Top2	LanguageBind/MoE-LLaVA-Phi2-Stage2
MoE-LLaVA-2.7B×4-Top2-384	LanguageBind/MoE-LLaVA-Phi2-Stage2-384

预训练模型

模型	检查点
MoE-LLaVA-1.6B×4-Top2	LanguageBind/MoE-LLaVA-StableLM-Pretrain
MoE-LLaVA-1.6B×4-Top2-384	LanguageBind/MoE-LLaVA-StableLM-384-Pretrain
MoE-LLaVA-1.8B×4-Top2	LanguageBind/MoE-LLaVA-Qwen-Pretrain
MoE-LLaVA-2.7B×4-Top2	LanguageBind/MoE-LLaVA-Phi2-Pretrain
MoE-LLaVA-2.7B×4-Top2-384	LanguageBind/MoE-LLaVA-Phi2-384-Pretrain

⚙️ 要求与安装

我们推荐以下要求：

• Python == 3.10
• Pytorch == 2.0.1
• CUDA版本 >= 11.7
• Transformers == 4.37.0
• Tokenizers==0.15.1
• 安装所需包：

git clone https://github.com/PKU-YuanGroup/MoE-LLaVA
cd MoE-LLaVA
conda create -n moellava python=3.10 -y
conda activate moellava
pip install --upgrade pip  # 启用PEP 660支持
pip install -e .
pip install -e ".[train]"
pip install flash-attn --no-build-isolation

# 以下是可选的。对于Qwen模型。
git clone https://github.com/Dao-AILab/flash-attention
cd flash-attention && pip install .
# 以下是可选的。安装它们可能会比较慢。
# pip install csrc/layer_norm
# 如果flash-attn版本高于2.1.1，则不需要以下操作。
# pip install csrc/rotary

[!警告]

🚨 我们发现使用flash attention2会导致性能下降。

🗝️ 训练与验证

训练与验证说明请参阅 TRAIN.md 和 EVAL.md。

💡 自定义你的MoE-LLaVA

自定义说明请参阅 CUSTOM.md。

😍 可视化

可视化说明请参阅 VISUALIZATION.md。

🤖 API

我们已将所有代码开源。 如果您想在本地加载该模型（例如 LanguageBind/MoE-LLaVA-Phi2-2.7B-4e），可以使用以下代码片段。

使用以下命令运行代码。

deepspeed --include localhost:0 predict.py

import torch
from PIL import Image
from moellava.constants import IMAGE_TOKEN_INDEX, DEFAULT_IMAGE_TOKEN
from moellava.conversation import conv_templates, SeparatorStyle
from moellava.model.builder import load_pretrained_model
from moellava.utils import disable_torch_init
from moellava.mm_utils import tokenizer_image_token, get_model_name_from_path, KeywordsStoppingCriteria

def main():
    disable_torch_init()
    image = 'moellava/serve/examples/extreme_ironing.jpg'
    inp = 'What is unusual about this image?'
    model_path = 'LanguageBind/MoE-LLaVA-Phi2-2.7B-4e'  # LanguageBind/MoE-LLaVA-Qwen-1.8B-4e 或 LanguageBind/MoE-LLaVA-StableLM-1.6B-4e
    device = 'cuda'
    load_4bit, load_8bit = False, False  # FIXME: Deepspeed 是否支持 4bit 或 8bit？
    model_name = get_model_name_from_path(model_path)
    tokenizer, model, processor, context_len = load_pretrained_model(model_path, None, model_name, load_8bit, load_4bit, device=device)
    image_processor = processor['image']
    conv_mode = "phi"  # qwen 或 stablelm
    conv = conv_templates[conv_mode].copy()
    roles = conv.roles
    image_tensor = image_processor.preprocess(Image.open(image).convert('RGB'), return_tensors='pt')['pixel_values'].to(model.device, dtype=torch.float16)

    print(f"{roles[1]}: {inp}")
    inp = DEFAULT_IMAGE_TOKEN + '\n' + inp
    conv.append_message(conv.roles[0], inp)
    conv.append_message(conv.roles[1], None)
    prompt = conv.get_prompt()
    input_ids = tokenizer_image_token(prompt, tokenizer, IMAGE_TOKEN_INDEX, return_tensors='pt').unsqueeze(0).cuda()
    stop_str = conv.sep if conv.sep_style != SeparatorStyle.TWO else conv.sep2
    keywords = [stop_str]
    stopping_criteria = KeywordsStoppingCriteria(keywords, tokenizer, input_ids)

    with torch.inference_mode():
        output_ids = model.generate(
            input_ids,
            images=image_tensor,
            do_sample=True,
            temperature=0.2,
            max_new_tokens=1024,
            use_cache=True,
            stopping_criteria=[stopping_criteria])

    outputs = tokenizer.decode(output_ids[0, input_ids.shape[1]:], skip_special_tokens=True).strip()
    print(outputs)

if __name__ == '__main__':
    main()

🙌 相关项目

• Video-LLaVA 该框架使模型能够高效利用统一的视觉标记。
• LanguageBind 一个开源的五模态语言检索框架。

👍 致谢

• LLaVA 我们在此基础上构建了代码库，它是一个高效的大规模语言和视觉助手。

🔒 许可证

• 本项目的大部分内容根据 LICENSE 文件中的 Apache 2.0 许可证发布。
• 该服务为研究预览版，仅供非商业用途，受 LLaMA 模型的 许可证、由 OpenAI 生成的数据的 使用条款以及 ShareGPT 的 隐私政策约束。如发现任何潜在违规行为，请与我们联系。

✏️ 引用

如果您在研究中发现我们的论文和代码有用，请考虑给个赞 :star: 和引用 :pencil:。

@article{lin2024moe,
  title={MoE-LLaVA: Mixture of Experts for Large Vision-Language Models},
  author={Lin, Bin and Tang, Zhenyu and Ye, Yang and Cui, Jiaxi and Zhu, Bin and Jin, Peng and Zhang, Junwu and Ning, Munan and Yuan, Li},
  journal={arXiv preprint arXiv:2401.15947},
  year={2024}
}

@article{lin2023video,
  title={Video-LLaVA: Learning United Visual Representation by Alignment Before Projection},
  author={Lin, Bin and Zhu, Bin and Ye, Yang and Ning, Munan and Jin, Peng and Yuan, Li},
  journal={arXiv preprint arXiv:2311.10122},
  year={2023}
}

✨ 星标历史

🤝 贡献者

MoE-LLaVA 快速上手指南

MoE-LLaVA 是一个基于混合专家（Mixture of Experts, MoE）架构的大型视觉 - 语言模型。它在仅激活少量参数（如 3B）的情况下，即可在多项视觉理解任务中达到甚至超越 LLaVA-1.5-7B/13B 的性能。

1. 环境准备

系统要求

• GPU: 推荐 NVIDIA A100 或同等算力显卡（推理可根据模型大小调整，训练建议 8x A100）。
• CUDA: 11.8 或更高版本。
• Python: 3.10 或更高版本。

前置依赖

确保已安装 git、conda 或 venv。本项目深度依赖 deepspeed 进行推理和训练。

2. 安装步骤

步骤一：克隆项目

git clone https://github.com/PKU-YuanGroup/MoE-LLaVA.git
cd MoE-LLaVA

步骤二：创建虚拟环境并安装依赖

推荐使用 Conda 管理环境：

conda create -n moellava python=3.10 -y
conda activate moellava

# 安装 PyTorch (根据实际 CUDA 版本调整，此处以 11.8 为例)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 安装项目核心依赖
pip install -e .

国内加速提示：如果下载缓慢，可使用清华或阿里镜像源：

pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

MoE-LLaVA 提供了多种预训练模型（基于 Phi2, Qwen, StableLM 等）。以下示例以性能较强的 Phi2 版本为例。

方式一：Gradio Web UI（推荐）

启动本地网页界面，支持上传图片并进行多轮对话。

# 使用 Phi2 底座模型 (激活参数约 3.6B)
deepspeed --include localhost:0 moellava/serve/gradio_web_server.py --model-path "LanguageBind/MoE-LLaVA-Phi2-2.7B-4e"

启动后在浏览器访问显示的本地地址（通常为 http://127.0.0.1:7860）即可使用。

其他可用模型路径：

• Qwen 底座: "LanguageBind/MoE-LLaVA-Qwen-1.8B-4e"
• StableLM 底座: "LanguageBind/MoE-LLaVA-StableLM-1.6B-4e"

方式二：命令行推理 (CLI)

直接在终端对单张图片进行问答。

deepspeed --include localhost:0 moellava/serve/cli.py --model-path "LanguageBind/MoE-LLaVA-Phi2-2.7B-4e" --image-file "image.jpg"

请将 image.jpg 替换为你本地的图片路径。运行后输入问题即可获取回答。

模型下载提示

• Hugging Face: 模型会自动从 HF 下载。
• 国内镜像: 如果无法访问 Hugging Face，项目支持通过 ModelScope (魔搭) 下载。
  • 例如 Phi2 模型地址：PKU-YuanLab/MoE-LLaVA-Phi2-2.7B-4e
  • 下载后可将 --model-path 指向本地文件夹路径。