add deploy cli and docs for mineru (#817)

Co-authored-by: wangzhihong <wangzhihong@sensetime.com>

Author: jisyST

Tutorial

@@ -218,7 +218,55 @@ print(f"answer: {res}")
 
 </details>
 
-## 版本-3：使用 flow
+## 版本-3：自定义文档解析工具，以MinerU为例
+
+lazyllm 内置了一套默认的文档解析算法。如果需要更高定制化的文档解析，可以使用自定义的文档解析器。
+[MinerU](https://github.com/opendatalab/MinerU) 是业界领先的 PDF 文档解析工具。我们为 MinerU 提供了专门的接入组件，无需额外定制，即可顺畅集成。
+
+目前提供一键启动的 MinerU 服务端（server）以及配套的 PDF 客户端。使用流程如下：先在本地启动 MinerU 解析服务，再通过接入 `MineruPDFReader` 获取解析后的文档内容。
+
+### 启动 MinerU 服务
+在开始之前，请先安装 MinerU 依赖：
+
+```bash
+lazyllm install mineru
+```
+> **提示**：为确保解析结果稳定，当前固定 MinerU 版本为2.5.4。服务运行所需资源请参考 [MinerU](https://github.com/opendatalab/MinerU)  官方文档。
+
+环境准备完毕后，通过以下命令一键部署服务：
+
+```bash
+lazyllm deploy mineru [--port <port>] [--cache_dir <cache_dir>] [--image_save_dir <image_save_dir>] [--model_source <model_source>]
+```
+
+** 参数说明 **
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--port` | 服务端口号 | **随机分配** |
+| `--cache_dir` | 文档解析缓存目录（设置后相同文档无需重复解析） | **None** |
+| `--image_save_dir` | 图片输出目录（设置后保存文档内提取的图片） | **None** |
+| `--model_source` | 模型来源（可选：`huggingface` 或 `modelscope`） | **huggingface** |
+
+
+> **提示**：所有参数均为可缺省，执行 lazyllm deploy mineru 即可启动默认服务。若希望持久化缓存解析结果和图片，请自行指定目录路径。
+
+### 通过 reader 无缝接入 MinerU 服务
+
+在RAG流程中，我们在 Part1 为 `documents` 对象注册用于PDF文件解析的解析器：
+
+```python
+from lazyllm.tools.rag.readers import MineruPDFReader
+
+# 注册 PDF 解析器，url 替换为已启动的 MinerU 服务地址
+documents.add_reader("*.pdf", MineruPDFReader(url="http://127.0.0.1:8888"))
+
+```
+
+其余流程保持不变，即可将 MinerU 服务集成到 RAG 流程中，实现 PDF 文档解析。
+
+
+## 版本-4：使用 flow
 
 从 版本-2 的流程图可以看到整个流程已经比较复杂了。我们注意到两个（或多个）`Retriever` 的检索过程互不影响，它们可以并行执行。同时整个流程上下游之间也有着明确的依赖关系，需要保证上游执行完成之后才可以进行下一步。
 
@@ -286,7 +334,7 @@ print(f"answer: {res}")
 
 `pipeline` 和 `parallel` 只是方便流程搭建以及可能的一些性能优化，并不会改成程序的逻辑。另外用户查询作为重要的提示内容，基本是中间每个模块都会用到，我们在这里还用了 `LazyLLM` 提供的 [bind()](../Best%20Practice/flow.md#use-bind) 函数将用户查询 `query` 作为参数传给 `ppl.reranker` 和 `ppl.formatter`。
 
-## 版本-4：自定义检索和排序策略
+## 版本-5：自定义检索和排序策略
 
 上面的例子使用的都是 `LazyLLM` 内置的组件。现实中总有我们覆盖不到的用户需求，为了满足这些需求，`Retriever` 和 `Reranker` 提供了插件机制，用户可以自定义检索和排序策略，通过 `LazyLLM` 提供的注册接口添加到框架中。
 
@@ -325,7 +373,7 @@ my_reranker = Reranker(name="MyReranker")
 
 这里只是简单介绍了怎么使用 `LazyLLM` 注册扩展的机制。可以参考 [Retriever](../Best%20Practice/rag.md#Retriever) 和 [Reranker](../Best%20Practice/rag.md#Reranker) 的文档，在遇到不能满足需求的时候通过编写自己的相似度计算和排序策略来实现自己的应用。
 
-## 版本-5：自定义存储后端
+## 版本-6：自定义存储后端
 
 在定义好 Node Group 的转换规则之后，`LazyLLM` 会把检索过程中用到的转换得到的 Node Group 内容保存起来，这样后续使用的时候可以避免重复执行转换操作。为了方便用户存取不同种类的数据，`LazyLLM` 支持用户自定义存储后端。
 
@@ -466,7 +514,7 @@ if __name__ == '__main__':
 
 </details>
 
-## 版本-6：离在线分离，接入远程部署的 `Document`
+## 版本-7：离在线分离，接入远程部署的 `Document`
 
 RAG系统往往包含文档解析与在线问答两阶段，其中文档解析阶段耗时较长，但可以离线执行，而问答阶段则需要快速响应。为了满足这一需求，`LazyLLM` 提供了 `Document` 的远程部署与接入功能，支持用户将 `Document` 部署在远程服务器上，并使用 url 的方式接入。
 

docs/zh/Cookbook/rag.md

@@ -57,6 +57,30 @@ def deploy(commands):
                 )
             )
         )
+    elif commands and commands[0] == 'mineru':
+        commands = commands[1:]
+        parser = argparse.ArgumentParser(description='lazyllm deploy command for deploying a mineru server.')
+        parser.add_argument('--port', help='Port for the mineru server.', default=None)
+        parser.add_argument('--cache_dir', help='Cache directory for the mineru server.', default=None)
+        parser.add_argument('--image_save_dir', help='Image save directory for the mineru server.', default=None)
+        parser.add_argument('--default_backend', help='Default backend for the mineru server.\
+            (pipeline|vlm-vllm-async-engine|vlm-transformers)', default='pipeline')
+        parser.add_argument('--model_source', help='Model source for the mineru server.(huggingface|modelscope)',
+                            default='huggingface')
+        args = parser.parse_args(commands)
+        os.environ['MINERU_MODEL_SOURCE'] = args.model_source
+
+        lazyllm.LOG.info('Starting mineru server')
+        lazyllm.LOG.info(f'Current model source: {args.model_source}')
+        from lazyllm.tools.servers.mineru import MineruServer
+        server = MineruServer(
+            cache_dir=args.cache_dir,
+            image_save_dir=args.image_save_dir,
+            default_backend=args.default_backend,
+            port=args.port,
+        )
+        server.start()
+        server.wait()
     else:
         parser = argparse.ArgumentParser(description='lazyllm deploy command for deploying a model.')
         parser.add_argument('model', help='model name')

lazyllm/cli/deploy.py

@@ -1362,29 +1362,60 @@
 ''')
 
 add_chinese_doc('rag.readers.MineruPDFReader', '''\
-用于通过 MinerU 服务解析 PDF 文件内容的模块。支持上传文件或通过 URL 方式调用解析接口，解析结果经过回调函数处理成文档节点列表。
-
-Args:
-    url (str): MineruPDFReader 服务的接口 URL。
-    upload_mode (bool): 是否采用文件上传模式调用接口，默认为 False，即通过 JSON 请求文件路径。
-    extract_table (bool): 是否提取表格，默认为 True。
-    extract_formula (bool): 是否提取公式，默认为 True。
-    split_doc (bool): 是否分割文档，默认为 True。
-    post_func (Optional[Callable]): 后处理函数。
+基于Mineru服务的PDF解析器，通过调用Mineru服务的API来解析PDF文件，支持丰富的文档结构识别。
+
+Args:
+    url (str): Mineru服务的完整API端点URL。
+    backend (str, optional): 解析引擎类型。可选值：
+        - 'pipeline': 标准处理流水线
+        - 'vlm-transformers': 基于Transformers的视觉语言模型
+        - 'vlm-vllm-async-engine': 基于异步VLLM的视觉语言模型
+        默认为 'pipeline'。
+    upload_mode (bool, optional): 文件传输模式。
+        - True: 使用multipart/form-data上传文件内容
+        - False: 通过文件路径传递（需确保服务端可访问该路径）
+        默认为 False。
+    extract_table (bool, optional): 是否提取表格内容并转换为Markdown格式。默认为 True。
+    extract_formula (bool, optional): 是否提取公式文本。
+        - True: 提取为LaTeX等文本格式
+        - False: 将公式保留为图片
+        默认为 True。
+    split_doc (bool, optional): 是否将文档分割为多个DocNode节点。默认为 True。
+    clean_content (bool, optional): 是否清理冗余内容（页眉、页脚、页码等）。默认为 True。
+    post_func (Optional[Callable[[List[DocNode]], Any]], optional): 后处理函数，
+        接收DocNode列表作为参数，用于自定义结果处理。默认为 None。
 ''')
 
 add_english_doc('rag.readers.MineruPDFReader', '''\
-Module to parse PDF content via the MineruPDFReader service. Supports file upload or URL-based parsing, with a callback to process the parsed elements into document nodes.
-
-Args:
-    url (str): The MineruPDFReader service API URL.
-    upload_mode (bool): Whether to use file upload mode for the API call. Default is False, meaning JSON request with file path.
-    extract_table (bool): Whether to extract tables. Default is True.
-    extract_formula (bool): Whether to extract formulas. Default is True.
-    split_doc (bool): Whether to split the document. Default is True.
-    post_func (Optional[Callable]): Post-processing function.
+Reader for PDF files by calling the Mineru service's API.
+
+Args:
+    url (str): The complete API endpoint URL for the Mineru service.
+    backend (str, optional): Type of parsing engine. Available options:
+        - 'pipeline': Standard processing pipeline
+        - 'vlm-transformers': Vision-language model based on Transformers
+        - 'vlm-vllm-async-engine': Vision-language model based on async VLLM engine
+        Defaults to 'pipeline'.
+    upload_mode (bool, optional): File transfer mode.
+        - True: Upload file content using multipart/form-data
+        - False: Pass by file path (ensure the server can access the path)
+        Defaults to False.
+    extract_table (bool, optional): Whether to extract table content and convert 
+        to Markdown format. Defaults to True.
+    extract_formula (bool, optional): Whether to extract formula text.
+        - True: Extract as text format (e.g., LaTeX)
+        - False: Keep formulas as images
+        Defaults to True.
+    split_doc (bool, optional): Whether to split the document into multiple 
+        DocNode nodes. Defaults to True.
+    clean_content (bool, optional): Whether to clean redundant content 
+        (headers, footers, page numbers, etc.). Defaults to True.
+    post_func (Optional[Callable[[List[DocNode]], Any]], optional): Post-processing 
+        function that takes a list of DocNodes as input for custom result handling. 
+        Defaults to None.
 ''')
 
+
 add_chinese_doc('rag.readers.MarkdownReader', '''\
 用于读取和解析 Markdown 文件的模块。支持去除超链接和图片，按标题和内容将 Markdown 划分成若干文本段落节点。
 
@@ -2864,6 +2895,11 @@ def _lazy_load_data(self, file_paths: list, **kwargs) -> Iterable[DocNode]:
 documents = reader.forward(file_paths=["doc1.txt", "doc2.txt"])
 ''')
 
+add_example('rag.readers.MineruPDFReader', '''\
+from lazyllm.tools.rag.readers import MineruPDFReader
+reader = MineruPDFReader("http://0.0.0.0:8888")  # Mineru server address
+nodes = reader("path/to/pdf")
+''')
 
 add_chinese_doc('rag.doc_node.QADocNode', '''\
 问答文档节点类，用于存储问答对数据。