{"record":{"id":"2ae7084a1fc0c754","repo":"opendatalab/MinerU","slug":"effort-must-be-medium-or-high","errorCode":null,"errorMessage":"effort must be \"medium\" or \"high\"","messagePattern":"effort must be \"medium\" or \"high\"","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mineru/backend/hybrid/hybrid_analyze.py","lineNumber":113,"sourceCode":"    \"number\": BlockType.PAGE_NUMBER,\n    \"paragraph_title\": BlockType.TITLE,\n    \"reference_content\": BlockType.REF_TEXT,\n    \"text\": BlockType.TEXT,\n    \"vertical_text\": BlockType.TEXT,\n    \"figure_title\": BlockType.IMAGE_CAPTION,\n    \"vision_footnote\": BlockType.IMAGE_FOOTNOTE,\n    \"image\": BlockType.IMAGE,\n    \"chart\": BlockType.CHART,\n    \"seal\": BlockType.IMAGE,\n    \"table\": BlockType.TABLE,\n    \"display_formula\": BlockType.EQUATION,\n}\n\n\ndef _validate_parse_effort(effort: str = \"medium\") -> str:\n    \"\"\"校验 Hybrid effort，避免静默走错解析强度分支。\"\"\"\n    if effort not in HYBRID_ANALYZE_EFFORTS:\n        raise ValueError('effort must be \"medium\" or \"high\"')\n    return effort\n\n\ndef _resolve_effective_image_analysis(effort: str, image_analysis: bool) -> bool:\n    \"\"\"根据 Hybrid 解析强度计算实际图片分析开关；medium 强制关闭以保持快速路径。\"\"\"\n    if effort == \"medium\":\n        return False\n    return image_analysis\n\n\ndef _vlm_type_for_medium_layout_label(label: str | None) -> str | None:\n    \"\"\"将 pipeline layout 标签映射为 mineru-vl-utils 支持的 VLM 抽取类型。\"\"\"\n    return MEDIUM_EFFORT_LAYOUT_LABEL_TO_VLM_TYPE.get(label)\n\n\ndef _apply_medium_visual_sub_type(block, label: str | None):\n    \"\"\"为视觉块补充下游需要透传的子类型。\"\"\"\n    if label == \"seal\":","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/hybrid/hybrid_analyze.py#L95-L131","documentation":"Raised by _validate_parse_effort() in the Hybrid backend when the effort argument is not in HYBRID_ANALYZE_EFFORTS (only \"medium\" and \"high\"). The validation exists to prevent silently falling into the wrong analysis-strength branch; anything other than the two allowed strings aborts immediately.","triggerScenarios":"Calling hybrid analysis with effort=\"low\", effort=\"\", or a future/unrecognized value; passing None; passing uppercase \"HIGH\" (values are case-sensitive).","commonSituations":"Porting configs from other APIs where effort=\"low\" is valid (e.g. OpenAI-style effort levels); typos; sharing config files across backend versions.","solutions":["Set effort to \"medium\" (fast path, image analysis forced off) or \"high\".","Check HYBRID_ANALYZE_EFFORTS in mineru/backend/hybrid/hybrid_analyze.py for the authoritative allowed set in your version.","Validate/normalize user-supplied effort at your config boundary (lowercase, membership check)."],"exampleFix":"# before\nresult = hybrid_analyze(pdf, effort=\"low\")\n\n# after\nresult = hybrid_analyze(pdf, effort=\"high\")","handlingStrategy":"validation","validationCode":"from mineru.backend.hybrid.hybrid_analyze import HYBRID_ANALYZE_EFFORTS\n\ndef normalize_effort(effort: str) -> str:\n    effort = (effort or \"medium\").strip().lower()\n    if effort not in HYBRID_ANALYZE_EFFORTS:\n        raise ValueError(f\"effort must be one of {sorted(HYBRID_ANALYZE_EFFORTS)}\")\n    return effort","typeGuard":"from mineru.backend.hybrid.hybrid_analyze import HYBRID_ANALYZE_EFFORTS\n\ndef is_valid_effort(value: object) -> bool:\n    return isinstance(value, str) and value in HYBRID_ANALYZE_EFFORTS","tryCatchPattern":"try:\n    vlm_analyze(..., effort=effort)\nexcept ValueError as e:\n    if 'effort must be' in str(e):\n        vlm_analyze(..., effort=\"medium\")  # explicit fallback to default\n    else:\n        raise","preventionTips":["Whitelist effort at your config boundary using the library's own constant.","Don't reuse effort vocabularies from other APIs (\"low\" is invalid here).","Document that only \"medium\" and \"high\" exist for the Hybrid backend."],"tags":["hybrid","validation","configuration","effort"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}