Auto-tagging of PEFT models (#2599)

Features like inference need correctly set tags on the repo / the model card
in order to be available. Also the Hub uses tags to index the models and make
them searchable.

With this change PEFT tags models automatically as lora if they happen to
be trained with LoRA, the base model and a custom `peft:method:<the method>`
tag.

* Base model tags were never supported, they are now

Before PEFT simply ignored tags provided by the base model. Now the
base model tags are added to the PEFT-specific model tags.

* Tag 'tranformers' and add pipeline tag if possible

We remove the `peft:method:*` tag because this change needs more discussion
and is partially unrelated to this change. It is replaced by the necessary
`transformers` tag if the model is based on transformers.

We're also trying to resolve the pipeline tag automatically if it isn't set.
While there is the `transformers.pipelines.base.SUPPORTED_PEFT_TASKS` mapping
it is not sufficient to resolve the pipeline tag automatically since it is
not a 1:1 mapping. Only the causal LM case is a unique mapping.

---------

Co-authored-by: Benjamin Bossan <BenjaminBossan@users.noreply.github.com>

Author: githubnemo

src/peft/peft_model.py

@@ -1438,6 +1438,26 @@ def base_model_torch_dtype(self):
     def active_peft_config(self):
         return self.peft_config[self.active_adapter]
 
+    def _get_peft_specific_model_tags(self):
+        """Derive tags for the model card from the adapter's config. For example, setting the
+        base model is important for enabling support for HF inference providers but it also makes models more
+        searchable on the HF hub.
+        """
+        peft_method = self.active_peft_config.peft_type.value
+
+        tags = []
+
+        if hasattr(self.base_model, "model") and isinstance(self.base_model.model, transformers.PreTrainedModel):
+            tags.append("transformers")
+
+        if peft_method == "LORA":
+            tags.append("lora")
+
+        if hasattr(self.base_model, "name_or_path"):
+            tags.append(f"base_model:adapter:{self.base_model.name_or_path}")
+
+        return tags
+
     def create_or_update_model_card(self, output_dir: str):
         """
         Updates or create model card to include information about peft:
@@ -1453,6 +1473,20 @@ def create_or_update_model_card(self, output_dir: str):
 
         card.data["library_name"] = "peft"
 
+        tags = set()
+        base_model = self.get_base_model()
+        if hasattr(base_model, "model_tags"):
+            tags = tags.union(base_model.model_tags or [])
+
+        tags = tags.union(self._get_peft_specific_model_tags())
+        if tags:
+            card.data["tags"] = sorted(tags)
+
+        # One of the rare moments where we can select the pipeline tag with certainty, so let's do that.
+        # Makes it easier to deploy an adapter with auto inference since the user doesn't have to add any tags.
+        if not card.data.pipeline_tag and isinstance(self, PeftModelForCausalLM):
+            card.data.pipeline_tag = "text-generation"
+
         model_config = BaseTuner.get_model_config(self)
         model_config = None if model_config == DUMMY_MODEL_CONFIG else model_config
         if model_config is not None and "_name_or_path" in model_config:

tests/test_hub_features.py

@@ -15,9 +15,12 @@
 
 import pytest
 import torch
+from huggingface_hub import ModelCard
 from transformers import AutoModelForCausalLM
 
-from peft import AutoPeftModelForCausalLM, LoraConfig, PeftConfig, PeftModel, get_peft_model
+from peft import AutoPeftModelForCausalLM, BoneConfig, LoraConfig, PeftConfig, PeftModel, TaskType, get_peft_model
+
+from .testing_common import hub_online_once
 
 
 PEFT_MODELS_TO_TEST = [("peft-internal-testing/test-lora-subfolder", "test")]
@@ -112,3 +115,106 @@ def test_load_different_peft_and_base_model_revision(self, tmp_path):
 
         assert peft_model.peft_config["default"].base_model_name_or_path == base_model_id
         assert peft_model.peft_config["default"].revision == base_model_revision
+
+
+class TestModelCard:
+    @pytest.mark.parametrize(
+        "model_id, peft_config, tags, excluded_tags, pipeline_tag",
+        [
+            (
+                "hf-internal-testing/tiny-random-Gemma3ForCausalLM",
+                LoraConfig(),
+                ["transformers", "base_model:adapter:hf-internal-testing/tiny-random-Gemma3ForCausalLM", "lora"],
+                [],
+                None,
+            ),
+            (
+                "hf-internal-testing/tiny-random-Gemma3ForCausalLM",
+                BoneConfig(),
+                ["transformers", "base_model:adapter:hf-internal-testing/tiny-random-Gemma3ForCausalLM"],
+                ["lora"],
+                None,
+            ),
+            (
+                "hf-internal-testing/tiny-random-BartForConditionalGeneration",
+                LoraConfig(),
+                [
+                    "transformers",
+                    "base_model:adapter:hf-internal-testing/tiny-random-BartForConditionalGeneration",
+                    "lora",
+                ],
+                [],
+                None,
+            ),
+            (
+                "hf-internal-testing/tiny-random-Gemma3ForCausalLM",
+                LoraConfig(task_type=TaskType.CAUSAL_LM),
+                ["transformers", "base_model:adapter:hf-internal-testing/tiny-random-Gemma3ForCausalLM", "lora"],
+                [],
+                "text-generation",
+            ),
+        ],
+    )
+    @pytest.mark.parametrize(
+        "pre_tags",
+        [
+            ["tag1", "tag2"],
+            [],
+        ],
+    )
+    def test_model_card_has_expected_tags(
+        self, model_id, peft_config, tags, excluded_tags, pipeline_tag, pre_tags, tmp_path
+    ):
+        """Make sure that PEFT sets the tags in the model card automatically and correctly.
+        This is important so that a) the models are searchable on the Hub and also 2) some features depend on it to
+        decide how to deal with them (e.g., inference).
+
+        Makes sure that the base model tags are still present (if there are any).
+        """
+        with hub_online_once(model_id):
+            base_model = AutoModelForCausalLM.from_pretrained(model_id)
+
+            if pre_tags:
+                base_model.add_model_tags(pre_tags)
+
+            peft_model = get_peft_model(base_model, peft_config)
+            save_path = tmp_path / "adapter"
+
+            peft_model.save_pretrained(save_path)
+
+            model_card = ModelCard.load(save_path / "README.md")
+            assert set(tags).issubset(set(model_card.data.tags))
+
+            if excluded_tags:
+                assert set(excluded_tags).isdisjoint(set(model_card.data.tags))
+
+            if pre_tags:
+                assert set(pre_tags).issubset(set(model_card.data.tags))
+
+            if pipeline_tag:
+                assert model_card.data.pipeline_tag == pipeline_tag
+
+    @pytest.fixture
+    def custom_model_cls(self):
+        class MyNet(torch.nn.Module):
+            def __init__(self):
+                super().__init__()
+                self.l1 = torch.nn.Linear(10, 20)
+                self.l2 = torch.nn.Linear(20, 1)
+
+            def forward(self, X):
+                return self.l2(self.l1(X))
+
+        return MyNet
+
+    def test_custom_models_dont_have_transformers_tag(self, custom_model_cls, tmp_path):
+        base_model = custom_model_cls()
+        peft_config = LoraConfig(target_modules="all-linear")
+        peft_model = get_peft_model(base_model, peft_config)
+
+        peft_model.save_pretrained(tmp_path)
+
+        model_card = ModelCard.load(tmp_path / "README.md")
+
+        assert model_card.data.tags is not None
+        assert "transformers" not in model_card.data.tags

tests/testing_common.py

@@ -266,6 +266,11 @@ def check_modelcard(self, tmp_dirname, model):
         else:  # a custom model
             assert "base_model" not in dct
 
+        # The Hub expects the lora tag to be set for PEFT LoRA models since they
+        # have explicit support for things like inference.
+        if model.active_peft_config.peft_type.value == "LORA":
+            assert "lora" in dct["tags"]
+
     def check_config_json(self, tmp_dirname, model):
         # check the generated config.json
         filename = os.path.join(tmp_dirname, "adapter_config.json")