mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
991c981529
* 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
68 lines
4.1 KiB
Markdown
68 lines
4.1 KiB
Markdown
---
|
|
description: "使用内置 Tesseract 或可选的高精度 RapidOCR 运行时从本地扫描的 PDF 中提取文本。"
|
|
i18n_output_hash: e2437a0ab8cf
|
|
i18n_source_hash: a19ba25a1ca8
|
|
i18n_provenance: human
|
|
---
|
|
|
|
# PDF OCR {#pdf-ocr}
|
|
|
|
从扫描的 PDF 文档中逐页提取文本，无需将 PDF 发送到外部服务。内置 `fast` 层使用 Tesseract。可选的 `balanced` 和 `best` 层使用 RapidOCR 和固定的 PP-OCR ONNX 模型。
|
|
|
|
|
|
<!-- korean-ocr-contract:start -->
|
|
::: 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` 拒绝。
|
|
:::
|
|
<!-- korean-ocr-contract:end -->
|
|
## API Endpoint {#api-endpoint}
|
|
|
|
`POST /api/v1/tools/pdf/ocr-pdf`
|
|
|
|
接受包含一个 PDF 文件和一个可选的 JSON `settings` 字段的 multipart 表单数据。
|
|
|
|
## Parameters {#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 {#example-request}
|
|
|
|
```bash
|
|
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 {#example-response}
|
|
|
|
返回 `202 Accepted`。通过 SSE 在 `/api/v1/jobs/{jobId}/progress` 跟踪进度。
|
|
|
|
```json
|
|
{
|
|
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"async": true
|
|
}
|
|
```
|
|
|
|
## Notes {#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](./pdf-to-text) 工具。
|