Merge pull request #906 from icecraft/feat/add_en_docs

Feat/add en docs

docs/zh_cn/additional_notes/faq.rst

+常见问题解答
+============
+
+1.在较新版本的mac上使用命令安装pip install magic-pdf[full] zsh: no matches found: magic-pdf[full]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+在 macOS 上，默认的 shell 从 Bash 切换到了 Z shell，而 Z shell
+对于某些类型的字符串匹配有特殊的处理逻辑，这可能导致no matches
+found错误。 可以通过在命令行禁用globbing特性，再尝试运行安装命令
+
+.. code:: bash
+
+   setopt no_nomatch
+   pip install magic-pdf[full]
+
+2.使用过程中遇到_pickle.UnpicklingError: invalid load key, ‘v’.错误
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+可能是由于模型文件未下载完整导致，可尝试重新下载模型文件后再试
+参考：https://github.com/opendatalab/MinerU/issues/143
+
+3.模型文件应该下载到哪里/models-dir的配置应该怎么填
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+模型文件的路径输入是在”magic-pdf.json”中通过
+
+.. code:: json
+
+   {
+     "models-dir": "/tmp/models"
+   }
+
+进行配置的。
+这个路径是绝对路径而不是相对路径，绝对路径的获取可在models目录中通过命令
+“pwd” 获取。
+参考：https://github.com/opendatalab/MinerU/issues/155#issuecomment-2230216874
+
+4.在WSL2的Ubuntu22.04中遇到报错\ ``ImportError: libGL.so.1: cannot open shared object file: No such file or directory``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+WSL2的Ubuntu22.04中缺少\ ``libgl``\ 库，可通过以下命令安装\ ``libgl``\ 库解决：
+
+.. code:: bash
+
+   sudo apt-get install libgl1-mesa-glx
+
+参考：https://github.com/opendatalab/MinerU/issues/388
+
+5.遇到报错 ``ModuleNotFoundError : Nomodulenamed 'fairscale'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+需要卸载该模块并重新安装
+
+.. code:: bash
+
+   pip uninstall fairscale
+   pip install fairscale
+
+参考：https://github.com/opendatalab/MinerU/issues/411
+
+6.在部分较新的设备如H100上，使用CUDA加速OCR时解析出的文字乱码。
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+cuda11对新显卡的兼容性不好，需要升级paddle使用的cuda版本
+
+.. code:: bash
+
+   pip install paddlepaddle-gpu==3.0.0b1 -i https://www.paddlepaddle.org.cn/packages/stable/cu123/
+
+参考：https://github.com/opendatalab/MinerU/issues/558
+
+7.在部分Linux服务器上，程序一运行就报错 ``非法指令 (核心已转储)`` 或 ``Illegal instruction (core dumped)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+可能是因为服务器CPU不支持AVX/AVX2指令集，或cpu本身支持但被运维禁用了，可以尝试联系运维解除限制或更换服务器。
+
+参考：https://github.com/opendatalab/MinerU/issues/591 ，
+https://github.com/opendatalab/MinerU/issues/736

docs/zh_cn/additional_notes/glossary.rst

+
+
+名词解释
+===========
+
+1. jsonl 
+    TODO: add description
+
+2. magic-pdf.json
+    TODO: add description
+

docs/zh_cn/additional_notes/known_issues.rst

+已知问题
+============
+
+-  阅读顺序基于模型对可阅读内容在空间中的分布进行排序，在极端复杂的排版下可能会部分区域乱序
+-  不支持竖排文字
+-  目录和列表通过规则进行识别，少部分不常见的列表形式可能无法识别
+-  标题只有一级，目前不支持标题分级
+-  代码块在layout模型里还没有支持
+-  漫画书、艺术图册、小学教材、习题尚不能很好解析
+-  表格识别在复杂表格上可能会出现行/列识别错误
+-  在小语种PDF上，OCR识别可能会出现字符不准确的情况（如拉丁文的重音符号、阿拉伯文易混淆字符等）
+-  部分公式可能会无法在markdown中渲染
+

next_docs/zh_cn/conf.py → docs/zh_cn/conf.py

@@ -15,7 +15,8 @@ import subprocess
 import sys
 
 from sphinx.ext import autodoc
-
+from docutils import nodes
+from docutils.parsers.rst import Directive
 
 def install(package):
     subprocess.check_call([sys.executable, '-m', 'pip', 'install', package])
@@ -33,8 +34,8 @@ sys.path.insert(0, os.path.abspath('../..'))
 # -- Project information -----------------------------------------------------
 
 project = 'MinerU'
-copyright = '2024, OpenDataLab'
-author = 'MinerU Contributors'
+copyright = '2024, MinerU Contributors'
+author = 'OpenDataLab'
 
 # The full version, including alpha/beta/rc tags
 version_file = '../../magic_pdf/libs/version.py'
@@ -58,10 +59,20 @@ extensions = [
     'sphinx_copybutton',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.inheritance_diagram',
     'myst_parser',
     'sphinxarg.ext',
+    'sphinxcontrib.autodoc_pydantic',
 ]
 
+# class hierarchy diagram
+inheritance_graph_attrs = dict(rankdir="LR", size='"8.0, 12.0"', fontsize=14, ratio='compress')
+inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75)
+inheritance_edge_attrs = dict(arrow='vee')
+
+autodoc_pydantic_model_show_json = True
+autodoc_pydantic_model_show_config_summary = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -120,3 +131,21 @@ class MockedClassDocumenter(autodoc.ClassDocumenter):
 autodoc.ClassDocumenter = MockedClassDocumenter
 
 navigation_with_keys = False
+
+
+# add custom directive 
+
+
+class VideoDirective(Directive):
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        url = self.arguments[0]
+        video_node = nodes.raw('', f'<iframe width="560" height="315" src="{url}" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>', format='html')
+        return [video_node]
+
+def setup(app):
+    app.add_directive('video', VideoDirective)
\ No newline at end of file

next_docs/zh_cn/index.rst → docs/zh_cn/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-欢迎来到 MinerU 的中文文档
+欢迎来到 MinerU 文档库
 ==============================================
 
 .. figure:: ./_static/image/logo.png
@@ -14,7 +14,7 @@
 .. raw:: html
 
    <p style="text-align:center">
-   <strong> 一站式开源高质量数据提取工具
+   <strong> 一站式、高质量的开源文档提取工具
    </strong>
    </p>
 
@@ -24,3 +24,58 @@
    <a class="github-button" href="https://github.com/opendatalab/MinerU/subscription" data-icon="octicon-eye" data-size="large" aria-label="Watch">Watch</a>
    <a class="github-button" href="https://github.com/opendatalab/MinerU/fork" data-icon="octicon-repo-forked" data-size="large" aria-label="Fork">Fork</a>
    </p>
+
+
+项目介绍
+--------------------
+
+MinerU是一款将PDF转化为机器可读格式的工具（如markdown、json），可以很方便地抽取为任意格式。
+MinerU诞生于\ `书生-浦语 <https://github.com/InternLM/InternLM>`__\ 的预训练过程中，我们将会集中精力解决科技文献中的符号转化问题，希望在大模型时代为科技发展做出贡献。
+相比国内外知名商用产品MinerU还很年轻，如果遇到问题或者结果不及预期请到\ `issue <https://github.com/opendatalab/MinerU/issues>`__\ 提交问题，同时\ **附上相关PDF**\ 。
+
+.. video:: https://github.com/user-attachments/assets/4bea02c9-6d54-4cd6-97ed-dff14340982c
+
+主要功能
+--------
+
+-  删除页眉、页脚、脚注、页码等元素，确保语义连贯
+-  输出符合人类阅读顺序的文本，适用于单栏、多栏及复杂排版
+-  保留原文档的结构，包括标题、段落、列表等
+-  提取图像、图片描述、表格、表格标题及脚注
+-  自动识别并转换文档中的公式为LaTeX格式
+-  自动识别并转换文档中的表格为LaTeX或HTML格式
+-  自动检测扫描版PDF和乱码PDF，并启用OCR功能
+-  OCR支持84种语言的检测与识别
+-  支持多种输出格式，如多模态与NLP的Markdown、按阅读顺序排序的JSON、含有丰富信息的中间格式等
+-  支持多种可视化结果，包括layout可视化、span可视化等，便于高效确认输出效果与质检
+-  支持CPU和GPU环境
+-  兼容Windows、Linux和Mac平台
+
+
+用户指南
+-------------
+.. toctree::
+   :maxdepth: 2
+   :caption: 用户指南
+
+   user_guide
+
+
+API 接口
+-------------
+本章节主要介绍函数、类、类方法的细节信息
+
+目前只提供英文版本的接口文档，请切换到英文版本的接口文档！
+
+
+附录
+------------------
+.. toctree::
+   :maxdepth: 1
+   :caption: 附录
+
+   additional_notes/known_issues
+   additional_notes/faq
+   additional_notes/glossary
+
+

docs/zh_cn/user_guide.rst

+
+
+.. toctree::
+    :maxdepth: 2
+
+    user_guide/install
+    user_guide/quick_start
+    user_guide/tutorial
+    user_guide/data
+    

docs/zh_cn/user_guide/data.rst

+
+
+数据
+=========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 数据
+
+   data/dataset
+
+   data/read_api
+
+   data/data_reader_writer 
+
+   data/io
+
+
+
+

docs/zh_cn/user_guide/data/data_reader_writer.rst

+
+数据读取和写入类 
+=================
+
+旨在从不同的媒介读取或写入字节。如果 MinerU 没有提供合适的类，你可以实现新的类以满足个人场景的需求。实现新的类非常容易，唯一的要求是继承自 DataReader 或 DataWriter。
+
+.. code:: python
+
+    class SomeReader(DataReader):
+        def read(self, path: str) -> bytes:
+            pass
+
+        def read_at(self, path: str, offset: int = 0, limit: int = -1) -> bytes:
+            pass
+
+
+    class SomeWriter(DataWriter):
+        def write(self, path: str, data: bytes) -> None:
+            pass
+
+        def write_string(self, path: str, data: str) -> None:
+            pass
+
+读者可能会对 io 和本节的区别感到好奇。乍一看，这两部分非常相似。io 提供基本功能，而本节则更注重应用层面。用户可以构建自己的类以满足特定应用需求，这些类可能共享相同的基本 IO 功能。这就是为什么我们有 io。
+
+重要类
+------------
+.. code:: python
+
+    class FileBasedDataReader(DataReader):
+        def __init__(self, parent_dir: str = ''):
+            pass
+
+
+    class FileBasedDataWriter(DataWriter):
+        def __init__(self, parent_dir: str = '') -> None:
+            pass
+
+类 FileBasedDataReader 使用单个参数 parent_dir 初始化。这意味着 FileBasedDataReader 提供的每个方法将具有以下特性：
+
+#. 从绝对路径文件读取内容，parent_dir 将被忽略。
+#. 从相对路径读取文件，首先将路径与 parent_dir 连接，然后从合并后的路径读取内容。
+
+.. note::
+
+    `FileBasedDataWriter` 与 `FileBasedDataReader` 具有相同的行为。
+
+.. code:: python
+
+    class MultiS3Mixin:
+        def __init__(self, default_prefix: str, s3_configs: list[S3Config]):
+            pass
+
+    class MultiBucketS3DataReader(DataReader, MultiS3Mixin):
+        pass
+
+MultiBucketS3DataReader 提供的所有读取相关方法将具有以下特性：
+
+#. 从完整的 S3 格式路径读取对象，例如 s3://test_bucket/test_object，default_prefix 将被忽略。
+#. 从相对路径读取对象，首先将路径与 default_prefix 连接并去掉 bucket_name，然后读取内容。bucket_name 是将 default_prefix 用分隔符 \ 分割后的第一个元素。
+
+.. note::
+    MultiBucketS3DataWriter 与 MultiBucketS3DataReader 具有类似的行为。
+
+.. code:: python
+
+    class S3DataReader(MultiBucketS3DataReader):
+        pass
+
+S3DataReader 基于 MultiBucketS3DataReader 构建，但仅支持单个桶。S3DataWriter 也是类似的情况。
+
+读取示例
+---------
+.. code:: python
+
+    # 文件相关的
+    file_based_reader1 = FileBasedDataReader('')
+
+    ## 将读取文件 abc 
+    file_based_reader1.read('abc') 
+
+    file_based_reader2 = FileBasedDataReader('/tmp')
+
+    ## 将读取 /tmp/abc
+    file_based_reader2.read('abc')
+
+    ## 将读取 /var/logs/message.txt
+    file_based_reader2.read('/var/logs/message.txt')
+
+    # 多桶 S3 相关的
+    multi_bucket_s3_reader1 = MultiBucketS3DataReader("test_bucket1/test_prefix", list[S3Config(
+            bucket_name=test_bucket1, access_key=ak, secret_key=sk, endpoint_url=endpoint_url
+        ),
+        S3Config(
+            bucket_name=test_bucket_2,
+            access_key=ak_2,
+            secret_key=sk_2,
+            endpoint_url=endpoint_url_2,
+        )])
+
+    ## 将读取 s3://test_bucket1/test_prefix/abc
+    multi_bucket_s3_reader1.read('abc')
+
+    ## 将读取 s3://test_bucket1/efg
+    multi_bucket_s3_reader1.read('s3://test_bucket1/efg')
+
+    ## 将读取 s3://test_bucket2/abc
+    multi_bucket_s3_reader1.read('s3://test_bucket2/abc')
+
+    # S3 相关的
+    s3_reader1 = S3DataReader(
+        default_prefix_without_bucket = "test_prefix",
+        bucket: "test_bucket",
+        ak: "ak",
+        sk: "sk",
+        endpoint_url: "localhost"
+    )
+
+    ## 将读取 s3://test_bucket/test_prefix/abc 
+    s3_reader1.read('abc')
+
+    ## 将读取 s3://test_bucket/efg
+    s3_reader1.read('s3://test_bucket/efg')
+
+写入示例
+----------
+.. code:: python
+
+    # 文件相关的
+    file_based_writer1 = FileBasedDataWriter('')
+
+    ## 将写入 123 到 abc
+    file_based_writer1.write('abc', '123'.encode()) 
+
+    ## 将写入 123 到 abc
+    file_based_writer1.write_string('abc', '123') 
+
+    file_based_writer2 = FileBasedDataWriter('/tmp')
+
+    ## 将写入 123 到 /tmp/abc
+    file_based_writer2.write_string('abc', '123')
+
+    ## 将写入 123 到 /var/logs/message.txt
+    file_based_writer2.write_string('/var/logs/message.txt', '123')
+
+    # 多桶 S3 相关的
+    multi_bucket_s3_writer1 = MultiBucketS3DataWriter("test_bucket1/test_prefix", list[S3Config(
+            bucket_name=test_bucket1, access_key=ak, secret_key=sk, endpoint_url=endpoint_url
+        ),
+        S3Config(
+            bucket_name=test_bucket_2,
+            access_key=ak_2,
+            secret_key=sk_2,
+            endpoint_url=endpoint_url_2,
+        )])
+
+    ## 将写入 123 到 s3://test_bucket1/test_prefix/abc
+    multi_bucket_s3_writer1.write_string('abc', '123')
+
+    ## 将写入 123 到 s3://test_bucket1/test_prefix/abc
+    multi_bucket_s3_writer1.write('abc', '123'.encode())
+
+    ## 将写入 123 到 s3://test_bucket1/efg
+    multi_bucket_s3_writer1.write('s3://test_bucket1/efg', '123'.encode())
+
+    ## 将写入 123 到 s3://test_bucket2/abc
+    multi_bucket_s3_writer1.write('s3://test_bucket2/abc', '123'.encode())
+
+    # S3 相关的
+    s3_writer1 = S3DataWriter(
+        default_prefix_without_bucket = "test_prefix",
+        bucket: "test_bucket",
+        ak: "ak",
+        sk: "sk",
+        endpoint_url: "localhost"
+    )
+
+    ## 将写入 123 到 s3://test_bucket/test_prefix/abc 
+    s3_writer1.write('abc', '123'.encode())
+
+    ## 将写入 123 到 s3://test_bucket/test_prefix/abc 
+    s3_writer1.write_string('abc', '123')
+
+    ## 将写入 123 到 s3://test_bucket/efg
+    s3_writer1.write('s3://test_bucket/efg', '123'.encode())
+

docs/zh_cn/user_guide/data/dataset.rst

+
+数据集
+======
+
+导入数据类
+-----------
+
+数据集
+^^^^^^^^
+
+每个 PDF 或图像将形成一个 Dataset。众所周知，PDF 有两种类别：:ref:`TXT <digital_method_section>` 或 :ref:`OCR <ocr_method_section>` 方法部分。从图像中可以获得 ImageDataset，它是 Dataset 的子类；从 PDF 文件中可以获得 PymuDocDataset。ImageDataset 和 PymuDocDataset 之间的区别在于 ImageDataset 仅支持 OCR 解析方法，而 PymuDocDataset 支持 OCR 和 TXT 两种方法。
+
+.. note::
+
+    实际上，有些 PDF 可能是由图像生成的，这意味着它们不支持 `TXT` 方法。目前，由用户保证不会调用 `TXT` 方法来解析图像生成的 PDF
+
+PDF 解析方法
+---------------
+
+.. _ocr_method_section:
+
+OCR
+^^^^
+通过 光学字符识别 技术提取字符。
+
+.. _digital_method_section:
+
+TXT
+^^^^^^^^
+通过第三方库提取字符，目前我们使用的是 pymupdf。
+

docs/zh_cn/user_guide/data/io.rst

+
+
+IO
+====
+
+旨在从不同的媒介读取或写入字节。目前，我们提供了 S3Reader 和 S3Writer 用于兼容 AWS S3 的媒介，以及 HttpReader 和 HttpWriter 用于远程 HTTP 文件。如果 MinerU 没有提供合适的类，你可以实现新的类以满足个人场景的需求。实现新的类非常容易，唯一的要求是继承自 IOReader 或 IOWriter。
+
+.. code:: python
+
+    class SomeReader(IOReader):
+        def read(self, path: str) -> bytes:
+            pass
+
+        def read_at(self, path: str, offset: int = 0, limit: int = -1) -> bytes:
+            pass
+
+
+    class SomeWriter(IOWriter):
+        def write(self, path: str, data: bytes) -> None:
+            pass
+        

docs/zh_cn/user_guide/data/read_api.rst

+
+
+read_api
+=========
+
+从文件或目录读取内容以创建 Dataset。目前，我们提供了几个覆盖某些场景的函数。如果你有新的、大多数用户都会遇到的场景，可以在官方 GitHub 问题页面上发布详细描述。同时，实现你自己的读取相关函数也非常容易。
+
+重要函数
+---------
+
+read_jsonl
+^^^^^^^^^^^^^^^^
+
+从本地机器或远程 S3 上的 JSONL 文件读取内容。如果你想了解更多关于 JSONL 的信息，请参阅 :doc:`../../additional_notes/glossary`。
+
+.. code:: python
+
+    # 从本地机器读取 JSONL
+    datasets = read_jsonl("tt.jsonl", None)
+
+    # 从远程 S3 读取 JSONL
+    datasets = read_jsonl("s3://bucket_1/tt.jsonl", s3_reader)
+
+read_local_pdfs
+^^^^^^^^^^^^^^^^
+
+从路径或目录读取 PDF 文件。
+
+.. code:: python
+
+    # 读取 PDF 路径
+    datasets = read_local_pdfs("tt.pdf")
+
+    # 读取目录下的 PDF 文件
+    datasets = read_local_pdfs("pdfs/")
+
+read_local_images
+^^^^^^^^^^^^^^^^^^^
+
+从路径或目录读取图像。
+
+.. code:: python
+
+    # 从图像路径读取
+    datasets = read_local_images("tt.png")
+
+    # 从目录读取以 suffixes 数组中指定后缀结尾的文件
+    datasets = read_local_images("images/", suffixes=["png", "jpg"])

docs/zh_cn/user_guide/install.rst

+
+安装
+==============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 安装文档
+
+   install/install
+   install//boost_with_cuda
+   install/download_model_weight_files
+
+

docs/zh_cn/user_guide/install/boost_with_cuda.rst

+使用 CUDA 加速
+================
+
+如果您的设备支持 CUDA 并符合主线环境的 GPU 要求，您可以使用 GPU 加速。请选择适合您系统的指南：
+
+-  :ref:`ubuntu_22_04_lts_section`
+-  :ref:`windows_10_or_11_section`
+
+.. admonition:: Important
+   :class: warning
+
+   使用 Docker 快速部署 > Docker 需要至少 16GB 显存的 GPU，并且所有加速功能默认启用。
+   在运行此 Docker 容器之前，您可以使用以下命令检查您的设备是否支持 Docker 上的 CUDA 加速。
+
+   .. code-block:: sh
+
+      bash  docker run --rm --gpus=all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
+
+.. code:: sh
+
+   wget https://github.com/opendatalab/MinerU/raw/master/Dockerfile
+   docker build -t mineru:latest .
+   docker run --rm -it --gpus=all mineru:latest /bin/bash
+   magic-pdf --help
+
+
+.. _ubuntu_22_04_lts_section:
+
+Ubuntu 22.04 LT
+----------------
+
+1.检查 NVIDIA 驱动程序是否已安装
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. code:: sh
+
+   nvidia-smi
+
+如果您看到类似以下的信息，则表示 NVIDIA 驱动程序已安装，可以跳过第 2 步。
+
+注意：“CUDA 版本”应 >= 12.1，如果显示的版本号小于 12.1，请升级驱动程序。
+
+.. code:: text
+
+   +---------------------------------------------------------------------------------------+
+   | NVIDIA-SMI 537.34                 Driver Version: 537.34       CUDA Version: 12.2     |
+   |-----------------------------------------+----------------------+----------------------+
+   | GPU  Name                     TCC/WDDM  | Bus-Id        Disp.A | Volatile Uncorr. ECC |
+   | Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
+   |                                         |                      |               MIG M. |
+   |=========================================+======================+======================|
+   |   0  NVIDIA GeForce RTX 3060 Ti   WDDM  | 00000000:01:00.0  On |                  N/A |
+   |  0%   51C    P8              12W / 200W |   1489MiB /  8192MiB |      5%      Default |
+   |                                         |                      |                  N/A |
+   +-----------------------------------------+----------------------+----------------------+
+
+
+2. 安装驱动程序
+~~~~~~~~~~~~~~~~~~~~~
+
+如果没有安装驱动程序，请使用以下命令：
+
+.. code:: sh
+
+   sudo apt-get update
+   sudo apt-get install nvidia-driver-545
+
+安装专有驱动程序并在安装后重启计算机。
+
+.. code:: sh
+
+   reboot
+
+3. 安装 Anaconda
+~~~~~~~~~~~~~~~~~~
+
+如果已经安装了 Anaconda，请跳过此步骤。
+
+.. code:: sh
+
+   wget https://repo.anaconda.com/archive/Anaconda3-2024.06-1-Linux-x86_64.sh
+   bash Anaconda3-2024.06-1-Linux-x86_64.sh
+
+在最后一步中输入 ``yes``，关闭终端并重新打开。
+
+4. 使用 Conda 创建环境
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+指定 Python 版本为 3.10。
+
+.. code:: sh
+
+   conda create -n MinerU python=3.10
+   conda activate MinerU
+
+5. 安装应用程序
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: sh
+
+   pip install -U magic-pdf[full] --extra-index-url https://wheels.myhloli.com
+
+❗ 安装完成后，请确保使用以下命令检查 ``magic-pdf`` 的版本：
+
+.. code:: sh
+
+   magic-pdf --version
+
+如果版本号小于 0.7.0，请报告问题。
+
+6. 下载模型
+~~~~~~~~~~~~~~~~~~
+
+参考详细说明 :doc:`下载模型权重文件 <download_model_weight_files>`
+
+7. 了解配置文件的位置
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+完成 `6. 下载模型 <#6-download-models>`__ 步骤后，脚本将自动在用户目录中生成一个 ``magic-pdf.json`` 文件并配置默认模型路径。您可以在用户目录中找到 ``magic-pdf.json`` 文件。
+
+   Linux 用户目录是 “/home/用户名”。
+
+8. 首次运行
+~~~~~~~~~~~~
+
+从仓库下载示例文件并测试它。
+
+.. code:: sh
+
+   wget https://github.com/opendatalab/MinerU/raw/master/demo/small_ocr.pdf
+   magic-pdf -p small_ocr.pdf -o ./output
+
+9. 测试 CUDA 加速
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如果您的显卡至少有 **8GB** 显存，请按照以下步骤测试 CUDA 加速：
+
+1. 修改位于用户目录中的 ``magic-pdf.json`` 配置文件中的 ``"device-mode"`` 值。
+
+   .. code:: json
+
+      {
+        "device-mode": "cuda"
+      }
+
+2. 使用以下命令测试 CUDA 加速：
+
+   .. code:: sh
+
+      magic-pdf -p small_ocr.pdf -o ./output
+
+10. 启用 OCR 的 CUDA 加速
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. 下载 ``paddlepaddle-gpu``。安装将自动启用 OCR 加速。
+
+   .. code:: sh
+
+      python -m pip install paddlepaddle-gpu==3.0.0b1 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/
+
+2. 使用以下命令测试 OCR 加速：
+
+   .. code:: sh
+
+      magic-pdf -p small_ocr.pdf -o ./output
+
+.. _windows_10_or_11_section:
+
+Windows 10/11
+--------------
+
+1. 安装 CUDA 和 cuDNN
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+所需版本：CUDA 11.8 + cuDNN 8.7.0
+
+-  CUDA 11.8: https://developer.nvidia.com/cuda-11-8-0-download-archive
+-  cuDNN v8.7.0（2022年11月28日发布），适用于 CUDA 11.x：
+   https://developer.nvidia.com/rdp/cudnn-archive
+
+2. 安装 Anaconda
+~~~~~~~~~~~~~~~~~~
+
+如果已经安装了 Anaconda，您可以跳过此步骤。
+
+下载链接：https://repo.anaconda.com/archive/Anaconda3-2024.06-1-Windows-x86_64.exe
+
+3. 使用 Conda 创建环境
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python 版本必须是 3.10。
+
+::
+
+   conda create -n MinerU python=3.10
+   conda activate MinerU
+
+4. 安装应用程序
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+   pip install -U magic-pdf[full] --extra-index-url https://wheels.myhloli.com
+
+
+❗️安装完成后，请验证 ``magic-pdf`` 的版本：
+
+.. code:: bash
+
+      magic-pdf --version
+
+如果版本号小于 0.7.0，请在问题部分报告。
+
+5. 下载模型
+~~~~~~~~~~~~~~~~~~
+
+参考详细说明 :doc:`下载模型权重文件 <download_model_weight_files>`
+
+6. 了解配置文件的位置
+~~~~~~~~~~~~~~~~~~~~
+
+完成 `5. 下载模型 <#5-download-models>__` 步骤后，脚本将自动在用户目录中生成一个 magic-pdf.json 文件并配置默认模型路径。您可以在【用户目录】中找到 magic-pdf.json 文件。
+
+Windows 用户目录是 “C:/Users/用户名”。
+
+7. 首次运行
+~~~~~~~~~~
+
+从仓库下载示例文件并测试它。
+
+.. code:: powershell
+
+     wget https://github.com/opendatalab/MinerU/raw/master/demo/small_ocr.pdf -O small_ocr.pdf
+     magic-pdf -p small_ocr.pdf -o ./output
+
+8. 测试CUDA加速
+~~~~~~~~~~~~~~~~
+
+如果您的显卡显存大于等于 **8GB**
+，可以进行以下流程，测试CUDA解析加速效果
+
+**1.覆盖安装支持cuda的torch和torchvision**
+
+.. code:: bash
+
+   pip install --force-reinstall torch==2.3.1 torchvision==0.18.1 --index-url https://download.pytorch.org/whl/cu118
+
+..
+
+   ❗️务必在命令中指定以下版本
+
+   .. code:: bash
+
+      torch==2.3.1 torchvision==0.18.1
+
+   这是我们支持的最高版本，如果不指定版本会自动安装更高版本导致程序无法运行
+
+**2.修改【用户目录】中配置文件magic-pdf.json中”device-mode”的值**
+
+.. code:: json
+
+   {
+     "device-mode":"cuda"
+   }
+
+**3.运行以下命令测试cuda加速效果**
+
+.. code:: bash
+
+   magic-pdf -p small_ocr.pdf -o ./output
+
+..
+
+   提示：CUDA加速是否生效可以根据log中输出的各个阶段的耗时来简单判断，通常情况下，\ ``layout detection time``
+   和 ``mfr time`` 应提速10倍以上。
+
+9. 为ocr开启cuda加速
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**1.下载paddlepaddle-gpu, 安装完成后会自动开启ocr加速**
+
+.. code:: bash
+
+   pip install paddlepaddle-gpu==2.6.1
+
+**2.运行以下命令测试ocr加速效果**
+
+.. code:: bash
+
+   magic-pdf -p small_ocr.pdf -o ./output
+
+..
+
+提示：CUDA加速是否生效可以根据log中输出的各个阶段cost耗时来简单判断，通常情况下，\ ``ocr time``\ 应提速10倍以上。

docs/zh_cn/user_guide/install/download_model_weight_files.rst

+下载模型权重文件
+===============
+
+模型下载分为初始下载和更新到模型目录。请参考相应的文档以获取如何操作的指示。
+
+初始下载模型文件
+--------------
+从 Hugging Face 下载模型
+
+
+使用 Python 脚本从 Hugging Face 下载模型文件
+
+.. code:: bash
+
+   pip install huggingface_hub
+   wget https://github.com/opendatalab/MinerU/raw/master/scripts/download_models_hf.py -O download_models_hf.py
+   python download_models_hf.py
+
+该 Python 脚本将自动下载模型文件，并在配置文件中配置模型目录。
+
+配置文件可以在用户目录中找到，文件名为 ``magic-pdf.json``。
+
+如何更新先前下载的模型
+-----------------------------------------
+
+1. 通过 Git LFS 下载的模型
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+   由于一些用户的反馈指出使用 git lfs 下载模型文件会出现不完整或导致模型文件损坏的情况，因此不再推荐使用这种方法。
+
+如果您之前通过 git lfs 下载了模型文件，您可以导航到之前的下载目录并使用 ``git pull`` 命令来更新模型。
+
+2. 通过 Hugging Face 或 ModelScope 下载的模型
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+如果您之前通过 Hugging Face 或 ModelScope 下载了模型，您可以重新运行用于初始下载的 Python 脚本。这将自动将模型目录更新到最新版本。
\ No newline at end of file

docs/zh_cn/user_guide/install/install.rst

+
+安装
+=====
+
+如果您遇到任何安装问题，请首先查阅 :doc:`../../additional_notes/faq`。如果解析结果不如预期，可参考 :doc:`../../additional_notes/known_issues`。
+
+预安装须知—硬件和软件环境支持
+-----------------------------
+
+为了确保项目的稳定性和可靠性，在开发过程中我们仅对特定的硬件和软件环境进行了优化和测试。这确保了在推荐系统配置上部署和运行项目的用户能够获得最佳性能，并且兼容性问题最少。
+
+通过将资源集中在主线环境中，我们的团队可以更高效地解决潜在的错误并开发新功能。
+
+在非主线环境中，由于硬件和软件配置的多样性以及第三方依赖项的兼容性问题，我们无法保证100%的项目可用性。因此，对于希望在非推荐环境中使用该项目的用户，我们建议首先仔细阅读文档和常见问题解答。大多数问题在常见问题解答中已经有相应的解决方案。我们也鼓励社区反馈，以帮助我们逐步扩大支持。
+
+
+.. raw:: html
+
+    <style>
+        table, th, td {
+        border: 1px solid black;
+        border-collapse: collapse;
+        }
+    </style>
+    <table>
+        <tr>
+            <td colspan="3" rowspan="2">操作系统</td>
+        </tr>
+        <tr>
+            <td>Ubuntu 22.04 LTS</td>
+            <td>Windows 10 / 11</td>
+            <td>macOS 11+</td>
+        </tr>
+        <tr>
+            <td colspan="3">CPU</td>
+            <td>x86_64(暂不支持ARM Linux)</td>
+            <td>x86_64(暂不支持ARM Windows)</td>
+            <td>x86_64 / arm64</td>
+        </tr>
+        <tr>
+            <td colspan="3">内存</td>
+            <td colspan="3">大于等于16GB，推荐32G以上</td>
+        </tr>
+        <tr>
+            <td colspan="3">python版本</td>
+            <td colspan="3">3.10 (请务必通过conda创建3.10虚拟环境)</td>
+        </tr>
+        <tr>
+            <td colspan="3">Nvidia Driver 版本</td>
+            <td>latest(专有驱动)</td>
+            <td>latest</td>
+            <td>None</td>
+        </tr>
+        <tr>
+            <td colspan="3">CUDA环境</td>
+            <td>自动安装[12.1(pytorch)+11.8(paddle)]</td>
+            <td>11.8(手动安装)+cuDNN v8.7.0(手动安装)</td>
+            <td>None</td>
+        </tr>
+        <tr>
+            <td rowspan="2">GPU硬件支持列表</td>
+            <td colspan="2">最低要求 8G+显存</td>
+            <td colspan="2">3060ti/3070/4060<br>
+            8G显存可开启layout、公式识别和ocr加速</td>
+            <td rowspan="2">None</td>
+        </tr>
+        <tr>
+            <td colspan="2">推荐配置 10G+显存</td>
+            <td colspan="2">3080/3080ti/3090/3090ti/4070/4070ti/4070tisuper/4080/4090<br>
+            10G显存及以上可以同时开启layout、公式识别和ocr加速和表格识别加速<br>
+            </td>
+        </tr>
+    </table>
+
+
+创建环境
+~~~~~~~~~~
+
+.. code-block:: shell
+
+    conda create -n MinerU python=3.10
+    conda activate MinerU
+    pip install -U magic-pdf[full] --extra-index-url https://wheels.myhloli.com
+
+
+下载模型权重文件
+~~~~~~~~~~~~~~~
+
+.. code-block:: shell
+
+    pip install huggingface_hub
+    wget https://github.com/opendatalab/MinerU/raw/master/scripts/download_models_hf.py -O download_models_hf.py
+    python download_models_hf.py    
+
+MinerU 已安装，查看 :doc:`../quick_start` 或阅读 :doc:`boost_with_cuda` 以加速推理。
+

docs/zh_cn/user_guide/quick_start.rst

+
+快速开始 
+==============
+
+从这里开始学习 MinerU 基本使用方法。若还没有安装，请参考安装文档进行安装
+
+.. toctree::
+    :maxdepth: 1
+    :caption: 快速开始
+
+    quick_start/command_line
+    quick_start/to_markdown
+

docs/zh_cn/user_guide/quick_start/command_line.rst

+
+
+命令行
+========
+
+.. code:: bash
+
+   magic-pdf --help
+   Usage: magic-pdf [OPTIONS]
+
+   Options:
+     -v, --version                display the version and exit
+     -p, --path PATH              local pdf filepath or directory  [required]
+     -o, --output-dir PATH        output local directory  [required]
+     -m, --method [ocr|txt|auto]  the method for parsing pdf. ocr: using ocr
+                                  technique to extract information from pdf. txt:
+                                  suitable for the text-based pdf only and
+                                  outperform ocr. auto: automatically choose the
+                                  best method for parsing pdf from ocr and txt.
+                                  without method specified, auto will be used by
+                                  default.
+     -l, --lang TEXT              Input the languages in the pdf (if known) to
+                                  improve OCR accuracy.  Optional. You should
+                                  input "Abbreviation" with language form url: ht
+                                  tps://paddlepaddle.github.io/PaddleOCR/en/ppocr
+                                  /blog/multi_languages.html#5-support-languages-
+                                  and-abbreviations
+     -d, --debug BOOLEAN          Enables detailed debugging information during
+                                  the execution of the CLI commands.
+     -s, --start INTEGER          The starting page for PDF parsing, beginning
+                                  from 0.
+     -e, --end INTEGER            The ending page for PDF parsing, beginning from
+                                  0.
+     --help                       Show this message and exit.
+
+
+   ## show version
+   magic-pdf -v
+
+   ## command line example
+   magic-pdf -p {some_pdf} -o {some_output_dir} -m auto
+
+``{some_pdf}`` 可以是单个 PDF 文件或者一个包含多个 PDF 文件的目录。 解析的结果文件存放在目录 ``{some_output_dir}`` 下。 生成的结果文件列表如下所示：
+
+.. code:: text
+
+   ├── some_pdf.md                          # markdown 文件
+   ├── images                               # 存放图片目录
+   ├── some_pdf_layout.pdf                  # layout 绘图 （包含layout阅读顺序）
+   ├── some_pdf_middle.json                 # minerU 中间处理结果
+   ├── some_pdf_model.json                  # 模型推理结果
+   ├── some_pdf_origin.pdf                  # 原 pdf 文件
+   ├── some_pdf_spans.pdf                   # 最小粒度的bbox位置信息绘图
+   └── some_pdf_content_list.json           # 按阅读顺序排列的富文本json
+
+
+.. admonition:: Tip
+   :class: tip
+
+   欲知更多有关结果文件的信息，请参考 :doc:`../tutorial/output_file_description`
+

docs/zh_cn/user_guide/quick_start/to_markdown.rst

+
+
+转换为 Markdown 文件
+========================
+
+.. code:: python
+
+    import os
+
+    from magic_pdf.data.data_reader_writer import FileBasedDataWriter, FileBasedDataReader
+    from magic_pdf.libs.MakeContentConfig import DropMode, MakeMode
+    from magic_pdf.pipe.OCRPipe import OCRPipe
+
+
+    ## args
+    model_list = []
+    pdf_file_name = "abc.pdf"  # replace with the real pdf path
+
+
+    ## prepare env
+    local_image_dir, local_md_dir = "output/images", "output"
+    os.makedirs(local_image_dir, exist_ok=True)
+
+    image_writer, md_writer = FileBasedDataWriter(local_image_dir), FileBasedDataWriter(
+        local_md_dir
+    ) # create 00
+    image_dir = str(os.path.basename(local_image_dir))
+
+    reader1 = FileBasedDataReader("")
+    pdf_bytes = reader1.read(pdf_file_name)   # read the pdf content
+
+
+    pipe = OCRPipe(pdf_bytes, model_list, image_writer)
+
+    pipe.pipe_classify()
+    pipe.pipe_analyze()
+    pipe.pipe_parse()
+
+    pdf_info = pipe.pdf_mid_data["pdf_info"]
+
+
+    md_content = pipe.pipe_mk_markdown(
+        image_dir, drop_mode=DropMode.NONE, md_make_mode=MakeMode.MM_MD
+    )
+
+    if isinstance(md_content, list):
+        md_writer.write_string(f"{pdf_file_name}.md", "\n".join(md_content))
+    else:
+        md_writer.write_string(f"{pdf_file_name}.md", md_content)
+
+
+前去 :doc:`../data/data_reader_writer` 获取更多有关**读写**示例
+