{"record":{"id":"112060e7b09dc599","repo":"PaddlePaddle/PaddleOCR","slug":"paddleocr-vl-models-require-paddleocrvloptions","errorCode":null,"errorMessage":"PaddleOCR-VL models require PaddleOCRVLOptions.","messagePattern":"PaddleOCR-VL models require PaddleOCRVLOptions\\.","errorType":"validation","errorClass":"InvalidRequestError","httpStatus":null,"severity":"error","filePath":"paddleocr/_api_client/_core.py","lineNumber":83,"sourceCode":"def resolve_model(model: Union[Model, str]) -> Model:\n    if isinstance(model, Model):\n        return model\n    try:\n        return Model(model)\n    except ValueError as e:\n        raise InvalidRequestError(f\"Unsupported model: {model}\") from e\n\n\ndef resolve_document_options(\n    model: Model, options: Optional[DocParsingOptions]\n) -> DocParsingOptions:\n    if options is not None:\n        if model == Model.PP_STRUCTURE_V3 and not isinstance(\n            options, PPStructureV3Options\n        ):\n            raise InvalidRequestError(\"PP-StructureV3 requires PPStructureV3Options.\")\n        if is_vl_model(model) and not isinstance(options, PaddleOCRVLOptions):\n            raise InvalidRequestError(\"PaddleOCR-VL models require PaddleOCRVLOptions.\")\n        return options\n    if model == Model.PP_STRUCTURE_V3:\n        return PPStructureV3Options()\n    return PaddleOCRVLOptions()\n\n\ndef job_id_for_task(job: Union[Job, str], task: str) -> str:\n    if isinstance(job, str):\n        return job\n    if job.task != task:\n        raise InvalidRequestError(\n            f\"Job task mismatch: expected {task}, got {job.task}.\"\n        )\n    if task == \"ocr\" and not is_ocr_model(job.model):\n        raise InvalidRequestError(f\"Job model is not an OCR model: {job.model}.\")\n    if task == \"document_parsing\" and not is_document_parsing_model(job.model):\n        raise InvalidRequestError(\n            f\"Job model is not a document parsing model: {job.model}.\"","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr/_api_client/_core.py#L65-L101","documentation":"Raised as InvalidRequestError by resolve_document_options() when the model is a PaddleOCR-VL model but options is not a PaddleOCRVLOptions instance. VL models only accept their own options type; passing PPStructureV3Options or a bare DocParsingOptions is rejected before the request is built.","triggerScenarios":"Calling document parsing with a VL model (per is_vl_model) and options=PPStructureV3Options() or another DocParsingOptions subclass.","commonSituations":"Reusing PP-StructureV3 options when switching to a VL model, or constructing a generic options object because the VL-specific class was not discovered.","solutions":["Use PaddleOCRVLOptions() with VL models.","Or pass options=None and let the default PaddleOCRVLOptions() be applied.","Add an assertion or helper mapping model -> options class."],"exampleFix":"# before\njob = client.parse_document(file_path=\"a.pdf\", model=\"PaddleOCR-VL\", options=PPStructureV3Options())\n\n# after\nfrom paddleocr._api_client.options import PaddleOCRVLOptions\njob = client.parse_document(file_path=\"a.pdf\", model=\"PaddleOCR-VL\", options=PaddleOCRVLOptions())","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"from paddleocr._api_client.models import is_vl_model\nfrom paddleocr._api_client.options import PaddleOCRVLOptions\n\ndef vl_options_ok(model, options) -> bool:\n    return not is_vl_model(model) or isinstance(options, PaddleOCRVLOptions)","tryCatchPattern":null,"preventionTips":["Construct options via a helper keyed by model so the class always matches.","When switching models in config, switch the options class in the same change."],"tags":["validation","options","model","client-side"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}