Add PaddleOCR-VL external parser support#3376
Open
ouyangfeng2022 wants to merge 15 commits into
Open
Conversation
added 15 commits
July 8, 2026 10:45
- Add PaddleOCR-VL external parser implementation - Update environment configuration with PaddleOCR related settings - Add PaddleOCR-VL to parser registry - Add tests for PaddleOCR-VL parser - Update documentation for FileProcessingPipeline
…oise - Add _nearest_neighbor helper to skip over page numbers/headers/footers when matching figure/table titles to their media elements - Improve caption heuristic with Chinese prefix recognition (表, 图, etc.) - Fix missing default values for show_formula_number, prettify_markdown, visualize - Change USE_OCR_FOR_IMAGE_BLOCK default to False - Refactor _coerce_text → _item_content and improve _item_label - Use regex for bbox parsing from image paths - Add docstrings and type improvements - Add comprehensive tests for caption matching logic
…ions - Split PaddleOCRVLParserOptions into nested DocParsingOptions for optionalPayload - Add generic _build_payload helper using dataclass fields - Add new options: merge_layout_blocks, format_block_content, vlm_extra_args - Change DEFAULT_PADDLEOCR_VL_API_MODE from 'local' to 'official' - Support PADDLEOCR_VL_ENDPOINT fallback for official endpoint - Reorder fields in DocParsingOptions for logical grouping - Update client to use nested optional_payload in request_payload
- Merge _coerce_* functions into a single generic _coerce_value - Add _resolve_option and _override_env helpers for consistent override/env handling - Simplify DocParsingOptions and PaddleOCRVLParserOptions construction - Add tests for None rejection and type coercion behavior
- Remove 20+ DEFAULT_* constants that are only used internally within DocParsingOptions.from_env() - Remove test-only helpers (current_endpoint_signature, current_options_signature, current_engine_version, snapshot_tunable_env) - Only 8 items remain in __all__, all actually used by production code - Update tests to access internal helpers via module object
…on and streamline endpoint handling
…add new parsing parameters
…ntation in env.example and processing pipeline
… and add IR validation method
- Added detailed instructions for using the PaddleOCR-VL file parsing engine in FileProcessingPipeline.md, including configuration for both official and local modes, deployment options, and troubleshooting tips. - Updated ParserDebugCLI-zh.md and ParserDebugCLI.md to include PaddleOCR-VL as a supported engine, with relevant command-line options and output directory structure. - Revised ThirdPartyParser-zh.md and ThirdPartyParser.md to reflect the inclusion of PaddleOCR-VL in the list of built-in engines and provided guidance for third-party parser development.
…ngs, and validation logic
… cache and client tests
Collaborator
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f0dedc49e9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
512
to
+514
| if spec.is_list and spec.canonical == "page_range": | ||
| segments = [p.strip() for p in value.split(",")] | ||
| seg_errors = _validate_page_range_segments(segments) | ||
| seg_errors = _validate_page_range_segments(engine, segments) |
There was a problem hiding this comment.
When a user supplies a per-file PaddleOCR-VL hint such as paddleocr_vl(page_range=2--2), this routes the value through the shared page-range validator that only accepts N or N-M, so ingestion rejects it before the request is sent. The PaddleOCR async API docs for pageRanges explicitly document "2--2" as a valid range meaning page 2 through the second-to-last page (https://ai.baidu.com/ai-doc/AISTUDIO/Mml7n69e7), and the env path can still pass it through unvalidated, so this only breaks the new per-file/rule override path for a supported PaddleOCR syntax.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This pull request adds PaddleOCR-VL as a first-class external parser engine for LightRAG. It wires the parser into the registry and pipeline configuration, implements the official API client/cache layer, converts PaddleOCR-VL layout results into the sidecar IR model, and documents configuration and debugging usage.
Related Issues
No linked issue.
Changes Made
paddleocr_vlexternal parser package with cache option normalization, official API client support, parser adapter, and sidecar IR builder.optionalPayloadhandling, environment configuration, and per-file hint validation.env.exampleconfiguration.Checklist
Additional Notes
Local verification completed:
uv run pytest tests/parser/external/paddleocr_vl tests/parser/test_registry.py tests/parser/test_engine_params.py tests/parser/external/test_engine_param_thread.py -q(85 passed, 1 skipped)uv run ruff check .(All checks passed!)git diff --check