Merge pull request #3076 from opendatalab/release-2.1.1

Release 2.1.1

.github/workflows/cli.yml

@@ -14,33 +14,37 @@ on:
 jobs:
   cli-test:
     if: github.repository == 'opendatalab/MinerU'
-    runs-on: pdf
+    runs-on: ubuntu-latest
     timeout-minutes: 240
     strategy:
       fail-fast: true
 
     steps:
     - name: PDF cli
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
+        ref: dev
         fetch-depth: 2
 
+    - name: install uv
+      uses: astral-sh/setup-uv@v5
+
     - name: install&test
       run: |
-        source activate mineru
-        conda env list
-        pip show coverage
-        cd $GITHUB_WORKSPACE && sh tests/retry_env.sh
-        # cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
-        # cd $GITHUB_WORKSPACE && coverage run -m pytest tests/unittest/ --cov=magic_pdf/  --cov-report html --cov-report term-missing
-        # cd $GITHUB_WORKSPACE && python tests/get_coverage.py
-        cd $GITHUB_WORKSPACE && pytest -m P0 -s -v tests/test_cli/test_cli_sdk.py
+        uv --version
+        uv venv --python 3.12
+        source .venv/bin/activate
+        uv pip install .[test]
+        cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
+        cd $GITHUB_WORKSPACE && coverage run
+        cd $GITHUB_WORKSPACE && python tests/get_coverage.py
+
 
   notify_to_feishu:
     if: ${{ always() && !cancelled() && contains(needs.*.result, 'failure')}}
     needs: cli-test
-    runs-on: pdf
+    runs-on: ubuntu-latest
     steps:
     - name: notify
       run: |
-        curl -X POST -H "Content-Type: application/json" -d '{"msg_type":"post","content":{"post":{"zh_cn":{"title":"'${{ github.repository }}' GitHubAction Failed","content":[[{"tag":"text","text":""},{"tag":"a","text":"Please click here for details ","href":"https://github.com/'${{ github.repository }}'/actions/runs/'${GITHUB_RUN_ID}'"},{"tag":"at","user_id":"'$USER_ID'"}]]}}}}'  $WEBHOOK_URL
+        curl -X POST -H "Content-Type: application/json" -d '{"msg_type":"post","content":{"post":{"zh_cn":{"title":"'${{ github.repository }}' GitHubAction Failed","content":[[{"tag":"text","text":""},{"tag":"a","text":"Please click here for details ","href":"https://github.com/'${{ github.repository }}'/actions/runs/'${GITHUB_RUN_ID}'"}]]}}}}'  ${{ secrets.FEISHU_WEBHOOK_URL }}

.github/workflows/huigui.yml

@@ -13,49 +13,36 @@ on:
 jobs:
   cli-test:
     if: github.repository == 'opendatalab/MinerU'
-    runs-on: pdf
+    runs-on: ubuntu-latest
     timeout-minutes: 240
     strategy:
       fail-fast: true
 
     steps:
     - name: PDF cli
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
+        ref: dev
         fetch-depth: 2
 
+    - name: install uv
+      uses: astral-sh/setup-uv@v5
+
     - name: install&test
       run: |
-        source activate mineru
-        conda env list
-        pip show coverage
-        cd $GITHUB_WORKSPACE && sh tests/retry_env.sh
-        # cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
-        # cd $GITHUB_WORKSPACE && coverage run -m pytest tests/unittest/ --cov=magic_pdf/  --cov-report html --cov-report term-missing
-        # cd $GITHUB_WORKSPACE && python tests/get_coverage.py
-        cd $GITHUB_WORKSPACE && pytest -s -v tests/test_cli/test_cli_sdk.py
+        uv --version
+        uv venv --python 3.12
+        source .venv/bin/activate
+        uv pip install .[test]
+        cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
+        cd $GITHUB_WORKSPACE && coverage run
+        cd $GITHUB_WORKSPACE && python tests/get_coverage.py
 
   notify_to_feishu:
     if: ${{ always() && !cancelled() && contains(needs.*.result, 'failure')}}
     needs: cli-test
-    runs-on: pdf
+    runs-on: ubuntu-latest
     steps:
-    - name: get_actor
-      run: |
-          metion_list="dt-yy"
-          echo $GITHUB_ACTOR
-          if [[ $GITHUB_ACTOR == "drunkpig" ]]; then
-            metion_list="xuchao"
-          elif [[ $GITHUB_ACTOR == "myhloli" ]]; then
-            metion_list="zhaoxiaomeng"
-          elif [[ $GITHUB_ACTOR == "icecraft" ]]; then
-            metion_list="xurui1"
-          fi
-          echo $metion_list
-          echo "METIONS=$metion_list" >> "$GITHUB_ENV"
-          echo ${{ env.METIONS }}
-
     - name: notify
       run: |
-        #echo ${{ secrets.USER_ID }}
-        curl -X POST -H "Content-Type: application/json" -d '{"msg_type":"post","content":{"post":{"zh_cn":{"title":"'${{ github.repository }}' GitHubAction Failed","content":[[{"tag":"text","text":""},{"tag":"a","text":"Please click here for details ","href":"https://github.com/'${{ github.repository }}'/actions/runs/'${GITHUB_RUN_ID}'"},{"tag":"at","user_id":"'$USER_ID'"}]]}}}}'  $WEBHOOK_URL
+        curl -X POST -H "Content-Type: application/json" -d '{"msg_type":"post","content":{"post":{"zh_cn":{"title":"'${{ github.repository }}' GitHubAction Failed","content":[[{"tag":"text","text":""},{"tag":"a","text":"Please click here for details ","href":"https://github.com/'${{ github.repository }}'/actions/runs/'${GITHUB_RUN_ID}'"}]]}}}}'  ${{ secrets.FEISHU_WEBHOOK_URL }}

.github/workflows/mkdocs.yml

+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - "master"
+      - "dev"
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v4
+        with:
+          ref: dev
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          REQUIREMENTS: /docs/requirements.txt

docker/china/Dockerfile

 # Use the official sglang image
 FROM lmsysorg/sglang:v0.4.8.post1-cu126
 
-# Install libgl for opencv support
-RUN apt-get update && apt-get install -y libgl1 && apt-get clean && rm -rf /var/lib/apt/lists/*
+# Install libgl for opencv support & Noto fonts for Chinese characters
+RUN apt-get update && \
+    apt-get install -y fonts-noto-core fonts-noto-cjk && \
+    apt-get install -y libgl1 && \
+    apt-get clean && \
+    fc-cache -fv && \
+    rm -rf /var/lib/apt/lists/*
 
 # Install mineru latest
 RUN python3 -m pip install -U 'mineru[core]' -i https://mirrors.aliyun.com/pypi/simple --break-system-packages

docker/compose.yaml

-# Documentation:
-# https://docs.sglang.ai/backend/server_arguments.html#common-launch-commands
 services:
-  mineru-sglang:
+  mineru-sglang-server:
     image: mineru-sglang:latest
-    container_name: mineru-sglang
+    container_name: mineru-sglang-server
     restart: always
+    profiles: ["sglang-server"]
     ports:
       - 30000:30000
     environment:
@@ -30,3 +29,66 @@ services:
             - driver: nvidia
               device_ids: ["0"]
               capabilities: [gpu]
+
+  mineru-api:
+    image: mineru-sglang:latest
+    container_name: mineru-api
+    restart: always
+    profiles: ["api"]
+    ports:
+      - 8000:8000
+    environment:
+      MINERU_MODEL_SOURCE: local
+    entrypoint: mineru-api
+    command:
+      --host 0.0.0.0
+      --port 8000
+      # parameters for sglang-engine
+      # --enable-torch-compile  # You can also enable torch.compile to accelerate inference speed by approximately 15%
+      # --dp-size 2  # If using multiple GPUs, increase throughput using sglang's multi-GPU parallel mode
+      # --tp-size 2  # If you have more than one GPU, you can expand available VRAM using tensor parallelism (TP) mode.
+      # --mem-fraction-static 0.5  # If running on a single GPU and encountering VRAM shortage, reduce the KV cache size by this parameter, if VRAM issues persist, try lowering it further to `0.4` or below.
+    ulimits:
+      memlock: -1
+      stack: 67108864
+    ipc: host
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              device_ids: [ "0" ]
+              capabilities: [ gpu ]
+
+  mineru-gradio:
+    image: mineru-sglang:latest
+    container_name: mineru-gradio
+    restart: always
+    profiles: ["gradio"]
+    ports:
+      - 7860:7860
+    environment:
+      MINERU_MODEL_SOURCE: local
+    entrypoint: mineru-gradio
+    command:
+      --server-name 0.0.0.0
+      --server-port 7860
+      --enable-sglang-engine true  # Enable the sglang engine for Gradio
+      # --enable-api false  # If you want to disable the API, set this to false
+      # --max-convert-pages 20  # If you want to limit the number of pages for conversion, set this to a specific number
+      # parameters for sglang-engine
+      # --enable-torch-compile  # You can also enable torch.compile to accelerate inference speed by approximately 15%
+      # --dp-size 2  # If using multiple GPUs, increase throughput using sglang's multi-GPU parallel mode
+      # --tp-size 2  # If you have more than one GPU, you can expand available VRAM using tensor parallelism (TP) mode.
+      # --mem-fraction-static 0.5  # If running on a single GPU and encountering VRAM shortage, reduce the KV cache size by this parameter, if VRAM issues persist, try lowering it further to `0.4` or below.
+    ulimits:
+      memlock: -1
+      stack: 67108864
+    ipc: host
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              device_ids: [ "0" ]
+              capabilities: [ gpu ]

docker/global/Dockerfile

@@ -2,7 +2,12 @@
 FROM lmsysorg/sglang:v0.4.8.post1-cu126
 
 # Install libgl for opencv support
-RUN apt-get update && apt-get install -y libgl1 && apt-get clean && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && \
+    apt-get install -y fonts-noto-core fonts-noto-cjk && \
+    apt-get install -y libgl1 && \
+    apt-get clean && \
+    fc-cache -fv && \
+    rm -rf /var/lib/apt/lists/*
 
 # Install mineru latest
 RUN python3 -m pip install -U 'mineru[core]' --break-system-packages

docs/FAQ_en_us.md

-# Frequently Asked Questions
-
-### 1. Encountered the error `ImportError: libGL.so.1: cannot open shared object file: No such file or directory` in Ubuntu 22.04 on WSL2
-
-The `libgl` library is missing in Ubuntu 22.04 on WSL2. You can install the `libgl` library with the following command to resolve the issue:
-
-```bash
-sudo apt-get install libgl1-mesa-glx
-```
-
-Reference: https://github.com/opendatalab/MinerU/issues/388
-
-
-### 2. Error when installing MinerU on CentOS 7 or Ubuntu 18: `ERROR: Failed building wheel for simsimd`
-
-The new version of albumentations (1.4.21) introduces a dependency on simsimd. Since the pre-built package of simsimd for Linux requires a glibc version greater than or equal to 2.28, this causes installation issues on some Linux distributions released before 2019. You can resolve this issue by using the following command:
-```
-conda create -n mineru python=3.11 -y
-conda activate mineru
-pip install -U "mineru[pipeline_old_linux]"
-```
-
-Reference: https://github.com/opendatalab/MinerU/issues/1004

docs/FAQ_zh_cn.md

-# 常见问题解答
-
-### 1.在WSL2的Ubuntu22.04中遇到报错`ImportError: libGL.so.1: cannot open shared object file: No such file or directory`
-
-WSL2的Ubuntu22.04中缺少`libgl`库，可通过以下命令安装`libgl`库解决：
-
-```bash
-sudo apt-get install libgl1-mesa-glx
-```
-
-参考：https://github.com/opendatalab/MinerU/issues/388
-
-
-### 2.在 CentOS 7 或 Ubuntu 18 系统安装MinerU时报错`ERROR: Failed building wheel for simsimd`
-
-新版本albumentations(1.4.21)引入了依赖simsimd,由于simsimd在linux的预编译包要求glibc的版本大于等于2.28，导致部分2019年之前发布的Linux发行版无法正常安装，可通过如下命令安装:
-```
-conda create -n mineru python=3.11 -y
-conda activate mineru
-pip install -U "mineru[pipeline_old_linux]"
-```
-
-参考：https://github.com/opendatalab/MinerU/issues/1004

docs/en/demo/index.md

+<script type="module" src="https://gradio.s3-us-west-2.amazonaws.com/5.35.0/gradio.js"></script>
+<gradio-app src="https://opendatalab-mineru.hf.space"></gradio-app>

docs/en/faq/index.md

+# Frequently Asked Questions
+
+If your question is not listed, try using [DeepWiki](https://deepwiki.com/opendatalab/MinerU)'s AI assistant for common issues.
+
+For unresolved problems, join our [Discord](https://discord.gg/Tdedn9GTXq) or [WeChat](http://mineru.space/s/V85Yl) community for support.
+
+??? question "Encountered the error `ImportError: libGL.so.1: cannot open shared object file: No such file or directory` in Ubuntu 22.04 on WSL2"
+
+    The `libgl` library is missing in Ubuntu 22.04 on WSL2. You can install the `libgl` library with the following command to resolve the issue:
+    
+    ```bash
+    sudo apt-get install libgl1-mesa-glx
+    ```
+    
+    Reference: [#388](https://github.com/opendatalab/MinerU/issues/388)
+
+
+??? question "Error when installing MinerU on CentOS 7 or Ubuntu 18: `ERROR: Failed building wheel for simsimd`"
+
+    The new version of albumentations (1.4.21) introduces a dependency on simsimd. Since the pre-built package of simsimd for Linux requires a glibc version greater than or equal to 2.28, this causes installation issues on some Linux distributions released before 2019. You can resolve this issue by using the following command:
+    ```
+    conda create -n mineru python=3.11 -y
+    conda activate mineru
+    pip install -U "mineru[pipeline_old_linux]"
+    ```
+    
+    Reference: [#1004](https://github.com/opendatalab/MinerU/issues/1004)
+
+
+??? question "Missing text information in parsing results when installing and using on Linux systems."
+
+    MinerU uses `pypdfium2` instead of `pymupdf` as the PDF page rendering engine in versions >=2.0 to resolve AGPLv3 license issues. On some Linux distributions, due to missing CJK fonts, some text may be lost during the process of rendering PDFs to images.
+    To solve this problem, you can install the noto font package with the following commands, which are effective on Ubuntu/Debian systems:
+    ```bash
+    sudo apt update
+    sudo apt install fonts-noto-core
+    sudo apt install fonts-noto-cjk
+    fc-cache -fv
+    ```
+    You can also directly use our [Docker deployment](../quick_start/docker_deployment.md) method to build the image, which includes the above font packages by default.
+    
+    Reference: [#2915](https://github.com/opendatalab/MinerU/issues/2915)

docs/en/index.md

+<div align="center" xmlns="http://www.w3.org/1999/html">
+<!-- logo -->
+<p align="center">
+  <img src="https://opendatalab.github.io/MinerU/images/MinerU-logo.png" width="300px" style="vertical-align:middle;">
+</p>
+</div>
+
+<!-- icon -->
+
+[![stars](https://img.shields.io/github/stars/opendatalab/MinerU.svg)](https://github.com/opendatalab/MinerU)
+[![forks](https://img.shields.io/github/forks/opendatalab/MinerU.svg)](https://github.com/opendatalab/MinerU)
+[![open issues](https://img.shields.io/github/issues-raw/opendatalab/MinerU)](https://github.com/opendatalab/MinerU/issues)
+[![issue resolution](https://img.shields.io/github/issues-closed-raw/opendatalab/MinerU)](https://github.com/opendatalab/MinerU/issues)
+[![PyPI version](https://img.shields.io/pypi/v/mineru)](https://pypi.org/project/mineru/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mineru)](https://pypi.org/project/mineru/)
+[![Downloads](https://static.pepy.tech/badge/mineru)](https://pepy.tech/project/mineru)
+[![Downloads](https://static.pepy.tech/badge/mineru/month)](https://pepy.tech/project/mineru)
+[![OpenDataLab](https://img.shields.io/badge/webapp_on_mineru.net-blue?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTM0IiBoZWlnaHQ9IjEzNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJtMTIyLDljMCw1LTQsOS05LDlzLTktNC05LTksNC05LDktOSw5LDQsOSw5eiIgZmlsbD0idXJsKCNhKSIvPjxwYXRoIGQ9Im0xMjIsOWMwLDUtNCw5LTksOXMtOS00LTktOSw0LTksOS05LDksNCw5LDl6IiBmaWxsPSIjMDEwMTAxIi8+PHBhdGggZD0ibTkxLDE4YzAsNS00LDktOSw5cy05LTQtOS05LDQtOSw5LTksOSw0LDksOXoiIGZpbGw9InVybCgjYikiLz48cGF0aCBkPSJtOTEsMThjMCw1LTQsOS05LDlzLTktNC05LTksNC05LDktOSw5LDQsOSw5eiIgZmlsbD0iIzAxMDEwMSIvPjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJtMzksNjJjMCwxNiw4LDMwLDIwLDM4LDctNiwxMi0xNiwxMi0yNlY0OWMwLTQsMy03LDYtOGw0Ni0xMmM1LTEsMTEsMywxMSw4djMxYzAsMzctMzAsNjYtNjYsNjYtMzcsMC02Ni0zMC02Ni02NlY0NmMwLTQsMy03LDYtOGwyMC02YzUtMSwxMSwzLDExLDh2MjF6bS0yOSw2YzAsMTYsNiwzMCwxNyw0MCwzLDEsNSwxLDgsMSw1LDAsMTAtMSwxNS0zQzM3LDk1LDI5LDc5LDI5LDYyVjQybC0xOSw1djIweiIgZmlsbD0idXJsKCNjKSIvPjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJtMzksNjJjMCwxNiw4LDMwLDIwLDM4LDctNiwxMi0xNiwxMi0yNlY0OWMwLTQsMy03LDYtOGw0Ni0xMmM1LTEsMTEsMywxMSw4djMxYzAsMzctMzAsNjYtNjYsNjYtMzcsMC02Ni0zMC02Ni02NlY0NmMwLTQsMy03LDYtOGwyMC02YzUtMSwxMSwzLDExLDh2MjF6bS0yOSw2YzAsMTYsNiwzMCwxNyw0MCwzLDEsNSwxLDgsMSw1LDAsMTAtMSwxNS0zQzM3LDk1LDI5LDc5LDI5LDYyVjQybC0xOSw1djIweiIgZmlsbD0iIzAxMDEwMSIvPjxkZWZzPjxsaW5lYXJHcmFkaWVudCBpZD0iYSIgeDE9Ijg0IiB5MT0iNDEiIHgyPSI3NSIgeTI9IjEyMCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNmZmYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMyZTJlMmUiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYiIgeDE9Ijg0IiB5MT0iNDEiIHgyPSI3NSIgeTI9IjEyMCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNmZmYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMyZTJlMmUiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYyIgeDE9Ijg0IiB5MT0iNDEiIHgyPSI3NSIgeTI9IjEyMCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNmZmYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMyZTJlMmUiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4=&labelColor=white)](https://mineru.net/OpenSourceTools/Extractor?source=github)
+[![HuggingFace](https://img.shields.io/badge/Demo_on_HuggingFace-yellow.svg?logo=data:image/png;base64,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&labelColor=white)](https://huggingface.co/spaces/opendatalab/MinerU)
+[![ModelScope](https://img.shields.io/badge/Demo_on_ModelScope-purple?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIzIiBoZWlnaHQ9IjIwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCiA8Zz4KICA8dGl0bGU+TGF5ZXIgMTwvdGl0bGU+CiAgPHBhdGggaWQ9InN2Z18xNCIgZmlsbD0iIzYyNGFmZiIgZD0ibTAsODkuODRsMjUuNjUsMGwwLDI1LjY0OTk5bC0yNS42NSwwbDAsLTI1LjY0OTk5eiIvPgogIDxwYXRoIGlkPSJzdmdfMTUiIGZpbGw9IiM2MjRhZmYiIGQ9Im05OS4xNCwxMTUuNDlsMjUuNjUsMGwwLDI1LjY1bC0yNS42NSwwbDAsLTI1LjY1eiIvPgogIDxwYXRoIGlkPSJzdmdfMTYiIGZpbGw9IiM2MjRhZmYiIGQ9Im0xNzYuMDksMTQxLjE0bC0yNS42NDk5OSwwbDAsMjIuMTlsNDcuODQsMGwwLC00Ny44NGwtMjIuMTksMGwwLDI1LjY1eiIvPgogIDxwYXRoIGlkPSJzdmdfMTciIGZpbGw9IiMzNmNmZDEiIGQ9Im0xMjQuNzksODkuODRsMjUuNjUsMGwwLDI1LjY0OTk5bC0yNS42NSwwbDAsLTI1LjY0OTk5eiIvPgogIDxwYXRoIGlkPSJzdmdfMTgiIGZpbGw9IiMzNmNmZDEiIGQ9Im0wLDY0LjE5bDI1LjY1LDBsMCwyNS42NWwtMjUuNjUsMGwwLC0yNS42NXoiLz4KICA8cGF0aCBpZD0ic3ZnXzE5IiBmaWxsPSIjNjI0YWZmIiBkPSJtMTk4LjI4LDg5Ljg0bDI1LjY0OTk5LDBsMCwyNS42NDk5OWwtMjUuNjQ5OTksMGwwLC0yNS42NDk5OXoiLz4KICA8cGF0aCBpZD0ic3ZnXzIwIiBmaWxsPSIjMzZjZmQxIiBkPSJtMTk4LjI4LDY0LjE5bDI1LjY0OTk5LDBsMCwyNS42NWwtMjUuNjQ5OTksMGwwLC0yNS42NXoiLz4KICA8cGF0aCBpZD0ic3ZnXzIxIiBmaWxsPSIjNjI0YWZmIiBkPSJtMTUwLjQ0LDQybDAsMjIuMTlsMjUuNjQ5OTksMGwwLDI1LjY1bDIyLjE5LDBsMCwtNDcuODRsLTQ3Ljg0LDB6Ii8+CiAgPHBhdGggaWQ9InN2Z18yMiIgZmlsbD0iIzM2Y2ZkMSIgZD0ibTczLjQ5LDg5Ljg0bDI1LjY1LDBsMCwyNS42NDk5OWwtMjUuNjUsMGwwLC0yNS42NDk5OXoiLz4KICA8cGF0aCBpZD0ic3ZnXzIzIiBmaWxsPSIjNjI0YWZmIiBkPSJtNDcuODQsNjQuMTlsMjUuNjUsMGwwLC0yMi4xOWwtNDcuODQsMGwwLDQ3Ljg0bDIyLjE5LDBsMCwtMjUuNjV6Ii8+CiAgPHBhdGggaWQ9InN2Z18yNCIgZmlsbD0iIzYyNGFmZiIgZD0ibTQ3Ljg0LDExNS40OWwtMjIuMTksMGwwLDQ3Ljg0bDQ3Ljg0LDBsMCwtMjIuMTlsLTI1LjY1LDBsMCwtMjUuNjV6Ii8+CiA8L2c+Cjwvc3ZnPg==&labelColor=white)](https://www.modelscope.cn/studios/OpenDataLab/MinerU)
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/gist/myhloli/3b3a00a4a0a61577b6c30f989092d20d/mineru_demo.ipynb)
+[![arXiv](https://img.shields.io/badge/arXiv-2409.18839-b31b1b.svg?logo=arXiv)](https://arxiv.org/abs/2409.18839)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/opendatalab/MinerU)
+
+<div align="center">
+<a href="https://trendshift.io/repositories/11174" target="_blank"><img src="https://trendshift.io/api/badge/repositories/11174" alt="opendatalab%2FMinerU | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+
+<!-- hot link -->
+
+<p align="center">
+🚀<a href="https://mineru.net/?source=github">MinerU Official Website→✅ Zero-Install Online Version ✅ Full-Featured Client ✅ Developer API Online Access, skip deployment hassles, get all product formats with one click, go fast!</a>
+</p>
+
+<!-- join us -->
+
+<p align="center">
+    👋 join us on <a href="https://discord.gg/Tdedn9GTXq" target="_blank">Discord</a> and <a href="http://mineru.space/s/V85Yl" target="_blank">WeChat</a>
+</p>
+</div>
+
+## Project Introduction
+
+MinerU is a tool that converts PDFs into machine-readable formats (e.g., markdown, JSON), allowing for easy extraction into any format.
+MinerU was born during the pre-training process of [InternLM](https://github.com/InternLM/InternLM). We focus on solving symbol conversion issues in scientific literature and hope to contribute to technological development in the era of large models.
+Compared to well-known commercial products domestically and internationally, MinerU is still young. If you encounter any issues or if the results are not as expected, please submit an issue on [GitHub Issues](https://github.com/opendatalab/MinerU/issues) and **attach the relevant PDF**.
+
+![type:video](https://github.com/user-attachments/assets/4bea02c9-6d54-4cd6-97ed-dff14340982c)
+
+
+## Key Features
+
+- Remove headers, footers, footnotes, page numbers and other elements to ensure semantic coherence
+- Output text in human reading order, suitable for single-column, multi-column and complex layouts
+- Retain the original document structure, including titles, paragraphs, lists, etc.
+- Extract images, image descriptions, tables, table titles and footnotes
+- Automatically identify and convert formulas in documents to LaTeX format
+- Automatically identify and convert tables in documents to HTML format
+- Automatically detect scanned PDFs and garbled PDFs, and enable OCR functionality
+- OCR supports detection and recognition of 84 languages
+- Support multiple output formats, such as multimodal and NLP Markdown, reading-order-sorted JSON, and information-rich intermediate formats
+- Support multiple visualization results, including layout visualization, span visualization, etc., for efficient confirmation of output effects and quality inspection
+- Support pure CPU environment operation, and support GPU(CUDA)/NPU(CANN)/MPS acceleration
+- Compatible with Windows, Linux and Mac platforms
+
+
+## User Guide
+
+- [Quick Start Guide](./quick_start/index.md)
+- [Detailed Usage Instructions](./usage/index.md)

docs/en/quick_start/docker_deployment.md

+# Deploying MinerU with Docker
+
+MinerU provides a convenient Docker deployment method, which helps quickly set up the environment and solve some tricky environment compatibility issues.
+
+## Build Docker Image using Dockerfile
+
+```bash
+wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfile
+docker build -t mineru-sglang:latest -f Dockerfile .
+```
+
+> [!TIP]
+> The [Dockerfile](https://github.com/opendatalab/MinerU/blob/master/docker/global/Dockerfile) uses `lmsysorg/sglang:v0.4.8.post1-cu126` as the base image by default, supporting Turing/Ampere/Ada Lovelace/Hopper platforms.
+> If you are using the newer `Blackwell` platform, please modify the base image to `lmsysorg/sglang:v0.4.8.post1-cu128-b200` before executing the build operation.
+
+## Docker Description
+
+MinerU's Docker uses `lmsysorg/sglang` as the base image, so it includes the `sglang` inference acceleration framework and necessary dependencies by default. Therefore, on compatible devices, you can directly use `sglang` to accelerate VLM model inference.
+
+> [!NOTE]
+> Requirements for using `sglang` to accelerate VLM model inference:
+> 
+> - Device must have Turing architecture or later graphics cards with 8GB+ available VRAM.
+> - The host machine's graphics driver should support CUDA 12.6 or higher; `Blackwell` platform should support CUDA 12.8 or higher. You can check the driver version using the `nvidia-smi` command.
+> - Docker container must have access to the host machine's graphics devices.
+>
+> If your device doesn't meet the above requirements, you can still use other features of MinerU, but cannot use `sglang` to accelerate VLM model inference, meaning you cannot use the `vlm-sglang-engine` backend or start the `vlm-sglang-server` service.
+
+## Start Docker Container:
+
+```bash
+docker run --gpus all \
+  --shm-size 32g \
+  -p 30000:30000 -p 7860:7860 -p 8000:8000 \
+  --ipc=host \
+  -it mineru-sglang:latest \
+  /bin/bash
+```
+
+After executing this command, you will enter the Docker container's interactive terminal with some ports mapped for potential services. You can directly run MinerU-related commands within the container to use MinerU's features.
+You can also directly start MinerU services by replacing `/bin/bash` with service startup commands. For detailed instructions, please refer to the [Start the service via command](https://opendatalab.github.io/MinerU/usage/quick_usage/#advanced-usage-via-api-webui-sglang-clientserver).
+
+## Start Services Directly with Docker Compose
+
+We provide a [compose.yaml](https://github.com/opendatalab/MinerU/blob/master/docker/compose.yaml) file that you can use to quickly start MinerU services.
+
+```bash
+# Download compose.yaml file
+wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml
+```
+
+>[!NOTE]
+>
+>- The `compose.yaml` file contains configurations for multiple services of MinerU, you can choose to start specific services as needed.
+>- Different services might have additional parameter configurations, which you can view and edit in the `compose.yaml` file.
+>- Due to the pre-allocation of GPU memory by the `sglang` inference acceleration framework, you may not be able to run multiple `sglang` services simultaneously on the same machine. Therefore, ensure that other services that might use GPU memory have been stopped before starting the `vlm-sglang-server` service or using the `vlm-sglang-engine` backend.
+
+---
+
+### Start sglang-server service
+connect to `sglang-server` via `vlm-sglang-client` backend
+  ```bash
+  docker compose -f compose.yaml --profile mineru-sglang-server up -d
+  ```
+  >[!TIP]
+  >In another terminal, connect to sglang server via sglang client (only requires CPU and network, no sglang environment needed)
+  > ```bash
+  > mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://<server_ip>:30000
+  > ```
+
+---
+
+### Start Web API service
+  ```bash
+  docker compose -f compose.yaml --profile mineru-api up -d
+  ```
+  >[!TIP]
+  >Access `http://<server_ip>:8000/docs` in your browser to view the API documentation.
+
+---
+
+### Start Gradio WebUI service
+  ```bash
+  docker compose -f compose.yaml --profile mineru-gradio up -d
+  ```
+  >[!TIP]
+  >
+  >- Access `http://<server_ip>:7860` in your browser to use the Gradio WebUI.
+  >- Access `http://<server_ip>:7860/?view=api` to use the Gradio API.

docs/en/quick_start/extension_modules.md

+# MinerU Extension Modules Installation Guide
+MinerU supports installing extension modules on demand based on different needs to enhance functionality or support specific model backends.
+
+## Common Scenarios
+
+### Core Functionality Installation
+The `core` module is the core dependency of MinerU, containing all functional modules except `sglang`. Installing this module ensures the basic functionality of MinerU works properly.
+```bash
+uv pip install mineru[core]
+```
+
+---
+
+### Using `sglang` to Accelerate VLM Model Inference
+The `sglang` module provides acceleration support for VLM model inference, suitable for graphics cards with Turing architecture and later (8GB+ VRAM). Installing this module can significantly improve model inference speed.
+In the configuration, `all` includes both `core` and `sglang` modules, so `mineru[all]` and `mineru[core,sglang]` are equivalent.
+```bash
+uv pip install mineru[all]
+```
+> [!TIP]
+> If exceptions occur during installation of the complete package including sglang, please refer to the [sglang official documentation](https://docs.sglang.ai/start/install.html) to try to resolve the issue, or directly use the [Docker](./docker_deployment.md) deployment method.
+
+---
+
+### Installing Lightweight Client to Connect to sglang-server
+If you need to install a lightweight client on edge devices to connect to `sglang-server`, you can install the basic mineru package, which is very lightweight and suitable for devices with only CPU and network connectivity.
+```bash
+uv pip install mineru
+```
+
+---
+
+### Using Pipeline Backend on Outdated Linux Systems
+If your system is too outdated to meet the dependency requirements of `mineru[core]`, this option can minimally meet MinerU's runtime requirements, suitable for old systems that cannot be upgraded and only need to use the pipeline backend.
+```bash
+uv pip install mineru[pipeline_old_linux]
+```

docs/en/quick_start/index.md

+# Quick Start
+
+If you encounter any installation issues, please check the [FAQ](../faq/index.md) first.
+
+## Online Experience
+
+### Official online web application
+The official online version has the same functionality as the client, with a beautiful interface and rich features, requires login to use  
+ 
+- [![OpenDataLab](https://img.shields.io/badge/webapp_on_mineru.net-blue?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTM0IiBoZWlnaHQ9IjEzNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJtMTIyLDljMCw1LTQsOS05LDlzLTktNC05LTksNC05LDktOSw5LDQsOSw5eiIgZmlsbD0idXJsKCNhKSIvPjxwYXRoIGQ9Im0xMjIsOWMwLDUtNCw5LTksOXMtOS00LTktOSw0LTksOS05LDksNCw5LDl6IiBmaWxsPSIjMDEwMTAxIi8+PHBhdGggZD0ibTkxLDE4YzAsNS00LDktOSw5cy05LTQtOS05LDQtOSw5LTksOSw0LDksOXoiIGZpbGw9InVybCgjYikiLz48cGF0aCBkPSJtOTEsMThjMCw1LTQsOS05LDlzLTktNC05LTksNC05LDktOSw5LDQsOSw5eiIgZmlsbD0iIzAxMDEwMSIvPjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJtMzksNjJjMCwxNiw4LDMwLDIwLDM4LDctNiwxMi0xNiwxMi0yNlY0OWMwLTQsMy03LDYtOGw0Ni0xMmM1LTEsMTEsMywxMSw4djMxYzAsMzctMzAsNjYtNjYsNjYtMzcsMC02Ni0zMC02Ni02NlY0NmMwLTQsMy03LDYtOGwyMC02YzUtMSwxMSwzLDExLDh2MjF6bS0yOSw2YzAsMTYsNiwzMCwxNyw0MCwzLDEsNSwxLDgsMSw1LDAsMTAtMSwxNS0zQzM3LDk1LDI5LDc5LDI5LDYyVjQybC0xOSw1djIweiIgZmlsbD0idXJsKCNjKSIvPjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJtMzksNjJjMCwxNiw4LDMwLDIwLDM4LDctNiwxMi0xNiwxMi0yNlY0OWMwLTQsMy03LDYtOGw0Ni0xMmM1LTEsMTEsMywxMSw4djMxYzAsMzctMzAsNjYtNjYsNjYtMzcsMC02Ni0zMC02Ni02NlY0NmMwLTQsMy03LDYtOGwyMC02YzUtMSwxMSwzLDExLDh2MjF6bS0yOSw2YzAsMTYsNiwzMCwxNyw0MCwzLDEsNSwxLDgsMSw1LDAsMTAtMSwxNS0zQzM3LDk1LDI5LDc5LDI5LDYyVjQybC0xOSw1djIweiIgZmlsbD0iIzAxMDEwMSIvPjxkZWZzPjxsaW5lYXJHcmFkaWVudCBpZD0iYSIgeDE9Ijg0IiB5MT0iNDEiIHgyPSI3NSIgeTI9IjEyMCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNmZmYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMyZTJlMmUiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYiIgeDE9Ijg0IiB5MT0iNDEiIHgyPSI3NSIgeTI9IjEyMCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNmZmYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMyZTJlMmUiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYyIgeDE9Ijg0IiB5MT0iNDEiIHgyPSI3NSIgeTI9IjEyMCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNmZmYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMyZTJlMmUiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4=&labelColor=white)](https://mineru.net/OpenSourceTools/Extractor?source=github)
+
+### Gradio-based online demo
+A WebUI developed based on Gradio, with a simple interface and only core parsing functionality, no login required  
+
+- [![ModelScope](https://img.shields.io/badge/Demo_on_ModelScope-purple?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIzIiBoZWlnaHQ9IjIwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCiA8Zz4KICA8dGl0bGU+TGF5ZXIgMTwvdGl0bGU+CiAgPHBhdGggaWQ9InN2Z18xNCIgZmlsbD0iIzYyNGFmZiIgZD0ibTAsODkuODRsMjUuNjUsMGwwLDI1LjY0OTk5bC0yNS42NSwwbDAsLTI1LjY0OTk5eiIvPgogIDxwYXRoIGlkPSJzdmdfMTUiIGZpbGw9IiM2MjRhZmYiIGQ9Im05OS4xNCwxMTUuNDlsMjUuNjUsMGwwLDI1LjY1bC0yNS42NSwwbDAsLTI1LjY1eiIvPgogIDxwYXRoIGlkPSJzdmdfMTYiIGZpbGw9IiM2MjRhZmYiIGQ9Im0xNzYuMDksMTQxLjE0bC0yNS42NDk5OSwwbDAsMjIuMTlsNDcuODQsMGwwLC00Ny44NGwtMjIuMTksMGwwLDI1LjY1eiIvPgogIDxwYXRoIGlkPSJzdmdfMTciIGZpbGw9IiMzNmNmZDEiIGQ9Im0xMjQuNzksODkuODRsMjUuNjUsMGwwLDI1LjY0OTk5bC0yNS42NSwwbDAsLTI1LjY0OTk5eiIvPgogIDxwYXRoIGlkPSJzdmdfMTgiIGZpbGw9IiMzNmNmZDEiIGQ9Im0wLDY0LjE5bDI1LjY1LDBsMCwyNS42NWwtMjUuNjUsMGwwLC0yNS42NXoiLz4KICA8cGF0aCBpZD0ic3ZnXzE5IiBmaWxsPSIjNjI0YWZmIiBkPSJtMTk4LjI4LDg5Ljg0bDI1LjY0OTk5LDBsMCwyNS42NDk5OWwtMjUuNjQ5OTksMGwwLC0yNS42NDk5OXoiLz4KICA8cGF0aCBpZD0ic3ZnXzIwIiBmaWxsPSIjMzZjZmQxIiBkPSJtMTk4LjI4LDY0LjE5bDI1LjY0OTk5LDBsMCwyNS42NWwtMjUuNjQ5OTksMGwwLC0yNS42NXoiLz4KICA8cGF0aCBpZD0ic3ZnXzIxIiBmaWxsPSIjNjI0YWZmIiBkPSJtMTUwLjQ0LDQybDAsMjIuMTlsMjUuNjQ5OTksMGwwLDI1LjY1bDIyLjE5LDBsMCwtNDcuODRsLTQ3Ljg0LDB6Ii8+CiAgPHBhdGggaWQ9InN2Z18yMiIgZmlsbD0iIzM2Y2ZkMSIgZD0ibTczLjQ5LDg5Ljg0bDI1LjY1LDBsMCwyNS42NDk5OWwtMjUuNjUsMGwwLC0yNS42NDk5OXoiLz4KICA8cGF0aCBpZD0ic3ZnXzIzIiBmaWxsPSIjNjI0YWZmIiBkPSJtNDcuODQsNjQuMTlsMjUuNjUsMGwwLC0yMi4xOWwtNDcuODQsMGwwLDQ3Ljg0bDIyLjE5LDBsMCwtMjUuNjV6Ii8+CiAgPHBhdGggaWQ9InN2Z18yNCIgZmlsbD0iIzYyNGFmZiIgZD0ibTQ3Ljg0LDExNS40OWwtMjIuMTksMGwwLDQ3Ljg0bDQ3Ljg0LDBsMCwtMjIuMTlsLTI1LjY1LDBsMCwtMjUuNjV6Ii8+CiA8L2c+Cjwvc3ZnPg==&labelColor=white)](https://www.modelscope.cn/studios/OpenDataLab/MinerU)
+- [![HuggingFace](https://img.shields.io/badge/Demo_on_HuggingFace-yellow.svg?logo=data:image/png;base64,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&labelColor=white)](https://huggingface.co/spaces/opendatalab/MinerU)
+
+## Local Deployment
+
+> [!WARNING]
+> **Prerequisites - Hardware and Software Environment Support**
+> 
+> To ensure the stability and reliability of the project, we have optimized and tested only specific hardware and software environments during development. This ensures that users can achieve optimal performance and encounter the fewest compatibility issues when deploying and running the project on recommended system configurations.
+>
+> By concentrating our resources and efforts on mainstream environments, our team can more efficiently resolve potential bugs and timely develop new features.
+>
+> In non-mainstream environments, due to the diversity of hardware and software configurations, as well as compatibility issues with third-party dependencies, we cannot guarantee 100% usability of the project. Therefore, for users who wish to use this project in non-recommended environments, we suggest carefully reading the documentation and FAQ first, as most issues have corresponding solutions in the FAQ. Additionally, we encourage community feedback on issues so that we can gradually expand our support range.
+
+<table border="1">
+    <tr>
+        <td>Parsing Backend</td>
+        <td>pipeline</td>
+        <td>vlm-transformers</td>
+        <td>vlm-sglang</td>
+    </tr>
+    <tr>
+        <td>Operating System</td>
+        <td>Linux / Windows / macOS</td>
+        <td>Linux / Windows</td>
+        <td>Linux / Windows (via WSL2)</td>
+    </tr>
+    <tr>
+        <td>CPU Inference Support</td>
+        <td>✅</td>
+        <td colspan="2">❌</td>
+    </tr>
+    <tr>
+        <td>GPU Requirements</td>
+        <td>Turing architecture and later, 6GB+ VRAM or Apple Silicon</td>
+        <td colspan="2">Turing architecture and later, 8GB+ VRAM</td>
+    </tr>
+    <tr>
+        <td>Memory Requirements</td>
+        <td colspan="3">Minimum 16GB+, recommended 32GB+</td>
+    </tr>
+    <tr>
+        <td>Disk Space Requirements</td>
+        <td colspan="3">20GB+, SSD recommended</td>
+    </tr>
+    <tr>
+        <td>Python Version</td>
+        <td colspan="3">3.10-3.13</td>
+    </tr>
+</table>
+
+### Install MinerU
+
+#### Install MinerU using pip or uv
+```bash
+pip install --upgrade pip
+pip install uv
+uv pip install -U "mineru[core]"
+```
+
+#### Install MinerU from source code
+```bash
+git clone https://github.com/opendatalab/MinerU.git
+cd MinerU
+uv pip install -e .[core]
+```
+
+> [!TIP]
+> `mineru[core]` includes all core features except `sglang` acceleration, compatible with Windows / Linux / macOS systems, suitable for most users.
+> If you need to use `sglang` acceleration for VLM model inference or install a lightweight client on edge devices, please refer to the documentation [Extension Modules Installation Guide](./extension_modules.md).
+
+---
+ 
+#### Deploy MinerU using Docker
+MinerU provides a convenient Docker deployment method, which helps quickly set up the environment and solve some tricky environment compatibility issues.
+You can get the [Docker Deployment Instructions](./docker_deployment.md) in the documentation.
+
+---
+
+### Using MinerU
+
+The simplest command line invocation is:
+```bash
+mineru -p <input_path> -o <output_path>
+```
+
+You can use MinerU for PDF parsing through various methods such as command line, API, and WebUI. For detailed instructions, please refer to the [Usage Guide](../usage/index.md).
\ No newline at end of file

docs/output_file_en_us.md → docs/en/reference/output_files.md

+# MinerU Output Files Documentation
+
 ## Overview
 
-After executing the `mineru` command, in addition to outputting files related to markdown, several other files unrelated to markdown will also be generated. These files will be introduced one by one.
+After executing the `mineru` command, in addition to the main markdown file output, multiple auxiliary files are generated for debugging, quality inspection, and further processing. These files include:
+
+- **Visual debugging files**: Help users intuitively understand the document parsing process and results
+- **Structured data files**: Contain detailed parsing data for secondary development
+
+The following sections provide detailed descriptions of each file's purpose and format.
+
+## Visual Debugging Files
+
+### Layout Analysis File (layout.pdf)
+
+**File naming format**: `{original_filename}_layout.pdf`
+
+**Functionality**:
+
+- Visualizes layout analysis results for each page
+- Numbers in the top-right corner of each detection box indicate reading order
+- Different background colors distinguish different types of content blocks
+
+**Use cases**:
+
+- Check if layout analysis is correct
+- Verify if reading order is reasonable
+- Debug layout-related issues
+
+![layout page example](../images/layout_example.png)
+
+### Text Spans File (spans.pdf)
+
+> [!NOTE]
+> Only applicable to pipeline backend
+
+**File naming format**: `{original_filename}_spans.pdf`
+
+**Functionality**:
+
+- Uses different colored line boxes to annotate page content based on span type
+- Used for quality inspection and issue troubleshooting
 
-### some_pdf_layout.pdf
+**Use cases**:
 
-Each page's layout consists of one or more bounding boxes. The number in the top-right corner of each box indicates the reading order. Additionally, different content blocks are highlighted with distinct background colors within the layout.pdf.
-![layout example](images/layout_example.png)
+- Quickly troubleshoot text loss issues
+- Check inline formula recognition
+- Verify text segmentation accuracy
 
-### some_pdf_spans.pdf(Applicable only to the pipeline backend)
+![span page example](../images/spans_example.png)
 
-All spans on the page are drawn with different colored line frames according to the span type. This file can be used for quality control, allowing for quick identification of issues such as missing text or unrecognized inline formulas.
+## Structured Data Files
 
-![spans example](images/spans_example.png)
+### Model Inference Results (model.json)
 
-### some_pdf_model.json(Applicable only to the pipeline backend)
+> [!NOTE]
+> Only applicable to pipeline backend
 
-#### Structure Definition
+**File naming format**: `{original_filename}_model.json`
+
+#### Data Structure Definition
 
 ```python
 from pydantic import BaseModel, Field
 from enum import IntEnum
 
 class CategoryType(IntEnum):
+    """Content category enumeration"""
     title = 0               # Title
     plain_text = 1          # Text
-     abandon = 2             # Includes headers, footers, page numbers, and page annotations
+    abandon = 2             # Including headers, footers, page numbers, and page annotations
     figure = 3              # Image
-     figure_caption = 4      # Image description
+    figure_caption = 4      # Image caption
     table = 5               # Table
-     table_caption = 6       # Table description
+    table_caption = 6       # Table caption
     table_footnote = 7      # Table footnote
-     isolate_formula = 8     # Block formula
-     formula_caption = 9     # Formula label
-
+    isolate_formula = 8     # Interline formula
+    formula_caption = 9     # Interline formula number
     embedding = 13          # Inline formula
-     isolated = 14           # Block formula
+    isolated = 14           # Interline formula
     text = 15               # OCR recognition result
 
-
 class PageInfo(BaseModel):
-    page_no: int = Field(description="Page number, the first page is 0", ge=0)
+    """Page information"""
+    page_no: int = Field(description="Page number, first page is 0", ge=0)
     height: int = Field(description="Page height", gt=0)
     width: int = Field(description="Page width", ge=0)
 
 class ObjectInferenceResult(BaseModel):
+    """Object recognition result"""
     category_id: CategoryType = Field(description="Category", ge=0)
-    poly: list[float] = Field(description="Quadrilateral coordinates, representing the coordinates of the top-left, top-right, bottom-right, and bottom-left points respectively")
-    score: float = Field(description="Confidence of the inference result")
+    poly: list[float] = Field(description="Quadrilateral coordinates, format: [x0,y0,x1,y1,x2,y2,x3,y3]")
+    score: float = Field(description="Confidence score of inference result")
     latex: str | None = Field(description="LaTeX parsing result", default=None)
     html: str | None = Field(description="HTML parsing result", default=None)
 
 class PageInferenceResults(BaseModel):
-     layout_dets: list[ObjectInferenceResult] = Field(description="Page recognition results", ge=0)
+    """Page inference results"""
+    layout_dets: list[ObjectInferenceResult] = Field(description="Page recognition results")
     page_info: PageInfo = Field(description="Page metadata")
 
-
-# The inference results of all pages, ordered by page number, are stored in a list as the inference results of MinerU
+# Complete inference results
 inference_result: list[PageInferenceResults] = []
-
 ```
 
-The format of the poly coordinates is \[x0, y0, x1, y1, x2, y2, x3, y3\], representing the coordinates of the top-left, top-right, bottom-right, and bottom-left points respectively.
-![Poly Coordinate Diagram](images/poly.png)
+#### Coordinate System Description
+
+`poly` coordinate format: `[x0, y0, x1, y1, x2, y2, x3, y3]`
+
+- Represents coordinates of top-left, top-right, bottom-right, bottom-left points respectively
+- Coordinate origin is at the top-left corner of the page
+
+![poly coordinate diagram](../images/poly.png)
 
-#### example
+#### Sample Data
 
 ```json
 [
@@ -116,142 +165,127 @@ The format of the poly coordinates is \[x0, y0, x1, y1, x2, y2, x3, y3\], repres
 ]
 ```
 
-### some_pdf_model_output.txt (Applicable only to the VLM backend)
+### VLM Output Results (model_output.txt)
 
-This file contains the output of the VLM model, with each page's output separated by `----`.  
-Each page's output consists of text blocks starting with `<|box_start|>` and ending with `<|md_end|>`.  
-The meaning of each field is as follows:  
-- `<|box_start|>x0 y0 x1 y1<|box_end|>`  
-  x0 y0 x1 y1 represent the coordinates of a quadrilateral, indicating the top-left and bottom-right points. The values are based on a normalized page size of 1000x1000.
-- `<|ref_start|>type<|ref_end|>`  
-  `type` indicates the block type. Possible values are:
-  ```json
-  {
-      "text": "Text",
-      "title": "Title",
-      "image": "Image",
-      "image_caption": "Image Caption",
-      "image_footnote": "Image Footnote",
-      "table": "Table",
-      "table_caption": "Table Caption",
-      "table_footnote": "Table Footnote",
-      "equation": "Interline Equation"
-  }
-  ```
-- `<|md_start|>Markdown content<|md_end|>`  
-  This field contains the Markdown content of the block. If `type` is `text`, the end of the text may contain the `<|txt_contd|>` tag, indicating that this block can be connected with the following `text` block(s).
-  If `type` is `table`, the content is in `otsl` format and needs to be converted into HTML for rendering in Markdown.
+> [!NOTE]
+> Only applicable to VLM backend
 
-### some_pdf_middle.json
+**File naming format**: `{original_filename}_model_output.txt`
 
-| Field Name     | Description                                                                                                    |
-|:---------------| :------------------------------------------------------------------------------------------------------------- |
-| pdf_info       | list, each element is a dict representing the parsing result of each PDF page, see the table below for details |
-| \_backend      | pipeline \| vlm, used to indicate the mode used in this intermediate parsing state                                  |
-| \_version_name | string, indicates the version of mineru used in this parsing                                                |
+#### File Format Description
 
-<br>
+- Uses `----` to separate output results for each page
+- Each page contains multiple text blocks starting with `<|box_start|>` and ending with `<|md_end|>`
 
-**pdf_info**
+#### Field Meanings
 
-Field structure description
+| Tag | Format | Description |
+|-----|--------|-------------|
+| Bounding box | `<\|box_start\|>x0 y0 x1 y1<\|box_end\|>` | Quadrilateral coordinates (top-left, bottom-right points), coordinate values after scaling page to 1000×1000 |
+| Type tag | `<\|ref_start\|>type<\|ref_end\|>` | Content block type identifier |
+| Content | `<\|md_start\|>markdown content<\|md_end\|>` | Markdown content of the block |
 
-| Field Name          | Description                                                                                                        |
-| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
-| preproc_blocks      | Intermediate result after PDF preprocessing, not yet segmented                                                     |
-| layout_bboxes       | Layout segmentation results, containing layout direction (vertical, horizontal), and bbox, sorted by reading order |
-| page_idx            | Page number, starting from 0                                                                                       |
-| page_size           | Page width and height                                                                                              |
-| \_layout_tree       | Layout tree structure                                                                                              |
-| images              | list, each element is a dict representing an img_block                                                             |
-| tables              | list, each element is a dict representing a table_block                                                            |
-| interline_equations | list, each element is a dict representing an interline_equation_block                                              |
-| discarded_blocks    | List, block information returned by the model that needs to be dropped                                             |
-| para_blocks         | Result after segmenting preproc_blocks                                                                             |
+#### Supported Content Types
 
-In the above table, `para_blocks` is an array of dicts, each dict representing a block structure. A block can support up to one level of nesting.
-
-<br>
-
-**block**
-
-The outer block is referred to as a first-level block, and the fields in the first-level block include:
-
-| Field Name | Description                                                    |
-| :--------- | :------------------------------------------------------------- |
-| type       | Block type (table\|image)                                      |
-| bbox       | Block bounding box coordinates                                 |
-| blocks     | list, each element is a dict representing a second-level block |
-
-<br>
-There are only two types of first-level blocks: "table" and "image". All other blocks are second-level blocks.
+```json
+{
+    "text": "Text",
+    "title": "Title", 
+    "image": "Image",
+    "image_caption": "Image caption",
+    "image_footnote": "Image footnote",
+    "table": "Table",
+    "table_caption": "Table caption", 
+    "table_footnote": "Table footnote",
+    "equation": "Interline formula"
+}
+```
 
-The fields in a second-level block include:
+#### Special Tags
 
-| Field Name | Description                                                                                                 |
-| :--------- | :---------------------------------------------------------------------------------------------------------- |
-| type       | Block type                                                                                                  |
-| bbox       | Block bounding box coordinates                                                                              |
-| lines      | list, each element is a dict representing a line, used to describe the composition of a line of information |
+- `<|txt_contd|>`: Appears at the end of text, indicating that this text block can be connected with subsequent text blocks
+- Table content uses `otsl` format and needs to be converted to HTML for rendering in Markdown
 
-Detailed explanation of second-level block types
+### Intermediate Processing Results (middle.json)
 
-| type               | Description            |
-| :----------------- | :--------------------- |
-| image_body         | Main body of the image |
-| image_caption      | Image description text |
-| image_footnote     | Image footnote         |
-| table_body         | Main body of the table |
-| table_caption      | Table description text |
-| table_footnote     | Table footnote         |
-| text               | Text block             |
-| title              | Title block            |
-| index              | Index block            |
-| list               | List block             |
-| interline_equation | Block formula          |
+**File naming format**: `{original_filename}_middle.json`
 
-<br>
+#### Top-level Structure
 
-**line**
+| Field Name | Type | Description |
+|------------|------|-------------|
+| `pdf_info` | `list[dict]` | Array of parsing results for each page |
+| `_backend` | `string` | Parsing mode: `pipeline` or `vlm` |
+| `_version_name` | `string` | MinerU version number |
 
-The field format of a line is as follows:
+#### Page Information Structure (pdf_info)
 
 | Field Name | Description |
-| :--------- | :------------------------------------------------------------------------------------------------------ |
-| bbox       | Bounding box coordinates of the line                                                                    |
-| spans      | list, each element is a dict representing a span, used to describe the composition of the smallest unit |
+|------------|-------------|
+| `preproc_blocks` | Unsegmented intermediate results after PDF preprocessing |
+| `layout_bboxes` | Layout segmentation results, including layout direction and bounding boxes, sorted by reading order |
+| `page_idx` | Page number, starting from 0 |
+| `page_size` | Page width and height `[width, height]` |
+| `_layout_tree` | Layout tree structure |
+| `images` | Image block information list |
+| `tables` | Table block information list |
+| `interline_equations` | Interline formula block information list |
+| `discarded_blocks` | Block information to be discarded |
+| `para_blocks` | Content block results after segmentation |
+
+#### Block Structure Hierarchy
 
-<br>
+```
+Level 1 blocks (table | image)
+└── Level 2 blocks
+    └── Lines
+        └── Spans
+```
 
-**span**
+#### Level 1 Block Fields
 
 | Field Name | Description |
-| :------------------ | :------------------------------------------------------------------------------------------------------- |
-| bbox                | Bounding box coordinates of the span                                                                     |
-| type                | Type of the span                                                                                         |
-| content \| img_path | Text spans use content, chart spans use img_path to store the actual text or screenshot path information |
-
-The types of spans are as follows:
-
-| type               | Description    |
-| :----------------- | :------------- |
-| image              | Image          |
-| table              | Table          |
-| text               | Text           |
-| inline_equation    | Inline formula |
-| interline_equation | Block formula  |
-
-**Summary**
+|------------|-------------|
+| `type` | Block type: `table` or `image` |
+| `bbox` | Rectangular box coordinates of the block `[x0, y0, x1, y1]` |
+| `blocks` | List of contained level 2 blocks |
 
-A span is the smallest storage unit for all elements.
+#### Level 2 Block Fields
 
-The elements stored within para_blocks are block information.
-
-The block structure is as follows:
-
-First-level block (if any) -> Second-level block -> Line -> Span
-
-#### example
+| Field Name | Description |
+|------------|-------------|
+| `type` | Block type (see table below) |
+| `bbox` | Rectangular box coordinates of the block |
+| `lines` | List of contained line information |
+
+#### Level 2 Block Types
+
+| Type | Description |
+|------|-------------|
+| `image_body` | Image body |
+| `image_caption` | Image caption text |
+| `image_footnote` | Image footnote |
+| `table_body` | Table body |
+| `table_caption` | Table caption text |
+| `table_footnote` | Table footnote |
+| `text` | Text block |
+| `title` | Title block |
+| `index` | Index block |
+| `list` | List block |
+| `interline_equation` | Interline formula block |
+
+#### Line and Span Structure
+
+**Line fields**:
+- `bbox`: Rectangular box coordinates of the line
+- `spans`: List of contained spans
+
+**Span fields**:
+- `bbox`: Rectangular box coordinates of the span
+- `type`: Span type (`image`, `table`, `text`, `inline_equation`, `interline_equation`)
+- `content` | `img_path`: Text content or image path
+
+#### Sample Data
 
 ```json
 {
@@ -354,29 +388,37 @@ First-level block (if any) -> Second-level block -> Line -> Span
 }
 ```
 
+### Content List (content_list.json)
 
-### some_pdf_content_list.json
+**File naming format**: `{original_filename}_content_list.json`
 
-This file is a JSON array where each element is a dict storing all readable content blocks in the document in reading order.  
-`content_list` can be viewed as a simplified version of `middle.json`. The content block types are mostly consistent with those in `middle.json`, but layout information is not included.  
+#### Functionality
 
-The content has the following types:
+This is a simplified version of `middle.json` that stores all readable content blocks in reading order as a flat structure, removing complex layout information for easier subsequent processing.
 
-| type     | desc          |
-|:---------|:--------------|
-| image    | Image         |
-| table    | Table         |
-| text     | Text / Title  |
-| equation | Block formula |
+#### Content Types
 
-Please note that both `title` and text blocks in `content_list` are uniformly represented using the text type. The `text_level` field is used to distinguish the hierarchy of text blocks:
-- A block without the `text_level` field or with `text_level=0` represents body text.
-- A block with `text_level=1` represents a level-1 heading.
-- A block with `text_level=2` represents a level-2 heading, and so on.
+| Type | Description |
+|------|-------------|
+| `image` | Image |
+| `table` | Table |
+| `text` | Text/Title |
+| `equation` | Interline formula |
 
-Each content contains the `page_idx` field, indicating the page number (starting from 0) where the content block resides.
+#### Text Level Identification
 
-#### example
+Text levels are distinguished through the `text_level` field:
+
+- No `text_level` or `text_level: 0`: Body text
+- `text_level: 1`: Level 1 heading
+- `text_level: 2`: Level 2 heading
+- And so on...
+
+#### Common Fields
+
+All content blocks include a `page_idx` field indicating the page number (starting from 0).
+
+#### Sample Data
 
 ```json
 [
@@ -438,3 +480,12 @@ Each content contains the `page_idx` field, indicating the page number (starting
     }
 ]
 ```
+
+## Summary
+
+The above files constitute MinerU's complete output results. Users can choose appropriate files for subsequent processing based on their needs:
+
+- **Model outputs**: Use raw outputs (model.json, model_output.txt)
+- **Debugging and verification**: Use visualization files (layout.pdf, spans.pdf) 
+- **Content extraction**: Use simplified files (*.md, content_list.json)
+- **Secondary development**: Use structured files (middle.json)

docs/en/usage/advanced_cli_parameters.md

+# Advanced Command Line Parameters
+
+## SGLang Acceleration Parameter Optimization
+
+### Memory Optimization Parameters
+> [!TIP]
+> SGLang acceleration mode currently supports running on Turing architecture graphics cards with a minimum of 8GB VRAM, but graphics cards with <24GB VRAM may encounter insufficient memory issues. You can optimize memory usage with the following parameters:
+> 
+> - If you encounter insufficient VRAM when using a single graphics card, you may need to reduce the KV cache size with `--mem-fraction-static 0.5`. If VRAM issues persist, try reducing it further to `0.4` or lower.
+> - If you have two or more graphics cards, you can try using tensor parallelism (TP) mode to simply expand available VRAM: `--tp-size 2`
+
+### Performance Optimization Parameters
+> [!TIP]
+> If you can already use SGLang normally for accelerated VLM model inference but still want to further improve inference speed, you can try the following parameters:
+> 
+> - If you have multiple graphics cards, you can use SGLang's multi-card parallel mode to increase throughput: `--dp-size 2`
+> - You can also enable `torch.compile` to accelerate inference speed by approximately 15%: `--enable-torch-compile`
+
+### Parameter Passing Instructions
+> [!TIP]
+> - All officially supported SGLang parameters can be passed to MinerU through command line arguments, including the following commands: `mineru`, `mineru-sglang-server`, `mineru-gradio`, `mineru-api`
+> - If you want to learn more about `sglang` parameter usage, please refer to the [SGLang official documentation](https://docs.sglang.ai/backend/server_arguments.html#common-launch-commands)
+
+## GPU Device Selection and Configuration
+
+### CUDA_VISIBLE_DEVICES Basic Usage
+> [!TIP]
+> - In any situation, you can specify visible GPU devices by adding the `CUDA_VISIBLE_DEVICES` environment variable at the beginning of the command line. For example:
+>   ```bash
+>   CUDA_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path>
+>   ```
+> - This specification method is effective for all command line calls, including `mineru`, `mineru-sglang-server`, `mineru-gradio`, and `mineru-api`, and applies to both `pipeline` and `vlm` backends.
+
+### Common Device Configuration Examples
+> [!TIP]
+> Here are some common `CUDA_VISIBLE_DEVICES` setting examples:
+>   ```bash
+>   CUDA_VISIBLE_DEVICES=1  # Only device 1 will be seen
+>   CUDA_VISIBLE_DEVICES=0,1  # Devices 0 and 1 will be visible
+>   CUDA_VISIBLE_DEVICES="0,1"  # Same as above, quotation marks are optional
+>   CUDA_VISIBLE_DEVICES=0,2,3  # Devices 0, 2, 3 will be visible; device 1 is masked
+>   CUDA_VISIBLE_DEVICES=""  # No GPU will be visible
+>   ```
+
+## Practical Application Scenarios
+> [!TIP]
+> Here are some possible usage scenarios:
+> 
+> - If you have multiple graphics cards and need to specify cards 0 and 1, using multi-card parallelism to start `sglang-server`, you can use the following command:
+>   ```bash
+>   CUDA_VISIBLE_DEVICES=0,1 mineru-sglang-server --port 30000 --dp-size 2
+>   ```
+> 
+> - If you have multiple GPUs and need to specify GPU 0–3, and start the `sglang-server` using multi-GPU data parallelism and tensor parallelism, you can use the following command:
+>   ```bash
+>   CUDA_VISIBLE_DEVICES=0,1,2,3 mineru-sglang-server --port 30000 --dp-size 2 --tp-size 2
+>   ```
+>       
+> - If you have multiple graphics cards and need to start two `fastapi` services on cards 0 and 1, listening on different ports respectively, you can use the following commands:
+>   ```bash
+>   # In terminal 1
+>   CUDA_VISIBLE_DEVICES=0 mineru-api --host 127.0.0.1 --port 8000
+>   # In terminal 2
+>   CUDA_VISIBLE_DEVICES=1 mineru-api --host 127.0.0.1 --port 8001
+>   ```

docs/en/usage/cli_tools.md

+# Command Line Tools Usage Instructions
+
+## View Help Information
+To view help information for MinerU command line tools, you can use the `--help` parameter. Here are help information examples for various command line tools:
+```bash
+mineru --help
+Usage: mineru [OPTIONS]
+
+Options:
+  -v, --version                   Show version and exit
+  -p, --path PATH                 Input file path or directory (required)
+  -o, --output PATH               Output directory (required)
+  -m, --method [auto|txt|ocr]     Parsing method: auto (default), txt, ocr (pipeline backend only)
+  -b, --backend [pipeline|vlm-transformers|vlm-sglang-engine|vlm-sglang-client]
+                                  Parsing backend (default: pipeline)
+  -l, --lang [ch|ch_server|ch_lite|en|korean|japan|chinese_cht|ta|te|ka|latin|arabic|east_slavic|cyrillic|devanagari]
+                                  Specify document language (improves OCR accuracy, pipeline backend only)
+  -u, --url TEXT                  Service address when using sglang-client
+  -s, --start INTEGER             Starting page number for parsing (0-based)
+  -e, --end INTEGER               Ending page number for parsing (0-based)
+  -f, --formula BOOLEAN           Enable formula parsing (default: enabled)
+  -t, --table BOOLEAN             Enable table parsing (default: enabled)
+  -d, --device TEXT               Inference device (e.g., cpu/cuda/cuda:0/npu/mps, pipeline backend only)
+  --vram INTEGER                  Maximum GPU VRAM usage per process (GB) (pipeline backend only)
+  --source [huggingface|modelscope|local]
+                                  Model source, default: huggingface
+  --help                          Show help information
+```
+```bash
+mineru-api --help
+Usage: mineru-api [OPTIONS]
+
+Options:
+  --host TEXT     Server host (default: 127.0.0.1)
+  --port INTEGER  Server port (default: 8000)
+  --reload        Enable auto-reload (development mode)
+  --help          Show this message and exit.
+```
+```bash
+mineru-gradio --help
+Usage: mineru-gradio [OPTIONS]
+
+Options:
+  --enable-example BOOLEAN        Enable example files for input. The example
+                                  files to be input need to be placed in the
+                                  `example` folder within the directory where
+                                  the command is currently executed.
+  --enable-sglang-engine BOOLEAN  Enable SgLang engine backend for faster
+                                  processing.
+  --enable-api BOOLEAN            Enable gradio API for serving the
+                                  application.
+  --max-convert-pages INTEGER     Set the maximum number of pages to convert
+                                  from PDF to Markdown.
+  --server-name TEXT              Set the server name for the Gradio app.
+  --server-port INTEGER           Set the server port for the Gradio app.
+  --latex-delimiters-type [a|b|all]
+                                  Set the type of LaTeX delimiters to use in
+                                  Markdown rendering: 'a' for type '$', 'b' for
+                                  type '()[]', 'all' for both types.
+  --help                          Show this message and exit.
+```
+
+## Environment Variables Description
+
+Some parameters of MinerU command line tools have equivalent environment variable configurations. Generally, environment variable configurations have higher priority than command line parameters and take effect across all command line tools.
+Here are the environment variables and their descriptions:
+
+- `MINERU_DEVICE_MODE`: Used to specify inference device, supports device types like `cpu/cuda/cuda:0/npu/mps`, only effective for `pipeline` backend.
+- `MINERU_VIRTUAL_VRAM_SIZE`: Used to specify maximum GPU VRAM usage per process (GB), only effective for `pipeline` backend.
+- `MINERU_MODEL_SOURCE`: Used to specify model source, supports `huggingface/modelscope/local`, defaults to `huggingface`, can be switched to `modelscope` or local models through environment variables.
+- `MINERU_TOOLS_CONFIG_JSON`: Used to specify configuration file path, defaults to `mineru.json` in user directory, can specify other configuration file paths through environment variables.
+- `MINERU_FORMULA_ENABLE`: Used to enable formula parsing, defaults to `true`, can be set to `false` through environment variables to disable formula parsing.
+- `MINERU_TABLE_ENABLE`: Used to enable table parsing, defaults to `true`, can be set to `false` through environment variables to disable table parsing.

docs/en/usage/index.md

+# Usage Guide
+
+This section provides comprehensive usage instructions for the project. We will help you progressively master the project's usage from basic to advanced through the following sections:
+
+## Table of Contents
+
+- [Quick Usage](./quick_usage.md) - Quick setup and basic usage
+- [Model Source Configuration](./model_source.md) - Detailed configuration instructions for model sources
+- [Command Line Tools](./cli_tools.md) - Detailed parameter descriptions for command line tools
+- [Advanced Optimization Parameters](./advanced_cli_parameters.md) - Advanced parameter descriptions for command line tool adaptation
+
+## Getting Started
+
+We recommend reading the documentation in the order listed above, which will help you better understand and use the project features.
+
+If you encounter issues during usage, please check the [FAQ](../faq/index.md)
\ No newline at end of file