[Docs] Optimize docs for deployment of PaddleOCR-VL (#16808)

* Optimize docs for deployment of PaddleOCR-VL

* Update docs

* Fix not-using-doc-prepeocessor bug

* Update dockerfiles and docs

* Add SFT

* Fix code style

* Add PaddleOCR-VL-0.9B model into offline pipeline image

* Support Windows

* Add lower bound for paddleocr version

* Revert windows and paddle 3.2.1

* Support setting paddleocr version

* Fix typo

* Update docker image sizes

* Fix bug

* Fix doc

deploy/paddleocr_vl_docker/build.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+build_for_offline='false'
+tag_suffix='latest'
+paddleocr_version='>=3.3.1,<3.4'
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --offline)
+            build_for_offline='true'
+            tag_suffix='latest-offline'
+            shift
+            ;;
+        --ppocr-version)
+            paddleocr_version="==$2"
+            shift
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+docker build \
+    -f pipeline.Dockerfile \
+    -t "ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:${tag_suffix}" \
+    --build-arg BUILD_FOR_OFFLINE="${build_for_offline}" \
+    --build-arg PADDLEOCR_VERSION="${paddleocr_version}" \
+    --build-arg http_proxy="${http_proxy}" \
+    --build-arg https_proxy="${https_proxy}" \
+    --build-arg no_proxy="${no_proxy}" \
+    .
+
+docker build \
+    -f vlm.Dockerfile \
+    -t "ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:${tag_suffix}" \
+    --build-arg BUILD_FOR_OFFLINE="${build_for_offline}" \
+    --build-arg PADDLEOCR_VERSION="${paddleocr_version}" \
+    --build-arg http_proxy="${http_proxy}" \
+    --build-arg https_proxy="${https_proxy}" \
+    --build-arg no_proxy="${no_proxy}" \
+    .

deploy/paddleocr_vl_docker/compose.yaml

@@ -0,0 +1,34 @@
+services:
+  paddleocr-vl-api:
+    image: ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline
+    container_name: paddleocr-vl-api
+    ports:
+      - 8080:8080
+    depends_on:
+      paddleocr-genai-vllm-server:
+        condition: service_healthy
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              device_ids: ["0"]
+              capabilities: [gpu]
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
+
+  paddleocr-genai-vllm-server:
+    image: ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-offline
+    container_name: paddleocr-genai-vllm-server
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              device_ids: ["0"]
+              capabilities: [gpu]
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
+      start_period: 300s

deploy/paddleocr_vl_docker/pipeline.Dockerfile

@@ -0,0 +1,51 @@
+FROM python:3.10
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+    && apt-get install -y libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PIP_NO_CACHE_DIR=0
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+RUN python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
+ARG PADDLEOCR_VERSION=">=3.3.1,<3.4"
+RUN python -m pip install "paddleocr[doc-parser]${PADDLEOCR_VERSION}" \
+    && python -m pip install https://paddle-whl.bj.bcebos.com/nightly/cu126/safetensors/safetensors-0.6.2.dev0-cp38-abi3-linux_x86_64.whl \
+    && paddlex --install serving
+
+RUN groupadd -g 1000 paddleocr \
+    && useradd -m -s /bin/bash -u 1000 -g 1000 paddleocr
+ENV HOME=/home/paddleocr
+WORKDIR /home/paddleocr
+
+USER paddleocr
+
+ARG BUILD_FOR_OFFLINE=false
+RUN if [ "${BUILD_FOR_OFFLINE}" = 'true' ]; then \
+        mkdir -p "${HOME}/.paddlex/official_models" \
+        && cd "${HOME}/.paddlex/official_models" \
+        && wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/UVDoc_infer.tar \
+            https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-LCNet_x1_0_doc_ori_infer.tar \
+            https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-DocLayoutV2_infer.tar \
+            https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PaddleOCR-VL_infer.tar \
+        && tar -xf UVDoc_infer.tar \
+        && mv UVDoc_infer UVDoc \
+        && tar -xf PP-LCNet_x1_0_doc_ori_infer.tar \
+        && mv PP-LCNet_x1_0_doc_ori_infer PP-LCNet_x1_0_doc_ori \
+        && tar -xf PP-DocLayoutV2_infer.tar \
+        && mv PP-DocLayoutV2_infer PP-DocLayoutV2 \
+        && tar -xf PaddleOCR-VL_infer.tar \
+        && mv PaddleOCR-VL_infer PaddleOCR-VL \
+        && rm -f UVDoc_infer.tar PP-LCNet_x1_0_doc_ori_infer.tar PP-DocLayoutV2_infer.tar PaddleOCR-VL_infer.tar \
+        && mkdir -p "${HOME}/.paddlex/fonts" \
+        && wget -P "${HOME}/.paddlex/fonts" https://paddle-model-ecology.bj.bcebos.com/paddlex/PaddleX3.0/fonts/PingFang-SC-Regular.ttf; \
+    fi
+
+COPY --chown=paddleocr:paddleocr pipeline_config.yaml /home/paddleocr
+
+EXPOSE 8080
+
+CMD ["paddlex", "--serve", "--pipeline", "/home/paddleocr/pipeline_config.yaml"]

deploy/paddleocr_vl_docker/pipeline_config.yaml

@@ -0,0 +1,97 @@
+
+pipeline_name: PaddleOCR-VL
+
+batch_size: 64
+
+use_queues: True
+
+use_doc_preprocessor: False
+use_layout_detection: True
+use_chart_recognition: False
+format_block_content: False
+
+SubModules:
+  LayoutDetection:
+    module_name: layout_detection
+    model_name: PP-DocLayoutV2
+    model_dir: null
+    batch_size: 8
+    threshold: 
+      0: 0.5 # abstract
+      1: 0.5 # algorithm
+      2: 0.5 # aside_text
+      3: 0.5 # chart
+      4: 0.5 # content
+      5: 0.4 # formula
+      6: 0.4 # doc_title
+      7: 0.5 # figure_title
+      8: 0.5 # footer
+      9: 0.5 # footer
+      10: 0.5 # footnote
+      11: 0.5 # formula_number
+      12: 0.5 # header
+      13: 0.5 # header
+      14: 0.5 # image
+      15: 0.4 # formula
+      16: 0.5 # number
+      17: 0.4 # paragraph_title
+      18: 0.5 # reference
+      19: 0.5 # reference_content
+      20: 0.45 # seal
+      21: 0.5 # table
+      22: 0.4 # text
+      23: 0.4 # text
+      24: 0.5 # vision_footnote
+    layout_nms: True
+    layout_unclip_ratio: [1.0, 1.0] 
+    layout_merge_bboxes_mode: 
+      0: "union" # abstract
+      1: "union" # algorithm
+      2: "union" # aside_text
+      3: "large" # chart
+      4: "union" # content
+      5: "large" # display_formula
+      6: "large" # doc_title
+      7: "union" # figure_title
+      8: "union" # footer
+      9: "union" # footer
+      10: "union" # footnote
+      11: "union" # formula_number
+      12: "union" # header
+      13: "union" # header
+      14: "union" # image
+      15: "large" # inline_formula
+      16: "union" # number
+      17: "large" # paragraph_title
+      18: "union" # reference
+      19: "union" # reference_content
+      20: "union" # seal
+      21: "union" # table
+      22: "union" # text
+      23: "union" # text
+      24: "union" # vision_footnote
+  VLRecognition:
+    module_name: vl_recognition
+    model_name: PaddleOCR-VL-0.9B
+    model_dir: null
+    batch_size: 2048
+    genai_config:
+      backend: vllm-server
+      server_url: http://paddleocr-genai-vllm-server:8080/v1
+
+SubPipelines:
+  DocPreprocessor:
+    pipeline_name: doc_preprocessor
+    batch_size: 8
+    use_doc_orientation_classify: True
+    use_doc_unwarping: True
+    SubModules:
+      DocOrientationClassify:
+        module_name: doc_text_orientation
+        model_name: PP-LCNet_x1_0_doc_ori
+        model_dir: null
+        batch_size: 8
+      DocUnwarping:
+        module_name: image_unwarping
+        model_name: UVDoc
+        model_dir: null

deploy/paddleocr_vl_docker/vlm.Dockerfile

@@ -0,0 +1,24 @@
+FROM ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server:latest
+
+ARG PADDLEOCR_VERSION=">=3.3.1,<3.4"
+RUN python -m pip install "paddleocr${PADDLEOCR_VERSION}"
+RUN paddleocr install_genai_server_deps vllm
+
+RUN groupadd -g 1000 paddleocr \
+    && useradd -m -s /bin/bash -u 1000 -g 1000 paddleocr
+ENV HOME=/home/paddleocr
+WORKDIR /home/paddleocr
+
+USER paddleocr
+
+ARG BUILD_FOR_OFFLINE=false
+RUN if [ "${BUILD_FOR_OFFLINE}" = 'true' ]; then \
+        mkdir -p "${HOME}/.paddlex/official_models" \
+        && cd "${HOME}/.paddlex/official_models" \
+        && wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PaddleOCR-VL_infer.tar \
+        && tar -xf PaddleOCR-VL_infer.tar \
+        && mv PaddleOCR-VL_infer PaddleOCR-VL \
+        && rm -f PaddleOCR-VL_infer.tar; \
+    fi
+
+CMD ["paddleocr", "genai_server", "--model_name", "PaddleOCR-VL-0.9B", "--host", "0.0.0.0", "--port", "8080", "--backend", "vllm"]

docs/version3.x/pipeline_usage/PaddleOCR-VL.en.md

@@ -10,53 +10,107 @@ PaddleOCR-VL is a SOTA and resource-efficient model tailored for document parsin
 
 ## 1. Environment Preparation
 
-Install PaddlePaddle and PaddleOCR:
+We recommend using the official Docker image (requires Docker version >= 19.03, a machine equipped with a GPU, and NVIDIA drivers supporting CUDA 12.8):
 
 ```shell
+docker run \
+    -it \
+    --gpus all \
+    --network host \
+    --user root \
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest \
+    /bin/bash
+# Call PaddleOCR CLI or Python API inside the container
+```
+
+The image size is approximately 8 GB. If you want to use **PaddleOCR-VL** in an environment without internet access, replace `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest` in the above command with the offline version image
+`ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline` (the offline image is about 11 GB). You’ll need to pull the image on a machine with internet access, import it to the offline machine, and then use it to start the container. For example:
+
+```shell
+# Execute on a machine with internet access
+docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline
+# Save the image to a file
+docker save ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline -o paddleocr-vl-latest-offline.tar
+
+# Transfer the image file to the offline machine
+
+# Execute on the offline machine
+docker load -i paddleocr-vl-latest-offline.tar
+# After this, you can use `docker run` to start the container on the offline machine
+```
+
+If you cannot use Docker, you can also manually install PaddlePaddle and PaddleOCR. Python version 3.8–3.12 is required.
+
+**We strongly recommend installing PaddleOCR-VL in a virtual environment to avoid dependency conflicts.** For example, use the Python venv standard library to create a virtual environment:
+
+```shell
+# Create a virtual environment
+python -m venv .venv_paddleocr
+# Activate the environment
+source .venv_paddleocr/bin/activate
+```
+
+Execute the following commands to complete the installation:
+
+```shell
+# The following command installs PaddlePaddle for CUDA 12.6. For other CUDA versions and CPU-only version, please refer to: https://www.paddlepaddle.org.cn/install/quick?docurl=/documentation/docs/zh/develop/install/pip/linux-pip.html
 python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
 python -m pip install -U "paddleocr[doc-parser]"
+# For Linux systems, run:
 python -m pip install https://paddle-whl.bj.bcebos.com/nightly/cu126/safetensors/safetensors-0.6.2.dev0-cp38-abi3-linux_x86_64.whl
 ```
-> For Windows users, please use WSL or a Docker container.
 
-Running the PaddleOCR-VL has the following GPU hardware requirements:
+> **Please make sure to install PaddlePaddle version 3.2.0 or above, and also install the special version of `safetensors`.** For Windows users, please use **WSL** or **Docker** to set up the environment; for macOS users, please use **Docker** for environment setup.
+
+# PaddleOCR-VL support for inference devices is as follows:
 
 <table border="1">
 <thead>
   <tr>
     <th>Inference Method</th>
-    <th>GPU Compute Capability</th>
+    <th>Supports x64 CPU</th>
+    <th>Supported GPU Compute Capability</th>
+    <th>Supported CUDA Versions</th>
   </tr>
 </thead>
 <tbody>
   <tr>
     <td>PaddlePaddle</td>
-    <td>≥ 8.5</td>
+    <td>✅</td>
+    <td>≥ 7</td>
+    <td>11.8, 12.6, 12.8</td>
   </tr>
   <tr>
     <td>vLLM</td>
+    <td>🚧</td>
     <td>≥ 8 (RTX 3060, RTX 5070, A10, A100, ...) <br />  
-    7 ≤ GPU Compute Capability < 8 (T4, V100, ...) Supported but may experience issues like request timeouts, OOM errors, etc. Not recommended for use.
+    7 ≤ GPU Compute Capability < 8 (T4, V100, ...) can run but may experience issues like request timeouts, OOM, etc. Not recommended for use.
     </td>
+    <td>12.8</td>
   </tr>
   <tr>
     <td>SGLang</td>
+     <td>🚧</td>
     <td>8 ≤ GPU Compute Capability < 12</td>
+    <td>12.8</td>
   </tr>
 </tbody>
 </table>
 
-The PaddleOCR-VL currently does not support CPU or Arm architecture. Support for more hardware will be expanded based on actual requirements in the future. Stay tuned!
+> Currently, PaddleOCR-VL does not support ARM architecture CPUs. Support for more hardware will be expanded based on actual requirements in the future. Stay tuned!  
+> vLLM and SGLang cannot run natively on Windows or macOS. Please use the Docker image we provide.
 
 ## 2. Quick Start
 
 PaddleOCR-VL supports two usage methods: CLI command line and Python API. The CLI command line method is simpler and suitable for quickly verifying functionality, while the Python API method is more flexible and suitable for integration into existing projects.
 
+> The methods introduced in this section are primarily for rapid validation. Their inference speed, memory usage, and stability may not meet the requirements of a production environment. **If deployment to a production environment is needed, we strongly recommend using a dedicated inference acceleration framework**. For specific methods, please refer to the next section.
+
 ### 2.1 Command Line Usage
 
 Run a single command to quickly test the PaddleOCR-VL ：
 
-```bash
+```shell
 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png
 
 # Use --use_doc_orientation_classify to enable document orientation classification
@@ -895,54 +949,58 @@ The inference performance under the default configuration has not been fully opt
 
 #### 3.1.1 Using Docker Images
 
-PaddleOCR provides Docker images for quickly starting the vLLM inference service. The service can be started using the following command:
+PaddleOCR provides Docker images for quickly launching vLLM inference services. You can use the following command to start the service (requires Docker version >= 19.03, a machine equipped with a GPU, and NVIDIA drivers supporting CUDA 12.8):
 
-```bash
+```shell
 docker run \
     -it \
     --rm \
     --gpus all \
     --network host \
-    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest
 ```
 
-The service listens on port **8080** by default.
+The image size is approximately 13 GB. The server listens on port **8080** by default.
 
-When starting the container, you can pass in parameters to override the default configuration. The parameters are consistent with the `paddleocr genai_server` command (see the next subsection for details). For example:
+If you wish to start the service in an environment without internet access, replace `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest` in the above command with the offline version image `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-offline`. The offline image size is approximately 15 GB.
 
-```bash
+You can pass parameters when starting the container to override the default configurations. For supported parameters, please refer to the next subsection. For example:
+
+```shell
 docker run \
     -it \
     --rm \
     --gpus all \
     --network host \
-    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server \
-    paddlex_genai_server --model_name PaddleOCR-VL-0.9B --host 0.0.0.0 --port 8118 --backend vllm
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest \
+    paddleocr genai_server --model_name PaddleOCR-VL-0.9B --host 0.0.0.0 --port 8118 --backend vllm
 ```
 
-If you are using an NVIDIA 50 series graphics card (Compute Capability >= 12), you need to install a specific version of FlashAttention before launching the service.
+If you are using an NVIDIA 50-series graphics card (Compute Capability >= 12), you need to install a specific version of FlashAttention before starting the service:
 
-```bash
+```shell
 docker run \
     -it \
     --rm \
     --gpus all \
     --network host \
-    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server \
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest \
     /bin/bash
-python -m pip install flash-attn==2.8.3
-paddlex_genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
+# After entering the container
+python -m pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.4.11/flash_attn-2.8.3+cu128torch2.8-cp310-cp310-linux_x86_64.whl
+paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
 ```
 
 #### 3.1.2 Installation and Usage via PaddleOCR CLI
 
 Since the inference acceleration framework may have dependency conflicts with the PaddlePaddle framework, it is recommended to install it in a virtual environment. Taking vLLM as an example:
 
-```bash
+```shell
+# If there is currently an activated virtual environment, first deactivate it using `deactivate`
 # Create a virtual environment
-python -m venv .venv
+python -m venv .venv_vlm
 # Activate the environment
-source .venv/bin/activate
+source .venv_vlm/bin/activate
 # Install PaddleOCR
 python -m pip install "paddleocr[doc-parser]"
 # Install dependencies for inference acceleration service
@@ -951,7 +1009,7 @@ paddleocr install_genai_server_deps vllm
 
 Usage of the `paddleocr install_genai_server_deps` command:
 
-```bash
+```shell
 paddleocr install_genai_server_deps <name of the inference acceleration framework>
 ```
 
@@ -959,13 +1017,17 @@ The currently supported frameworks are named `vllm` and `sglang`, corresponding
 
 If you are using an NVIDIA 50 series graphics card (Compute Capability >= 12), you need to install a specific version of FlashAttention before launching the service.
 
-```bash
+```shell
 python -m pip install flash-attn==2.8.3
 ```
 
+The vLLM and SGLang installed via `paddleocr install_genai_server_deps` are both **CUDA 12** versions. Please ensure your local GPU drivers are compatible with this requirement.
+
+> During the execution of the `paddleocr install_genai_server_deps` command, CUDA compilation tools such as nvcc may be required. If these tools are not available in your environment (for example, when using the `paddleocr-vl` image), you can obtain precompiled versions of FlashAttention from [this repository](https://github.com/mjun0812/flash-attention-prebuild-wheels) (install version 2.8.3 for NVIDIA 50-series GPUs, and version 2.8.2 for other GPU models). Install the precompiled package first, and then proceed with the subsequent command. For example, if you are using a non-50-series GPU, execute the following command in the `paddleocr-vl` image: `python -m pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.3.14/flash_attn-2.8.2+cu128torch2.8-cp310-cp310-linux_x86_64.whl`.
+
 After installation, you can start the service using the `paddlex_genai_server` command:
 
-```bash
+```shell
 paddlex_genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
 ```
 
@@ -988,7 +1050,7 @@ After starting the VLM inference service, the client can invoke the service thro
 
 The backend type (`vllm-server` or `sglang-server`) can be specified via `--vl_rec_backend`, and the service address can be specified via `--vl_rec_server_url`. For example:
 
-```bash
+```shell
 paddleocr doc_parser --input paddleocr_vl_demo.png --vl_rec_backend vllm-server --vl_rec_server_url http://127.0.0.1:8118/v1
 ```
 
@@ -1000,18 +1062,6 @@ Pass the `vl_rec_backend` and `vl_rec_server_url` parameters when creating the `
 pipeline = PaddleOCRVL(vl_rec_backend="vllm-server", vl_rec_server_url="http://127.0.0.1:8118/v1")
 ```
 
-#### 3.2.3 Service-Oriented Deployment
-
-The fields `VLRecognition.genai_config.backend` and `VLRecognition.genai_config.server_url` can be modified in the configuration file, for example:
-
-```yaml
-VLRecognition:
-  ...
-  genai_config:
-    backend: vllm-server
-    server_url: http://127.0.0.1:8118/v1
-```
-
 ### 3.3 Performance Tuning
 
 The default configuration is tuned on a single NVIDIA A100 and assumes exclusive client service, so it may not be suitable for other environments. If users encounter performance issues during actual use, they can try the following optimization methods.
@@ -1034,7 +1084,7 @@ gpu-memory-utilization: 0.3
 
 2. Specify the configuration file path when starting the service, for example, using the `paddleocr genai_server` command:
 
-```bash
+```shell
 paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --backend_config vllm_config.yaml
 
 
@@ -1064,27 +1114,52 @@ The following configurations are tailored for scenarios with a one-to-one corres
 
 ## 4. Serving
 
-If you need to directly apply PaddleOCR-VL in your Python project, you can refer to the example code in [2.2 Python Script Integration](#22-python-script-integration).
+If you wish to directly integrate PaddleOCR-VL into your Python project, you can refer to the sample code provided in [2.2 Python Script Method](#22-python-script-method-integration).
 
-Additionally, PaddleOCR offers other deployment methods, detailed as follows:
+Furthermore, PaddleOCR also supports deploying PaddleOCR-VL as a service. This section will detail the serving steps. Please note that the pipeline service introduced in this section differs from the VLM inference service in the previous section: the latter is only responsible for one step (i.e., VLM inference) in the complete workflow and is called as an underlying service by the former.
 
-### 1.1 Install Dependencies
+### 4.1 Running the Server
 
-Run the following command to install the PaddleX serving plugin via PaddleX CLI:
+#### 4.1.1 Using Docker Compose
 
-```bash
+You can obtain the Compose file from [here](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/paddleocr_vl_docker/compose.yaml). After downloading it locally, execute the following command to start the server:
+
+```shell
+docker compose up
+```
+
+After startup, you will see output similar to the following:
+
+```text
+paddleocr-vl-api             | INFO:     Started server process [1]
+paddleocr-vl-api             | INFO:     Waiting for application startup.
+paddleocr-vl-api             | INFO:     Application startup complete.
+paddleocr-vl-api             | INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
+```
+
+The server listens on port **8080** by default.
+
+This method accelerates VLM inference based on the vLLM framework, making it more suitable for production environment deployment. However, it requires the machine to be equipped with a GPU and the NVIDIA drivers to support CUDA 12.8. The default Docker images are not compatible with NVIDIA 50-series graphics cards. If you wish to use these graphics cards, please refer to Section 3 for instructions on installing a specific version of FlashAttention in the `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server` image.
+
+Additionally, after starting the server using this method, no internet connection is required except for pulling the images. For deployment in an offline environment, you can first pull the images involved in the Compose file on a networked machine, export them, transfer them to the offline machine, and import them. The service can then be started in the offline environment.
+
+If you need to adjust pipeline configurations (such as model path, batch size, deployment device, etc.), you can overwrite the modified pipeline configuration file to `/home/paddleocr/pipeline_config.yaml` in the `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl` image (or the corresponding container). For the correspondence between PaddleOCR pipelines and PaddleX pipeline registration names, as well as how to obtain and modify PaddleX pipeline configuration files, please refer to [PaddleOCR and PaddleX](../paddleocr_and_paddlex.en.md). Furthermore, section 4.1.3 will introduce how to adjust the pipeline configuration based on common requirements.
+
+#### 4.1.2 Local Installation and Startup
+
+Execute the following command to install the serving plugin via the PaddleX CLI:
+
+```shell
 paddlex --install serving
 ```
 
-### 1.2 Run the Server
+Then, use the PaddleX CLI to start the server:
 
-Run the server via PaddleX CLI:
-
-```bash
+```shell
 paddlex --serve --pipeline PaddleOCR-VL
 ```
 
-You should see information similar to the following:
+After startup, you will see output similar to the following:
 
 ```text
 INFO:     Started server process [63108]
@@ -1093,7 +1168,7 @@ INFO:     Application startup complete.
 INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
 ```
 
-To adjust configurations (such as model path, batch size, deployment device, etc.), specify `--pipeline` as a custom configuration file. Refer to [PaddleOCR and PaddleX](../paddleocr_and_paddlex.en.md) for the mapping between PaddleOCR pipelines and PaddleX pipeline registration names, as well as how to obtain and modify PaddleX pipeline configuration files.
+The server listens on port **8080** by default.
 
 The command-line options related to serving are as follows:
 
@@ -1132,9 +1207,82 @@ The command-line options related to serving are as follows:
 </tbody>
 </table>
 
+If you need to adjust pipeline configurations (such as model path, batch size, deployment device, etc.), you can specify the `--pipeline` parameter as a custom configuration file path. For the correspondence between PaddleOCR pipelines and PaddleX pipeline registration names, as well as how to obtain and modify PaddleX pipeline configuration files, please refer to [PaddleOCR and PaddleX](../paddleocr_and_paddlex.en.md). Furthermore, section 4.1.3 will introduce how to adjust the pipeline configuration based on common requirements.
+
+#### 4.1.3 Pipeline Configuration Adjustment Instructions
+
+**Using Acceleration Frameworks to Improve VLM Inference Performance**
+
+To use acceleration frameworks like vLLM to improve VLM inference performance, you can modify the `VLRecognition.genai_config.backend` and `VLRecognition.genai_config.server_url` fields in the pipeline configuration file, for example:
+
+```yaml
+VLRecognition:
+  ...
+  genai_config:
+    backend: vllm-server
+    server_url: http://127.0.0.1:8118/v1
+```
+
+Section 2 has already detailed how to start the VLM inference service.
+
+**Enabling Document Image Preprocessing Functionality**
+
+The service started with the default configuration does not support the document preprocessing function. If a client calls this function, an error message will be returned. To enable document preprocessing, set `use_doc_preprocessor` to `True` in the pipeline configuration file and start the service using the modified configuration file.
+
+**Disabling Result Visualization Functionality**
+
+The service returns visualized results by default, which introduces additional overhead. To disable this functionality, add the following configuration to the pipeline configuration file:
+
+```yaml
+Serving:
+  visualize: False
+```
+
+Alternatively, you can set the `visualize` field to `false` in the request body to disable visualization for a single request.
+
+**Configuring Returned Image URLs**
+
+For the visualized result images and images contained within Markdown, the service returns them as Base64 encoded strings by default. To return images as URLs instead, add the following configuration to the pipeline configuration file:
+
+```yaml
+Serving:
+  extra:
+    file_storage:
+      type: bos
+      endpoint: https://bj.bcebos.com
+      bucket_name: some-bucket
+      ak: xxx
+      sk: xxx
+      key_prefix: deploy
+    return_img_urls: True
+```
+
+Currently, it supports storing the generated images to Baidu Object Storage (BOS) and returning URLs. The relevant parameters are explained below:
+
+- `endpoint`: Access domain name. Must be configured.
+- `ak`: Baidu AI Cloud AK. Must be configured.
+- `sk`: Baidu AI Cloud SK. Must be configured.
+- `bucket_name`: Bucket name. Must be configured.
+- `key_prefix`: Uniform prefix for object keys.
+- `connection_timeout_in_mills`: Request timeout period (in milliseconds).
+
+For more information, such as how to obtain AK/SK, please refer to the [Baidu Intelligent Cloud Official Documentation](https://cloud.baidu.com/doc/BOS/index.html).
+
+**Modifying PDF Parsing Page Limit**
+
+For performance considerations, the service only processes the first 10 pages of received PDF files by default. To adjust the page limit, add the following configuration to the pipeline configuration file:
+
+```yaml
+Serving:
+  extra:
+    max_num_input_imgs: <new page limit, e.g., 100>
+```
+
+Setting `max_num_input_imgs` to `null` removes the page limit.
+
 ### 4.3 Client-Side Invocation
 
-Below are the API references for basic service-based deployment and examples of multilingual service invocation:
+Below are the API reference and examples of multi-language service invocation:
 
 <details><summary>API Reference</summary>
 <p>Main operations provided by the service:</p>
@@ -1436,7 +1584,7 @@ Below are the API references for basic service-based deployment and examples of
 </tr>
 </tbody>
 </table></details>
-<details><summary>Multilingual Service Invocation Example</summary>
+<details><summary>Multi-Language Service Invocation Examples</summary>
 <details>
 <summary>Python</summary>
 
@@ -1961,3 +2109,9 @@ foreach ($result as $i => $item) {
 </code></pre></details>
 </details>
 <br/>
+
+## 5. Model Fine-Tuning
+
+If you find that the accuracy of PaddleOCR-VL does not meet expectations in specific business scenarios, we recommend using the [ERNIEKit toolkit](https://github.com/PaddlePaddle/ERNIE/tree/release/v1.4) to perform Supervised Fine-Tuning (SFT) on the PaddleOCR-VL-0.9B model. For detailed steps, please refer to the [ERNIEKit documentation](https://github.com/PaddlePaddle/ERNIE/blob/release/v1.4/docs/paddleocr_vl_sft.md).
+
+> Fine-tuning for the layout detection sorting model is currently not supported.

docs/version3.x/pipeline_usage/PaddleOCR-VL.md

@@ -10,53 +10,106 @@ PaddleOCR-VL 是一款先进、高效的文档解析模型，专为文档中的
 
 ## 1. 环境准备
 
-安装 PaddlePaddle 和 PaddleOCR:
+我们推荐使用官方 Docker 镜像（要求 Docker 版本 >= 19.03，机器装配有 GPU 且 NVIDIA 驱动支持 CUDA 12.8）：
 
 ```shell
+docker run \
+    -it \
+    --gpus all \
+    --network host \
+    --user root \
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest \
+    /bin/bash
+# 在容器中调用 PaddleOCR CLI 或 Python API
+```
+
+镜像的大小约为 8 GB。如果您希望在无法连接互联网的环境中使用 PaddleOCR-VL，请将上述命令中的 `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest` 更换为离线版本镜像 `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline`（离线镜像大小约为 11 GB）。您需要在可以联网的机器上拉取镜像，将镜像导入到离线机器，然后在离线机器使用该镜像启动容器。例如：
+
+```shell
+# 在能够联网的机器上执行
+docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline
+# 将镜像保存到文件中
+docker save ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline -o paddleocr-vl-latest-offline.tar
+
+# 将镜像文件传输到离线机器
+
+# 在离线机器上执行
+docker load -i paddleocr-vl-latest-offline.tar
+# 之后可以在离线机器上使用 `docker run` 启动容器
+```
+
+如果您无法使用 Docker，也可以手动安装 PaddlePaddle 和 PaddleOCR。要求 Python 版本为 3.8–3.12。
+
+**我们强烈推荐您在虚拟环境中安装 PaddleOCR-VL，以避免发生依赖冲突。** 例如，使用 Python venv 标准库创建虚拟环境：
+
+```shell
+# 创建虚拟环境
+python -m venv .venv_paddleocr
+# 激活环境
+source .venv_paddleocr/bin/activate
+```
+
+执行如下命令完成安装：
+
+```shell
+# 以下命令安装 CUDA 12.6 版本的 PaddlePaddle，对于其他 CUDA 版本以及 CPU 版本，请参考 https://www.paddlepaddle.org.cn/install/quick?docurl=/documentation/docs/zh/develop/install/pip/linux-pip.html
 python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
 python -m pip install -U "paddleocr[doc-parser]"
+# 对于 Linux 系统，执行：
 python -m pip install https://paddle-whl.bj.bcebos.com/nightly/cu126/safetensors/safetensors-0.6.2.dev0-cp38-abi3-linux_x86_64.whl
 ```
-> 对于 Windows 用户，请使用 WSL 或者 Docker 进行环境搭建。
 
-运行 PaddleOCR-VL 对 GPU 硬件有以下要求：
+> **请注意安装 3.2.0 及以上版本的飞桨框架，同时安装特殊版本的 safetensors。** 对于 Windows 用户，请使用 WSL 或者 Docker 进行环境搭建；对于 macOS 用户，请使用 Docker 进行环境搭建。
+
+PaddleOCR-VL 对推理设备的支持情况如下：
 
 <table border="1">
 <thead>
   <tr>
     <th>推理方式</th>
-    <th>GPU Compute Capability</th>
+    <th>支持 x64 CPU</th>
+    <th>支持的 GPU Compute Capability</th>
+    <th>支持的 CUDA 版本</th>
   </tr>
 </thead>
 <tbody>
   <tr>
     <td>PaddlePaddle</td>
-    <td>≥ 8.5</td>
+    <td>✅</td>
+    <td>≥ 7</td>
+    <td>11.8、12.6、12.8</td>
   </tr>
   <tr>
     <td>vLLM</td>
+    <td>🚧</td>
     <td>≥ 8 （RTX 3060，RTX 5070，A10，A100, ...） <br />  
     7 ≤ GPU Compute Capability < 8 （T4，V100，...）支持运行，但可能出现请求超时、OOM 等异常情况，不推荐使用
     </td>
+    <td>12.8</td>
   </tr>
   <tr>
     <td>SGLang</td>
+     <td>🚧</td>
     <td>8 ≤ GPU Compute Capability < 12</td>
+    <td>12.8</td>
   </tr>
 </tbody>
 </table>
 
-目前 PaddleOCR-VL 暂不支持 CPU 及 Arm 架构，后续将根据实际需求扩展更多硬件支持，敬请期待！
+> 当前，PaddleOCR-VL 暂不支持 ARM 架构 CPU。后续将根据实际需求扩展更多硬件支持，敬请期待！  
+> vLLM 与 SGLang 无法在 Windows 或 macOS 上原生运行，请使用我们提供的 Docker 镜像。
 
 ## 2. 快速开始
 
 PaddleOCR-VL 支持 CLI 命令行方式和 Python API 两种使用方式，其中 CLI 命令行方式更简单，适合快速验证功能，而 Python API 方式更灵活，适合集成到现有项目中。
 
+> 本节所介绍的方法主要用于快速验证，其推理速度、显存占用及稳定性表现未必能满足生产环境的要求。**若需部署至生产环境，我们强烈建议使用专门的推理加速框架** ，具体方法请参考下一节。
+
 ### 2.1 命令行方式体验
 
 一行命令即可快速体验 PaddleOCR-VL 效果：
 
-```bash
+```shell
 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png
 
 # 通过 --use_doc_orientation_classify 指定是否使用文档方向分类模型
@@ -933,54 +986,58 @@ MKL-DNN 缓存容量。
 
 #### 3.1.1 使用 Docker 镜像
 
-PaddleOCR 提供了 Docker 镜像，用于快速启动 vLLM 推理服务。可使用以下命令启动服务：
+PaddleOCR 提供了 Docker 镜像，用于快速启动 vLLM 推理服务。可使用以下命令启动服务（要求 Docker 版本 >= 19.03，机器装配有 GPU 且 NVIDIA 驱动支持 CUDA 12.8）：
 
-```bash
+```shell
 docker run \
     -it \
     --rm \
     --gpus all \
     --network host \
-    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest
 ```
 
-服务默认监听 **8080** 端口。
+镜像大小约为 13 GB。服务器默认监听 **8080** 端口。
 
-启动容器时可传入参数覆盖默认配置，参数与 `paddleocr genai_server` 命令一致（详见下一小节）。例如：
+如果您希望在无法连接互联网的环境中启动服务，请将上述命令中的 `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest` 更换为离线版本镜像 `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-offline`。离线镜像大小约为 15 GB。
 
-```bash
+启动容器时可传入参数覆盖默认配置，支持的参数详见下一小节。例如：
+
+```shell
 docker run \
     -it \
     --rm \
     --gpus all \
     --network host \
-    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server \
-    paddlex_genai_server --model_name PaddleOCR-VL-0.9B --host 0.0.0.0 --port 8118 --backend vllm
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest \
+    paddleocr genai_server --model_name PaddleOCR-VL-0.9B --host 0.0.0.0 --port 8118 --backend vllm
 ```
 
 若您使用的是  NVIDIA 50 系显卡 (Compute Capability >= 12)，需要在启动服务前安装指定版本的 FlashAttention:
 
-```bash
+```shell
 docker run \
     -it \
     --rm \
     --gpus all \
     --network host \
-    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server \
+    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest \
     /bin/bash
-python -m pip install flash-attn==2.8.3
-paddlex_genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
+# 进入容器后
+python -m pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.4.11/flash_attn-2.8.3+cu128torch2.8-cp310-cp310-linux_x86_64.whl
+paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
 ```
 
 #### 3.1.2 通过 PaddleOCR CLI 安装和使用
 
 由于推理加速框架可能与飞桨框架存在依赖冲突，建议在虚拟环境中安装。以 vLLM 为例：
 
-```bash
+```shell
+# 如果当前存在已激活的虚拟环境，先通过 `deactivate` 取消激活
 # 创建虚拟环境
-python -m venv .venv
+python -m venv .venv_vlm
 # 激活环境
-source .venv/bin/activate
+source .venv_vlm/bin/activate
 # 安装 PaddleOCR
 python -m pip install "paddleocr[doc-parser]"
 # 安装推理加速服务依赖
@@ -989,7 +1046,7 @@ paddleocr install_genai_server_deps vllm
 
 `paddleocr install_genai_server_deps` 命令用法：
 
-```bash
+```shell
 paddleocr install_genai_server_deps <推理加速框架名称>
 ```
 
@@ -997,14 +1054,18 @@ paddleocr install_genai_server_deps <推理加速框架名称>
 
 若您使用的是  NVIDIA 50 系显卡 (Compute Capability >= 12)，需要在启动服务前安装指定版本的 FlashAttention:
 
-```bash
+```shell
 python -m pip install flash-attn==2.8.3
 ```
 
-安装完成后，可通过 `paddlex_genai_server` 命令启动服务：
+通过 `paddleocr install_genai_server_deps` 安装的 vLLM 与 SGLang 均为 **CUDA 12.8** 版本，请确保本地 GPU 驱动与之兼容。
 
-```bash
-paddlex_genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
+> `paddleocr install_genai_server_deps` 命令在执行过程中可能需要使用 nvcc 等 CUDA 编译工具。如果您的环境中没有这些工具（例如在使用 `paddleocr-vl` 镜像），可以从 [此仓库](https://github.com/mjun0812/flash-attention-prebuild-wheels) 获取 FlashAttention 的预编译版本（对于 NVIDIA 50 系显卡，安装 2.8.3；对于其他型号显卡，安装 2.8.2），先安装预编译包，再执行后续命令。例如，如果您使用非 50 系显卡，在 `paddleocr-vl` 镜像中，执行 `python -m pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.3.14/flash_attn-2.8.2+cu128torch2.8-cp310-cp310-linux_x86_64.whl`。
+
+安装完成后，可通过 `paddleocr genai_server` 命令启动服务：
+
+```shell
+paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
 ```
 
 该命令支持的参数如下：
@@ -1026,7 +1087,7 @@ paddlex_genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118
 
 可通过 `--vl_rec_backend` 指定后端类型（`vllm-server` 或 `sglang-server`），通过 `--vl_rec_server_url` 指定服务地址，例如：
 
-```bash
+```shell
 paddleocr doc_parser --input paddleocr_vl_demo.png --vl_rec_backend vllm-server --vl_rec_server_url http://127.0.0.1:8118/v1
 ```
 
@@ -1038,18 +1099,6 @@ paddleocr doc_parser --input paddleocr_vl_demo.png --vl_rec_backend vllm-server
 pipeline = PaddleOCRVL(vl_rec_backend="vllm-server", vl_rec_server_url="http://127.0.0.1:8118/v1")
 ```
 
-#### 3.2.3 服务化部署
-
-可在配置文件中修改 `VLRecognition.genai_config.backend` 和 `VLRecognition.genai_config.server_url` 字段，例如：
-
-```yaml
-VLRecognition:
-  ...
-  genai_config:
-    backend: vllm-server
-    server_url: http://127.0.0.1:8118/v1
-```
-
 ### 3.3 性能调优
 
 默认配置是在单张 NVIDIA A100 上进行调优的，并假设客户端独占服务，因此可能不适用于其他环境。如果用户在实际使用中遇到性能问题，可以尝试以下优化方法。
@@ -1072,7 +1121,7 @@ PaddleOCR VLM 推理服务支持通过配置文件进行调参。以下示例展
 
 2. 启动服务时指定配置文件路径，例如使用 `paddleocr genai_server` 命令：
 
-   ```bash
+   ```shell
    paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --backend_config vllm_config.yaml
    ```
 
@@ -1104,27 +1153,52 @@ PaddleOCR 会将来自单张或多张输入图像中的子图分组并对服务
 
 ## 4. 服务化部署
 
-若您需要将 PaddleOCR-VL 直接应用在您的Python项目中，可以参考 [2.2 Python脚本方式](#22-python脚本方式集成)中的示例代码。
+如果您希望将 PaddleOCR-VL 直接集成到您的 Python 项目中，可以参考 [2.2 Python脚本方式](#22-python脚本方式集成) 中提供的示例代码。
 
-此外，PaddleOCR 也提供了服务化部署方式，详细说明如下：
+此外，PaddleOCR 还支将 PaddleOCR-VL 部署成服务，本节将对服务化部署进行详细介绍。请注意，本节所介绍产线服务与上一节中的VLM推理服务有所区别：后者仅负责完整流程中的一个环节（即 VLM 推理），并作为前者的底层服务被调用。
 
-### 4.1 安装依赖
+### 4.1 运行服务器
 
-执行如下命令，通过 PaddleX CLI 安装 PaddleX 服务化部署插件：
+#### 4.1.1 使用 Docker Compose
 
-```bash
+您可以从 [此处](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/paddleocr_vl_docker/compose.yaml) 获取 Compose 文件，下载到本地后，执行以下命令启动服务器：
+
+```shell
+docker compose up
+```
+
+启动后将看到类似如下输出：
+
+```text
+paddleocr-vl-api             | INFO:     Started server process [1]
+paddleocr-vl-api             | INFO:     Waiting for application startup.
+paddleocr-vl-api             | INFO:     Application startup complete.
+paddleocr-vl-api             | INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
+```
+
+服务器默认监听 **8080** 端口。
+
+此方式基于 vLLM 框架对 VLM 推理进行加速，更适合生产环境部署，但要求机器配备 GPU，并且 NVIDIA 驱动程序支持 CUDA 12.8。默认的 Docker 镜像并不适用于 NVIDIA 50 系显卡，如果希望在这些显卡上使用，请参考第 3 节中的介绍，在 `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server` 镜像中安装特定版本的 FlashAttention。
+
+此外，使用此方式启动服务器后，除拉取镜像外，无需连接互联网。如需在离线环境中部署，可先在联网机器上拉取 Compose 文件中涉及的镜像，导出并传输至离线机器中导入，即可在离线环境下启动服务。
+
+如需调整产线相关配置（如模型路径、批处理大小、部署设备等），可将修改后的产线配置文件覆盖至 `ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl`（或对应容器）中的 `/home/paddleocr/pipeline_config.yaml`。有关 PaddleOCR 产线与 PaddleX 产线注册名的对应关系，以及 PaddleX 产线配置文件的获取与修改方法，请参阅 [PaddleOCR 与 PaddleX](../paddleocr_and_paddlex.md)。此外，4.1.3 小节将介绍如何根据常见需求对产线配置进行调整。
+
+#### 4.1.2 本地安装与启动
+
+执行以下命令，通过 PaddleX CLI 安装服务化部署插件：
+
+```shell
 paddlex --install serving
 ```
 
-### 4.2 运行服务器
+然后，使用 PaddleX CLI 启动服务器：
 
-通过 PaddleX CLI 运行服务器：
-
-```bash
+```shell
 paddlex --serve --pipeline PaddleOCR-VL
 ```
 
-可以看到类似以下展示的信息：
+启动后将看到类似如下输出：
 
 ```text
 INFO:     Started server process [63108]
@@ -1133,9 +1207,9 @@ INFO:     Application startup complete.
 INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
 ```
 
-如需调整配置（如模型路径、batch size、部署设备等），可指定 `--pipeline` 为自定义配置文件。请参考 [PaddleOCR 与 PaddleX](../paddleocr_and_paddlex.md) 了解 PaddleOCR 产线与 PaddleX 产线注册名的对应关系，以及 PaddleX 产线配置文件的获取与修改方式。
+服务器默认监听 **8080** 端口。
 
-与服务化部署相关的命令行选项如下：
+与服务化部署相关的命令行参数如下：
 
 <table>
 <thead>
@@ -1151,19 +1225,19 @@ INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
 </tr>
 <tr>
 <td><code>--device</code></td>
-<td>产线部署设备。默认情况下，当 GPU 可用时，将使用 GPU；否则使用 CPU。</td>
+<td>产线部署设备。默认情况下，若 GPU 可用则使用 GPU，否则使用 CPU。</td>
 </tr>
 <tr>
 <td><code>--host</code></td>
-<td>服务器绑定的主机名或 IP 地址。默认为 <code>0.0.0.0</code>。</td>
+<td>服务器绑定的主机名或 IP 地址，默认为 <code>0.0.0.0</code>。</td>
 </tr>
 <tr>
 <td><code>--port</code></td>
-<td>服务器监听的端口号。默认为 <code>8080</code>。</td>
+<td>服务器监听的端口号，默认为 <code>8080</code>。</td>
 </tr>
 <tr>
 <td><code>--use_hpip</code></td>
-<td>如果指定，则使用高性能推理。请参考高性能推理文档了解更多信息。</td>
+<td>启用高性能推理模式。请参考高性能推理文档了解更多信息。</td>
 </tr>
 <tr>
 <td><code>--hpi_config</code></td>
@@ -1172,11 +1246,84 @@ INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
 </tbody>
 </table>
 
-### 4.3 客户端调用
+如需调整产线相关配置（如模型路径、批处理大小、部署设备等），可将 `--pipeline` 参数指定为自定义配置文件路径。有关 PaddleOCR 产线与 PaddleX 产线注册名的对应关系，以及 PaddleX 产线配置文件的获取与修改方法，请参阅 [PaddleOCR 与 PaddleX](../paddleocr_and_paddlex.md)。此外，4.1.3 小节将介绍如何根据常见需求对产线配置进行调整。
 
-以下是基础服务化部署的API参考与多语言服务调用示例：
+#### 4.1.3 产线配置调整说明
 
-<details><summary>API参考</summary>
+**使用加速框架提升 VLM 推理性能**
+
+如需使用 vLLM 等加速框架提升 VLM 推理性能，可在产线配置文件中修改 `VLRecognition.genai_config.backend` 和 `VLRecognition.genai_config.server_url` 字段，例如：
+
+```yaml
+VLRecognition:
+  ...
+  genai_config:
+    backend: vllm-server
+    server_url: http://127.0.0.1:8118/v1
+```
+
+第 2 节已详细介绍如何启动 VLM 推理服务。
+
+**启用文档图像预处理功能**
+
+默认配置启动的服务不支持文档预处理功能。若客户端调用该功能，将返回错误信息。如需启用文档预处理，请在产线配置文件中将 `use_doc_preprocessor` 设置为 `True`，并使用修改后的配置文件启动服务。
+
+**禁用结果可视化功能**
+
+服务默认返回可视化结果，这会引入额外开销。如需禁用该功能，可在产线配置文件中添加如下配置：
+
+```yaml
+Serving:
+  visualize: False
+```
+
+此外，也可在请求体中设置 `visualize` 字段为 `false`，以针对单次请求禁用可视化。
+
+**配置返回图像 URL**
+
+对于可视化结果图及 Markdown 中包含的图像，服务默认以 Base64 编码返回。如需以 URL 形式返回图像，可在产线配置文件中添加如下配置：
+
+```yaml
+Serving:
+  extra:
+    file_storage:
+      type: bos
+      endpoint: https://bj.bcebos.com
+      bucket_name: some-bucket
+      ak: xxx
+      sk: xxx
+      key_prefix: deploy
+    return_img_urls: True
+```
+
+目前支持将生成的图像存储至百度智能云对象存储（BOS）并返回 URL。相关参数说明如下：
+
+- `endpoint`：访问域名，必须配置。
+- `ak`：百度智能云 AK，必须配置。
+- `sk`：百度智能云 SK，必须配置。
+- `bucket_name`：存储空间名称，必须配置。
+- `key_prefix`：Object key 的统一前缀。
+- `connection_timeout_in_mills`：请求超时时间（单位：毫秒）。
+
+有关 AK/SK 获取等更多信息，请参考 [百度智能云官方文档](https://cloud.baidu.com/doc/BOS/index.html)。
+
+**修改 PDF 解析页数限制**
+
+出于性能考虑，服务默认仅处理接收到的 PDF 文件的前 10 页。如需调整页数限制，可在产线配置文件中添加如下配置：
+
+```yaml
+Serving:
+  extra:
+    max_num_input_imgs: <新的页数限制，例如 100>
+```
+
+将 `max_num_input_imgs` 设置为 `null` 可解除页数限制。
+
+### 4.2 客户端调用
+
+以下是服务化部署的 API 参考与多语言服务调用示例：
+
+<details><summary>API 参考</summary>
 <p>对于服务提供的主要操作：</p>
 <ul>
 <li>HTTP请求方法为POST。</li>
@@ -2007,3 +2154,9 @@ foreach ($result as $i => $item) {
 </code></pre></details>
 </details>
 <br/>
+
+## 5. 模型微调
+
+若您发现 PaddleOCR-VL 在特定业务场景中的精度表现未达预期，我们推荐使用 [ERNIEKit 套件](https://github.com/PaddlePaddle/ERNIE/tree/release/v1.4) 对 PaddleOCR-VL-0.9B 模型进行有监督微调（SFT）。具体操作步骤可参考 [ERNIEKit 官方文档](https://github.com/PaddlePaddle/ERNIE/blob/release/v1.4/docs/paddleocr_vl_sft_zh.md)。
+
+> 目前暂不支持对版面检测排序模型进行微调。

paddleocr/_pipelines/formula_recognition.py

@@ -152,6 +152,8 @@ class FormulaRecognitionPipeline(PaddleXPipelineWrapper):
             "SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "use_doc_preprocessor": self._params["use_doc_orientation_classify"]
+            or self._params["use_doc_unwarping"],
             "SubPipelines.DocPreprocessor.SubModules.DocOrientationClassify.model_name": self._params[
                 "doc_orientation_classify_model_name"
             ],

paddleocr/_pipelines/ocr.py

@@ -278,6 +278,8 @@ class PaddleOCR(PaddleXPipelineWrapper):
             "SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "use_doc_preprocessor": self._params["use_doc_orientation_classify"]
+            or self._params["use_doc_unwarping"],
             "use_textline_orientation": self._params["use_textline_orientation"],
             "SubModules.TextDetection.limit_side_len": self._params[
                 "text_det_limit_side_len"

paddleocr/_pipelines/paddleocr_vl.py

@@ -169,6 +169,8 @@ class PaddleOCRVL(PaddleXPipelineWrapper):
             "SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "use_doc_preprocessor": self._params["use_doc_orientation_classify"]
+            or self._params["use_doc_unwarping"],
             "use_layout_detection": self._params["use_layout_detection"],
             "use_chart_recognition": self._params["use_chart_recognition"],
             "format_block_content": self._params["format_block_content"],

paddleocr/_pipelines/pp_chatocrv4_doc.py

@@ -356,6 +356,10 @@ class PPChatOCRv4Doc(PaddleXPipelineWrapper):
             "SubPipelines.LayoutParser.SubPipelines.GeneralOCR.use_textline_orientation": self._params[
                 "use_textline_orientation"
             ],
+            "SubPipelines.LayoutParser.use_doc_preprocessor": self._params[
+                "use_doc_orientation_classify"
+            ]
+            or self._params["use_doc_unwarping"],
             "SubPipelines.LayoutParser.use_seal_recognition": self._params[
                 "use_seal_recognition"
             ],

paddleocr/_pipelines/pp_doctranslation.py

@@ -328,6 +328,10 @@ class PPDocTranslation(PaddleXPipelineWrapper):
             "SubPipelines.LayoutParser.SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "SubPipelines.LayoutParser.use_doc_preprocessor": self._params[
+                "use_doc_orientation_classify"
+            ]
+            or self._params["use_doc_unwarping"],
             "SubPipelines.LayoutParser.SubPipelines.GeneralOCR.use_textline_orientation": self._params[
                 "use_textline_orientation"
             ],

paddleocr/_pipelines/pp_structurev3.py

@@ -299,6 +299,8 @@ class PPStructureV3(PaddleXPipelineWrapper):
             "SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "use_doc_preprocessor": self._params["use_doc_orientation_classify"]
+            or self._params["use_doc_unwarping"],
             "SubPipelines.GeneralOCR.use_textline_orientation": self._params[
                 "use_textline_orientation"
             ],

paddleocr/_pipelines/seal_recognition.py

@@ -202,6 +202,8 @@ class SealRecognition(PaddleXPipelineWrapper):
             "SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "use_doc_preprocessor": self._params["use_doc_orientation_classify"]
+            or self._params["use_doc_unwarping"],
             "SubPipelines.SealOCR.SubModules.TextDetection.model_name": self._params[
                 "seal_text_detection_model_name"
             ],

paddleocr/_pipelines/table_recognition_v2.py

@@ -177,6 +177,8 @@ class TableRecognitionPipelineV2(PaddleXPipelineWrapper):
             "SubPipelines.DocPreprocessor.use_doc_unwarping": self._params[
                 "use_doc_unwarping"
             ],
+            "use_doc_preprocessor": self._params["use_doc_orientation_classify"]
+            or self._params["use_doc_unwarping"],
             "use_layout_detection": self._params["use_layout_detection"],
             "use_ocr_model": self._params["use_ocr_model"],
             "SubModules.LayoutDetection.model_name": self._params[

ppocr/data/imaug/operators.py

@@ -241,7 +241,9 @@ class DetResizeForTest(object):
         data["image"] = img
         data["shape"] = np.array([src_h, src_w, ratio_h, ratio_w])
         if "iluvatar_gpu" in get_device():
-            data["shape"] = np.array([src_h, src_w, ratio_h, ratio_w]).astype(np.float32)
+            data["shape"] = np.array([src_h, src_w, ratio_h, ratio_w]).astype(
+                np.float32
+            )
         return data
 
     def image_padding(self, im, value=0):

tools/program.py

@@ -115,7 +115,14 @@ def merge_config(config, opts):
     return config
 
 
-def check_device(use_gpu, use_xpu=False, use_npu=False, use_mlu=False, use_gcu=False, use_iluvatar_gpu=False):
+def check_device(
+    use_gpu,
+    use_xpu=False,
+    use_npu=False,
+    use_mlu=False,
+    use_gcu=False,
+    use_iluvatar_gpu=False,
+):
     """
     Log error and exit when set use_gpu=true in paddlepaddle
     cpu version.