Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(docreader): crop the original image after detecting on a probe (#4586)

tayadwx96924f571962
diff --git a/.env.example b/.env.example
index b31f190a1..7d060002e 100644
--- a/.env.example
+++ b/.env.example
@@ -419,12 +419,14 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
# DOCREADER_GRPC_MAX_WORKERS=4
# Optional RapidOCR preprocessing: the knowledge-base switch defaults to off.
# Limits are per docreader replica; memory is per child (MiB). Busy/limited jobs use the original image.
+# Detection runs on a copy capped at PROBE_EDGE; the crop is taken from the original and capped at MAX_EDGE.
# DOCREADER_PREPROCESS_MAX_WORKERS=1
# DOCREADER_PREPROCESS_TIMEOUT_SECONDS=30
# DOCREADER_PREPROCESS_THREADS=2
# DOCREADER_PREPROCESS_MEMORY_MB=2048
# DOCREADER_PREPROCESS_MAX_PIXELS=16000000
# DOCREADER_PREPROCESS_MAX_EDGE=2000
+# DOCREADER_PREPROCESS_PROBE_EDGE=2000
# gRPC 单条消息大小上限(MB,默认 50)。通常跟随 MAX_FILE_SIZE_MB;过大扫描件图可能超此值。
# DOCREADER_GRPC_MAX_FILE_SIZE_MB=50
# gRPC 监听端口(默认 50051)一般无需修改,需要与docker-compose中的docreader port保持一致。
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 5a00eaef3..f654c9de2 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -276,6 +276,7 @@ services:
- DOCREADER_PREPROCESS_MEMORY_MB=${DOCREADER_PREPROCESS_MEMORY_MB:-2048}
- DOCREADER_PREPROCESS_MAX_PIXELS=${DOCREADER_PREPROCESS_MAX_PIXELS:-16000000}
- DOCREADER_PREPROCESS_MAX_EDGE=${DOCREADER_PREPROCESS_MAX_EDGE:-2000}
+ - DOCREADER_PREPROCESS_PROBE_EDGE=${DOCREADER_PREPROCESS_PROBE_EDGE:-2000}
# ========== 解析通用 ==========
- DOCREADER_DOCX_MAX_PAGES=${DOCREADER_DOCX_MAX_PAGES:-0}
- DOCREADER_MARKITDOWN_MAX_WORKERS=${DOCREADER_MARKITDOWN_MAX_WORKERS:-1}
diff --git a/docker-compose.yml b/docker-compose.yml
index b4ccc7f0e..daf976dcd 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -467,6 +467,7 @@ services:
- DOCREADER_PREPROCESS_MEMORY_MB=${DOCREADER_PREPROCESS_MEMORY_MB:-2048}
- DOCREADER_PREPROCESS_MAX_PIXELS=${DOCREADER_PREPROCESS_MAX_PIXELS:-16000000}
- DOCREADER_PREPROCESS_MAX_EDGE=${DOCREADER_PREPROCESS_MAX_EDGE:-2000}
+ - DOCREADER_PREPROCESS_PROBE_EDGE=${DOCREADER_PREPROCESS_PROBE_EDGE:-2000}
# ========== 解析通用 ==========
- DOCREADER_DOCX_MAX_PAGES=${DOCREADER_DOCX_MAX_PAGES:-0}
- DOCREADER_MARKITDOWN_MAX_WORKERS=${DOCREADER_MARKITDOWN_MAX_WORKERS:-1}
diff --git a/docreader/README.md b/docreader/README.md
index 50c79577e..85176eec1 100644
--- a/docreader/README.md
+++ b/docreader/README.md
@@ -103,7 +103,8 @@ docreader:
| `DOCREADER_PREPROCESS_THREADS` | `2` | 每个 ONNX 模型的算子内线程数及 OpenCV/数值库线程设置;算子间线程数为 1 |
| `DOCREADER_PREPROCESS_MEMORY_MB` | `2048` | 每个子进程的内存预算,单位 MiB;Linux 同时设置硬地址空间上限 `RLIMIT_AS`,父进程监测 RSS,超额即终止 |
| `DOCREADER_PREPROCESS_MAX_PIXELS` | `16000000` | 解码前检查图片头的像素上限,过大的输入直接回退 |
-| `DOCREADER_PREPROCESS_MAX_EDGE` | `2000` | 进入几何预处理前按比例缩小图片的最长边,输出也基于此工作图 |
+| `DOCREADER_PREPROCESS_PROBE_EDGE` | `2000` | 仅用于检测的工作图最长边;RapidOCR 自身也把检测器限在 2000,裁切仍回原图 |
+| `DOCREADER_PREPROCESS_MAX_EDGE` | `2000` | 裁切结果的最长边上限,超过才按比例缩小;不改写原图分辨率 |
所有限制必须为正数;非法值回落到默认值,`0` 不会关闭限制。编码后的输入最多为 20 MiB。未启用此功能时不启动子进程、不加载 RapidOCR 模型。
diff --git a/docreader/config.py b/docreader/config.py
index df9d404c9..fe28e07d4 100644
--- a/docreader/config.py
+++ b/docreader/config.py
@@ -83,6 +83,7 @@ class DocReaderConfig:
preprocess_memory_mb: int
preprocess_max_pixels: int
preprocess_max_edge: int
+ preprocess_probe_edge: int
# Proxy
external_http_proxy: str
@@ -175,6 +176,7 @@ def load_config() -> DocReaderConfig:
preprocess_memory_mb=_positive_int("DOCREADER_PREPROCESS_MEMORY_MB", 2048),
preprocess_max_pixels=_positive_int("DOCREADER_PREPROCESS_MAX_PIXELS", 16_000_000),
preprocess_max_edge=_positive_int("DOCREADER_PREPROCESS_MAX_EDGE", 2000),
+ preprocess_probe_edge=_positive_int("DOCREADER_PREPROCESS_PROBE_EDGE", 2000),
external_http_proxy=external_http_proxy,
external_https_proxy=external_https_proxy,
image_output_dir=image_output_dir,
@@ -210,6 +212,7 @@ def dump_config(mask_secrets: bool = True) -> Dict[str, Any]:
"DOCREADER_PREPROCESS_MEMORY_MB": cfg.preprocess_memory_mb,
"DOCREADER_PREPROCESS_MAX_PIXELS": cfg.preprocess_max_pixels,
"DOCREADER_PREPROCESS_MAX_EDGE": cfg.preprocess_max_edge,
+ "DOCREADER_PREPROCESS_PROBE_EDGE": cfg.preprocess_probe_edge,
"DOCREADER_EXTERNAL_HTTP_PROXY": cfg.external_http_proxy,
"DOCREADER_EXTERNAL_HTTPS_PROXY": cfg.external_https_proxy,
"DOCREADER_IMAGE_OUTPUT_DIR": cfg.image_output_dir,
diff --git a/docreader/parser/image_preprocess.py b/docreader/parser/image_preprocess.py
index a7d4dbe00..84cf9b8d9 100644
--- a/docreader/parser/image_preprocess.py
+++ b/docreader/parser/image_preprocess.py
@@ -344,6 +344,28 @@ def warp(img, quad, pad=PAD):
return rect, q
+def warp_ordered(img, quad, pad=0.0):
+ """Warp an ALREADY-ORDERED quad (TL, TR, BR, BL), with optional extra padding.
+
+ `preprocess`'s `quad_input` is already ordered and padded in the rotated
+ frame, so it must NOT go through `order_pts` again: on a rotated page the
+ sum/difference heuristic can pick a different corner and the crop comes back
+ twisted. This lets a caller detect on a smaller probe and still crop the
+ original bytes at their own resolution.
+ """
+ q = np.asarray(quad, "float32").reshape(4, 2)
+ if pad:
+ side = float(np.mean([np.linalg.norm(q[(i + 1) % 4] - q[i]) for i in range(4)]))
+ d = pad * side
+ q = q + np.array([[-d, -d], [d, -d], [d, d], [-d, d]], "float32")
+ wA, wB = np.linalg.norm(q[1] - q[0]), np.linalg.norm(q[2] - q[3])
+ hA, hB = np.linalg.norm(q[3] - q[0]), np.linalg.norm(q[2] - q[1])
+ Wt, Ht = int(max(wA, wB)), int(max(hA, hB))
+ dst = np.array([[0, 0], [Wt - 1, 0], [Wt - 1, Ht - 1], [0, Ht - 1]], "float32")
+ return cv2.warpPerspective(img, cv2.getPerspectiveTransform(q, dst), (Wt, Ht),
+ borderValue=(255, 255, 255))
+
+
def rec_score(img):
"""Mean recognition score with cls DISABLED (orientation-sensitive)."""
try:
diff --git a/docreader/preprocess.py b/docreader/preprocess.py
index 8e0e89879..e242b64f8 100644
--- a/docreader/preprocess.py
+++ b/docreader/preprocess.py
@@ -34,6 +34,9 @@ class PreprocessLimits:
memory_mb: int = 2048
max_pixels: int = 16_000_000
max_edge: int = 2000
+ # Detection runs on a copy capped at probe_edge; the crop itself is taken
+ # from the original image and only capped at max_edge.
+ probe_edge: int = 2000
def __post_init__(self):
if any(value <= 0 for value in asdict(self).values()):
diff --git a/docreader/preprocess_worker.py b/docreader/preprocess_worker.py
index e50cf03f5..7a2a53b64 100644
--- a/docreader/preprocess_worker.py
+++ b/docreader/preprocess_worker.py
@@ -36,7 +36,7 @@ def process_image(image, limits):
import numpy as np
from PIL import Image, UnidentifiedImageError
- from docreader.parser.image_preprocess import preprocess
+ from docreader.parser.image_preprocess import preprocess, warp_ordered
from docreader.proto.docreader_pb2 import PreprocessImageResponse
try:
@@ -56,11 +56,20 @@ def process_image(image, limits):
height, width = bgr.shape[:2]
if width * height > limits.max_pixels:
return PreprocessImageResponse(fallback_needed=True, status="image_too_large")
- scale = min(1.0, limits.max_edge / max(width, height))
- if scale < 1:
- bgr = cv2.resize(bgr, (max(1, round(width * scale)), max(1, round(height * scale))),
- interpolation=cv2.INTER_AREA)
- out = preprocess(bgr)
+
+ # Detection only needs a probe: RapidOCR caps its own detector at 2000,
+ # so a probe at that size loses no localisation. The crop, however, must
+ # come from the ORIGINAL bytes — cropping the probe would scale every
+ # glyph by the probe ratio (a 500px block would come back at 250px).
+ probe = bgr
+ probe_scale = min(1.0, limits.probe_edge / max(width, height))
+ if probe_scale < 1:
+ probe = cv2.resize(
+ bgr,
+ (max(1, round(width * probe_scale)), max(1, round(height * probe_scale))),
+ interpolation=cv2.INTER_AREA,
+ )
+ out = preprocess(probe)
fields = dict(
theta=float(out.get("theta") or 0), residual=float(out.get("residual") or 0),
n_boxes=int(out.get("n_boxes") or 0), n_kept=int(out.get("n_kept") or 0),
@@ -71,7 +80,27 @@ def process_image(image, limits):
fallback_needed=True, status=str(out.get("status", "unknown")), **fields)
if fields["residual"] > 2:
return PreprocessImageResponse(fallback_needed=True, status="low_quality", **fields)
- ok, encoded = cv2.imencode(".jpg", out["rect"], [cv2.IMWRITE_JPEG_QUALITY, 92])
+ if probe is bgr:
+ rect = out["rect"] # the crop already came from the original
+ else:
+ # `quad_input` is the content quad in probe coordinates, already
+ # ordered and padded; scale it back and crop the original image.
+ factor = np.array([width / probe.shape[1], height / probe.shape[0]], "float32")
+ quad = np.asarray(out["quad_input"], "float32").reshape(4, 2) * factor
+ rect = warp_ordered(bgr, quad)
+ if fields["flip"]:
+ rect = cv2.rotate(rect, cv2.ROTATE_180)
+ # The edge limit applies to the CROP, not to the source page: a small
+ # text block keeps its pixels even when the page around it is huge.
+ crop_scale = min(1.0, limits.max_edge / max(rect.shape[:2]))
+ if crop_scale < 1:
+ rect = cv2.resize(
+ rect,
+ (max(1, round(rect.shape[1] * crop_scale)),
+ max(1, round(rect.shape[0] * crop_scale))),
+ interpolation=cv2.INTER_AREA,
+ )
+ ok, encoded = cv2.imencode(".jpg", rect, [cv2.IMWRITE_JPEG_QUALITY, 92])
if not ok:
return PreprocessImageResponse(fallback_needed=True, status="encode_failed", **fields)
return PreprocessImageResponse(image=encoded.tobytes(), status="ok", **fields)
diff --git a/docreader/tests/test_config.py b/docreader/tests/test_config.py
index 64e9ec781..847b07d64 100644
--- a/docreader/tests/test_config.py
+++ b/docreader/tests/test_config.py
@@ -64,9 +64,10 @@ class DocReaderConfigTest(unittest.TestCase):
self.assertEqual(cfg.preprocess_memory_mb, 2048)
self.assertEqual(cfg.preprocess_max_pixels, 16_000_000)
self.assertEqual(cfg.preprocess_max_edge, 2000)
+ self.assertEqual(cfg.preprocess_probe_edge, 2000)
def test_preprocess_limits_cannot_be_disabled_by_invalid_values(self):
- for name in ("MAX_WORKERS", "THREADS", "TIMEOUT_SECONDS", "MEMORY_MB", "MAX_PIXELS", "MAX_EDGE"):
+ for name in ("MAX_WORKERS", "THREADS", "TIMEOUT_SECONDS", "MEMORY_MB", "MAX_PIXELS", "MAX_EDGE", "PROBE_EDGE"):
key = f"DOCREADER_PREPROCESS_{name}"
for value in ("0", "-1", "invalid"):
with self.subTest(key=key, value=value), patch.dict(os.environ, {key: value}, clear=True):
diff --git a/docreader/tests/test_preprocess_runner.py b/docreader/tests/test_preprocess_runner.py
index 302b61fbb..65988f84d 100644
--- a/docreader/tests/test_preprocess_runner.py
+++ b/docreader/tests/test_preprocess_runner.py
@@ -11,6 +11,7 @@ from concurrent.futures import ThreadPoolExecutor
from unittest.mock import patch
import grpc
+import numpy as np
from PIL import Image
from docreader.preprocess import MAX_IMAGE_BYTES, PreprocessLimits, PreprocessRunner
@@ -229,19 +230,53 @@ class ImageBudgetTest(unittest.TestCase):
decode.assert_not_called()
preprocess.assert_not_called()
- def test_working_image_is_resized_before_ocr(self):
+ def test_crop_keeps_original_resolution_when_under_the_output_cap(self):
+ # A 4000x4000 page whose only content is a 500x500 block: detect on a
+ # 2000 probe, but crop the original, so the block stays 500x500.
shapes = []
+ quad_probe = np.array([[0, 0], [250, 0], [250, 250], [0, 250]], "float32")
def inspect(img):
- shapes.append(img.shape)
- return {"status": "ok", "rect": img, "n_boxes": 4, "n_kept": 4}
+ shapes.append(img.shape[:2])
+ return {"status": "ok", "rect": np.zeros((10, 10, 3), "uint8"),
+ "quad_input": quad_probe, "n_boxes": 4, "n_kept": 4,
+ "residual": 0.0, "flip": False}
with patch("docreader.parser.image_preprocess.preprocess", side_effect=inspect):
- response = process_image(self.image((400, 200)), PreprocessLimits(max_edge=100))
- self.assertEqual(shapes, [(50, 100, 3)])
+ response = process_image(self.image((4000, 4000)),
+ PreprocessLimits(probe_edge=2000, max_edge=2000))
+ self.assertEqual(shapes, [(2000, 2000)])
self.assertEqual(response.status, "ok")
with Image.open(io.BytesIO(response.image)) as encoded:
- self.assertEqual(encoded.size, (100, 50))
+ self.assertEqual(encoded.size, (500, 500))
+
+ def test_output_is_capped_after_cropping(self):
+ quad_probe = np.array([[0, 0], [200, 0], [200, 200], [0, 200]], "float32")
+
+ def inspect(img):
+ return {"status": "ok", "rect": np.zeros((10, 10, 3), "uint8"),
+ "quad_input": quad_probe, "n_boxes": 4, "n_kept": 4,
+ "residual": 0.0, "flip": False}
+
+ with patch("docreader.parser.image_preprocess.preprocess", side_effect=inspect):
+ response = process_image(self.image((400, 400)),
+ PreprocessLimits(probe_edge=200, max_edge=100))
+ self.assertEqual(response.status, "ok")
+ with Image.open(io.BytesIO(response.image)) as encoded:
+ self.assertEqual(encoded.size, (100, 100))
+
+ def test_small_input_uses_the_crop_directly(self):
+ rect = np.full((40, 30, 3), 200, "uint8")
+
+ def inspect(img):
+ return {"status": "ok", "rect": rect, "n_boxes": 4, "n_kept": 4,
+ "residual": 0.0, "flip": False}
+
+ with patch("docreader.parser.image_preprocess.preprocess", side_effect=inspect):
+ response = process_image(self.image((200, 200)), PreprocessLimits(probe_edge=200))
+ self.assertEqual(response.status, "ok")
+ with Image.open(io.BytesIO(response.image)) as encoded:
+ self.assertEqual(encoded.size, (30, 40))
def test_bad_image_and_declined_geometry_keep_original(self):
self.assertTrue(process_image(b"not an image", PreprocessLimits()).fallback_needed)