# How to Deploy MinerU for Production Integration: Complete Setup Guide

> Deploy MinerU for production integration. Set up using Docker, FastAPI, OpenAI-compatible server, or Gradio to expose REST endpoints for document processing and retrieval.

- Repository: [OpenDataLab/MinerU](https://github.com/opendatalab/mineru)
- Tags: how-to-guide
- Published: 2026-02-23

---

**You can deploy MinerU as a Docker container, standalone FastAPI service, OpenAI-compatible server, or Gradio UI, exposing REST endpoints at `/api/v1/tasks/submit` for document processing and retrieval.**

MinerU is a modular document-parsing platform maintained by the **opendatalab/MinerU** repository. When you **deploy MinerU** for integration with other applications, you gain access to programmable HTTP endpoints that convert PDFs and images into structured Markdown via a scalable, GPU-accelerated backend architecture.

## Understanding the MinerU Deployment Architecture

The platform separates concerns across three distinct layers defined in the source code.

### CLI Entry Points

The `mineru` command-line interface defined in [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py) provides four primary entry points: `mineru` (pipeline), `mineru-api`, `mineru-openai-server`, and `mineru-gradio`. These scripts parse environment variables and configuration files before launching the appropriate backend service.

### Backend Inference Engines

The system supports multiple inference backends through [`mineru/cli/vlm_server.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/vlm_server.py), which automatically selects between **VLLM** and **LMDeploy** engines. This layer exposes a `/v1/chat/completions` compatible endpoint when operating in OpenAI server mode, enabling integration with standard LLM client libraries.

### FastAPI Service Layer

The production HTTP interface lives in [`projects/mineru_tianshu/api_server.py`](https://github.com/opendatalab/MinerU/blob/main/projects/mineru_tianshu/api_server.py). This FastAPI application handles task submission, status polling via a SQLite database (`TaskDB` in [`task_db.py`](https://github.com/opendatalab/MinerU/blob/main/task_db.py)), and optional MinIO image storage for extracted assets.

## Four Methods to Deploy MinerU

### Docker Compose Deployment (Recommended)

For production environments requiring resource isolation, use the pre-configured [`docker/compose.yaml`](https://github.com/opendatalab/MinerU/blob/main/docker/compose.yaml). The configuration mounts GPU devices via the NVIDIA Container Toolkit and exposes port 8000 for the REST API.

```yaml

# docker/compose.yaml

services:
  mineru-api:
    image: mineru:latest               # Build locally or pull from a registry

    container_name: mineru-api
    restart: always
    ports:
      - 8000:8000                      # FastAPI REST interface

    environment:
      MINERU_MODEL_SOURCE: local       # Use local model files (or "modelscope")

    entrypoint: mineru-api
    command:
      --host 0.0.0.0
      --port 8000
    ulimits:
      memlock: -1
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]        # Adjust for multi‑GPU

              capabilities: [gpu]

```

Run the deployment:

```bash
docker compose -f docker/compose.yaml --profile api up -d

```

The API will be reachable at `http://localhost:8000/docs` (FastAPI Swagger UI).

### Standalone FastAPI Server

Run `mineru-api` directly on the host machine for development or lightweight deployments. The CLI invokes `uvicorn.run(app, ...)` binding to `0.0.0.0:8000` without container overhead.

### OpenAI-Compatible Server Mode

Execute `mineru-openai-server` to launch a VLLM or LMDeploy backend that mimics the OpenAI chat completions API. This mode enables drop-in replacement for existing LLM clients.

```bash

# Install optional VLLM dependency

uv pip install "mineru[all]" vllm

# Start the OpenAI‑compatible endpoint on port 30000

mineru-openai-server --host 0.0.0.0 --port 30000

```

### Gradio Web Interface

Launch `mineru-gradio` to start a web UI on port 7860. This frontend internally calls the same backend APIs, providing a visual interface for document processing.

```bash
mineru-gradio --server-name 0.0.0.0 --server-port 7860

```

Open `http://localhost:7860` in a browser to access the interface.

## Configuring Your MinerU Deployment

All deployment modes respect environment variables prefixed with `MINERU_`, such as `MINERU_MODEL_SOURCE`, `MINERU_BACKEND`, and `MINERU_DEVICE`. The system also reads from a user-level [`mineru.json`](https://github.com/opendatalab/MinerU/blob/main/mineru.json) configuration file generated by `mineru-models-download` or copied from [`mineru.template.json`](https://github.com/opendatalab/MinerU/blob/main/mineru.template.json).

## Integrating Applications with the MinerU API

The typical integration flow involves submitting documents to `/api/v1/tasks/submit`, polling `/api/v1/tasks/{task_id}` for completion, and fetching results from `/api/v1/tasks/{task_id}/data`.

```python
import requests

api_url = "http://localhost:8000/api/v1/tasks/submit"
pdf_path = "sample.pdf"

files = {"file": open(pdf_path, "rb")}
data = {
    "backend": "pipeline",
    "lang": "en",
    "method": "auto",
    "formula_enable": "true",
    "table_enable": "true",
    "priority": 10,
}

r = requests.post(api_url, files=files, data=data)
task = r.json()
task_id = task["task_id"]
print(f"Submitted, task_id={task_id}")

# Poll until completed

import time
while True:
    status = requests.get(f"http://localhost:8000/api/v1/tasks/{task_id}").json()
    if status["status"] == "completed":
        break
    time.sleep(2)

# Fetch full result (markdown + images)

result = requests.get(
    f"http://localhost:8000/api/v1/tasks/{task_id}/data",
    params={"include_fields": "md,images", "upload_images": "true"},
).json()
print(result["data"]["markdown"]["content"])

```

Set `upload_images=true` to store extracted images in MinIO and receive public URLs in the response.

## Deploying the OpenAI-Compatible Endpoint

To integrate with LangChain or existing OpenAI SDK clients, start the compatible server and point your client to the local endpoint.

```python
from langchain.llms import OpenAI

# Point to the local server

llm = OpenAI(model_name="gpt-4o-mini", openai_api_base="http://localhost:30000/v1")
response = llm.invoke("请把以下 PDF 内容转成 markdown：<PDF_URL>")
print(response)

```

## Summary

- **Deploy MinerU** via Docker Compose for production isolation or run `mineru-api` directly for development environments
- Configure deployments using `MINERU_` environment variables and the [`mineru.json`](https://github.com/opendatalab/MinerU/blob/main/mineru.json) file located in the user directory
- Use the FastAPI endpoints at `/api/v1/tasks/submit` for asynchronous document processing with SQLite-backed task tracking
- Enable OpenAI-compatible mode for seamless integration with LangChain and existing LLM frameworks
- Store extracted images in MinIO by setting `upload_images=true` in API requests to offload asset storage

## Frequently Asked Questions

### What are the hardware requirements for deploying MinerU?

MinerU requires GPU acceleration for optimal performance, with support for NVIDIA GPUs via the CUDA runtime. The Docker Compose configuration uses the `nvidia` driver with device reservations, while CPU-only modes may be available for smaller documents depending on the backend configuration in [`mineru.json`](https://github.com/opendatalab/MinerU/blob/main/mineru.json).

### How do I configure GPU access in Docker deployments?

Modify the `deploy.resources.reservations.devices` section in [`docker/compose.yaml`](https://github.com/opendatalab/MinerU/blob/main/docker/compose.yaml) to specify `driver: nvidia` and the appropriate `device_ids`. Set `capabilities: [gpu]` to enable CUDA access within the container, and adjust `device_ids: ["0"]` to target specific GPUs in multi-GPU systems.

### Can MinerU replace OpenAI endpoints in existing applications?

Yes. Running `mineru-openai-server` creates a compatible endpoint at `/v1/chat/completions` using VLLM or LMDeploy backends as implemented in [`mineru/cli/vlm_server.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/vlm_server.py). You can point any OpenAI SDK or LangChain client to `http://localhost:30000/v1` to process documents through the chat completions interface.

### Where does MinerU store processing results and logs?

The FastAPI server maintains task state in a lightweight SQLite database managed by `TaskDB` in [`task_db.py`](https://github.com/opendatalab/MinerU/blob/main/task_db.py). Results persist locally unless you configure the optional MinIO integration by setting `upload_images=true` during task submission, which stores assets in external object storage. The server also provides an administrative endpoint at `/api/v1/admin/cleanup` for automatic removal of old results.