============================================================
测试 MinerU API with backend: pipeline
============================================================
API URL: http://192.168.130.4:50000/file_parse
PDF 文件: ./2507.05595v1.pdf
Backend: pipeline
发送请求...
请求成功!
使用的 backend: pipeline
版本: 2.6.4
结果数量: 1
Markdown 内容预览 (前500字符):
------------------------------------------------------------
# PaddleOCR 3.0 Technical Report
Cheng Cui, Ting Sun, Manhui Lin, Tingquan Gao, Yubo Zhang, Jiaxuan Liu, Xueqing Wang, Zelun Zhang, Changda Zhou, Hongen Liu, Yue Zhang, Wenyu Lv, Kui Huang, Yichao Zhang, Jing Zhang, Jun Zhang, Yi Liu, Dianhai Yu, Yanjun Ma
PaddlePaddle Team, Baidu Inc. paddleocr@baidu.com
Source Code: https://github.com/PaddlePaddle/PaddleOCR Document: https://paddlepaddle.github.io/PaddleOCR Models & Online Demo: https://huggingface.co/PaddlePaddl
# Abstract
This technical
------------------------------------------------------------
完整 Markdown 已保存到: output_pipeline.md
============================================================
测试 2: vlm-vllm-async-engine backend (vLLM 加速)
============================================================
============================================================
测试 MinerU API with backend: vlm-vllm-async-engine
============================================================
API URL: http://192.168.130.4:50000/file_parse
PDF 文件: ./2507.05595v1.pdf
Backend: vlm-vllm-async-engine
发送请求...
请求成功!
使用的 backend: vlm-vllm-async-engine
版本: 2.6.4
结果数量: 1
Markdown 内容预览 (前500字符):
------------------------------------------------------------
# PaddleOCR 3.0 Technical Report
Cheng Cui, Ting Sun, Manhui Lin, Tingquan Gao, Yubo Zhang, Jiaxuan Liu, Xueqing Wang, Zelun Zhang, Changda Zhou, Hongen Liu, Yue Zhang, Wenyu Lv, Kui Huang, Yichao Zhang, Jing Zhang, Jun Zhang, Yi Liu, Dianhai Yu, Yanjun Ma
PaddlePaddle Team, Baidu Inc.
paddleocr@baidu.com
Source Code: https://github.com/PaddlePaddle/PaddleOCR
Document: https://paddlepaddle.github.io/PaddleOCR
Models & Online Demo: https://huggingface.co/PaddlePaddle
# Abstract
This tec
------------------------------------------------------------
完整 Markdown 已保存到: output_vlm-vllm-async-engine.md
============================================================
测试总结
============================================================
Pipeline backend: 成功
vLLM backend: 成功
所有测试通过! MinerU 可以通过 backend 参数切换不同模型
💡 提示:
- pipeline: 使用本地 PyTorch，适合调试
- vlm-vllm-async-engine: 使用 vLLM 加速，速度更快
| 启动方式 | 典型命令/镜像 | 端口 & 路径 | 适用场景 | 依赖 |
|---|
| SGLang 后端服务 | mineru-sglang-server --host 0.0.0.0 --port 30000 | POST /file_parse | 高并发、GPU 推理、本地私有化 | Python + CUDA/SGLang |
| Docker 一键 | docker run -p 30000:30000 opendatalab/mineru:latest mineru-sglang-server | 同上 | 免环境配置、快速试用 | Docker (GPU 可选) |
| 命令行离线解析 | mineru -p <输入> -o <输出> | 无服务；直接落盘 | 批处理、无网络、脚本化 | 纯 Python CLI |
| Gradio WebUI | mineru-gradio --enable-sglang-engine | 浏览器 UI | 交互演示、无代码使用 | Gradio 前端 |
| FastAPI API 服 务 | git clone .../mineru-api && docker compose up | PUT /api/parse | 需要依托自定义业务接口 | FastAPI + Uvicorn |
| MCP-Server（外壳） | uv run mineru-mcp --transport streamable-http | /mcp 或 /sse | 给 ADK/Agent 暴露工具 | fastmcp 框架 |
| n8n/Serverless 封装 | n8n「MCP Client」节点或 Runpod 镜像 | 由平台分配 | 无代码工作流 | 平台函数 |
实际上，MinerU 会输出非常丰富的信息，主要是：
-
images:这是一个文件夹，里面存储了PDF 文档中出现的所有图片；
-
.origin.pdf：进行解析的原始PDF文件；
-
.markdown：PDF 文档的解析结果，输出为xxx.md 的 Markdown 格式；
-
.layout.pdf：这个文件用不同的背景色块圈定不同的内容块，以此来区分整体的布局识别结果；
-
.model.json：这个文件的主要作用是将 PDF 从像素级别的展示转换为结构化的数据，使计算机能够"理解"文档的组成部分。主要存储的信息是：
- 文档布局识别：存储文档中的各种元素（标题、正文、图表等）及其在页面上的精确位置
- 内容分类：将识别出的元素分类为不同类型（如标题、表格、公式等）
- 特殊内容解析：对于公式、表格等特殊内容，提供其结构化表示（如LaTeX、HTML格式）
其示例数据如下：
FENCE13
其中每一个layout_dets 中存储了PDF 文档中每一页的布局识别结果，poly 是四边形坐标, 分别是 左上，右上，右下，左下 四点的坐标，形式为：[x0, y0, x1, y1, x2, y2, x3, y3], 分别表示左上、右上、右下、左下四点的坐标，page_info 是PDF 文档中每一页元数据，包含页码、高度、宽度信息，而category_id 为PDF 文档中每一页的布局识别结果的类型，分别为：
category_id 的类别
| 类别 ID | 类别名称 | 描述 |
|---|
| 0 | title | 标题 |
| 1 | plain_text | 文本 |
| 2 | abandon | 包括页眉页脚页码和页面注释 |
| 3 | figure | 图片 |
| 4 | figure_caption | 图片描述 |
| 5 | table | 表格 |
| 6 | table_caption | 表格描述 |
| 7 | table_footnote | 表格注释 |
| 8 | isolate_formula | 行间公式 |
| 9 | formula_caption | 行间公式的标号 |
| 13 | embedding | 行内公式 |
| 14 | isolated | 行间公式 |
| 15 | text | OCR 识别结果 |
这个.json文件主要可以内容提取，比如精确提取特定类型的内容（如所有表格或公式），搜索，比如实现对文档内容的结构化搜索，文档分析，比如分析文档的结构特征（如有多少图表、公式密度等）等需求场景。
- _middle.json：这个文件的核心作用是存储
PDF 文档解析过程中多层次结构化数据，它比 model.json 提供了更详细的层次结构和内容信息, 其示例数据是这样的：
FENCE14
解析结果是一个多层嵌套，从大到小依次为：PDF 文档 → 包含多个页面 → 包含多个区块(blocks) → 分为一级区块和二级区块 → 每个区块包含多行 → 每行包含多个最小单元， 其中para_blocks内存储的元素为区块信息， span是所有元素的最小存储单元。大家理解了这个结构后，可以结合下图对每个字段进行理解，我们这里不再赘述。
一级
| 字段名 | 解释 |
|---|
| pdf_info | list，每个元素都是一个 dict，这个 dict 是每一页 PDF 的解析结果，详见下表 |
| _parse_type | ocr |
| _version_name | string，表示本次解析使用的 magic-pdf 的版本号 |
二级
| 字段名 | 解释 |
|---|
| preproc_blocks | PDF 预处理后，未分段的中间结果 |
| layout_bboxes | 布局分割的结果，含有布局的方向（垂直、水平），和 bbox，按阅读顺序排序 |
| page_idx | 页码，从 0 开始 |
| page_size | 页面宽度和高度 |
| _layout_tree | 布局树状结构 |
| images | list，每个元素是一个 dict，每个 dict 表示一个 img_block |
| tables | list，每个元素是一个 dict，每个 dict 表示一个 table_block |
| interline_equations | list，每个元素是一个 dict，每个 dict 表示一个 interline_equation_block |
| discarded_blocks | list，模型返回的需要 drop 的 block 信息 |
| para_blocks | 将 preproc_blocks 进行分段之后的结果 |
三级（最外层block）
| 字段名 | 解释 |
|---|
| type | block 类型（table 或 image） |
| bbox | block 矩形框坐标 |
| blocks | list，里面的每个元素都是一个 dict 格式的二级 block |
四级（内层block）
| 字段名 | 解释 |
|---|
| type | block 类型 |
| bbox | block 矩形框坐标 |
| lines | list，每个元素都是一个 dict 表示的 line，用来描述一行信息的构成 |
| ----------------------- | -------------------------- |
| 其中 type 类型 | 描述 |
| image_body | 图像的本体 |
| image_caption | 图像的描述文本 |
| image_footnote | 图像的脚注 |
| table_body | 表格本体 |
| table_caption | 表格的描述文本 |
| table_footnote | 表格的脚注 |
| text | 文本块 |
| title | 标题块 |
| index | 目录块 |
| list | 列表块 |
| interline_equation | 行间公式块 |
五级（lines）
| 字段名 | 解释 |
|---|
| bbox | line 的矩形框坐标 |
| spans | list，每个元素都是一个 dict 表示的 span，用来描述一个最小组成单元的构成 |
六级（spans）
| 字段名 | 解释 |
|---|
| bbox | span 的矩形框坐标 |
| type | span 的类型 |
| content | img_path |
| ----------------------- | -------------------------- |
| 其中 type 类型 | 描述 |
| type | 描述 |
| image | 图片 |
| table | 表格 |
| text | 文本 |
| inline_equation | 行内公式 |
| interline_equation | 行间公式 |
该.json文件除了能像model.json一样提取特定类型的内容，因为其内容的丰富程度，可以做更精细化的文本分析，比如段落级别的文本分析，建立更精确的搜索索引，支持按内容类型搜索等。
7. span.pdf：根据 span 类型的不同，采用不同颜色线框绘制页面上所有 span。该文件可以用于质检，可以快速排查出文本丢失、行间公式未识别等问题。
最后一个 .content_list.json 文件，是PDF 文档中所有内容的列表，使用 JSON 格式存储数据，每个元素都是一个字典，包含了不同类型的内容（文本、图像等）。
FENCE15
字段说明
| 字段名 | 出现位置 | 数据类型 | 说明 |
|---|
| type | 所有内容块 | 字符串 | 内容块的类型，可能的值有："text"、"image"、"table" |
| page_idx | 所有内容块 | 整数 | 内容所在的页码，从0开始计数 |
| text | 文本类型块 | 字符串 | 文本内容 |
| text_level | 部分文本类型块 | 整数 | 文本的层级，通常用于标题，1表示一级标题 |
| img_path | 图像和表格类型块 | 字符串 | 图像或表格截图的文件路径 |
| img_caption | 图像类型块 | 数组 | 图像的说明文字，通常为空数组 |
| img_footnote | 图像类型块 | 数组 | 图像的脚注，通常为空数组 |
| table_caption | 表格类型块 | 数组 | 表格的说明文字，通常为空数组 |
| table_footnote | 表格类型块 | 数组 | 表格的脚注，通常为空数组 |
| table_body | 表格类型块 | 字符串 | 表格的HTML内容，包含完整的表格结构 |
以上是对MinerU解析结果的说明，通过这些文件，我们基本上可以获取到PDF文档中所有内容的位置、类型、内容等信息，理解各个文件的结构，也是我们后续进行自定义处理的关键，所以这里大家务必明确文件及其内部结构的组成。除此以外，除了PDF格式，该流程也可以支持图像（.jpg及.png）、PDF、Word（.doc及.docx）、以及PowerPoint（.ppt及.pptx）在内的多种文档格式的解析，大家可以进行尝试。
四、PaddleOCR项目介绍及vLLM服务启动
本小节课程，我们将从零开始，详细介绍如何在本地环境中完整部署 PaddleOCR-VL 并通过 vLLM 服务启动 PaddleOCR API 服务。
对于硬件要求，官方给出了如上说明。其中使用原生的PaddlePaddle方式，需要GPU算力≥8.5（RTX 3090/4090、A100 等），最稳定。使用vLLM方式，需要GPU算力≥8（RTX 3060 及以上），速度最快，但算力7-8之间（T4/V100）虽可运行但不推荐，易超时或OOM。使用SGLang方式，需要GPU算力8-12之间（RTX 3060-4090），性能与稳定性的平衡选择。
注意：表格里的 "≥8" 指的是 GPU Compute Capability（GPU 算力版本号），不是显存大小！根据实测，根据PaddleOCR-VL-0.9B 模型（模型文件约 3.8GB）：
- 最低要求：6GB 显存（勉强够用，单张图）
- 推荐配置：8GB+ 显存（运行舒适）
- 理想配置：12GB+ 显存（可以批处理多张图）
所以：8GB 显存 + RTX 30 系列以上达到高效运行是完全没问题的。整个过程主要包括以下几个核心步骤：
- 创建 Python 虚拟环境 - 隔离项目依赖，避免环境冲突；
- 安装 PaddlePaddle 深度学习框架 - PaddleOCR 的底层依赖；
- 安装 PaddleOCR 库 - 核心 OCR 功能库；
- 下载预训练模型 - PaddleOCR-VL-0.9B 和 PP-DocLayoutV2；
- 验证安装 - 运行测试确保环境正常；
公开课所使用的硬件环境为：Ubuntu 22.04 + 4 * 3090，共计显存96G显存，运行起来非常流畅。
4.1 创建虚拟环境
首先，我们需要创建一个独立的 Python 虚拟环境。虚拟环境可以隔离项目依赖，避免与系统其他 Python 项目产生冲突。执行如下命令
FENCE16
其中：
--name ppocr-vllm：虚拟环境名称，可以自定义python==3.11：指定 Python 版本为 3.11（PaddleOCR 推荐版本）
执行效果如下图所示：
接下来激活虚拟环境：
FENCE17
激活后，命令行提示符前会显示 (ppocr-vllm)，表示已进入虚拟环境。
4.2 安装 PaddleOCR 工具框架
首先需要区分PaddleOCR 和 PaddleOCR-VL 两个之间的区别和联系。首先。PaddleOCR 是一个较为成熟、功能全面的 OCR＋文档理解开源工具库，其开源地址：https://github.com/PaddlePaddle/PaddleOCR/tree/main
PaddleOCR-VL 是在这个生态内新发布的一个专注于“文档解析／视觉-语言模型 (Vision-Language Model, VLM)”功能的新模块。
简单来说，PaddleOCR 是一个“全面且成熟”的 OCR＋文档理解工具箱，而 PaddleOCR-VL 是在这个工具箱里“专门为复杂文档解析”设计的新模块，采用了视觉-语言模型架构以应对更高阶的需求。
因此，在使用PaddleOCR-VL 时，我们首先需要安装 PaddleOCR 工具框架。https://www.paddlepaddle.org.cn/install/quick?docurl=/documentation/docs/zh/develop/install/pip/linux-pip.html
这里安装 PaddlePaddle 3.2.0 版本。执行如下命令：
FENCE18
其中:
paddlepaddle-gpu==3.2.0：GPU 版本的 PaddlePaddle 3.2.0-i https://...：使用百度官方镜像源，下载速度更快cu126：对应 CUDA 12.6 版本
安装过程如下图所示：
安装结束后，需要验证 PaddlePaddle 安装状态，依次运行以下命令验证：
FENCE19
如果看到如下“”信息，说明 PaddlePaddle 已成功安装。
接下来要重点关注的是：PaddleOCR-VL 使用 safetensors 格式存储模型权重，需要额外安装，同时需要安装指定版本的，执行如下命令
FENCE20
这是兼容最新PaddleOCR-Vl 的 safetensors 版本，安装很快。
4.3 下载PaddleOCR-VL模型
使用 PaddleOCR-VL 解析功能需要两个预训练模型，其中：
- PaddleOCR-VL-0.9B - 视觉语言模型（用于文本识别）
- PP-DocLayoutV2 - 文档布局检测模型（用于布局分析）
该模型权重的HuggingFace 地址为：https://huggingface.co/PaddlePaddle/PaddleOCR-VL ，
此外，对于我们国内用户来说，更建议通过 ModelScope 下载（推荐）。https://modelscope.cn/models/PaddlePaddle/PaddleOCR-VL/summary
ModelScope 是阿里云的模型托管平台，国内访问速度快。首先执行如下命令：
FENCE21
新建一个 download_paddleocr_vl.py 文件，写入如下代码：
FENCE22
其中：
'PaddlePaddle/PaddleOCR-VL'：模型仓库 IDlocal_dir='.'：下载到当前目录（也可以指定其他路径，如 './models'）
接下来执行如下代码进行模型权重安装：
FENCE23
下载完成后的模型目录结构如下所示：
其中 PaddleOCR-VL-0.9B 文件夹中存储的就是本次最新开源的超紧凑视觉语言模型，具有以下特点：
PaddleOCR-VL-0.9B 模型特性
| 特性 | 说明 |
|---|
| 模型规模 | 0.9B 参数（极小，推理速度快） |
| 语言支持 | 109 种语言（包括中文、英文、日语、韩语等） |
| 识别能力 | 文本、表格、公式、图表等复杂元素 |
| 输出格式 | Markdown、JSON、HTML |
| 资源消耗 | GPU 显存 4GB+，推理速度 1.22 页/秒（A100） |
| 优势 | 比 MinerU 快 15.8%，显存占用比 dots.ocr 少 40% |
接下来，在进行运行前需要依次安装依赖包，首先是paddleocr[all], 其中：
FENCE24
这里我们安装doc-parser，如下图所示：
然后，使用 PaddleOCR CLI 安装 vLLM 的推理加速服务依赖：
FENCE25
安装完成后，继续安装 flash-atten 编译包：
FENCE26
接下来，就可以启动vLLM 服务器服务器了。如下代码所示：
FENCE27
vLLM 服务启动后，保持这个终端窗口运行，不要关闭。同时打开一个新的终端，使用paddlex连接启动的paddleocr-vl服务，首先进行初始化服务配置：
FENCE28
然后生成 .yaml 配置文件：
FENCE29
找到 genai_config 配置项，修改为如下所示：
最后，启动 PaddleOCR API 服务：
FENCE30
成功启动后，在浏览器中访问 http://192.168.110.131:10800/docs 查看API文档，如下图所示：
至此，PaddleOCR API 服务启动成功。
4.4 PaddleOCR vLLM API服务连接测试
FENCE31
PaddleOCR Doc Parser 命令参数如下表所示：
基础参数
| 参数名 | 说明 |
|---|
-i INPUT, --input INPUT | 输入路径或 URL（必需） |
--save_path SAVE_PATH | 输出目录路径 |
布局检测参数
| 参数名 | 说明 |
|---|
--layout_detection_model_name | 布局检测模型名称 |
--layout_detection_model_dir | 布局检测模型目录路径 |
--layout_threshold | 布局检测模型的分数阈值 |
--layout_nms | 是否在布局检测中使用 NMS（非极大值抑制） |
--layout_unclip_ratio | 布局检测的扩展系数 |
--layout_merge_bboxes_mode | 重叠框过滤方法 |
VL识别模型参数
| 参数名 | 说明 |
|---|
--vl_rec_model_name | VL 识别模型名称 |
--vl_rec_model_dir | VL 识别模型目录路径（指定本地 PaddleOCR-VL-0.9B 模型路径） |
--vl_rec_backend | VL 识别模块使用的后端（native, vllm-server, sglang-server） |
--vl_rec_server_url | VL 识别模块使用的服务器 URL |
--vl_rec_max_concurrency | VLM 请求的最大并发数 |
文档处理模型
| 参数名 | 说明 |
|---|
--doc_orientation_classify_model_name | 文档图像方向分类模型名称 |
--doc_orientation_classify_model_dir | 文档图像方向分类模型目录路径 |
--doc_unwarping_model_name | 文本图像矫正模型名称 |
--doc_unwarping_model_dir | 图像矫正模型目录路径 |
功能开关参数
| 参数名 | 说明 |
|---|
--use_doc_orientation_classify | 是否使用文档图像方向分类 |
--use_doc_unwarping | 是否使用文本图像矫正 |
--use_layout_detection | 是否使用布局检测 |
--use_chart_recognition | 是否使用图表识别 |
--format_block_content | 是否将块内容格式化为 Markdown |
--use_queues | 是否使用队列进行异步处理 |
VLM生成参数
| 参数名 | 说明 |
|---|
--prompt_label | VLM 的提示标签 |
--repetition_penalty | VLM 采样中使用的重复惩罚系数 |
--temperature | VLM 采样中使用的温度参数 |
--top_p | VLM 采样中使用的 top-p 参数 |
--min_pixels | VLM 图像预处理的最小像素数 |
--max_pixels | VLM 图像预处理的最大像素数 |
硬件与性能参数
| 参数名 | 说明 |
|---|
--device | 用于推理的设备，例如 cpu、gpu、npu、gpu:0、gpu:0,1。如果指定多个设备，将并行执行推理。注意：并非所有情况都支持并行推理。默认情况下，如果可用将使用 GPU 0，否则使用 CPU |
--enable_hpi | 启用高性能推理 |
--use_tensorrt | 是否使用 Paddle Inference TensorRT 子图引擎。如果模型不支持 TensorRT 加速，即使设置此标志也不会使用加速 |
--precision | 使用 Paddle Inference TensorRT 子图引擎时的 TensorRT 精度（fp32, fp16） |
--enable_mkldnn | 为推理启用 MKL-DNN 加速。如果 MKL-DNN 不可用或模型不支持，即使设置此标志也不会使用加速 |
--mkldnn_cache_capacity | MKL-DNN 缓存容量 |
--cpu_threads | 在 CPU 上用于推理的线程数 |
--paddlex_config | PaddleX 管道配置文件路径 |
当然，上述代码也是LangChain1.0 + OCR 多模态PDF解析实战项目中PaddleOCR 的核心代码逻辑：
五、DeepSeek-OCR vLLM 服务接口启动
DeepSeek-OCR 作为刚刚开源的小型多模态视觉模型，经过我们团队大量的测试，其不仅识别精度高，同时对中文的支持也非常出色，同时也能够输出结构化的 Markdown 格式文档。
5.1 环境配置要求
在开始部署之前，我们首先需要确认自己的服务器是否满足运行条件。
硬件配置要求（建议）
| 硬件类型 | 最低要求 | 推荐配置 | 说明 |
|---|
| GPU | NVIDIA RTX 3090 | RTX 4090 或更高 | 必须是NVIDIA显卡，支持CUDA |
| 显存 | 24GB | 24GB+ | 显存越大，处理速度越快 |
| 内存 | 32GB | 64GB+ | 用于图像预处理和数据缓存 |
| 硬盘 | 50GB可用空间 | 100GB+ | 模型文件较大，需要足够空间 |
除了硬件，我们还需要准备相应的软件环境：主要包括操作系统：建议使用 Ubuntu 22.04，同时需要 CUDA 12.0+，而Python 环境建议使用 Python 3.10+。
课程使用的配置环境为：Ubuntu 22.04 + 四卡 3090。大家在使用 vLLM 启动DeepSeek-OCR时，首先需要做如下配置校验：
FENCE32
执行上述命令后，如果看到类似下面的输出，说明GPU正常工作：
接下来检查 Conda 是否安装，执行如下命令：
FENCE33
如果看到类似 conda XXX 的版本号，说明conda已经安装。如果提示命令不存在，需要先安装 miniconda 或者 anaconda3。
5.2 DeepSeek-OCR模型下载
环境准备好之后，接下来我们需要下载 DeepSeek-OCR 模型文件，并进行相应的配置。这一步是整个部署过程的核心。国内用户强烈建议大家使用 ModelScope 下载模型，没有网络限制，同时速度也会快很多。
首先，我们需要创建一个独立的 Python 虚拟环境。虚拟环境可以隔离项目依赖，避免与系统其他 Python 项目产生冲突。执行如下命令
FENCE34
其中：
--name deepseek-ocr-vllm：虚拟环境名称，可以自定义python==3.10：指定 Python 版本为 3.10（PaddleOCR 推荐版本）
执行效果如下图所示：
接下来激活虚拟环境：
FENCE35
激活后，命令行提示符前会显示 (deepseek-ocr-vllm)，表示已进入虚拟环境。
接下来，在ModelScope 平台下载 DeepSeek-OCR 模型文件。地址：https://modelscope.cn/models/deepseek-ai/DeepSeek-OCR
ModelScope 是阿里云的模型托管平台，国内访问速度快。首先执行如下命令：
FENCE36
然后执行如下代码：
FENCE37
其中：
'deepseek-ai/DeepSeek-OCR'：模型仓库 IDlocal_dir='.'：下载到当前目录（也可以指定其他路径，如 './models'）
接下来执行如下代码进行模型权重安装：
FENCE38
下载完成后的模型目录结构如下所示：
5.3 Deepseek-OCR vLLM 项目文件
DeepSeek-OCR通过 vLLM 平台启动，我们是借助DeepSeek-OCR官方提供的项目代码，并做了一些优化和调整，其官方源码下载地址：https://github.com/deepseek-ai/DeepSeek-OCR/tree/main/DeepSeek-OCR-master/DeepSeek-OCR-vllm
我们将项目文件下载到本地并上传到服务器上：
其中deepseek_ocr.py 和 flash_attn-2.7.3+cu12torch2.6cxx11abiFALSE-cp310-cp310-linux_x86_64.whl 使我们给大家提供的两个核心文件，一个用于封装 DeepSeek OCR API 接口，另一个则是离线安装的 fla_ttn 的离线安装包。
接下来一键安装 vLLM 运行 DeepSeek-OCR的依赖包：
安装结束后，使用我们给大家提供的deepseek_ocr.py文件，启动 DeepSeek OCR API 接口 服务。
启动命令如下：
FENCE39
启动成功后，会显示如下：
接下来，便可以在网页端查看到 FastAPI 接口：
5.4 DeepSeek-OCR API 连接测试
前面我们完成了服务的部署和启动，接下来我们要学习如何在实际项目中调用这个 OCR 服务。本节将通过完整的代码示例，带领大家掌握图片识别和 PDF 文档处理的全流程。
在开始编写调用代码之前，我们先来了解一下 OCR 服务提供的 API 接口规范。
OCR API 接口规范
| 项目 | 说明 |
|---|
| 接口地址 | http://localhost:8797/ocr |
| 请求方式 | POST |
| 内容类型 | multipart/form-data |
| 文件参数 | file（支持 jpg, png, pdf 等格式） |
| 可选参数 | enable_description（是否生成图片描述，默认 False） |
返回的数据格式如下：
FENCE40
返回的 markdown 字段就是我们需要的识别结果，它保留了原文档的格式结构，包括标题、列表、表格等。
下面我们通过一个完整的代码示例，来演示如何调用 OCR 服务。
FENCE41
测试文件: ./course.pdf
API 地址: http://192.168.110.131:8797/ocr
输出目录: ./
------------------------------------------------------------
发送请求到 DeepSeek API...
API 响应成功
响应包含的字段: ['markdown', 'page_count', 'images']
------------------------------------------------------------
Markdown 长度: 10026 字符
页数: 12
图像数量: 14
图像列表:
- page_0_img_0.png: 161960 字符 (base64)
- page_1_img_0.png: 9892 字符 (base64)
- page_1_img_1.png: 111764 字符 (base64)
- page_1_img_2.png: 43132 字符 (base64)
- page_2_img_0.png: 66016 字符 (base64)
- page_3_img_0.png: 57016 字符 (base64)
- page_4_img_0.png: 53420 字符 (base64)
- page_5_img_0.png: 166376 字符 (base64)
- page_6_img_0.png: 34012 字符 (base64)
- page_8_img_0.png: 227632 字符 (base64)
------------------------------------------------------------
Markdown 已保存: course_deepseek.md
响应摘要已保存: course_response.json
图像数据已保存: course_images.json
------------------------------------------------------------
统计信息:
- HTML 表格: 9 个
- Markdown 图片引用: 14 个
- Markdown 行数: 264 行
------------------------------------------------------------
测试完成！
通过不同的提示词，对输入的PDF文档的每一页做格式化提取：
FENCE42
当然，上述代码也是LangChain1.0 + OCR 多模态PDF解析实战项目中DeepSeek-OCR 的核心代码逻辑：
六、OCR 多模态解析系统本地部署
完整的系统需要同时启动后端和前端两个服务。首先对于后端服务启动，需要依次执行如下操作：
FENCE43
启动服务执行如下代码：
FENCE44
然后，便可以在 http://192.168.110.131:8000/docs 查看 API 文档：
前端服务启动，需要依次执行如下操作:
FENCE45
启动成功后，即可通过http://localhost:3000访问应用。
【加餐】 LangChain1.0 接入 MinerU MCP Server
随着MinerU项目的发展，除了解析性能上进一步提升，同时也支持了MCP协议，可以通过stdio、Http + Sse和 Streamable Http三种通信模型进行访问。因此，本小节我们重点讲解MinerU项目在MCP协议下的使用，并基于LangChain 1.0 新版本实现MinerU MCP的接入。
最新版本的MinerU 项目中内置了MCP Server 服务，我们可以通过该服务将MinerU 的解析服务暴露给ADK 或 Agent 使用。与常规的MCP Server 构建方式一样，也是通过 FastMCP 外放FastAPI 服务并支持stdio、Http+Sse和StreamableHttp 三种传输方式。源码位置如下：
这里我们使用StreamableHttp 传输方式，并且在启动前，修改下源码，使其可以加载我们通过命令行传递的host参数，否则只能使用默认的localhost 地址。如下所示：
接下来创建MCP的uv环境，首先通过pip 安装 uv:
FENCE46
然后通过uv 创建MCP 的uv 环境，并安装MinerU 项目中用到的依赖：
FENCE47
安装完成后，我们就可以通过uv 启动MCP 服务了：
FENCE48
启动后，我们可以在浏览器中访问http://192.168.110.131:8000/mcp快速进行验证：
需要重点注意的是：parse_documents 工具是MinerU 项目中通过FastAPI 外放的工具接口，其本质上，调用的是mineru-api 服务中的/api/parse 接口。所以，大家要理解的逻辑是：
FastMCP 负责暴露parse_documents和get_ocr_languages 工具协议，而真正做 PDF→Markdown 的逻辑在 MinerU 的“本地解析服务”里，并通过 /file_parse 路由完成。MCP 只是一个工具“壳”，真正干活的是mineru-api。因此，我们首先需要修改MinerU MCP Server的配置文件，让其找到解析服务。如下所示：
FENCE49
修改如下：
其中USE_LOCAL_API=true 表示使用本地解析服务，LOCAL_API_URL 表示本地解析服务的地址。修改完成后重新启动MinerU MCP Server 服务。
FENCE50
接下来新打开一个终端，启动`mineru-api` 服务：
FENCE51
启动后，在192.168.110.131:30000/docs中可以看到接口服务：
全部验证成功后，我们就可以在LangChain中使用MCP 服务了。代码如下：
FENCE52
[33mWARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.[0m[33m
[0m
安装完成后，让我们导入必要的模块：
FENCE53
现在，配置连接到 MinerU MCP 服务的参数。根据服务启动日志，
FENCE54
MCP 服务器地址: http://192.168.110.131:8001/mcp
服务器参数配置完成
在实际解析 PDF 之前，我们先要了解 MCP 服务器提供了哪些工具。这就像进入一个工具箱，先看看里面有什么工具可用。如下函数来列出所有可用的 MCP 工具：
FENCE55
🔌 正在连接 MCP 服务器...
MCP 会话初始化成功
发现 2 个可用工具：
================================================================================
工具 1: parse_documents
描述: 统一接口，将文件转换为Markdown格式。支持本地文件和URL，会根据USE_LOCAL_API配置自动选择合适的处理方式。
当USE_LOCAL_API=true时:
- 会过滤掉http/https开头的URL路径
- 对本地文件使用本地API进行解析
当USE_LOCAL_API=false时:
- 将http/https开头的路径使用convert_file_url处理
- 将其他路径使用convert_file_path处理
处理完成后，会自动尝试读取转换后的文件内容并返回。
返回:
成功: {"status": "success", "content": "文件内容"} 或 {"status": "success", "results": [处理结果列表]}
失败: {"status": "error", "error": "错误信息"}
参数结构:
工具 2: get_ocr_languages
描述: 获取 OCR 支持的语言列表。
Returns:
Dict[str, Any]: 包含所有支持的OCR语言列表的字典
参数结构:
================================================================================
接下来，构建一个完整的客户端类，封装所有的功能，使其更易用。客户端类将包含以下功能：
- 连接管理
- 工具列表查询
- PDF 文档解析
- 结果保存
FENCE56
MinerU 客户端已初始化
服务器地址: http://192.168.110.131:8001/mcp
客户端创建成功！
在实际运行之前，我们需要准备一个 PDF 文件用于测试。
FENCE57
================================================================================
创建 LangChain Agent 自动调用 MCP 工具
================================================================================
加载 MCP 工具...
已加载 2 个 MCP 工具
- parse_documents: 统一接口，将文件转换为Markdown格式。支持本地文件和URL，会根据USE_LOCAL_API配置自动选择合适的处理...
- get_ocr_languages: 获取 OCR 支持的语言列表。
Returns:
Dict[str, Any]: 包含所有支持的OCR语言列表...
================================================================================
使用 parse_documents 工具解析 PDF
================================================================================
文件: course.pdf
大小: 1391.70 KB
调用 parse_documents 工具...
解析完成！
解码文件名: course
================================================================================
解析结果统计
================================================================================
总字符数: 12,693
总行数: 364
结果已保存到: /home/MuyuWorkSpace/course_parsed.md
当前工作目录: /home/MuyuWorkSpace
文件大小: 16.40 KB
--------------------------------------------------------------------------------
解析结果预览（前 1500 字符）:
--------------------------------------------------------------------------------
# 五、项目：PaddleOCR-VL构建多模态RAG系统
本节内容，我们将详细介绍如何部署和运行这个基于PaddleOCR-VL的多模态AgenticRAG智能问答系统。该系统支持复杂PDF文档、图片、表格、公式等多种格式的智能分析和问答，并具备精准的溯源能力。
# 5.1 项目核心模块代码详解
PaddleOCR-VL的输出格式非常适合构建多模态RAG系统，如果想要明确的区分出图像、表格、普通文本等信息，一个基本的处理流程是这样的：
```txt
PaddleOCR-VL JSON 输出↓
```
1. 数据预处理
```txt
按block_order排序过滤无用内容（footer等）合并相邻同类型块
```
2. 分类处理
```txt
文本类 $\rightarrow$ 标准 chunk 表格类 $\rightarrow$ 结构化提取 $+$ 文本描述 公式类 $\rightarrow$ 保留格式 $+$ 语义转换 图片类 $\rightarrow$ 多模态向量 / 标题关联
```
3. 元数据增强
```txt
- block_id（溯源ID）
- block_bbox（位置坐标）
- block_type（元素类型）
- page_index（页码）
- 上下文信息（前后标题、图表编号）
```
4. 向量化与索引
```txt
文本 Embedding
表格 Embedding（多策略）建立多级索引
```
5. 检索与溯源
语义检索
坐标定位
可视化标注
分享 | 下载(195.7M) | 删除 : 更多
全部文件/木羽公开课资料/20251022基于PaddleOCR-VL搭建企...
首先第一步做的就是完成PaddleOCR-VL模型的接入及实现解析过程。核心代码文件为:
这个服务的核心流程是：初始化时异步加载 PaddleOCRVL 模型到，然后在 parse_document() 中通过线程池执行阻塞的 OCR 调用，PaddleOCR 会将文档解析为多页结果并保存为 JSON/Markdown/可视化图片到磁盘。服务优先从生成的 *_res.json 文件中读取每页的 parsing_res_list，将其中的每个 block（包含 block_id、block_label、block_content、block_bbox、block_order 等字段）转换为 ParsingBlock 对象，最后通过 calculate.stats() 按 label 关键词（table/image/formula/其他）统计各类型块的数量并返回 DocumentStats。即：
1. 初始化 $\rightar
... (后续内容已省略)
--------------------------------------------------------------------------------
================================================================================
成功！
================================================================================
同时也可以看到后端的服务运行情况：
我们下期公开课，再见！ 👋
