{"record":{"id":"c0ac6693f4d658a9","repo":"opendatalab/MinerU","slug":"mlx-engine-backend-is-only-supported-on-macos-13-5","errorCode":null,"errorMessage":"mlx-engine backend is only supported on macOS 13.5+ with Apple Silicon.","messagePattern":"mlx-engine backend is only supported on macOS 13\\.5\\+ with Apple Silicon\\.","errorType":"exception","errorClass":"EnvironmentError","httpStatus":null,"severity":"error","filePath":"mineru/backend/vlm/vlm_analyze.py","lineNumber":111,"sourceCode":"                        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\":\n                    mlx_supported = is_mac_os_version_supported()\n                    if not mlx_supported:\n                        raise EnvironmentError(\"mlx-engine backend is only supported on macOS 13.5+ with Apple Silicon.\")\n                    from mineru_vl_utils.mlx_compat import load_mlx_model\n                    model, processor = load_mlx_model(model_path)\n                else:\n                    if os.getenv('OMP_NUM_THREADS') is None:\n                        os.environ[\"OMP_NUM_THREADS\"] = \"1\"\n\n                    if backend == \"vllm-engine\":\n                        try:\n                            import vllm\n                        except ImportError:\n                            raise ImportError(\"Please install vllm to use the vllm-engine backend.\")\n\n                        kwargs = mod_kwargs_by_device_type(kwargs, vllm_mode=\"sync_engine\")\n\n                        if \"compilation_config\" in kwargs:\n                            if isinstance(kwargs[\"compilation_config\"], str):\n                                try:\n                                    kwargs[\"compilation_config\"] = json.loads(kwargs[\"compilation_config\"])","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/vlm/vlm_analyze.py#L93-L129","documentation":"Raised on the mlx-engine branch (vlm_analyze.py) when is_mac_os_version_supported() reports the machine is not macOS 13.5+ on Apple Silicon. MLX (and therefore MinerU's mlx-engine backend) only exists on that platform, so the check fails fast before attempting load_mlx_model.","triggerScenarios":"backend='mlx-engine' on Linux/Windows, on an Intel Mac, or on a macOS version older than 13.5.","commonSituations":"Sharing one config across a mixed fleet (Linux server + Mac laptop); CI runners on Linux with a config authored on a Mac; older macOS that cannot run MLX.","solutions":["On Linux/Windows with NVIDIA GPU use vllm-engine or lmdeploy-engine; on Apple Silicon update macOS to >=13.5.","On Intel Macs use the transformers backend (CPU) or an http-client backend to a remote GPU server.","Make backend selection platform-conditional in your launch script."],"exampleFix":"# before (Linux)\nrun(backend=\"mlx-engine\", ...)  # EnvironmentError\n\n# after\nimport platform\nbackend = \"mlx-engine\" if platform.system() == \"Darwin\" else \"vllm-engine\"\nrun(backend=backend, ...)","handlingStrategy":"type-guard","validationCode":"import platform\n\ndef mlx_platform_ok() -> bool:\n    if platform.system() != \"Darwin\":\n        return False\n    return tuple(int(x) for x in platform.mac_ver()[0].split(\".\")[:2]) >= (13, 5)","typeGuard":"import platform\n\ndef can_use_mlx_engine() -> bool:\n    return platform.system() == \"Darwin\" and platform.machine() == \"arm64\"","tryCatchPattern":"try:\n    vlm_analyze(..., backend=\"mlx-engine\")\nexcept EnvironmentError as e:\n    if \"mlx-engine\" in str(e):\n        vlm_analyze(..., backend=\"transformers\")  # portable fallback\n    else:\n        raise","preventionTips":["Choose backend per platform in your launcher: Darwin+arm64 -> mlx-engine, else vllm/transformers.","Keep macOS >= 13.5 on dev machines that use MLX.","Don't bake one backend into shared Docker images used on Linux."],"tags":["mlx","macos","apple-silicon","platform","backend"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}