mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

SnapOtterandGitHub 991c981529 fix: make OCR portable and reliable across AMD64 and ARM64 (#519 )

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

2026-07-15 03:34:24 +08:00

4.1 KiB

Raw Blame History

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
使用内置 Tesseract 或可选的高精度 RapidOCR 运行时从本地扫描的 PDF 中提取文本。	e2437a0ab8cf	a19ba25a1ca8	human

PDF OCR

从扫描的 PDF 文档中逐页提取文本，无需将 PDF 发送到外部服务。内置 fast 层使用 Tesseract。可选的 balanced 和 best 层使用 RapidOCR 和固定的 PP-OCR ONNX 模型。

::: info 韩语 OCR 兼容性快速 OCR 支持 auto、en、de、es、fr、zh 和 ja，但不支持韩语 (ko)。韩语需要精确 OCR 包以及 balanced 或 best。该包可在官方 Linux amd64 和 arm64 容器上运行；即使是 NVIDIA 主机，OCR 仍使用 CPU。不受支持的系统会返回明确的兼容性错误，绝不会静默回退到 fast。韩语与 fast 或旧版 tesseract 别名的组合会在入队前以 FEATURE_INCOMPATIBLE 和 fast-korean-unsupported 拒绝。 :::

API Endpoint

POST /api/v1/tools/pdf/ocr-pdf

接受包含一个 PDF 文件和一个可选的 JSON settings 字段的 multipart 表单数据。

Parameters

Parameter	Type	Required	Default	Description
file	file	是的	-	PDF 文件（多部分），最多 512 个 MiB 编码；较低的运营商上传限制仍然适用
quality	string	不	动态的	OCR 质量等级：`fast`、`balanced` 或 `best`
language	string	No	`"auto"`	文档语言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`
pages	string	No	`"all"`	页面选择，例如 `"all"`、`"1-3"`、`"1,3,5"`
enhance	boolean	不	取决于层级	提高识别前的局部对比度。快速直接应用；仅当校准评分改善结果时，平衡和最佳才会保留变体。对于 `best` 默认为 `true`，对于 `fast`/`balanced` 默认为 `false`
engine	string	不	-	已弃用的兼容性别名。请改用 `quality`。 `tesseract` 映射到 `fast`；旧版 `paddleocr` 值映射到 `balanced` 但不加载 PaddlePaddle

省略 quality 和 engine 时，SnapOtter 会按 best、balanced、fast 的顺序选择可用的最高质量层。韩语绝不会选择 fast；它会使用 best，其次是 balanced，否则返回精确运行时的安装或兼容性错误。

Example Request

curl -X POST http://localhost:1349/api/v1/tools/pdf/ocr-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@scanned.pdf" \
  -F 'settings={"quality": "best", "language": "en", "pages": "1-5", "enhance": true}'

Example Response

返回 202 Accepted。通过 SSE 在 /api/v1/jobs/{jobId}/progress 跟踪进度。

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

Notes

接受的输入格式：.pdf。
内置fast，并在官方镜像中添加了约25个 MiB。 balanced 和 best 需要可选的精确 OCR 包（大约下载 208-234 MiB 并安装 409-488 MiB，具体取决于目标）。
准确包支持 Linux amd64 和 arm64，并在 CPU（包括 NVIDIA 主机）上使用 ONNX Runtime。
明确请求的等级绝不会默默降级。如果 balanced 或 best 不可用，则 API 返回 501 和 FEATURE_NOT_INSTALLED 或 FEATURE_INCOMPATIBLE。
PDF 页面在 OCR 之前以高分辨率进行光栅化。 best 运行更高精度的中型 PP-OCRv6 模型，并对方向和增强变体进行评分，以速度为代价提高识别能力。
auto 语言设置可以跨支持的脚本集进行识别；明确的提示可以改善已知文档语言的结果。
你可以使用范围（"1-3"）、逗号分隔的列表（"1,3,5"）或 "all" 来针对特定页面处理所有页面。
一个请求最多可以处理 50 个页面。光栅化暂存数据的上限为 512 MiB，聚合 UTF-8 OCR 响应的上限为 1,000,000 字节；超出限制的作业失败而不是返回部分文本。
对于已经包含可选择文本的 PDF，请考虑改用更快的 PDF to Text 工具。

4.1 KiB Raw Blame History