{"record":{"id":"0941c41074b99a9b","repo":"opendatalab/MinerU","slug":"please-install-transformers-to-use-the-transformer","errorCode":null,"errorMessage":"Please install transformers to use the transformers backend.","messagePattern":"Please install transformers to use the transformers backend\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"mineru/backend/vlm/vlm_analyze.py","lineNumber":90,"sourceCode":"                http_timeout = kwargs.get(\"http_timeout\", 600)  # for http-client backend only\n                server_headers = kwargs.get(\"server_headers\", None)  # for http-client backend only\n                max_retries = kwargs.get(\"max_retries\", 3)  # for http-client backend only\n                retry_backoff_factor = kwargs.get(\"retry_backoff_factor\", 0.5)  # for http-client backend only\n                # 从kwargs中移除这些参数，避免传递给不相关的初始化函数\n                for param in [\"batch_size\", \"max_concurrency\", \"http_timeout\", \"server_headers\", \"max_retries\", \"retry_backoff_factor\"]:\n                    if param in kwargs:\n                        del kwargs[param]\n                if backend not in [\"http-client\"] and not model_path:\n                    model_path = auto_download_and_get_model_root_path(\"/\",\"vlm\")\n                if backend == \"transformers\":\n                    try:\n                        from transformers import (\n                            AutoProcessor,\n                            Qwen2VLForConditionalGeneration,\n                        )\n                        from transformers import __version__ as transformers_version\n                    except ImportError:\n                        raise ImportError(\"Please install transformers to use the transformers backend.\")\n\n                    if version.parse(transformers_version) >= version.parse(\"4.56.0\"):\n                        dtype_key = \"dtype\"\n                    else:\n                        dtype_key = \"torch_dtype\"\n                    device = get_device()\n                    model = Qwen2VLForConditionalGeneration.from_pretrained(\n                        model_path,\n                        device_map={\"\": device},\n                        **{dtype_key: \"auto\"},  # type: ignore\n                    )\n                    processor = AutoProcessor.from_pretrained(\n                        model_path,\n                        use_fast=True,\n                    )\n                    if batch_size == 0:\n                        batch_size = set_default_batch_size()\n                elif backend == \"mlx-engine\":","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/vlm/vlm_analyze.py#L72-L108","documentation":"Raised on the transformers branch of VLM model loading (vlm_analyze.py) when `from transformers import AutoProcessor, Qwen2VLForConditionalGeneration` fails with ImportError. The transformers backend requires the transformers package (new enough for Qwen2-VL) before it can call from_pretrained on the auto-downloaded model path.","triggerScenarios":"backend='transformers' with transformers not installed, an old version lacking Qwen2VLForConditionalGeneration, or a dependency conflict (tokenizers/numpy ABI) making the import raise.","commonSituations":"Minimal install chosen to avoid heavy GPU deps; transformers pinned <4.x by another app in the same env; broken env after partial pip upgrades.","solutions":["pip install transformers (>= the version supporting Qwen2-VL, e.g. 4.37+; note the code adapts dtype kwarg for >=4.56).","If already installed, run python -c \"from transformers import Qwen2VLForConditionalGeneration\" to surface the real underlying error and fix that dep.","Consider a dedicated virtualenv/uv env for MinerU to avoid version conflicts."],"exampleFix":"# before\nrun(backend=\"transformers\", ...)  # ImportError\n\n# after\npip install \"transformers>=4.51\"\nrun(backend=\"transformers\", ...)","handlingStrategy":"validation","validationCode":"def transformers_backend_available() -> bool:\n    try:\n        from transformers import AutoProcessor, Qwen2VLForConditionalGeneration  # noqa\n        return True\n    except ImportError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    vlm_analyze(..., backend=\"transformers\")\nexcept ImportError as e:\n    if \"install transformers\" in str(e):\n        subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"transformers\"])\n        vlm_analyze(..., backend=\"transformers\")  # retry once\n    else:\n        raise","preventionTips":["Use the documented MinerU install extras for the backend you plan to use.","Pin transformers (and its tokenizers) versions in lockfiles.","Isolate MinerU in its own virtualenv to avoid cross-app conflicts."],"tags":["transformers","dependency","import","vlm","backend"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}