# MinerU Output Files MinerU writes a document-specific wrapper directory after profiling a PDF, then places the actual run artifacts under a MinerU-native run directory inside that wrapper. Tabulus treats this output as adapter-owned source output: keep it intact, then copy canonical table crops into the normalized Tabulus table-crop handoff. For the Tabulus-facing overview of MinerU itself and the MinerU options exposed through `tabulus profile`, see {doc}`../external-tools/mineru`. A typical MinerU output tree looks like: ```text / └── / ├── images/ ├── _content_list.json ├── _content_list_v2.json ├── _layout.pdf ├── _middle.json ├── _model.json ├── _origin.pdf ├── .md ├── mineru_stdout.log ├── mineru_stderr.log └── tabulus_run.txt ``` The JSON, PDF, Markdown, and `images/` entries are MinerU artifacts. The `mineru_stdout.log`, `mineru_stderr.log`, and `tabulus_run.txt` files are Tabulus diagnostic metadata written beside the successful MinerU output. Downstream Tabulus code locates `*_content_list.json` recursively, so consumers should not hard-code a native run-directory name such as `auto` or `hybrid_auto`. ## Files ### `.md` MinerU's reconstructed Markdown representation of the document. Use it for quick human inspection of the parsed document content and reading order. ### `_layout.pdf` A visual debugging PDF showing detected layout regions on the original pages. Use it to inspect: - whether tables, figures, text blocks, and other elements were detected - whether bounding boxes are plausible - whether reading order looks reasonable This is usually the first file to inspect when PDF profiling fails or table crops look wrong. ### `_content_list.json` A simplified flat list of parsed content elements in reading order. This is the most important MinerU file for the current Tabulus table workflow. Tabulus reads this file, selects entries where `type == "table"`, then resolves each table's `img_path`. A table entry may include: ```json { "type": "table", "img_path": "images/example_table.png", "page_idx": 5, "bbox": [100, 200, 900, 600], "table_caption": ["Table 1. Example caption"], "table_footnote": ["Example footnote"], "table_body": "..." } ``` Relevant fields: | Field | Meaning | Tabulus use | | --- | --- | --- | | `type` | Content element type | Filter for `table`. | | `img_path` | Path to the MinerU-generated table image | Copy into the Tabulus table image output. | | `page_idx` | Zero-based page index | Convert or preserve as page metadata. | | `bbox` | Detected table bounding box | Preserve for traceability and QA. | | `table_caption` | Detected table caption text | Preserve for matching and QA. | | `table_footnote` | Detected table footnote text | Preserve for matching and QA. | | `table_body` | MinerU's structured table reconstruction, often HTML | Compare against table-reconstruction adapter output. | ### `_content_list_v2.json` MinerU's newer structured content representation. Compared with `content_list.json`, this format is more page-oriented and uses a more regular `type` plus `content` structure. Treat it as a candidate future adapter input after the current `content_list.json` workflow is stable. ### `_middle.json` Detailed intermediate parsing output. Use it when lower-level layout information is needed, such as page sizes, preprocessing blocks, paragraph blocks, detected tables and images, lines, spans, discarded blocks, equations, and bounding boxes. For normal downstream table extraction, `content_list.json` is easier to consume. ### `_model.json` Model-level inference results from MinerU. This is mainly useful for debugging raw predictions and should not be the default downstream interface. ### `_origin.pdf` A copy of the original input PDF stored beside the MinerU outputs. ### `images/` Images extracted or generated by MinerU. For table processing, table entries in `content_list.json` point into this directory through `img_path`. In the current clean workflow, Tabulus copies those generated images rather than recropping the PDF from `bbox`. ## Recommended Tabulus Usage The current GPU workflow should treat MinerU as the PDF profiling adapter: ```text PDF | v MinerU | v _content_list.json | v select entries where type == "table" | v read img_path for each table | v copy MinerU table images into the normalized table-crop handoff | v run a table reconstruction adapter on those crops ``` Keep the full MinerU directory so that: - table detection can be inspected in `_layout.pdf` - `table_body` can be compared against table-reconstruction adapter output - low-level parsing problems can be investigated using `_middle.json` - every downstream table image can be traced back to its MinerU table entry ## Profiling Notes When timing MinerU on a GPU server, distinguish first-run setup cost from steady-state document processing cost. The first invocation may include: - model checkpoint download - vLLM engine initialization and model loading - Torch compilation and CUDA graph capture - OCR and layout model downloads - cache warm-up Do not treat that full first-run wall-clock time as the steady-state runtime for later documents. For a controlled benchmark, process the same document a second time after model files and compilation caches are already present. Record at least: - MinerU version - backend - effort setting - document page count - GPU model - number of visible GPUs - model-loading and warm-up time - layout-analysis time - OCR-detection time - OCR-recognition time - total wall-clock time - peak GPU memory if available - number of detected tables Example profiling record from a 53-page GPU run: ```text Document: 53 pages Backend: hybrid-engine Effort: high GPU: 1 x NVIDIA L40S VLM engine: vLLM async engine VLM model: MinerU2.5-Pro-2605-1.2B VLM model memory at load: ~2.16 GiB Available KV-cache memory: ~18.66 GiB Hybrid batch ratio selected automatically: 16 Layout prediction: ~15 s for 53 pages Two-step extraction: ~20 s for 53 pages OCR detection: ~17 s for 1760 regions Page processing: ~7 s for 53 pages OCR recognition: <1 s for 95 recognition items ``` These timings are useful as an orientation point only. They should be reported with hardware, backend, document size, cache state, and model version.