BUG: task=parse rejects a 31-page A4 PDF at every zoomin, and lowering zoomin makes it worse

[OliverBryant]

Describe the bug

task="parse" rejects a 31-page A4 PDF at every zoomin value from 1 to 6, so the document cannot be parsed at all. The error tells the caller to lower zoomin, but doing so makes the computed budget larger, not smaller.

The document is an ordinary text PDF: 31 A4 pages, 393 KB. At zoomin=3 it actually rasterizes to about 140 MP — well under the 1 GP whole-document budget. It is rejected because the budget is enforced against a worst case that overstates real usage by 10x.

To Reproduce

curl -X POST http://<host>:<port>/v1/images/ocr \
  -H "Authorization: Bearer $TOKEN" \
  -F model=DeepDoc \
  -F 'image=@thesis-31-pages.pdf;type=application/pdf' \
  -F 'kwargs={"task":"parse","zoomin":3}'

{"detail": "The uploaded PDF would rasterize to more than 1037049300 pixels in total at zoomin 3 (the parser re-renders at up to 9x when a page yields no text), exceeding the whole-document limit of 1000000000; lower `zoomin` or split the document"}

Following the advice and lowering zoomin reports a bigger number:

zoomin	worst-case scale	reported total	rejected
3	9	1,037,049,300	yes
2	18	1,082,138,400	yes
1	9	1,037,049,300	yes

Why lowering zoomin does not help

worst_case_parse_zoom in xinference/api/pdf_ocr.py triples the scale until it reaches the limit:

def worst_case_parse_zoom(zoomin: int) -> int:
    scale = zoomin
    while scale < PDF_PARSE_RETRY_ZOOM_LIMIT:   # 9
        scale *= PDF_PARSE_RETRY_ZOOM_FACTOR    # 3
    return scale

The loop exits on scale >= 9, so it overshoots whenever zoomin is not a power-of-three divisor of 9:

zoomin	escalation chain	worst-case scale
1	1 → 3 → 9	9
2	2 → 6 → 18	18
3	3 → 9	9
4	4 → 12	12
5	5 → 15	15
6	6 → 18	18

So zoomin=2 is budgeted at 4x the pixels of zoomin=3, and no value in 1..6 admits a 31-page A4 document:

zoomin	worst-case scale	peak per A4 page	31 pages	over 1 GP
1	9	45.1 MP	1.398 GP	yes
2	18	180.4 MP	5.591 GP	yes
3	9	45.1 MP	1.398 GP	yes
4	12	80.2 MP	2.485 GP	yes
5	15	125.2 MP	3.883 GP	yes
6	18	180.4 MP	5.591 GP	yes

There is a second, larger question behind the arithmetic. The 9x retry only fires for a page that yields no text at all, which for a text PDF essentially never happens, yet every page is budgeted as if it will. At zoomin=3 an A4 page really renders at 4.5 MP but is budgeted at 45.1 MP, so the ceiling lands at 22 A4 pages where actual usage would allow ~221:

Page size	max pages at zoomin=3 (worst case)	max pages by actual render
A4	22	221
A3	11	110
Letter	22	229

A 22-page cap on the default settings is restrictive for the documents this feature targets — theses, reports, papers.

Suggested fixes

Two separate things, either useful on its own:

1. Make the advice in the error message true, or change the advice. I checked deepdoc-lib before assuming the budget was wrong here, and it is not:

   # deepdoc/parser/pdf_parser.py, __images__
   if len(self.boxes) == 0 and zoomin < 9:
       self.__images__(fnm, zoomin * 3, page_from, page_to, callback)

   The guard is on the pre-multiplication value, so a run started at 2 really does reach 18. worst_case_parse_zoom faithfully models that. The bug is therefore not the calculation but the recommendation: "lower zoomin" is not sound advice when the retry ladder is non-monotonic in zoomin.

   Either clamp upstream so the ladder never exceeds 9 (min(zoomin * 3, 9), which also caps the real allocation and would be a fix in deepdoc-lib), or keep the budget as is and stop advising a knob that can make things worse — e.g. name the largest zoomin that would fit, or just say to split the document.

2. Don't budget every page for a retry that is conditional. Options, roughly in order of how invasive they are: validate against the requested scale and let the retry path re-validate if it triggers; keep the worst case per page (where it guards a single large MediaBox) but budget the document at the requested scale; or make the whole-document ceiling configurable so deployments with headroom can raise it.

Happy to send a PR for (1) if the clamp is the wanted direction.

Context

Found while adding remote DeepDoc parsing to xagent (xorbitsai/xagent#1161, client in xorbitsai/xagent#1271). The client behaves correctly — the 400 is treated as a remote failure and it falls back to local CPU parsing — so this is not a correctness problem downstream, but it does mean documents above ~22 A4 pages silently never get the GPU speedup they configured.

For reference, on the first 15 pages of the same document (which does pass), remote GPU parsing took 14.45s against 23.42s for local CPU, a 1.6x speedup, with full-text agreement of 99.993% between the two.

Environment

• xinference e45894915 (feat(ocr): expose DeepDoc's document-parsing pipeline as task="parse" #5299 merged)
• Python 3.12.13, CUDA, RTX 3090 Ti
• deepdoc-lib 0.2.2, model files from ModelScope Xorbits/deepdoc
• Document: 31 A4 pages (595x842 pt), 393 KB, text-based

[OliverBryant]

The batching this budget was waiting for now exists upstream

The comment above MAX_PDF_PARSE_TOTAL_PIXELS anticipates the fix:

pages-style batching in deepdoc-lib would lift it properly.

That batching has landed on xorbitsai/deepdoc-lib HEAD. parse_into_bboxes now renders one window at a time:

def parse_into_bboxes(self, fnm, callback=None, zoomin=3, from_page=0, to_page=MAXIMUM_PAGE_NUMBER):
    batch_size = max(1, int(os.getenv("PDF_PARSER_PAGE_BATCH_SIZE", "50")))
    ...
    for page_from in range(from_page, effective_to_page, batch_size):
        page_to = min(page_from + batch_size, effective_to_page)
        self.__images__(fnm, zoomin, page_from=page_from, page_to=page_to, callback=None)
        chunk_boxes = self._parse_loaded_window_into_bboxes(zoomin)
        all_boxes.extend(self._to_global_boxes(chunk_boxes))

Peak memory is now one window, not the whole document, and _to_global_boxes stitches the coordinates back.

Verified on the reported document

The 31-page A4 PDF from the report, parsed with HEAD against the same model files on an RTX 3090 Ti:

batch size	result	wall time
50 (default, no batching for 31 pages)	1762 elements	31.87s
10 (forced, 4 windows)	1765 elements	31.58s

It parses. Same element counts either way, same speed, so the windowing carries no measurable overhead. (The 1762 vs 1765 delta is the KMeans column-assignment nondeterminism, which reproduces run-to-run on a single version.)

What this changes, and what it does not

Does change: the memory argument behind the 1 GP whole-document ceiling. With windowing, a 31-page document never holds 31 pages of bitmaps at once, so budgeting it as though it does is what makes the rejection spurious.

Does not change: the non-monotonic retry ladder. HEAD still has the same guard, so zoomin=2 still escalates to 18:

if len(self.boxes) == 0 and zoomin < 9:
    self.__images__(fnm, zoomin * 3, page_from, page_to, callback)

So "lower zoomin" remains unsound advice regardless of which deepdoc-lib version is installed. Both halves of this issue still need addressing; upgrading only addresses the first.

Blocker: the batching is not released

PyPI's newest deepdoc-lib is still 0.2.2 (2026-06-26); the batching is only on git HEAD (pushed 2026-07-24). Both consumers pin to it:

• xinference/model/image/model_spec.json: deepdoc-lib[gpu]~=0.2.2 ; has_cuda
• xagent pyproject.toml: deepdoc-lib==0.2.2

Note ~=0.2.2 would not pick up a 0.3.x either, so a release alone will not propagate it.

Suggested sequence

1. Cut a deepdoc-lib release containing the batching.
2. Bump the spec constraint, and surface PDF_PARSER_PAGE_BATCH_SIZE so the server can size windows to its worker memory.
3. Budget the document at one window rather than the whole file — that is what actually lifts the ~22-page ceiling.
4. Separately, fix the retry-ladder advice (see the original report).

Happy to send the server-side PR for 2-4 once a release exists.