External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
c0dc0378607c6ca882d29443f3b443475cf50970
SnapOtter/apps/docs/ko/tools/image/ocr.md
T
SnapOtterandGitHub 5f21588f6c chore: prepare the 2.2.0 release (#660) 
Bumps every version surface to 2.2.0, fixes a latent version-coupling bug in the
OCR runtime tests, and stops an absent GPU runner from silently stalling a
release.

Version surfaces: scripts/sync-version.sh covers the 11 workspaces, APP_VERSION,
and the docs release commands across all locales. Root package.json plus the
three surfaces the script never reaches are done by hand: the DOCKERHUB.md banner
and tag table, the docker-tags.md pinning table in 21 locales, and the example
runtimeVersion in tools/image/ocr.md in 21 locales. The release-notes archive step
is deliberately not pre-run, so the notes text stays editable until the release.

Latent bug: runtime-state rejects any runtime whose compatibility.snapotterVersion
is not exactly APP_VERSION, and five fixtures pinned the literal 2.1.0. Since
semantic-release rewrites APP_VERSION on every release, the first PR after any
bump would have gone red for a reason nobody would trace to the release. The
fixtures now derive from APP_VERSION.

GPU runner: sign-ocr-index needs verify-ocr-nvidia on self-hosted hardware, and
the gated manifest job needs ai-bundles, so a missing runner queued instead of
failing and produced no image tags. preflight-gpu-runner claims the same labels
with no dependencies, so it is scheduled first and validates the GPU before the
90-minute build. An API preflight is impossible because listing self-hosted
runners needs Administration:read, which GITHUB_TOKEN cannot hold, so RELEASE.md
carries the maintainer-side check.
2026-07-27 22:09:31 +08:00

6.8 KiB
Raw Blame History

description, i18n_output_hash, i18n_source_hash, i18n_provenance
description i18n_output_hash i18n_source_hash i18n_provenance
내장된 Tesseract 또는 선택적인 고정밀 RapidOCR 런타임을 사용하여 이미지에서 로컬로 텍스트를 추출합니다. 8320ed5125e7 0d453b49db02 human

OCR / Text Extraction

이미지를 외부 서비스로 보내지 않고 이미지에서 텍스트를 추출합니다. 기본 제공 fast 계층은 Tesseract 를 사용합니다. 선택적 balanced 및 best 계층은 고정된 PP-OCR ONNX 모델과 함께 RapidOCR 를 사용합니다.

::: 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/image/ocr

처리: OCR은 항상 비동기로 실행됩니다. 유효성 검사와 대기열 등록이 끝나면 엔드포인트는 jobId와 함께 즉시 202 Accepted를 반환합니다. 작업의 SSE 진행 스트림을 최종 complete 또는 failed 이벤트까지 추적하세요. 성공 이벤트의 result에는 OCR 필드가 포함됩니다.

정확한 OCR 팩: 선택적 ocr 런타임(대상에 따라 약 208-234 MiB 다운로드 및 409-488 MiB 설치). fast에는 이 팩이 필요하지 않습니다. 설치 프로그램은 서명된 인덱스에 의해 제한되는 정확한 크기를 확인합니다.

Parameters

Parameter Type Required Default Description
file file 예 - 이미지 파일(멀티파트), 최대 512 MiB 인코딩 및 40 메가픽셀 디코딩; 더 낮은 운영자 업로드 제한이 여전히 적용됩니다.
quality string 아니요 동적 품질 등급: fast(Tesseract), balanced(소형 PP-OCRv6 모델이 포함된 RapidOCR) 또는 best(보정된 변형 스코어링이 포함된 정확도가 높은 중간 PP-OCRv6 모델)
language string No "auto" 언어 힌트: auto, en, de, fr, es, zh, ja, ko
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/image/ocr \
  -F "file=@document.png" \
  -F 'settings={"quality":"best","language":"en","enhance":true}'

수락 응답 (202)

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

진행 상황 및 결과 (SSE)

202 응답에서 반환된 jobId(또는 제공한 clientJobId)를 사용해 GET /api/v1/jobs/{jobId}/progress에 연결합니다. 최종 complete 또는 failed 이벤트까지 스트림을 열어 두세요. 성공한 최종 프레임의 result에는 OCR 출력이 포함됩니다.

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "single",
  "phase": "complete",
  "stage": "complete",
  "percent": 100,
  "result": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document_ocr.txt",
    "originalSize": 12345,
    "processedSize": 47,
    "text": "Extracted text content from the image...",
    "engine": "rapidocr-onnx",
    "requestedQuality": "best",
    "actualQuality": "best",
    "device": "cpu",
    "provider": "CPUExecutionProvider",
    "degraded": false,
    "warnings": [],
    "runtimeVersion": "2.2.0",
    "modelVersion": "PP-OCRv6-best-v1-medium"
  }
}

처리 실패는 최종 failed 이벤트의 error 필드로 전달되며, 대기열 등록 후 HTTP 422로 반환되지 않습니다.

Notes

  • 지원되는 SnapOtter 이미지에서는 fast를 항상 사용할 수 있습니다. balanced와 best에는 선택 사항인 고정확도 OCR 팩이 필요합니다.
  • 내장 Tesseract는 공식 이미지에 약 25 MiB를 추가합니다. 고정확도 팩은 이미지에 포함되지 않고 /data/ai에 저장됩니다.
  • 고정확도 팩은 공식 Linux amd64 및 arm64 컨테이너용으로 배포됩니다. NVIDIA 호스트에서도 ONNX Runtime의 CPU 공급자를 사용하므로 CUDA 라이브러리나 GPU 호환성에 의존하지 않습니다. 소스 및 사전 빌드된 bare-metal 설치에서는 자체 호환 런타임을 제공하지 않는 한 Fast OCR를 사용합니다.
  • 성공한 최종 result에는 text의 추출된 텍스트와 downloadUrl의 다운로드 가능한 .txt 아티팩트가 모두 포함됩니다.
  • SnapOtter 는 명시적으로 요청된 계층을 존중합니다. balanced 또는 best를 사용할 수 없는 경우 API 는 FEATURE_NOT_INSTALLED 또는 FEATURE_INCOMPATIBLE와 함께 501를 반환합니다. 요청을 다른 계층으로 자동으로 다운그레이드하지 않습니다.
  • 성공적인 빈 결과는 빈 결과로 유지됩니다. 런타임 실패는 낮은 품질의 엔진으로 다시 시도하는 대신 오류를 반환합니다.
  • 성공한 최종 result는 requestedQuality 및 actualQuality와 엔진, 장치, 공급자, 런타임 및 모델 버전과 모든 경고를 보고합니다.
  • HEIC/HEIF, RAW, TGA, PSD, EXR, HDR 입력 형식을 자동 디코딩으로 지원합니다.
  • 대형 인코딩 입력은 413를 반환합니다. 40 메가픽셀이 넘는 이미지와 제한된 출력 제한을 초과하는 OCR 응답은 부분적으로 처리되는 대신 거부됩니다.
Reference in New Issue View Git Blame Copy Permalink