pretraining/LlamaFactory/tests/model/model_utils/test_visual.py

# Copyright 2025 the LlamaFactory team.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import os
from types import SimpleNamespace

import pytest
import torch
from safetensors.torch import load_file
from transformers import AutoConfig, AutoModelForImageTextToText

from llamafactory.extras.packages import is_transformers_version_greater_than
from llamafactory.hparams import FinetuningArguments, ModelArguments
from llamafactory.model.adapter import _setup_freeze_tuning, _setup_full_tuning, init_adapter
from llamafactory.model.model_utils.misc import find_all_linear_modules
from llamafactory.model.model_utils.visual import COMPOSITE_MODELS, autocast_projector_dtype, patch_target_modules


class _MossVLFixture(torch.nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.config = SimpleNamespace(
            model_type="moss_vl",
            text_config=SimpleNamespace(num_hidden_layers=2),
        )
        self.model = torch.nn.Module()
        self.model.separator_token = torch.nn.Parameter(torch.empty(4))
        self.model.visual = torch.nn.Module()
        self.model.visual.pos_embed = torch.nn.Embedding(4, 4)
        self.model.visual.patch_embed = torch.nn.Module()
        self.model.visual.patch_embed.proj = torch.nn.Linear(4, 4)
        self.model.visual.blocks = torch.nn.ModuleList([self._make_block(), self._make_block()])
        self.model.visual.merger = torch.nn.Module()
        self.model.visual.merger.linear_fc1 = torch.nn.Linear(4, 4)
        self.model.language_model = torch.nn.Module()
        self.model.language_model.layers = torch.nn.ModuleList([self._make_layer(), self._make_layer()])
        self.lm_head = torch.nn.Linear(4, 4)

    @staticmethod
    def _make_block() -> torch.nn.Module:
        block = torch.nn.Module()
        block.attn = torch.nn.Module()
        block.attn.qkv = torch.nn.Linear(4, 4)
        return block

    @staticmethod
    def _make_layer() -> torch.nn.Module:
        layer = torch.nn.Module()
        layer.self_attn = torch.nn.Module()
        layer.self_attn.q_proj = torch.nn.Linear(4, 4)
        return layer


@pytest.mark.parametrize("freeze_vision_tower", (False, True))
@pytest.mark.parametrize("freeze_multi_modal_projector", (False, True))
@pytest.mark.parametrize("freeze_language_model", (False, True))
def test_moss_vl_full(
    freeze_vision_tower: bool,
    freeze_multi_modal_projector: bool,
    freeze_language_model: bool,
):
    model = _MossVLFixture()
    finetuning_args = FinetuningArguments(
        finetuning_type="full",
        freeze_vision_tower=freeze_vision_tower,
        freeze_multi_modal_projector=freeze_multi_modal_projector,
        freeze_language_model=freeze_language_model,
    )

    _setup_full_tuning(model, finetuning_args, is_trainable=True, cast_trainable_params_to_fp32=False)

    for name, param in model.named_parameters():
        if name.startswith("model.visual.merger") or name == "model.separator_token":
            assert param.requires_grad != freeze_multi_modal_projector
        elif name.startswith("model.visual"):
            assert param.requires_grad != freeze_vision_tower
        else:
            assert param.requires_grad != freeze_language_model


@pytest.mark.parametrize("freeze_multi_modal_projector", (False, True))
def test_moss_vl_freeze(freeze_multi_modal_projector: bool):
    model = _MossVLFixture()
    finetuning_args = FinetuningArguments(
        finetuning_type="freeze",
        freeze_trainable_layers=1,
        freeze_vision_tower=True,
        freeze_multi_modal_projector=freeze_multi_modal_projector,
        freeze_language_model=False,
    )

    _setup_freeze_tuning(model, finetuning_args, is_trainable=True, cast_trainable_params_to_fp32=False)

    assert model.model.separator_token.requires_grad != freeze_multi_modal_projector
    assert model.model.visual.merger.linear_fc1.weight.requires_grad != freeze_multi_modal_projector
    assert model.model.visual.patch_embed.proj.weight.requires_grad is False
    assert model.model.language_model.layers[0].self_attn.q_proj.weight.requires_grad is False
    assert model.model.language_model.layers[1].self_attn.q_proj.weight.requires_grad is True


@pytest.mark.parametrize("freeze_vision_tower", (False, True))
def test_moss_vl_lora_target_all(freeze_vision_tower: bool):
    model = _MossVLFixture()
    finetuning_args = FinetuningArguments(
        finetuning_type="lora",
        lora_target="all",
        freeze_vision_tower=freeze_vision_tower,
        freeze_multi_modal_projector=True,
        freeze_language_model=False,
    )

    target_modules = find_all_linear_modules(model, freeze_vision_tower)
    target_modules = patch_target_modules(model, finetuning_args, target_modules)

    assert any(name.startswith("model.language_model") and name.endswith("q_proj") for name in target_modules)
    assert any(name.startswith("model.visual.blocks") and name.endswith("qkv") for name in target_modules) != (
        freeze_vision_tower
    )
    assert all("patch_embed" not in name for name in target_modules)
    assert all("merger" not in name for name in target_modules)
    assert all("lm_head" not in name for name in target_modules)


def test_moss_vl_projector_modules():
    model = _MossVLFixture()
    composite_model = COMPOSITE_MODELS["moss_vl"]

    assert composite_model.projector_keys == ["model.visual.merger", "model.separator_token"]
    assert composite_model.get_projectors(model) == [model.model.visual.merger]


def test_moss_vl_quantized_projector_hook_skips_parameter():
    model = _MossVLFixture()
    model.quantization_method = "bitsandbytes"

    autocast_projector_dtype(model, SimpleNamespace(compute_dtype=torch.float16))

    assert len(model.model.visual.merger._forward_hooks) == 1


@pytest.mark.parametrize("freeze_vision_tower", (False, True))
@pytest.mark.parametrize("freeze_multi_modal_projector", (False, True))
@pytest.mark.parametrize("freeze_language_model", (False, True))
def test_visual_full(freeze_vision_tower: bool, freeze_multi_modal_projector: bool, freeze_language_model: bool):
    model_args = ModelArguments(model_name_or_path="Qwen/Qwen2-VL-2B-Instruct")
    finetuning_args = FinetuningArguments(
        finetuning_type="full",
        freeze_vision_tower=freeze_vision_tower,
        freeze_multi_modal_projector=freeze_multi_modal_projector,
        freeze_language_model=freeze_language_model,
    )
    config = AutoConfig.from_pretrained(model_args.model_name_or_path)
    with torch.device("meta"):
        model = AutoModelForImageTextToText.from_config(config)

    model = init_adapter(config, model, model_args, finetuning_args, is_trainable=True)
    for name, param in model.named_parameters():
        if any(key in name for key in ["visual.patch_embed", "visual.blocks"]):
            assert param.requires_grad != freeze_vision_tower
        elif "visual.merger" in name:
            assert param.requires_grad != freeze_multi_modal_projector
        else:
            assert param.requires_grad != freeze_language_model


@pytest.mark.parametrize("freeze_vision_tower,freeze_language_model", ((False, False), (False, True), (True, False)))
def test_visual_lora(freeze_vision_tower: bool, freeze_language_model: bool):
    model_args = ModelArguments(model_name_or_path="Qwen/Qwen2-VL-2B-Instruct")
    finetuning_args = FinetuningArguments(
        finetuning_type="lora", freeze_vision_tower=freeze_vision_tower, freeze_language_model=freeze_language_model
    )
    config = AutoConfig.from_pretrained(model_args.model_name_or_path)
    with torch.device("meta"):
        model = AutoModelForImageTextToText.from_config(config)

    model = init_adapter(config, model, model_args, finetuning_args, is_trainable=True)
    trainable_params, frozen_params = set(), set()
    for name, param in model.named_parameters():
        if param.requires_grad:
            trainable_params.add(name)
        else:
            frozen_params.add(name)

    if is_transformers_version_greater_than("4.52.0"):
        visual_param_name = "base_model.model.model.visual.blocks.0.attn.qkv.lora_A.default.weight"
        language_param_name = "base_model.model.model.language_model.layers.0.self_attn.q_proj.lora_A.default.weight"
        merger_param_name = "base_model.model.model.visual.merger.lora_A.default.weight"
    else:
        visual_param_name = "base_model.model.visual.blocks.0.attn.qkv.lora_A.default.weight"
        language_param_name = "base_model.model.model.layers.0.self_attn.q_proj.lora_A.default.weight"
        merger_param_name = "base_model.model.visual.merger.lora_A.default.weight"

    assert (visual_param_name in trainable_params) != freeze_vision_tower
    assert (language_param_name in trainable_params) != freeze_language_model
    assert (merger_param_name in trainable_params) is False


def test_visual_model_save_load():
    # check VLM's state dict: https://github.com/huggingface/transformers/pull/38385
    model_args = ModelArguments(model_name_or_path="Qwen/Qwen2-VL-2B-Instruct")
    finetuning_args = FinetuningArguments(finetuning_type="full")
    config = AutoConfig.from_pretrained(model_args.model_name_or_path)
    with torch.device("meta"):
        model = AutoModelForImageTextToText.from_config(config)

    model = init_adapter(config, model, model_args, finetuning_args, is_trainable=False)
    model.to_empty(device="cpu")
    loaded_model_weight = dict(model.named_parameters())

    model.save_pretrained(os.path.join("output", "qwen2_vl"), max_shard_size="10GB", safe_serialization=True)
    saved_model_weight = load_file(os.path.join("output", "qwen2_vl", "model.safetensors"))

    if is_transformers_version_greater_than("4.52.0"):
        assert "model.language_model.layers.0.self_attn.q_proj.weight" in loaded_model_weight
    else:
        assert "model.layers.0.self_attn.q_proj.weight" in loaded_model_weight

    assert "model.layers.0.self_attn.q_proj.weight" in saved_model_weight