Fix NameError: PeftConfigLike triggered by PreTrainedModel.__init_subclass__

[qgallouedec]

#45425 added a class-level peft_config annotation in integrations/peft.py:

transformers/src/transformers/integrations/peft.py

Lines 407 to 428 in 63378d9

	class PeftAdapterMixin:
	"""
	A class containing all functions for loading and using adapters weights that are supported in PEFT library. For
	more details about adapters and injecting them on a transformer-based model, check out the documentation of PEFT
	library: https://huggingface.co/docs/peft/index
	Currently supported PEFT methods are all non-prompt learning methods (LoRA, IA³, etc.). Other PEFT models such as
	prompt tuning, prompt learning are out of scope as these adapters are not "injectable" into a torch module. For
	using these methods, please refer to the usage guide of PEFT library.
	With this mixin, if the correct PEFT version is installed (>= 0.18.0), it is possible to:
	- Load an adapter stored on a local path or in a remote Hub repository, and inject it in the model
	- Attach new adapters in the model and train them with Trainer or by your own.
	- Attach multiple adapters and iteratively activate / deactivate them
	- Activate / deactivate all adapters from the model.
	- Get the `state_dict` of the active adapter.
	"""
	_hf_peft_config_loaded = False
	_prepare_peft_hotswap_kwargs: dict | None = None
	peft_config: dict[str, "PeftConfigLike"]

PeftConfigLike is imported only under TYPE_CHECKING, so it does not exist in the module's runtime namespace.

PreTrainedModel inherits from PeftAdapterMixin, and modeling_utils.py:1296 runs get_type_hints(cls) inside __init_subclass__.

transformers/src/transformers/modeling_utils.py

Lines 1285 to 1297 in 63378d9

	def __init_subclass__(cls, **kwargs):
	super().__init_subclass__(**kwargs)
	# For BC we keep the original `config_class` definition in case
	# there is a `config_class` attribute (e.g. remote code models),
	# otherwise we derive it from the annotated `config` attribute.
	# defined in this particular subclass
	child_annotation = inspect.get_annotations(cls).get("config", None)
	child_attribute = cls.__dict__.get("config_class", None)
	# defined in the class (this subclass or any parent class)
	full_annotation = get_type_hints(cls).get("config", None)
	full_attribute = cls.config_class

get_type_hints walks the MRO and eagerly evaluates every forward reference in each base's module globals, so the unresolved "PeftConfigLike" raises NameError the moment any PreTrainedModel subclass is defined.

It's an import-time failure. It fires while transformers.modeling_utils itself is being imported (first triggered by PreTrainedAudioTokenizerBase), so any downstream library that imports a model (e.g. trl's SFTTrainer) fails at collection

Fix

Move PeftConfigLike out of the TYPE_CHECKING block so it's available at runtime, and drop the now-unneeded forward-reference quotes on the annotation.

[tarekziade]

Thanks!

[albertvillanova]

Thanks for the quick fix!

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.