- 
+ 
+
## 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, MinerU is still young. If you encounter any issues or if the results are not as expected, please submit an issue on [issue](https://github.com/opendatalab/MinerU/issues) and **attach the relevant PDF**.
+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**.
+
## Key Features
-- Remove headers, footers, footnotes, page numbers, etc., to ensure semantic coherence.
-- Output text in human-readable order, suitable for single-column, multi-column, and complex layouts.
-- Preserve the structure of the original document, including headings, paragraphs, lists, etc.
-- Extract images, image descriptions, tables, table titles, and footnotes.
-- Automatically recognize and convert formulas in the document to LaTeX format.
-- Automatically recognize and convert tables in the document to HTML format.
-- Automatically detect scanned PDFs and garbled PDFs and enable OCR functionality.
-- OCR supports detection and recognition of 84 languages.
-- Supports multiple output formats, such as multimodal and NLP Markdown, JSON sorted by reading order, and rich intermediate formats.
-- Supports various visualization results, including layout visualization and span visualization, for efficient confirmation of output quality.
-- Supports running in a pure CPU environment, and also supports GPU(CUDA)/NPU(CANN)/MPS acceleration
-- Compatible with Windows, Linux, and Mac platforms.
\ No newline at end of file
+- 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)
diff --git a/docs/en/quick_start/docker_deployment.md b/docs/en/quick_start/docker_deployment.md
new file mode 100644
index 00000000..e1c9ed7f
--- /dev/null
+++ b/docs/en/quick_start/docker_deployment.md
@@ -0,0 +1,68 @@
+# 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/china/Dockerfile
+docker build -t mineru-sglang:latest -f Dockerfile .
+```
+
+> [!TIP]
+> The [Dockerfile](https://github.com/opendatalab/MinerU/blob/master/docker/china/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 [MinerU Usage Documentation](../usage/index.md).
+
+## Start Services Directly with Docker Compose
+
+We provide a `compose.yml` 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
+```
+
+- Start `sglang-server` service and connect to `sglang-server` via `vlm-sglang-client` backend:
+ ```bash
+ docker compose -f compose.yaml --profile mineru-sglang-server up -d
+ # In another terminal, connect to sglang server via sglang client (only requires CPU and network, no sglang environment needed)
+ mineru -p
-PDF-Extract-Kit: High-Quality PDF Extraction Toolkit🔥🔥🔥
-
-
-🚀Access MinerU Now→✅ Zero-Install Web Version ✅ Full-Featured Desktop Client ✅ Instant API Access; Skip deployment headaches – get all product formats in one click. Developers, dive in!
+🚀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!
| Operating System | -windows/linux/mac | -windows/linux | -windows(wsl2)/linux | +Linux / Windows / macOS | +Linux / Windows | +Linux / Windows (via WSL2) |
| CPU Inference Support | @@ -41,12 +42,12 @@ There are three different ways to experience MinerU:||||||
| GPU Requirements | -Turing architecture or later, 6GB+ VRAM or Apple Silicon | -Ampere architecture or later, 8GB+ VRAM | +Turing architecture and later, 6GB+ VRAM or Apple Silicon | +Turing architecture and later, 8GB+ VRAM | ||
| Memory Requirements | -Minimum 16GB+, 32GB+ recommended | +Minimum 16GB+, recommended 32GB+ | ||||
| Disk Space Requirements | @@ -56,4 +57,32 @@ There are three different ways to experience MinerU:Python Version | 3.10-3.13 | ||||
+
-o -b vlm-sglang-client -u http://:30000
+ ```
+- 启动 API 服务：
+ ```bash
+ docker compose -f compose.yaml --profile mineru-api up -d
+ ```
+ 在浏览器中访问 `http://:8000/docs` 查看API文档。
+- 启动 Gradio WebUI 服务：
+ ```bash
+ docker compose -f compose.yaml --profile mineru-gradio up -d
+ ```
+ 在浏览器中访问 `http://:7860` 使用 Gradio WebUI 或访问 `http://:7860/?view=api` 使用 Gradio API。
\ No newline at end of file
diff --git a/docs/zh/quick_start/extension_modules.md b/docs/zh/quick_start/extension_modules.md
new file mode 100644
index 00000000..fc6f7f5a
--- /dev/null
+++ b/docs/zh/quick_start/extension_modules.md
@@ -0,0 +1,37 @@
+# MinerU 扩展模块安装指南
+MinerU 支持根据不同需求，按需安装扩展模块，以增强功能或支持特定的模型后端。
+
+## 常见场景
+
+### 核心功能安装
+`core` 模块是 MinerU 的核心依赖，包含了除`sglang`外的所有功能模块。安装此模块可以确保 MinerU 的基本功能正常运行。
+```bash
+uv pip install mineru[core]
+```
+
+---
+
+### 使用`sglang`加速 VLM 模型推理
+`sglang` 模块提供了对 VLM 模型推理的加速支持，适用于具有 Turing 及以后架构的显卡（8G 显存及以上）。安装此模块可以显著提升模型推理速度。
+在配置中，`all`包含了`core`和`sglang`模块，因此`mineru[all]`和`mineru[core,sglang]`是等价的。
+```bash
+uv pip install mineru[all]
+```
+> [!TIP]
+> 如在安装包含sglang的完整包过程中发生异常，请参考 [sglang 官方文档](https://docs.sglang.ai/start/install.html) 尝试解决，或直接使用 [Docker](./docker_deployment.md) 方式部署镜像。
+
+---
+
+### 安装轻量版client连接sglang-server使用
+如果您需要在边缘设备上安装轻量版的 client 端以连接 `sglang-server`，可以安装mineru的基础包，非常轻量，适合在只有cpu和网络连接的设备上使用。
+```bash
+uv pip install mineru
+```
+
+---
+
+### 在过时的linux系统上使用pipeline后端
+如果您的系统过于陈旧，无法满足`mineru[core]`的依赖要求，该选项可以最低限度的满足 MinerU 的运行需求，适用于老旧系统无法升级且仅需使用 pipeline 后端的场景。
+```bash
+uv pip install mineru[pipeline_old_linux]
+```
\ No newline at end of file
diff --git a/docs/zh/quick_start/index.md b/docs/zh/quick_start/index.md
index 3f8ba2d3..f308e3e5 100644
--- a/docs/zh/quick_start/index.md
+++ b/docs/zh/quick_start/index.md
@@ -2,15 +2,16 @@
如果遇到任何安装问题，请先查询 [FAQ](../FAQ/index.md)
+## 在线体验
-如果遇到解析效果不及预期，参考 [Known Issues](../known_issues.md)
+- 官网在线demo：官网在线版功能与客户端一致，界面美观，功能丰富，需要登录使用
+ - [](https://mineru.net/OpenSourceTools/Extractor?source=github)
+- 基于Gradio的在线demo：基于gradio开发的webui，界面简洁，仅包含核心解析功能，免登录
+ - [](https://www.modelscope.cn/studios/OpenDataLab/MinerU)
+ - [](https://huggingface.co/spaces/opendatalab/MinerU)
-有2种不同方式可以体验MinerU的效果：
-
-- [在线体验](online_demo.md)
-- [本地部署](local_deployment.md)
-
+## 本地部署
> [!WARNING]
> **安装前必看——软硬件环境支持说明**
@@ -30,9 +31,9 @@
操作系统
- windows/linux/mac
- windows/linux
- windows(wsl2)/linux
+ Linux / Windows / macOS
+ Linux / Windows
+ Linux / Windows (via WSL2)
CPU推理支持
@@ -42,7 +43,7 @@
GPU要求
Turing及以后架构，6G显存以上或Apple Silicon
- Ampere及以后架构，8G显存以上
+ Turing及以后架构，8G显存以上
内存要求
@@ -56,4 +57,32 @@
python版本
3.10-3.13
-
\ No newline at end of file
+
+
+### 安装 MinerU
+
+#### 使用pip或uv安装MinerU
+```bash
+pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
+pip install uv -i https://mirrors.aliyun.com/pypi/simple
+uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
+```
+
+#### 通过源码安装MinerU
+```bash
+git clone https://github.com/opendatalab/MinerU.git
+cd MinerU
+uv pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple
+```
+
+> [!TIP]
+> `mineru[core]`包含除`sglang`加速外的所有核心功能，兼容Windows / Linux / macOS系统，适合绝大多数用户。
+> 如果您有使用`sglang`加速VLM模型推理，或是在边缘设备安装轻量版client端等需求，可以参考文档[安装扩展模块指南](./extension_modules.md)。
+
+---
+
+#### 使用docker部署Mineru
+MinerU提供了便捷的docker部署方式，这有助于快速搭建环境并解决一些棘手的环境兼容问题。
+您可以在文档中获取[Docker部署说明](./docker_deployment.md)。
+
+---
\ No newline at end of file
diff --git a/docs/zh/quick_start/local_deployment.md b/docs/zh/quick_start/local_deployment.md
deleted file mode 100644
index 9594aa19..00000000
--- a/docs/zh/quick_start/local_deployment.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# 本地部署
-
-## 安装 MinerU
-
-### 使用 pip 或 uv 安装
-
-```bash
-pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
-pip install uv -i https://mirrors.aliyun.com/pypi/simple
-uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
-```
-
-### 源码安装
-
-```bash
-git clone https://github.com/opendatalab/MinerU.git
-cd MinerU
-uv pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple
-```
-
-> [!NOTE]
-> Linux和macOS系统安装后自动支持cuda/mps加速，Windows用户如需使用cuda加速，
-> 请前往 [Pytorch官网](https://pytorch.org/get-started/locally/) 选择合适的cuda版本安装pytorch。
-
-### 安装完整版（支持 sglang 加速）（需确保设备有Turing及以后架构，8G显存及以上显卡）
-
-如需使用 **sglang 加速 VLM 模型推理**，请选择合适的方式安装完整版本：
-
-- 使用uv或pip安装
- ```bash
- uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
- ```
-- 从源码安装：
- ```bash
- uv pip install -e .[all] -i https://mirrors.aliyun.com/pypi/simple
- ```
-
-> [!TIP]
-> sglang安装过程中如发生异常，请参考[sglang官方文档](https://docs.sglang.ai/start/install.html)尝试解决或直接使用docker方式安装。
-
-- 使用 Dockerfile 构建镜像：
- ```bash
- wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfile
- docker build -t mineru-sglang:latest -f Dockerfile .
- ```
- 启动 Docker 容器：
- ```bash
- docker run --gpus all \
- --shm-size 32g \
- -p 30000:30000 \
- --ipc=host \
- mineru-sglang:latest \
- mineru-sglang-server --host 0.0.0.0 --port 30000
- ```
- 或使用 Docker Compose 启动：
- ```bash
- wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml
- docker compose -f compose.yaml up -d
- ```
-
-> [!TIP]
-> Dockerfile默认使用`lmsysorg/sglang:v0.4.8.post1-cu126`作为基础镜像，支持Turing/Ampere/Ada Lovelace/Hopper平台，
-> 如您使用较新的`Blackwell`平台，请将基础镜像修改为`lmsysorg/sglang:v0.4.8.post1-cu128-b200`。
-
-### 安装client（用于在仅需 CPU 和网络连接的边缘设备上连接 sglang-server）
-
-```bash
-uv pip install -U mineru -i https://mirrors.aliyun.com/pypi/simple
-mineru -p -o -b vlm-sglang-client -u http://:
-```
-
----
\ No newline at end of file
diff --git a/docs/zh/quick_start/online_demo.md b/docs/zh/quick_start/online_demo.md
deleted file mode 100644
index 8e1b738e..00000000
--- a/docs/zh/quick_start/online_demo.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# 在线体验
-
-[](https://mineru.net/OpenSourceTools/Extractor?source=github)
-[](https://www.modelscope.cn/studios/OpenDataLab/MinerU)
-[](https://huggingface.co/spaces/opendatalab/MinerU)
\ No newline at end of file
diff --git a/docs/zh/todo.md b/docs/zh/todo.md
deleted file mode 100644
index 76bf6b7c..00000000
--- a/docs/zh/todo.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# TODO
-
-- [x] 基于模型的阅读顺序
-- [x] 正文中目录、列表识别
-- [x] 表格识别
-- [x] 标题分级
-- [ ] 正文中代码块识别
-- [ ] [化学式识别](../chemical_knowledge_introduction/introduction.pdf)
-- [ ] 几何图形识别
\ No newline at end of file
diff --git a/docs/zh/usage/advanced_cli_parameters.md b/docs/zh/usage/advanced_cli_parameters.md
new file mode 100644
index 00000000..042b409b
--- /dev/null
+++ b/docs/zh/usage/advanced_cli_parameters.md
@@ -0,0 +1,56 @@
+# 命令行参数进阶技巧
+
+## SGLang 加速参数优化
+
+### 显存优化参数
+> [!TIP]
+>sglang加速模式目前支持在最低8G显存的Turing架构显卡上运行，但在显存<24G的显卡上可能会遇到显存不足的问题, 可以通过使用以下参数来优化显存使用：
+>- 如果您使用单张显卡遇到显存不足的情况时，可能需要调低KV缓存大小，`--mem-fraction-static 0.5`，如仍出现显存不足问题，可尝试进一步降低到`0.4`或更低。
+>- 如您有两张以上显卡，可尝试通过张量并行（TP）模式简单扩充可用显存：`--tp-size 2`
+
+### 性能优化参数
+> [!TIP]
+>如果您已经可以正常使用sglang对vlm模型进行加速推理，但仍然希望进一步提升推理速度，可以尝试以下参数：
+>- 如果您有超过多张显卡，可以使用sglang的多卡并行模式来增加吞吐量：`--dp-size 2`
+>- 同时您可以启用`torch.compile`来将推理速度加速约15%：`--enable-torch-compile`
+
+### 参数传递说明
+> [!TIP]
+>- 如果您想了解更多有关`sglang`的参数使用方法，请参考 [sglang官方文档](https://docs.sglang.ai/backend/server_arguments.html#common-launch-commands)
+>- 所有sglang官方支持的参数都可用通过命令行参数传递给 MinerU，包括以下命令:`mineru`、`mineru-sglang-server`、`mineru-gradio`、`mineru-api`
+
+## GPU 设备选择与配置
+
+### CUDA_VISIBLE_DEVICES 基本用法
+> [!TIP]
+> - 任何情况下，您都可以通过在命令行的开头添加`CUDA_VISIBLE_DEVICES` 环境变量来指定可见的 GPU 设备。例如：
+> ```bash
+> CUDA_VISIBLE_DEVICES=1 mineru -p -o
+> ```
+> - 这种指定方式对所有的命令行调用都有效，包括 `mineru`、`mineru-sglang-server`、`mineru-gradio` 和 `mineru-api`，且对`pipeline`、`vlm`后端均适用。
+
+### 常见设备配置示例
+> [!TIP]
+> - 以下是一些常见的 `CUDA_VISIBLE_DEVICES` 设置示例：
+> ```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
+> ```
+
+### 实际应用场景
+> [!TIP]
+>以下是一些可能的使用场景：
+>- 如果您有多张显卡，需要指定卡0和卡1，并使用多卡并行来启动'sglang-server'，可以使用以下命令：
+> ```bash
+> CUDA_VISIBLE_DEVICES=0,1 mineru-sglang-server --port 30000 --dp-size 2
+> ```
+>- 如果您有多张显卡，需要在卡0和卡1上启动两个`fastapi`服务，并分别监听不同的端口，可以使用以下命令：
+> ```bash
+> # 在终端1中
+> CUDA_VISIBLE_DEVICES=0 mineru-api --host 127.0.0.1 --port 8000
+> # 在终端2中
+> CUDA_VISIBLE_DEVICES=1 mineru-api --host 127.0.0.1 --port 8001
+> ```
diff --git a/docs/zh/usage/api.md b/docs/zh/usage/api.md
deleted file mode 100644
index 3f1ca4f0..00000000
--- a/docs/zh/usage/api.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# API 调用 或 可视化调用
-
-1. 使用python api直接调用：[Python 调用示例](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py)
-2. 使用fast api方式调用：
- ```bash
- mineru-api --host 127.0.0.1 --port 8000
- ```
- 在浏览器中访问 http://127.0.0.1:8000/docs 查看API文档。
-
-3. 使用gradio webui 或 gradio api调用
- ```bash
- # 使用 pipeline/vlm-transformers/vlm-sglang-client 后端
- mineru-gradio --server-name 127.0.0.1 --server-port 7860
- # 或使用 vlm-sglang-engine/pipeline 后端
- mineru-gradio --server-name 127.0.0.1 --server-port 7860 --enable-sglang-engine true
- ```
- 在浏览器中访问 http://127.0.0.1:7860 使用 Gradio WebUI 或访问 http://127.0.0.1:7860/?view=api 使用 Gradio API。
-
-> [!TIP]
-> - 以下是一些使用sglang加速模式的建议和注意事项：
-> - sglang加速模式目前支持在最低8G显存的Turing架构显卡上运行，但在显存<24G的显卡上可能会遇到显存不足的问题, 可以通过使用以下参数来优化显存使用：
-> - 如果您使用单张显卡遇到显存不足的情况时，可能需要调低KV缓存大小，`--mem-fraction-static 0.5`，如仍出现显存不足问题，可尝试进一步降低到`0.4`或更低。
-> - 如您有两张以上显卡，可尝试通过张量并行（TP）模式简单扩充可用显存：`--tp-size 2`
-> - 如果您已经可以正常使用sglang对vlm模型进行加速推理，但仍然希望进一步提升推理速度，可以尝试以下参数：
-> - 如果您有超过多张显卡，可以使用sglang的多卡并行模式来增加吞吐量：`--dp-size 2`
-> - 同时您可以启用`torch.compile`来将推理速度加速约15%：`--enable-torch-compile`
-> - 如果您想了解更多有关`sglang`的参数使用方法，请参考 [sglang官方文档](https://docs.sglang.ai/backend/server_arguments.html#common-launch-commands)
-> - 所有sglang官方支持的参数都可用通过命令行参数传递给 MinerU，包括以下命令:`mineru`、`mineru-sglang-server`、`mineru-gradio`、`mineru-api`
-
-> [!TIP]
-> - 任何情况下，您都可以通过在命令行的开头添加`CUDA_VISIBLE_DEVICES` 环境变量来指定可见的 GPU 设备。例如：
-> ```bash
-> CUDA_VISIBLE_DEVICES=1 mineru -p -o
-> ```
-> - 这种指定方式对所有的命令行调用都有效，包括 `mineru`、`mineru-sglang-server`、`mineru-gradio` 和 `mineru-api`，且对`pipeline`、`vlm`后端均适用。
-> - 以下是一些常见的 `CUDA_VISIBLE_DEVICES` 设置示例：
-> ```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
-> ```
-> - 以下是一些可能的使用场景：
-> - 如果您有多张显卡，需要指定卡0和卡1，并使用多卡并行来启动'sglang-server'，可以使用以下命令：
-> ```bash
-> CUDA_VISIBLE_DEVICES=0,1 mineru-sglang-server --port 30000 --dp-size 2
-> ```
-> - 如果您有多张显卡，需要在卡0和卡1上启动两个`fastapi`服务，并分别监听不同的端口，可以使用以下命令：
-> ```bash
-> # 在终端1中
-> CUDA_VISIBLE_DEVICES=0 mineru-api --host 127.0.0.1 --port 8000
-> # 在终端2中
-> CUDA_VISIBLE_DEVICES=1 mineru-api --host 127.0.0.1 --port 8001
-> ```
-
----
diff --git a/docs/zh/usage/cli_tools.md b/docs/zh/usage/cli_tools.md
new file mode 100644
index 00000000..7f010e23
--- /dev/null
+++ b/docs/zh/usage/cli_tools.md
@@ -0,0 +1,73 @@
+# 命令行工具使用说明
+
+## 查看帮助信息
+要查看 MinerU 命令行工具的帮助信息，可以使用 `--help` 参数。以下是各个命令行工具的帮助信息示例：
+```bash
+mineru --help
+Usage: mineru [OPTIONS]
+
+Options:
+ -v, --version 显示版本并退出
+ -p, --path PATH 输入文件路径或目录（必填）
+ -o, --output PATH 输出目录（必填）
+ -m, --method [auto|txt|ocr] 解析方法：auto（默认）、txt、ocr（仅用于 pipeline 后端）
+ -b, --backend [pipeline|vlm-transformers|vlm-sglang-engine|vlm-sglang-client]
+ 解析后端（默认为 pipeline）
+ -l, --lang [ch|ch_server|ch_lite|en|korean|japan|chinese_cht|ta|te|ka|latin|arabic|east_slavic|cyrillic|devanagari]
+ 指定文档语言（可提升 OCR 准确率，仅用于 pipeline 后端）
+ -u, --url TEXT 当使用 sglang-client 时，需指定服务地址
+ -s, --start INTEGER 开始解析的页码（从 0 开始）
+ -e, --end INTEGER 结束解析的页码（从 0 开始）
+ -f, --formula BOOLEAN 是否启用公式解析（默认开启）
+ -t, --table BOOLEAN 是否启用表格解析（默认开启）
+ -d, --device TEXT 推理设备（如 cpu/cuda/cuda:0/npu/mps，仅 pipeline 后端）
+ --vram INTEGER 单进程最大 GPU 显存占用(GB)（仅 pipeline 后端）
+ --source [huggingface|modelscope|local]
+ 模型来源，默认 huggingface
+ --help 显示帮助信息
+```
+```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.
+```
+
+## 环境变量说明
+
+MinerU命令行工具的某些参数存在相同功能的环境变量配置，通常环境变量配置的优先级高于命令行参数，且在所有命令行工具中都生效。
+- `MINERU_DEVICE_MODE`：用于指定推理设备，支持`cpu/cuda/cuda:0/npu/mps`等设备类型，仅对`pipeline`后端生效。
+- `MINERU_VIRTUAL_VRAM_SIZE`：用于指定单进程最大 GPU 显存占用(GB)，仅对`pipeline`后端生效。
+- `MINERU_MODEL_SOURCE`：用于指定模型来源，支持`huggingface/modelscope/local`，默认为`huggingface`，可通过环境变量切换为`modelscope`或使用本地模型。
+- `MINERU_TOOLS_CONFIG_JSON`：用于指定配置文件路径，默认为用户目录下的`mineru.json`，可通过环境变量指定其他配置文件路径。
+- `MINERU_FORMULA_ENABLE`：用于启用公式解析，默认为`true`，可通过环境变量设置为`false`来禁用公式解析。
+- `MINERU_TABLE_ENABLE`：用于启用表格解析，默认为`true`，可通过环境变量设置为`false`来禁用表格解析。
+
+
diff --git a/docs/zh/usage/config.md b/docs/zh/usage/config.md
deleted file mode 100644
index 86083e64..00000000
--- a/docs/zh/usage/config.md
+++ /dev/null
@@ -1,11 +0,0 @@
-
-# 基于配置文件扩展 MinerU 功能
-
-- MinerU 现已实现开箱即用，但也支持通过配置文件扩展功能。您可以在用户目录下创建 `mineru.json` 文件，添加自定义配置。
-- `mineru.json` 文件会在您使用内置模型下载命令 `mineru-models-download` 时自动生成，也可以通过将[配置模板文件](../../mineru.template.json)复制到用户目录下并重命名为 `mineru.json` 来创建。
-- 以下是一些可用的配置选项：
- - `latex-delimiter-config`：用于配置 LaTeX 公式的分隔符，默认为`$`符号，可根据需要修改为其他符号或字符串。
- - `llm-aided-config`：用于配置 LLM 辅助标题分级的相关参数，兼容所有支持`openai协议`的 LLM 模型，默认使用`阿里云百炼`的`qwen2.5-32b-instruct`模型，您需要自行配置 API 密钥并将`enable`设置为`true`来启用此功能。
- - `models-dir`：用于指定本地模型存储目录，请为`pipeline`和`vlm`后端分别指定模型目录，指定目录后您可通过配置环境变量`export MINERU_MODEL_SOURCE=local`来使用本地模型。
-
----
\ No newline at end of file
diff --git a/docs/zh/usage/index.md b/docs/zh/usage/index.md
index 62d6235d..5a37a82a 100644
--- a/docs/zh/usage/index.md
+++ b/docs/zh/usage/index.md
@@ -1,125 +1,74 @@
# 使用 MinerU
-## 命令行使用方式
-
-### 基础用法
-
-最简单的命令行调用方式如下：
-
-```bash
-mineru -p -o
-```
-
-- ``：本地 PDF/图片 文件或目录（支持 pdf/png/jpg/jpeg/webp/gif）
-- ``：输出目录
-
-### 查看帮助信息
-
-获取所有可用参数说明：
-
-```bash
-mineru --help
-```
-
-### 参数详解
-
-```text
-Usage: mineru [OPTIONS]
-
-Options:
- -v, --version 显示版本并退出
- -p, --path PATH 输入文件路径或目录（必填）
- -o, --output PATH 输出目录（必填）
- -m, --method [auto|txt|ocr] 解析方法：auto（默认）、txt、ocr（仅用于 pipeline 后端）
- -b, --backend [pipeline|vlm-transformers|vlm-sglang-engine|vlm-sglang-client]
- 解析后端（默认为 pipeline）
- -l, --lang [ch|ch_server|ch_lite|en|korean|japan|chinese_cht|ta|te|ka|latin|arabic|east_slavic|cyrillic|devanagari]
- 指定文档语言（可提升 OCR 准确率，仅用于 pipeline 后端）
- -u, --url TEXT 当使用 sglang-client 时，需指定服务地址
- -s, --start INTEGER 开始解析的页码（从 0 开始）
- -e, --end INTEGER 结束解析的页码（从 0 开始）
- -f, --formula BOOLEAN 是否启用公式解析（默认开启）
- -t, --table BOOLEAN 是否启用表格解析（默认开启）
- -d, --device TEXT 推理设备（如 cpu/cuda/cuda:0/npu/mps，仅 pipeline 后端）
- --vram INTEGER 单进程最大 GPU 显存占用(GB)（仅 pipeline 后端）
- --source [huggingface|modelscope|local]
- 模型来源，默认 huggingface
- --help 显示帮助信息
-```
-
----
-
-## 模型源配置
-
-MinerU 默认在首次运行时自动从 HuggingFace 下载所需模型。若无法访问 HuggingFace，可通过以下方式切换模型源：
-
-### 切换至 ModelScope 源
-
-```bash
-mineru -p -o --source modelscope
-```
-
-或设置环境变量：
-
+## 快速配置模型源
+MinerU默认使用`huggingface`作为模型源，若用户网络无法访问`huggingface`，可以通过环境变量便捷地切换模型源为`modelscope`：
```bash
export MINERU_MODEL_SOURCE=modelscope
-mineru -p -o
-```
-
-### 使用本地模型
-
-#### 1. 下载模型到本地
-
-```bash
-mineru-models-download --help
-```
-
-或使用交互式命令行工具选择模型下载：
-
-```bash
-mineru-models-download
-```
-
-下载完成后，模型路径会在当前终端窗口输出，并自动写入用户目录下的 `mineru.json`。
-
-#### 2. 使用本地模型进行解析
-
-```bash
-mineru -p -o --source local
-```
-
-或通过环境变量启用：
-
-```bash
-export MINERU_MODEL_SOURCE=local
-mineru -p -o
```
+有关模型源配置和自定义本地模型路径的更多信息，请参考文档中的[模型源说明](./model_source.md)。
---
-## 使用 sglang 加速 VLM 模型推理
-
-### 通过 sglang-engine 模式
-
+## 通过命令行快速使用
+MinerU内置了命令行工具，用户可以通过命令行快速使用MinerU进行PDF解析：
```bash
-mineru -p -o -b vlm-sglang-engine
+# 默认使用pipeline后端解析
+mineru -p -o
```
+- ``：本地 PDF/图片 文件或目录
+- ``：输出目录
-### 通过 sglang-server/client 模式
-
-1. 启动 Server：
-
-```bash
-mineru-sglang-server --port 30000
-```
-
-2. 在另一个终端中使用 Client 调用：
-
-```bash
-mineru -p -o -b vlm-sglang-client -u http://127.0.0.1:30000
-```
+> [!NOTE]
+> 命令行工具会在Linux和macOS系统自动尝试cuda/mps加速。Windows用户如需使用cuda加速，
+> 请前往 [Pytorch官网](https://pytorch.org/get-started/locally/) 选择适合自己cuda版本的命令安装支持加速的`torch`和`torchvision`。
> [!TIP]
-> 更多关于输出文件的信息，请参考 [输出文件说明](../output_file.md)
+> 更多关于输出文件的信息，请参考[输出文件说明](./output_file.md)。
+
+```bash
+# 或指定vlm后端解析
+mineru -p -o -b vlm-transformers
+```
+> [!TIP]
+> vlm后端另外支持`sglang`加速，与`transformers`后端相比，`sglang`的加速比可达20～30倍，可以在[扩展模块安装指南](../quick_start/extension_modules.md)中查看支持`sglang`加速的完整包安装方法。
+
+如果需要通过自定义参数调整解析选项，您也可以在文档中查看更详细的[命令行工具使用说明](./cli_tools.md)。
---
+
+## 通过api、webui、sglang-client/server进阶使用
+
+- 通过python api直接调用：[Python 调用示例](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py)
+- 通过fast api方式调用：
+ ```bash
+ mineru-api --host 127.0.0.1 --port 8000
+ ```
+ 在浏览器中访问 http://127.0.0.1:8000/docs 查看API文档。
+- 启动gradio webui 可视化前端：
+ ```bash
+ # 使用 pipeline/vlm-transformers/vlm-sglang-client 后端
+ mineru-gradio --server-name 127.0.0.1 --server-port 7860
+ # 或使用 vlm-sglang-engine/pipeline 后端（需安装sglang环境）
+ mineru-gradio --server-name 127.0.0.1 --server-port 7860 --enable-sglang-engine true
+ ```
+ 在浏览器中访问 http://127.0.0.1:7860 使用 Gradio WebUI 或访问 http://127.0.0.1:7860/?view=api 使用 Gradio API。
+- 使用`sglang-client/server`方式调用：
+ ```bash
+ # 启动sglang server(需要安装sglang环境)
+ mineru-sglang-server --port 30000
+ # 在另一个终端中通过sglang client连接sglang server（只需cpu与网络，不需要sglang环境）
+ mineru -p -o -b vlm-sglang-client -u http://127.0.0.1:30000
+ ```
+> [!TIP]
+> 所有sglang官方支持的参数都可用通过命令行参数传递给 MinerU，包括以下命令:`mineru`、`mineru-sglang-server`、`mineru-gradio`、`mineru-api`，
+> 我们整理了一些`sglang`使用中的常用参数和使用方法，可以在文档[命令行参数进阶技巧](./advanced_cli_parameters.md)中获取。
+
+
+## 基于配置文件扩展 MinerU 功能
+
+- MinerU 现已实现开箱即用，但也支持通过配置文件扩展功能。您可以在用户目录下创建 `mineru.json` 文件，添加自定义配置。
+- `mineru.json` 文件会在您使用内置模型下载命令 `mineru-models-download` 时自动生成，也可以通过将[配置模板文件](https://github.com/opendatalab/MinerU/blob/master/mineru.template.json)复制到用户目录下并重命名为 `mineru.json` 来创建。
+- 以下是一些可用的配置选项：
+ - `latex-delimiter-config`：用于配置 LaTeX 公式的分隔符，默认为`$`符号，可根据需要修改为其他符号或字符串。
+ - `llm-aided-config`：用于配置 LLM 辅助标题分级的相关参数，兼容所有支持`openai协议`的 LLM 模型，默认使用`阿里云百炼`的`qwen2.5-32b-instruct`模型，您需要自行配置 API 密钥并将`enable`设置为`true`来启用此功能。
+ - `models-dir`：用于指定本地模型存储目录，请为`pipeline`和`vlm`后端分别指定模型目录，指定目录后您可通过配置环境变量`export MINERU_MODEL_SOURCE=local`来使用本地模型。
diff --git a/docs/zh/usage/model_source.md b/docs/zh/usage/model_source.md
new file mode 100644
index 00000000..e4cf6c70
--- /dev/null
+++ b/docs/zh/usage/model_source.md
@@ -0,0 +1,55 @@
+# 模型源说明
+
+MinerU使用 `HuggingFace` 和 `ModelScope` 作为模型仓库，用户可以根据需要切换模型源或使用本地模型。
+
+- `HuggingFace` 是默认的模型源，在全球范围内提供了优异的加载速度和极高稳定性。
+- `ModelScope` 是中国大陆地区用户的最佳选择，提供了无缝兼容`hf`的SDK模块，适用于无法访问HuggingFace的用户。
+
+## 模型源的切换方法
+
+### 通过命令行参数切换
+目前仅`mineru`命令行工具支持通过命令行参数切换模型源，其他命令行工具如`mineru-api`、`mineru-gradio`等暂不支持。
+```bash
+mineru -p -o --source modelscope
+```
+
+### 通过环境变量切换
+在任何情况下可以通过设置环境变量来切换模型源，这适用于所有命令行工具和API调用。
+```bash
+export MINERU_MODEL_SOURCE=modelscope
+```
+或
+```python
+import os
+os.environ["MINERU_MODEL_SOURCE"] = "modelscope"
+```
+>[!TIP]
+> 通过环境变量设置的模型源会在当前终端会话中生效，直到终端关闭或环境变量被修改。且优先级高于命令行参数，如同时设置了命令行参数和环境变量，命令行参数将被忽略。
+
+
+## 使用本地模型
+
+### 1. 下载模型到本地
+```bash
+mineru-models-download --help
+```
+或使用交互式命令行工具选择模型下载：
+```bash
+mineru-models-download
+```
+>[!TIP]
+>- 下载完成后，模型路径会在当前终端窗口输出，并自动写入用户目录下的 `mineru.json`。
+>- 模型下载到本地后，您可以自由移动模型文件夹到其他位置，同时需要在 `mineru.json` 中更新模型路径。
+>- 如您将模型文件夹部署到其他服务器上，请确保将 `mineru.json`文件一同移动到新设备的用户目录中并正确配置模型路径。
+>- 如您需要更新模型文件，可以再次运行 `mineru-models-download` 命令，模型更新暂不支持自定义路径，如您没有移动本地模型文件夹，模型文件会增量更新；如您移动了模型文件夹，模型文件会重新下载到默认位置并更新`mineru.json`。
+
+### 2. 使用本地模型进行解析
+
+```bash
+mineru -p -o --source local
+```
+或通过环境变量启用：
+```bash
+export MINERU_MODEL_SOURCE=local
+mineru -p -o
+```
\ No newline at end of file
diff --git a/docs/zh/output_file.md b/docs/zh/usage/output_file.md
similarity index 100%
rename from docs/zh/output_file.md
rename to docs/zh/usage/output_file.md
diff --git a/mkdocs.yml b/mkdocs.yml
index 036683f4..1695adb8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -49,15 +49,16 @@ nav:
- "MinerU": index.md
- Quick Start:
- quick_start/index.md
- - Online Demo: quick_start/online_demo.md
- - Local Deployment: quick_start/local_deployment.md
+ - Extension Modules: quick_start/extension_modules.md
+ - Docker Deployment: quick_start/docker_deployment.md
- Usage:
- usage/index.md
- - API Calls or Visual Invocation: usage/api.md
- - Extending MinerU Functionality Through Configuration Files: usage/config.md
+ - CLI Tools: usage/cli_tools.md
+ - Model Source: usage/model_source.md
+ - Advanced CLI Parameters: usage/advanced_cli_parameters.md
+ - Output File Format: usage/output_file.md
- FAQ:
- FAQ: FAQ/index.md
- - Output File Format: output_file.md
- Known Issues: known_issues.md
- TODO: todo.md
@@ -76,14 +77,15 @@ plugins:
nav_translations:
Home: 主页
Quick Start: 快速开始
- Online Demo: 在线体验
- Local Deployment: 本地部署
+ Extension Modules: 扩展模块
+ Docker Deployment: Docker部署
Usage: 使用方法
- API Calls or Visual Invocation: API 调用 或 可视化调用
- Extending MinerU Functionality Through Configuration Files: 基于配置文件扩展 MinerU 功能
+ CLI Tools: 命令行工具
+ Model Source: 模型源
+ Advanced CLI Parameters: 命令行参数进阶技巧
FAQ: FAQ
Output File Format: 输出文件格式
- Known Issues: Known Issues
+ Known Issues: 已知问题
TODO: TODO
- mkdocs-video
-PDF-Extract-Kit: 高质量PDF解析工具箱🔥🔥🔥
-
-
🚀MinerU 官网入口→✅ 免装在线版 ✅ 全功能客户端 ✅ 开发者API在线调用，省去部署麻烦，多种产品形态一键get，速冲！