# Integrating MinerU PDF Parsing

> Use MinerU to parse PDF documents with image extraction, layout recognition, table recognition, and formula recognition

Source: https://doc.fastgpt.io/self-host/custom-models/mineru
Last Updated: 2026-11-12

## Background

PDF is a relatively complex file format. FastGPT's built-in PDF parser relies on the pdfjs library, which uses logical parsing and cannot effectively handle complex PDF files. When parsing PDFs containing images, tables, formulas, or other non-plain-text content, the results are often poor.

There are several PDF parsing solutions available. [MinerU](https://github.com/opendatalab/MinerU) uses YOLO, PaddleOCR, and table recognition models for vision-based parsing, effectively extracting images, tables, formulas, and other complex content.

Community edition users can set the `CUSTOM_PDF_PARSE_URL` and `CUSTOM_PDF_PARSE_KEY` environment variables to use MinerU for PDF parsing (starting with 4.15.0, the open-source edition reads these settings from environment variables). Commercial edition users can configure this in **Admin → System Configuration → Basic Configuration → PDF Parsing Configuration** -- details are covered in the tutorial below.

## Tutorial

Hardware requirements: 16GB+ GPU VRAM, minimum 16GB+ RAM (32GB+ recommended). See the [official page](https://github.com/opendatalab/MinerU) for other requirements.

### 1. Install MinerU

Quick Docker installation:

Pull the fastgpt-mineru image --> Create and start the parsing service container --> Set the deployed URL in the `CUSTOM_PDF_PARSE_URL` environment variable of `fastgpt-app`

```bash
docker pull crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/fastgpt_ck/mineru:v1
docker run --gpus all -itd -p 7231:8001 --name mode_pdf_minerU crpi-h3snc261q1dosroc.cn-hangzhou.personal.cr.aliyuncs.com/fastgpt_ck/mineru:v1
```

This MinerU integration uses pipeline mode with built-in parallelization inside the Docker container. It creates multiple processes based on the number of GPUs to handle uploaded PDFs concurrently.

### 2. Add FastGPT Configuration

Add these environment variables to `fastgpt-app`:

```dotenv
CUSTOM_PDF_PARSE_URL=http://<gpu-server-ip>:7231/v2/parse/file # Custom PDF parsing service URL for MinerU
CUSTOM_PDF_PARSE_KEY= # Custom PDF parsing service key
DOC2X_KEY= # doc2x service key (optional)
```

See [Environment Variables](https://doc.fastgpt.io/self-host/config/env#enhanced-pdf-parsing) for details.

For the commercial edition, open **Admin → System Configuration → Basic Configuration → PDF Parsing Configuration**. Enter your deployed MinerU URL, including `/v2/parse/file`, in the custom PDF parsing URL field. Enter the parsing service key if configured, then click **Save**.

![2. Add FastGPT Configuration — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/oxr/admin-pdf-config.png)

**Note:** Services added via environment variables require a restart to take effect.

### 3. Test

Upload a PDF file through the Dataset and enable the `Enhanced PDF Parsing` option.

![3. Test — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru1.png.webp)

After uploading, you should see the following logs (`LOG_CONSOLE_LEVEL` must be set to info or debug):

```
Start parsing file via external service
External file parsing completed
```

Similarly, in apps you can enable `Enhanced PDF Parsing` in the file upload settings.

![3. Test — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru2.png.webp)

## Results

Using Tsinghua's [ChatDev Communicative Agents for Software Develop.pdf](https://arxiv.org/abs/2307.07924) as an example:

|                                                                                                                   |                                                                                                                   |                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| ![Results — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru3-1.png.webp) | ![Results — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru4-1.png.webp) | ![Results — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru5-1.png.webp) |
| ![Results — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru3.png.webp)   | ![Results — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru4.png.webp)   | ![Results — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/mineru5.png.webp)   |

The top row shows chunked results; the bottom row shows the original PDF. Images, formulas, and OCR handwriting are all extracted effectively.

Note that [MinerU](https://github.com/opendatalab/MinerU) is licensed under `GPL-3.0 license`. Please ensure compliance with the license when using it.
