🌋 LLaVA：大型语言与视觉助手

面向具备 GPT-4 级别能力的大型语言和视觉模型的视觉指令微调。

[📢 LLaVA-NeXT 博客] [项目页面] [演示] [数据] [模型库]

🤝社区贡献：[llama.cpp] [Colab] [🤗Space] [Replicate] [AutoGen] [BakLLaVA]

通过视觉指令微调改进基线模型 [论文] [HF]
刘浩天, 李春元, 李宇恒, 李永宰

视觉指令微调（NeurIPS 2023，口头报告）[论文] [HF]
刘浩天*, 李春元*, 吴庆阳, 李永宰 (同等贡献)

发布

• [2024/05/10] 🔥 LLaVA-NeXT（更强）模型发布，支持 LLama-3（8B）和 Qwen-1.5（72B/110B）的更强大的 LMM。[博客] [检查点] [演示] [代码]
• [2024/05/10] 🔥 LLaVA-NeXT（视频）发布。仅基于图像训练的 LLaVA-NeXT 模型在视频任务上表现出惊人的强大性能，实现了零样本模态迁移。通过对视频进行 AI 反馈的 DPO 训练可以显著提升性能。[博客] [检查点] [代码]
• [03/10] 发布 LMMs-Eval，这是我们开发 LLaVA-NeXT 时使用的高效评估流水线。它支持对数十个公开数据集上的 LMM 进行评估，并允许新数据集的接入，从而大大加快了新 LMM 的开发速度。[博客] [代码库]
• [1/30] 🔥 LLaVA-NeXT（LLaVA-1.6）发布！通过对 LLaVA-1.5 进一步扩展，LLaVA-NeXT-34B 在某些基准测试中超越了 Gemini Pro。现在它可以处理 4 倍于以往的像素，并执行更多任务和应用。请查看 博客文章 并体验 演示！模型可在 模型库 中找到。训练/评估数据和脚本将很快发布。
• [11/10] LLaVA-Plus 发布：学习使用工具创建多模态智能体，配备 LLaVA-Plus（可插拔并学习技能的 LLaVA）。[项目页面] [演示] [代码] [论文]
• [11/2] LLaVA-Interactive 发布：通过一体化演示体验人机多模态交互的未来，涵盖图像聊天、分割、生成和编辑等功能。[项目页面] [演示] [代码] [论文]
• [10/26] 🔥 使用 LoRA 的 LLaVA-1.5 获得了与全模型微调相当的性能，同时降低了 GPU 内存需求（检查点，脚本）。我们还提供了一份 文档，介绍如何使用 LoRA 在您自己的数据集上对 LLaVA-1.5 进行微调。
• [10/12] 请查看由 ETRI 创造的韩语版 LLaVA（Ko-LLaVA），ETRI 慷慨地支持了我们的研究！[🤗 演示]
• [10/5] 🔥 LLaVA-1.5 发布！在 11 个基准测试中达到 SOTA 水平，仅通过对原始 LLaVA 进行简单修改，便利用了所有公开数据，在单个 8-A100 节点上约 1 天内完成训练，超越了诸如 Qwen-VL-Chat 等使用数十亿规模数据的方法。请查看 技术报告，并体验 演示！模型可在 模型库 中找到。LLaVA-1.5 的训练数据和脚本已在 这里 发布，评估脚本则在 这里 发布！
• [9/26] LLaVA 通过人类反馈强化学习（RLHF）进行了改进，以提高事实准确性并减少幻觉现象。请在项目 [LLavA-RLHF] 中查看新的 SFT 和 RLHF 检查点。
• [9/22] LLaVA 被 NeurIPS 2023 接受为 口头报告，而 LLaVA-Med 则被 NeurIPS 2023 数据集与基准测试赛道接受为 亮点报告。

使用与许可声明：本项目使用了某些数据集和检查点，这些资源受其各自原始许可证的约束。用户必须遵守所有这些原始许可证中的条款与条件，包括但不限于针对该数据集的 OpenAI 使用条款，以及针对使用该数据集训练的检查点所采用的基础语言模型的具体许可证（例如，针对 LLaMA-2 和 Vicuna-v1.5 的 Llama 社区许可证）。本项目不会施加超出原始许可证规定之外的任何额外限制。此外，提醒用户务必确保其对数据集和检查点的使用符合所有适用的法律法规。

目录

• 安装
• LLaVA 权重
• 演示
• 模型库
• 数据集
• 训练
• 评估

安装

如果您不使用 Linux，请不要继续操作，而是参阅适用于 macOS 和 Windows 的说明。

1. 克隆本仓库并进入 LLaVA 文件夹

git clone https://github.com/haotian-liu/LLaVA.git
cd LLaVA

2. 安装软件包

conda create -n llava python=3.10 -y
conda activate llava
pip install --upgrade pip  # 启用 PEP 660 支持
pip install -e .

3. 安装用于训练场景的附加包

pip install -e ".[train]"
pip install flash-attn --no-build-isolation

升级至最新代码库

git pull
pip install -e .

# 如果升级后出现一些导入错误，
# 请尝试运行以下命令（去掉 #）
# pip install flash-attn --no-build-isolation --no-cache-dir

HuggingFace 快速入门

from llava.model.builder import load_pretrained_model
from llava.mm_utils import get_model_name_from_path
from llava.eval.run_llava import eval_model

model_path = "liuhaotian/llava-v1.5-7b"

tokenizer, model, image_processor, context_len = load_pretrained_model(
    model_path=model_path,
    model_base=None,
    model_name=get_model_name_from_path(model_path)
)

model_path = "liuhaotian/llava-v1.5-7b"
prompt = "我来这里参观时需要注意些什么？"
image_file = "https://llava-vl.github.io/static/images/view.jpg"

args = type('Args', (), {
    "model_path": model_path,
    "model_base": None,
    "model_name": get_model_name_from_path(model_path),
    "query": prompt,
    "conv_mode": None,
    "image_file": image_file,
    "sep": ",",
    "temperature": 0,
    "top_p": None,
    "num_beams": 1,
    "max_new_tokens": 512
})()

eval_model(args)

LLaVA 权重

请查看我们的 模型动物园，以获取所有公开的 LLaVA 检查点，以及如何使用这些权重的说明。

演示

Gradio Web UI

要在本地启动 Gradio 演示，请依次运行以下命令。如果您计划启动多个模型工作节点来比较不同的检查点，只需一次启动控制器和 Web 服务器即可。

flowchart BT
    %% 声明节点
    gws("Gradio (UI 服务器)")
    c("控制器 (API 服务器):<br/>端口: 10000")
    mw7b("模型工作节点:<br/>llava-v1.5-7b<br/>端口: 40000")
    mw13b("模型工作节点:<br/>llava-v1.5-13b<br/>端口: 40001")
    sglw13b("SGLang 后端:<br/>llava-v1.6-34b<br/>http://localhost:30000")
    lsglw13b("SGLang 工作节点:<br/>llava-v1.6-34b<br/>端口: 40002")

    %% 声明样式
    classDef data fill:#3af,stroke:#48a,stroke-width:2px,color:#444
    classDef success fill:#8f8,stroke:#0a0,stroke-width:2px,color:#444
    classDef failure fill:#f88,stroke:#f00,stroke-width:2px,color:#444

    %% 分配样式
    class id,od data;
    class cimg,cs_s,scsim_s success;
    class ncimg,cs_f,scsim_f failure;

    subgraph 演示连接
        direction BT
        c<-->gws
        
        mw7b<-->c
        mw13b<-->c
        lsglw13b<-->c
        sglw13b<-->lsglw13b
    end

启动控制器

python -m llava.serve.controller --host 0.0.0.0 --port 10000

启动 Gradio Web 服务器。

python -m llava.serve.gradio_web_server --controller http://localhost:10000 --model-list-mode reload

您已经成功启动了 Gradio Web 界面。现在，您可以使用屏幕上打印的 URL 打开该界面。您可能会注意到模型列表中还没有任何模型。不用担心，因为我们尚未启动任何模型工作节点。当您启动一个模型工作节点时，模型列表会自动更新。

启动 SGLang 工作节点

这是以高吞吐量服务 LLaVA 模型的推荐方式，您需要先安装 SGLang。请注意，目前 SGLang-LLaVA 尚不支持 4-bit 量化。如果您 GPU 显存有限，请查看带有量化的模型工作节点。

pip install "sglang[all]"

首先，您将启动一个 SGLang 后端工作节点，它将在 GPU 上执行模型推理。请记住您设置的 --port，稍后会用到。

# 单 GPU
CUDA_VISIBLE_DEVICES=0 python3 -m sglang.launch_server --model-path liuhaotian/llava-v1.5-7b --tokenizer-path llava-hf/llava-1.5-7b-hf --port 30000

# 多 GPU 张量并行
CUDA_VISIBLE_DEVICES=0,1 python3 -m sglang.launch_server --model-path liuhaotian/llava-v1.5-13b --tokenizer-path llava-hf/llava-1.5-13b-hf --port 30000 --tp 2

临时分词器：llava-hf/llava-1.5-7b-hf、llava-hf/llava-1.5-13b-hf、liuhaotian/llava-v1.6-34b-tokenizer。

接下来，您将启动一个 LLaVA-SGLang 工作节点，它负责在 LLaVA 控制器和 SGLang 后端之间通信，以路由请求。将 --sgl-endpoint 设置为 http://127.0.0.1:端口，其中 端口 是您刚刚设置的（默认为 30000）。

python -m llava.serve.sglang_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --sgl-endpoint http://127.0.0.1:30000

启动模型工作节点

这是实际在 GPU 上执行推理的工作节点。每个工作节点负责 --model-path 中指定的单个模型。

python -m llava.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path liuhaotian/llava-v1.5-13b

等待进程完成模型加载，并看到“Uvicorn 正在运行…”的消息。此时，刷新您的 Gradio Web 界面，您就会在模型列表中看到刚刚启动的模型。

您可以根据需要启动任意数量的工作节点，并在同一 Gradio 界面中比较不同模型的检查点。请保持 --controller 不变，但为每个工作节点修改 --port 和 --worker 的端口号。

python -m llava.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port <不同于 40000，例如 40001> --worker http://localhost:<相应地更改，即 40001> --model-path <ckpt2>

如果您使用的是搭载 M1 或 M2 芯片的 Apple 设备，可以通过 --device 标志指定 mps 设备：--device mps。

启动模型工作节点（多 GPU，当 GPU 显存 ≤ 24GB）

如果您的 GPU 显存小于 24GB（例如 RTX 3090、RTX 4090 等），可以尝试使用多 GPU 运行。我们最新的代码库会在您拥有多个 GPU 时自动尝试使用多 GPU。您可以通过 CUDA_VISIBLE_DEVICES 指定要使用的 GPU。以下是使用前两块 GPU 的示例：

CUDA_VISIBLE_DEVICES=0,1 python -m llava.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path liuhaotian/llava-v1.5-13b

启动模型工作节点（4-bit、8-bit 推理，量化）

您可以启动带有量化位数（4-bit、8-bit）的模型工作节点，这样可以减少 GPU 内存占用，从而可能在显存低至 12GB 的 GPU 上运行。请注意，使用量化位数进行推理的准确性可能不如全精度模型。只需在您正在执行的模型工作节点命令中添加 --load-4bit 或 --load-8bit 即可。以下是使用 4-bit 量化运行的示例：

python -m llava.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path liuhaotian/llava-v1.5-13b --load-4bit

启动模型工作节点（LoRA 权重，未合并）

您可以启动带有 LoRA 权重的模型工作节点，而不将其与基础检查点合并，以节省磁盘空间。虽然加载时间会有所增加，但推理速度与已合并的检查点相同。未合并的 LoRA 检查点在模型名称中没有 lora-merge，通常比已合并的检查点小得多（7B 的未合并版本小于 1GB，而 13B 的未合并版本约为 25GB）。

要加载未合并的 LoRA 权重，您只需传递一个额外的参数 --model-base，即用于训练 LoRA 权重的基础 LLM。您可以在 模型动物园中查看每组 LoRA 权重对应的基础 LLM。

python -m llava.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path liuhaotian/llava-v1-0719-336px-lora-vicuna-13b-v1.3 --model-base lmsys/vicuna-13b-v1.3

命令行推理

使用 LLaVA 在无需 Gradio 界面的情况下对图像进行对话。它还支持多 GPU、4 位和 8 位量化推理。采用 4 位量化后，对于我们的 LLaVA-1.5-7B 模型，在单个 GPU 上仅需不到 8GB 显存。

python -m llava.serve.cli \
    --model-path liuhaotian/llava-v1.5-7b \
    --image-file "https://llava-vl.github.io/static/images/view.jpg" \
    --load-4bit

训练

以下是 LLaVA v1.5 的最新训练配置。对于旧版本模型，请暂时参考 此 版本的 README。我们稍后会将其添加到单独的文档中。

LLaVA 的训练分为两个阶段：(1) 特征对齐阶段：使用我们从 LAION-CC-SBU 数据集中提取的 55.8 万张子集，将一个 冻结的预训练 视觉编码器与一个 冻结的 LLM 连接起来；(2) 视觉指令微调阶段：使用由 GPT 生成的 15 万条多模态指令遵循数据，再加上约 51.5 万条面向学术任务的 VQA 数据，来训练模型遵循多模态指令。

LLaVA 在 8 张 80GB 显存的 A100 GPU 上进行训练。如果希望在较少的 GPU 上训练，可以相应地减少 per_device_train_batch_size 并增加 gradient_accumulation_steps。务必保持全局批次大小不变：per_device_train_batch_size × gradient_accumulation_steps × num_gpus。

超参数

我们在微调时使用了与 Vicuna 类似的超参数集合。以下同时提供了预训练和微调所使用的超参数。

1. 预训练

2. 微调

自动下载 Vicuna 检查点

我们的基础模型 Vicuna v1.5 是一个经过指令微调的聊天机器人，当您运行我们提供的训练脚本时，它会自动下载，无需任何操作。

预训练（特征对齐）

请从 这里 下载我们在论文中使用的带有 BLIP 字幕的 LAION-CC-SBU 数据集 55.8 万张子集。

由于分辨率提升至 336px，LLaVA-v1.5-13B 在 8 张 A100 (80G) 上预训练大约需要 5.5 小时。而 LLaVA-v1.5-7B 则大约需要 3.5 小时。

使用 DeepSpeed ZeRO-2 的训练脚本：pretrain.sh。

• --mm_projector_type mlp2x_gelu：两层 MLP 视觉-语言连接器。
• --vision_tower openai/clip-vit-large-patch14-336：CLIP ViT-L/14 336px。

视觉指令微调

1. 准备数据

请下载我们指令微调数据最终混合体的标注文件 llava_v1_5_mix665k.json，并从组成数据集的各个来源下载图像：

• COCO：train2017
• GQA：images
• OCR-VQA：下载脚本，我们将所有文件保存为 .jpg 格式
• TextVQA：train_val_images
• VisualGenome：part1、part2

全部下载完成后，请按照以下方式在 ./playground/data 目录下组织数据：

├── coco
│   └── train2017
├── gqa
│   └── images
├── ocr_vqa
│   └── images
├── textvqa
│   └── train_images
└── vg
    ├── VG_100K
    └── VG_100K_2

2. 开始训练！

您可以从 Model Zoo 下载我们预训练好的投影器。不建议使用旧版投影器，因为它们可能是用不同版本的代码库训练的，一旦有任何选项设置错误，模型将无法按预期运行或训练。

由于分辨率提升至 336px，LLaVA-v1.5-13B 在 8 张 A100 (80G) 上视觉指令微调大约需要 20 小时。而 LLaVA-v1.5-7B 在 8 张 A100 (40G) 上则大约需要 10 小时。

使用 DeepSpeed ZeRO-3 的训练脚本：finetune.sh。

如果您显存不足：

• 使用 LoRA：finetune_lora.sh。我们可以在 8 张 A100-40G 或 8 张 A6000 上完成 13B 模型的训练，在 8 张 RTX3090 上完成 7B 模型的训练。请确保 per_device_train_batch_size*gradient_accumulation_steps 与提供的脚本一致，以获得最佳的可重复性。
• 将 zero3.json 替换为 zero3_offload.json，该文件会将部分参数卸载到 CPU 内存中。这会降低训练速度。

如果您有兴趣将 LLaVA 模型微调到自己的任务或数据上，请参阅 Finetune_Custom_Data.md。

需要注意的新选项：

• --mm_projector_type mlp2x_gelu：两层 MLP 视觉-语言连接器。
• --vision_tower openai/clip-vit-large-patch14-336：CLIP ViT-L/14 336px。
• --image_aspect_ratio pad：此选项会将非正方形图像填充为正方形，而不是裁剪它们；这可以略微减少幻觉现象。
• --group_by_modality_length True：此选项仅应在您的指令微调数据集同时包含语言（例如 ShareGPT）和多模态（例如 LLaVA-Instruct）数据时使用。它会使训练采样器在训练过程中只采样单一模态（要么是图像，要么是语言），我们观察到这样可以使训练速度加快约 25%，且不会影响最终结果。

评估

在 LLaVA-1.5 中，我们使用一组多样化的 12 个基准测试来评估模型。为了确保可重复性，我们使用贪婪解码来评估模型。我们不使用束搜索进行评估，以使推理过程与实时输出的聊天演示保持一致。

详情请参阅 Evaluation.md。

GPT辅助评估

我们提供的多模态建模GPT辅助评估流程，旨在全面了解视觉-语言模型的能力。更多详情请参阅我们的论文。

1. 生成LLaVA响应

python model_vqa.py \
    --model-path ./checkpoints/LLaVA-13B-v0 \
    --question-file \
    playground/data/coco2014_val_qa_eval/qa90_questions.jsonl \
    --image-folder \
    /path/to/coco2014_val \
    --answers-file \
    /path/to/answer-file-our.jsonl

2. 对生成的响应进行评估。在本例中，answer-file-ref.jsonl 是由纯文本GPT-4 (0314) 生成的响应，上下文包含说明文字和边界框信息。

OPENAI_API_KEY="sk-***********************************" python llava/eval/eval_gpt_review_visual.py \
    --question playground/data/coco2014_val_qa_eval/qa90_questions.jsonl \
    --context llava/eval/table/caps_boxes_coco2014_val_80.jsonl \
    --answer-list \
    /path/to/answer-file-ref.jsonl \
    /path/to/answer-file-our.jsonl \
    --rule llava/eval/table/rule.json \
    --output /path/to/review.json

3. 总结评估结果

python summarize_gpt_review.py

引用

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

@misc{liu2024llavanext,
    title={LLaVA-NeXT：改进的推理能力、OCR与世界知识},
    url={https://llava-vl.github.io/blog/2024-01-30-llava-next/},
    author={刘浩天、李春元、李宇恒、李博、张元翰、沈胜、李勇宰},
    month={一月},
    year={2024}
}

@misc{liu2023improvedllava,
      title={通过视觉指令微调改进基线}, 
      author={刘浩天、李春元、李宇恒、李勇宰},
      publisher={arXiv:2310.03744},
      year={2023},
}

@misc{liu2023llava,
      title={视觉指令微调}, 
      author={刘浩天、李春元、吴清阳、李勇宰},
      publisher={NeurIPS},
      year={2023},
}

致谢

• Vicuna：我们基于其代码库构建，并以此为基础模型Vicuna-13B，它拥有卓越的语言能力！

相关项目

• 使用GPT-4进行指令微调
• LLaVA-Med：一天内训练用于生物医学的大规模视觉-语言助手
• Otter：上下文多模态指令微调

如需未来项目创意，请查看：

• SEEM：一次完成所有地方的所有内容分割
• Grounded-Segment-Anything，通过结合Grounding DINO和Segment-Anything，实现检测、分割及生成任何内容的功能。

LLaVA 快速上手指南

LLaVA (Large Language and Vision Assistant) 是一个开源的多模态大语言模型，通过视觉指令微调，实现了接近 GPT-4 级别的图像理解与对话能力。本指南将帮助你快速在本地部署并运行 LLaVA。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: 推荐 Linux (Ubuntu/CentOS 等)。
  • 注：macOS 和 Windows 用户请参考官方文档中的特定适配方案，本指南主要针对 Linux 环境。
• 硬件要求:
  • GPU: 推荐使用 NVIDIA GPU。
    • 运行 7B/13B 模型建议显存 ≥ 16GB (使用量化版本可降低至 12GB 或更低)。
    • 训练或运行更大参数模型（如 34B+）需要更高显存或多卡环境。
  • CPU: 多核处理器，建议 8 核以上。
  • 内存: 建议 32GB 以上。
• 软件依赖:
  • Conda: 用于管理 Python 环境 (推荐 Miniconda 或 Anaconda)。
  • CUDA: 已安装与你的 GPU 驱动的兼容版本 (通常建议 CUDA 11.8 或 12.1)。
  • Git: 用于克隆代码库。

2. 安装步骤

第一步：克隆仓库

打开终端，执行以下命令获取最新代码：

git clone https://github.com/haotian-liu/LLaVA.git
cd LLaVA

第二步：创建并激活 Conda 环境

创建一个名为 llava 的 Python 3.10 环境：

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

第三步：安装核心依赖

升级 pip 以支持 PEP 660，并安装 LLaVA 包：

pip install --upgrade pip  # enable PEP 660 support
pip install -e .

国内加速提示：如果下载速度较慢，可临时切换至清华或阿里镜像源： pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

第四步：安装训练与推理增强包（可选但推荐）

如果你计划进行模型训练或使用 Flash Attention 加速推理，请执行：

pip install -e ".[train]"
pip install flash-attn --no-build-isolation

注意：flash-attn 编译可能需要较长时间，请确保已安装对应的 CUDA Toolkit。若遇到导入错误，可尝试添加 --no-cache-dir 参数重新安装。

3. 基本使用

安装完成后，你可以通过 Python 脚本快速加载模型并进行图像对话。以下是一个基于 Hugging Face transformers 接口的最小化示例。

前提条件：你需要先从 Hugging Face Model Zoo 或 LLaVA 官方模型库 下载模型权重（例如 llava-v1.5-7b），或者直接在代码中使用模型 ID（需联网）。

import torch
from llava.model.builder import load_pretrained_model
from llava.mm_utils import get_model_name_from_path, process_images, tokenizer_image_token
from llava.constants import IMAGE_TOKEN_INDEX, DEFAULT_IMAGE_TOKEN, DEFAULT_IM_START_TOKEN, DEFAULT_IM_END_TOKEN
from transformers import TextIteratorStreamer
from threading import Thread

# 配置模型路径 (可以是本地路径或 HF model_id)
model_path = "llava-hf/llava-1.5-7b-hf" 

# 加载预训练模型
tokenizer, model, image_processor, context_len = load_pretrained_model(
    model_path=model_path,
    model_base=None,
    model_name=get_model_name_from_path(model_path),
    device="cuda",
    device_map={"": "cuda"},
    torch_dtype=torch.float16,
    load_8bit=False,
    cpu_offloading=False,
    debug=False
)

# 准备输入
image_file = "example.jpg"  # 替换为你的图片路径
prompt = "这张图片里有什么？请详细描述。"

# 处理图像和文本
# 注意：实际使用时需根据具体版本调整 prompt 格式，LLaVA-1.5+ 通常自动处理 <image> 标记
inputs = tokenizer_image_token(prompt, tokenizer, return_tensors='pt').unsqueeze(0).cuda()

# 生成回复 (简化版调用，实际生产环境建议使用完整的 generate 流程)
# 此处仅为演示加载成功，完整生成逻辑需参考官方 demo 脚本
print("模型加载成功！可以进行推理。")

更简单的命令行测试方式： 如果你已经下载了模型权重，可以使用官方提供的推理脚本（需确保图片路径正确）：

python llava/serve/cli.py \
    --model-path /path/to/llava-v1.5-7b \
    --image-file ./images/llama.png \
    --query "What is the animal in the picture doing?"

运行后，终端将输出模型对图片的描述。