{"record":{"id":"0e132ddfaafe74f5","repo":"docling-project/docling","slug":"rednote-hilab-dots-mocr-requires-flash-attn-with-t-0e132d","errorCode":null,"errorMessage":"rednote-hilab/dots.mocr requires flash-attn with the Transformers engine. Install flash-attn in the transformers-v4 environment before using this model.","messagePattern":"rednote-hilab/dots\\.mocr requires flash-attn with the Transformers engine\\. Install flash-attn in the transformers-v4 environment before using this model\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/hf_transformers_model.py","lineNumber":44,"sourceCode":"from docling.models.utils.generation_utils import GenerationStopper\nfrom docling.models.utils.hf_model_download import (\n    HuggingFaceModelDownloadMixin,\n)\nfrom docling.models.utils.hf_stopping_criteria import HFStoppingCriteriaWrapper\nfrom docling.utils.accelerator_utils import decide_device\nfrom docling.utils.profiling import TimeRecorder\n\n_log = logging.getLogger(__name__)\n\n_DOTS_REPO_IDS = {\"rednote-hilab/dots.ocr\", \"rednote-hilab/dots.mocr\"}\n_DOTS_FLASH_ATTN_REQUIRED_REPO_IDS = {\"rednote-hilab/dots.mocr\"}\n\n\ndef _ensure_dots_flash_attn_import() -> None:\n    try:\n        importlib.import_module(\"flash_attn\")\n    except ImportError as exc:\n        raise ImportError(\n            \"rednote-hilab/dots.mocr requires flash-attn with the Transformers \"\n            \"engine. Install flash-attn in the transformers-v4 environment \"\n            \"before using this model.\"\n        ) from exc\n\n\nclass HuggingFaceTransformersVlmModel(BaseVlmPageModel, HuggingFaceModelDownloadMixin):\n    def __init__(\n        self,\n        enabled: bool,\n        artifacts_path: Path | None,\n        accelerator_options: AcceleratorOptions,\n        vlm_options: InlineVlmOptions,\n    ):\n        self.enabled = enabled\n\n        self.vlm_options = vlm_options\n","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/hf_transformers_model.py#L26-L62","documentation":"The rednote-hilab/dots.mocr model requires flash-attention kernels with the Transformers engine; Docling probes for the flash_attn module at model construction and raises ImportError (chained from the real ImportError) when it is absent. This check only fires for dots.mocr — plain dots.ocr does not require it.","triggerScenarios":"Setting VlmOptions repo_id='rednote-hilab/dots.mocr' with the Transformers engine in an environment where flash_attn is not installed (it is not a default docling dependency and often needs matching CUDA/torch versions).","commonSituations":"Using docling in the recommended transformers-v4 environment but flash-attn was never built there; upgrading torch so the previously compiled flash-attn wheel no longer imports; CPU-only environments where flash-attn is impractical.","solutions":["Install a flash-attn wheel matching your torch/CUDA version in the transformers-v4 environment: pip install flash-attn --no-build-isolation (or use a prebuilt wheel)","If you cannot install flash-attn, switch repo_id to rednote-hilab/dots.ocr which has no such requirement","Alternatively drive dots.mocr through the vLLM engine, which manages its own attention backend"],"exampleFix":"# before\nvlm_options.repo_id = \"rednote-hilab/dots.mocr\"  # ImportError: needs flash_attn\n# after (option 1)\n# pip install flash-attn --no-build-isolation\n# after (option 2)\nvlm_options.repo_id = \"rednote-hilab/dots.ocr\"","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif vlm_options.repo_id == 'rednote-hilab/dots.mocr':\n    if importlib.util.find_spec('flash_attn') is None:\n        raise ImportError('dots.mocr needs flash-attn; install it or use dots.ocr')","typeGuard":null,"tryCatchPattern":"try:\n    model = HuggingFaceTransformersVlmModel(...)\nexcept ImportError as e:\n    if 'flash-attn' in str(e):\n        vlm_options.repo_id = 'rednote-hilab/dots.ocr'\n        model = HuggingFaceTransformersVlmModel(...)\n    else:\n        raise","preventionTips":["Pin torch and install a matching flash-attn wheel when provisioning the transformers-v4 env","Probe importlib.util.find_spec('flash_attn') at app startup before model selection","Document per-model extras (dots.mocr -> flash-attn) next to your model registry"],"tags":["dependencies","flash-attn","dots-mocr","transformers","import-error"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}