Handle Transformers 5 vLLM import errors (#3908)

* Handle Transformers 5 vLLM import errors

* Deduplicate vLLM transformers mismatch handling

---------

Co-authored-by: danielhanchen <danielhanchen@users.noreply.github.com>

unsloth/import_fixes.py

@@ -307,16 +307,43 @@ def fix_vllm_aimv2_issue():
 
 
 def fix_vllm_guided_decoding_params():
+    def _maybe_raise_vllm_transformers_mismatch(error):
+        error_text = str(error)
+        if (
+            "ALLOWED_LAYER_TYPES" in error_text
+            or "transformers.configuration_utils" in error_text
+        ):
+            try:
+                vllm_version = importlib_version("vllm")
+            except Exception:
+                vllm_version = "unknown"
+            raise RuntimeError(
+                "Unsloth: vLLM with version "
+                f"{vllm_version} does not yet support transformers>=5.0.0. "
+                "Please downgrade to transformers==4.57.3 via "
+                'pip install --force-reinstall "transformers==4.57.3". '
+                f"Original error: {error}"
+            ) from error
+
     if importlib.util.find_spec("vllm") is None:
         return
     # GuidedDecodingParmas is renamed to StructuredOutputsParams in vLLM
     # https://github.com/vllm-project/vllm/pull/22772/files
     # trl still wants to use GuidedDecodingParams. This is a temporary patch till trl updates
-    import vllm
+    try:
+        import vllm
+    except ImportError as e:
+        _maybe_raise_vllm_transformers_mismatch(e)
+        raise
 
     try:
         from vllm.sampling_params import GuidedDecodingParams
-    except ImportError:
+    except ImportError as e:
+        _maybe_raise_vllm_transformers_mismatch(e)
+        if not hasattr(vllm, "sampling_params") or not hasattr(
+            vllm.sampling_params, "StructuredOutputsParams"
+        ):
+            raise
         vllm.sampling_params.GuidedDecodingParams = (
             vllm.sampling_params.StructuredOutputsParams
         )

unsloth/models/vision.py

@@ -106,7 +106,7 @@ PRE_COMPILE_INFERENCE = [
     "gpt_oss",
 ]
 
-from transformers import GenerationConfig, CompileConfig, HybridCache, AutoConfig
+from transformers import GenerationConfig, CompileConfig, AutoConfig
 
 try:
     from transformers import PreTrainedConfig
@@ -117,7 +117,7 @@ except:
 
 HAS_TORCH_DTYPE = "torch_dtype" in PretrainedConfig.__doc__
 
-from transformers import GenerationConfig, CompileConfig, HybridCache
+from transformers import GenerationConfig, CompileConfig
 
 _compile_config = CompileConfig(
     fullgraph = False,