Merge branch 'main' into feat/intel-amd

Author: Bobholamovic

.github/workflows/docs-anchor-check.yml

@@ -0,0 +1,36 @@
+name: Docs Anchor Link Check
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'mkdocs-ci.yml'
+      - 'overrides/**'
+
+jobs:
+  check-anchor-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-mkdocs-${{ hashFiles('mkdocs.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-mkdocs-
+
+      - name: Install dependencies
+        run: pip install mike mkdocs-material jieba mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n markdown-callouts
+
+      - name: Check for broken anchor links
+        env:
+          ENABLE_GIT_PLUGINS: 'false'
+        run: mkdocs build -f mkdocs-ci.yml

.github/workflows/python-publish.yml

@@ -33,7 +33,7 @@ jobs:
     - name: Build package
       run: python -m build
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@ec4db0b4ddc65acdf4bff5fa45ac92d78b56bdf0  # v1.13.0
+      uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1.13.0
       with:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}

configs/rec/multi_language/generate_multi_language_configs.py

@@ -17,7 +17,7 @@
 import os.path
 import logging
 
-logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("ppocr")
 
 support_list = {
     "it": "italian",
@@ -281,27 +281,27 @@ def loss_file(path):
 
     with open(save_file_path, "w") as f:
         yaml.dump(dict(global_config), f, default_flow_style=False, sort_keys=False)
-    logging.info("Project path is          :{}".format(project_path))
-    logging.info(
+    logger.info("Project path is          :{}".format(project_path))
+    logger.info(
         "Train list path set to   :{}".format(
             global_config["Train"]["dataset"]["label_file_list"][0]
         )
     )
-    logging.info(
+    logger.info(
         "Eval list path set to    :{}".format(
             global_config["Eval"]["dataset"]["label_file_list"][0]
         )
     )
-    logging.info(
+    logger.info(
         "Dataset root path set to :{}".format(
             global_config["Eval"]["dataset"]["data_dir"]
         )
     )
-    logging.info(
+    logger.info(
         "Dict path set to         :{}".format(
             global_config["Global"]["character_dict_path"]
         )
     )
-    logging.info(
+    logger.info(
         "Config file set to       :configs/rec/multi_language/{}".format(save_file_path)
     )

deploy/cpp_infer/src/utils/args.cc

@@ -54,7 +54,7 @@ DEFINE_string(text_det_limit_side_len, "64",
               "text detection model.");
 DEFINE_string(text_det_limit_type, "min",
               "This determines how the side length limit is applied to the "
-              "input image before feeding it into the text deteciton model.");
+              "input image before feeding it into the text detection model.");
 DEFINE_string(text_det_thresh, "0.3",
               "Detection pixel threshold for the text detection model. Pixels "
               "with scores greater than this threshold in the output "

deploy/paddleocr_vl_docker/hps/.env.example

@@ -0,0 +1,42 @@
+# PaddleOCR-VL-1.5 HPS Configuration
+# Copy this file to .env and modify as needed
+
+# =============================================================================
+# Gateway Configuration
+# =============================================================================
+
+# Maximum concurrent inference requests (layout-parsing / infer)
+# Increase for higher throughput, decrease if device is overloaded
+HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=16
+
+# Maximum concurrent non-inference requests (restructure-pages)
+# Can be set higher since non-inference operations are lighter
+HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS=64
+
+# Inference timeout in seconds
+# Increase for complex documents, decrease for faster failure detection
+HPS_INFERENCE_TIMEOUT=600
+
+# Health check timeout in seconds
+HPS_HEALTH_CHECK_TIMEOUT=5
+
+# VLM server URL for health checks
+# HPS_VLM_URL=http://paddleocr-vlm-server:8080
+
+# Log level: DEBUG, INFO, WARNING, ERROR
+HPS_LOG_LEVEL=INFO
+
+# Filter health check endpoints from access logs (true/false)
+# Set to false to see all access logs including health checks
+HPS_FILTER_HEALTH_ACCESS_LOG=true
+
+# Number of Uvicorn worker processes
+# Recommended: 2-4 workers per CPU core
+UVICORN_WORKERS=4
+
+# =============================================================================
+# Device Configuration
+# =============================================================================
+
+# Inference device ID to use (0, 1, 2, etc.)
+DEVICE_ID=0

deploy/paddleocr_vl_docker/hps/README.md

@@ -0,0 +1,206 @@
+# PaddleOCR-VL-1.5 高性能服务化部署
+
+[English](README_en.md)
+
+本目录提供一套支持并发请求处理的 PaddleOCR-VL-1.5 高性能服务化部署方案。
+
+> 本方案目前暂时只支持 NVIDIA GPU，对其他推理设备的支持仍在完善中。
+
+## 架构
+
+```
+客户端 → FastAPI 网关 → Triton 服务器 → vLLM 服务器
+```
+
+| 组件           | 说明                                   |
+|----------------|----------------------------------------|
+| FastAPI 网关   | 统一访问入口、简化客户端调用、并发控制 |
+| Triton 服务器  | 版面检测模型（PP-DocLayoutV3）及产线串联逻辑，负责模型管理、动态批处理、推理调度 |
+| vLLM 服务器    | VLM（PaddleOCR-VL-1.5），连续批处理推理 |
+
+**Triton 模型：**
+
+| 模型 | 设备 | 说明 |
+|------|------|------|
+| `layout-parsing` | 推理设备（如 GPU） | 版面解析推理 |
+| `restructure-pages` | CPU | 多页结果后处理（跨页表格合并、标题层级重分配） |
+
+## 环境要求
+
+- x64 CPU
+- NVIDIA GPU，Compute Capability >= 8.0 且 < 12.0
+- NVIDIA 驱动支持 CUDA 12.6
+- Docker >= 19.03
+- Docker Compose >= 2.0
+
+## 快速开始
+
+1. 拉取 PaddleOCR 源码并切换到当前目录：
+
+```bash
+git clone https://github.com/PaddlePaddle/PaddleOCR.git
+cd PaddleOCR/deploy/paddleocr_vl_docker/hps
+```
+
+2. 准备必要文件：
+
+```bash
+bash prepare.sh
+```
+
+3. 启动服务：
+
+```bash
+docker compose up
+```
+
+上述命令将依次启动 3 个容器：
+
+| 服务 | 说明 | 端口 |
+|------|------|------|
+| `paddleocr-vl-api` | FastAPI 网关（对外入口） | 8080 |
+| `paddleocr-vl-tritonserver` | Triton 推理服务器 | 8000（内部） |
+| `paddleocr-vlm-server` | 基于 vLLM 的 VLM 推理服务 | 8080（内部） |
+
+> 首次启动会自动下载并构建镜像，耗时较长；从第二次启动起将直接使用本地镜像，启动速度更快。
+
+## 配置说明
+
+### 环境变量
+
+复制 `.env.example` 到 `.env` 并根据需要修改。
+
+```bash
+cp .env.example .env
+```
+
+除了通过 `.env` 文件设置，也可以直接设置环境变量，如：
+
+```bash
+export HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=8
+```
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `HPS_MAX_CONCURRENT_INFERENCE_REQUESTS` | 16 | 推理操作（版面解析）最大并发请求数 |
+| `HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS` | 64 | 非推理操作（多页重组）最大并发请求数 |
+| `HPS_INFERENCE_TIMEOUT` | 600 | 请求超时时间（秒） |
+| `HPS_HEALTH_CHECK_TIMEOUT` | 5 | 健康检查超时时间（秒） |
+| `HPS_VLM_URL` | http://paddleocr-vlm-server:8080 | VLM 服务器地址（用于健康检查） |
+| `HPS_LOG_LEVEL` | INFO | 日志级别（DEBUG, INFO, WARNING, ERROR） |
+| `HPS_FILTER_HEALTH_ACCESS_LOG` | true | 是否过滤健康检查的访问日志 |
+| `UVICORN_WORKERS` | 4 | 网关 Worker 进程数 |
+| `DEVICE_ID` | 0 | 使用的推理设备 ID |
+
+### 产线配置调整
+
+如需调整产线相关配置（如模型路径、批处理大小、部署设备等），请参考 [PaddleOCR-VL 使用教程](https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/pipeline_usage/PaddleOCR-VL.md) 中的产线配置调整说明章节。
+
+## API 使用
+
+### 文档解析
+
+请参考 [PaddleOCR-VL 使用教程](https://github.com/PaddlePaddle/PaddleOCR/blob/main/docs/version3.x/pipeline_usage/PaddleOCR-VL.md) 中的客户端调用相关章节。
+
+### 健康检查
+
+```bash
+# 存活检查
+curl http://localhost:8080/health
+
+# 就绪检查（验证 Triton 和 VLM 服务是否已准备好处理请求）
+curl http://localhost:8080/health/ready
+```
+
+## 性能调优
+
+### 并发设置
+
+网关对推理操作和非推理操作各自独立地进行并发控制：
+
+- **`HPS_MAX_CONCURRENT_INFERENCE_REQUESTS`**（默认 16）：控制 `layout-parsing`（版面解析）等推理操作的并发数
+  - 过低（4）：推理设备利用率不足，请求不必要地排队
+  - 过高（64）：可能导致 Triton 过载，出现 OOM 或超时
+  - 默认值 16 允许在当前批次处理时有足够请求排队形成下一批次
+  - 如推理设备资源有限，建议适当降低此值
+- **`HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS`**（默认 64）：控制 `restructure-pages`（多页重组）等非推理操作的并发数
+  - 非推理操作不占用推理设备资源，可以设置更高的并发数
+  - 可根据 CPU 核数和内存情况调整
+
+**高吞吐配置示例：**
+
+```bash
+# .env
+HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=32
+HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS=128
+UVICORN_WORKERS=8
+```
+
+**低延迟配置示例：**
+
+```bash
+# .env
+HPS_MAX_CONCURRENT_INFERENCE_REQUESTS=8
+HPS_MAX_CONCURRENT_NON_INFERENCE_REQUESTS=32
+HPS_INFERENCE_TIMEOUT=300
+UVICORN_WORKERS=2
+```
+
+### Worker 进程数
+
+每个 Uvicorn Worker 是独立的进程，有自己的事件循环：
+
+- **1 个 Worker**：简单，但受限于单进程
+- **4 个 Worker**：适合大多数场景
+- **8+ 个 Worker**：适用于高并发、大量小请求的场景
+
+### Triton 动态批处理
+
+Triton 自动将请求批处理以提高推理设备利用率。最大批处理大小通过模型配置文件中的 `max_batch_size` 参数控制（默认：8），配置文件位于模型仓库目录下的 `config.pbtxt`（如 `model_repo/layout-parsing/config.pbtxt`）。
+
+### Triton 实例数
+
+每个 Triton 模型的并行推理实例数通过 `config.pbtxt` 中的 `instance_group` 配置（默认：1）。增加实例数可以提高并行处理能力，但会占用更多设备资源。
+
+```
+# model_repo/layout-parsing/config.pbtxt
+instance_group [
+  {
+      count: 1       # 实例数，增大可提高并行度
+      kind: KIND_GPU
+      gpus: [ 0 ]
+  }
+]
+```
+
+实例数与动态批处理之间存在权衡：
+
+- **单实例（`count: 1`）**：动态批处理会将多个请求合并为一个批次并行执行，但同批次的请求需等待最慢的那个完成后才能一起返回，可能导致部分请求的时延升高。同时，单实例同一时刻只能处理一个批次，当前批次未完成时后续请求只能排队等待。适合显存有限或请求耗时较均匀的场景
+- **多实例（`count: 2+`）**：多个实例可以同时各自处理不同的批次，能够同时处理更多请求，减少排队等待时间，单个请求的时延也会有所改善。但需注意，同一实例内的批次仍然遵循动态批处理的行为（批内请求一起开始、一起结束）。每增加一个实例会额外占用一份版面检测模型的显存，同时也会增加对 VLM 推理服务的负载以及内存和 CPU 的使用，需根据推理设备的资源情况酌情设置
+
+非推理模型（如 `restructure-pages`）运行在 CPU 上，可根据 CPU 核数适当增加实例数。
+
+## 故障排查与解决
+
+### 服务无法启动
+
+查看各服务的日志以定位问题：
+
+```bash
+docker compose logs paddleocr-vl-api
+docker compose logs paddleocr-vl-tritonserver
+docker compose logs paddleocr-vlm-server
+```
+
+常见原因包括端口被占用、推理设备不可用或镜像拉取失败。
+
+### 超时错误
+
+- 增加 `HPS_INFERENCE_TIMEOUT`（针对复杂文档）
+- 如果推理设备过载，减少 `HPS_MAX_CONCURRENT_INFERENCE_REQUESTS`
+
+### 内存/显存不足
+
+- 减少 `HPS_MAX_CONCURRENT_INFERENCE_REQUESTS`
+- 确保每个推理设备只运行一个服务
+- 检查 compose.yaml 中的 `shm_size`（默认：4GB）