arcships/light-ocr 딥다이브
— 파이썬 없이 Node.js에서 도는 오프라인 OCR 엔진

1프로젝트 한 줄 요약

가장 작은 사용 예시가 이 라이브러리의 성격을 압축한다. 파이썬도, 별도 서버도, 모델 다운로드 스크립트도 없다:

import { createEngine } from "@arcships/light-ocr";
import { readFile } from "node:fs/promises";

const engine = await createEngine();                 // 모델·네이티브 로드(오프라인)
const result = await engine.recognizeEncoded(await readFile("image.jpg"));
for (const line of result.lines)
    console.log(line.text, line.confidence, line.box);  // 글자 · 신뢰도 · 사각형 좌표
await engine.close();                                   // 명시적 정리

정리하면 light-ocr의 정체는 두 겹이다. ① C++ OCR 코어(light_ocr::core 정적 라이브러리): 이미지 디코딩 → 글자 영역 검출 → 인식 → 후처리까지 손으로 짠 파이프라인. ② 비동기 N-API 어댑터: 그 C++ 코어를 Node.js의 이벤트 루프를 막지 않고 비동기 Promise로 노출하는 얇지만 정교한 다리. 여기에 CLI(light-ocr)와 AI 에이전트용 스킬까지 얹었다. OCR "정확도"는 바이두 모델에서 오고, 이 레포의 진짜 가치는 그 모델을 Node 생태계에 매끄럽게·안전하게 심는 엔지니어링에 있다.

저자는 GitHub 조직 arcships(커밋 작성자 chenghan)이며, Apache-2.0으로 공개했다. 2026년 7월 14일 생성된 아주 신생 레포인데 별점이 빠르게 붙어 TrendShift Daily 상위에 올랐다. 흥미롭게도 AGENTS.md는 모든 커밋·PR·이슈 제목에 "중국 고전 시구 · 영어 제목" 형식을 요구하는 독특한 규약을 둔다(예: 修正平台標識 · fix platform id).

2왜 주목받는가 — "파이썬 없는 OCR"의 무게

Node.js/자바스크립트 개발자가 "이미지에서 글자 좀 뽑자"고 마음먹으면, 지금까지 선택지는 셋 다 어딘가 불편했다. light-ocr은 그 셋의 약점을 정확히 겨냥한다.

차별점 ① — 설치 한 번, 그 안에 모델·바이너리가 다 들어 있다

npm install @arcships/light-ocr 하면 끝이다. 컴파일러도, 파이썬도, post-install 다운로드도 없다. 비결은 npm 패키징 방식이다. 얇은 자바스크립트 파사드 패키지 하나가, 운영체제·CPU에 맞는 프리빌트 네이티브 패키지(6종)와 모델 패키지를 optionalDependencies로 두고 런타임에 자동 선택한다. 사용자는 이 복잡함을 전혀 못 느낀다.

차별점 ② — 오프라인·온디바이스: 이미지가 기기를 떠나지 않는다

설치 후에는 네트워크가 전혀 필요 없다. 이미지도, 인식 결과도 전부 로컬에서 처리된다. 개인정보가 담긴 문서·영수증·신분증을 다루는 앱이라면 이건 기능이 아니라 규정 준수(compliance) 요건이다. 클라우드 OCR로는 넘기 어려운 벽을, 라이브러리 하나로 넘는다.

차별점 ③ — 하드웨어 가속을 기본으로, 그런데 결과는 CPU와 동일하게

기본 모드(createEngine())는 플랫폼에 맞는 가속기를 자동 선택한다: Apple Silicon macOS 15+는 Core ML(뉴럴 엔진), Linux/Windows x64는 WebGPU. 실측(v0.3.0)으로 Apple M4 Max에서 최대 2.85배, NVIDIA RTX 5060 Ti(WebGPU/Vulkan)에서 5.70배 빨라졌다. 인상적인 건 WebGPU 결과가 CPU FP32와 바이트 단위로 동일했다는 점 — "빠른데 결과가 달라지는" 흔한 함정을 품질 게이트로 막았다.

3기술 스택 전체 지도 — C++ 코어·N-API·npm 패키징

light-ocr은 "프론트/백엔드"로 나눌 웹 앱이 아니다. 스택을 이해하려면 세 개의 층으로 보는 게 빠르다: 실제 OCR을 계산하는 C++ 코어, 그걸 JS에 잇는 N-API 어댑터, 그리고 이 모든 걸 사용자에게 배달하는 npm 패키징. 여기에 가속기(Core ML/WebGPU)가 코어 밑에 끼어든다.

① C++ 코어 층 — light_ocr::core (C++17)

손으로 짠 C++17 정적 라이브러리가 심장이다. 외부 딥러닝 프레임워크 없이, 추론은 ONNX Runtime에 맡기고 이미지 처리·후처리는 직접 구현했다. 의존성은 전부 버전 고정(models/deps.lock.json)이다.

② N-API 어댑터 층 — bindings/node

이 층의 핵심은 뒤(4장)에서 자세히 볼 비동기 모델이다. 무거운 C++ 연산을 JS 메인 스레드 밖에서 돌리면서도, 결과를 안전하게 Promise로 돌려준다.

③ npm 패키징 층 — 파사드 + 플랫폼 + 모델

가장 영리한 부분. 하나의 얇은 파사드 패키지가, 무거운 바이너리·모델을 별도 패키지로 쪼개 두고 런타임에 필요한 것만 고른다. binding.gyp도, node-gyp도, post-install 스크립트도 전혀 없다 — 빌드는 순수 CMake다.

④ 가속 층 — Core ML · WebGPU (FP16 파생 모델)

기본 모델은 CPU용 FP32다. WebGPU 가속을 위해 저자는 이 모델을 FP16으로 변환한 파생 모델을 따로 만들어 두되(검출 4.97MB·인식 10.6MB), GPU가 잘 못 하는 연산(NonMaxSuppression·TopK 등)은 FP32·CPU에 남기는 "op 블록 리스트"를 적용했다. 그 결과가 앞서 말한 "GPU인데 CPU와 바이트 동일"의 비결이다.

4아키텍처 심화 — 스레드 한 개로 C++를 JS에 안전하게 잇기

이 레포에서 가장 배울 게 많은 부분이 바로 여기다. "무거운 C++ 작업을 Node의 이벤트 루프를 막지 않고 어떻게 돌리는가"라는 오래된 문제를, light-ocr은 교과서와 다른 방식으로 푼다.

흔한 방법이 아니다 — AsyncWorker 대신 전용 스레드

보통 네이티브 애드온은 Napi::AsyncWorker로 작업을 libuv 스레드풀에 던진다. light-ocr은 대신 엔진 하나당 전용 std::thread 워커 한 개를 띄우고, 그 스레드가 FIFO 큐를 blocking으로 지키며 요청을 하나씩 처리한다.

// addon.cpp — 엔진 워커 스레드의 메인 루프 (개념 축약)
void EngineState::run() {
  load_bundle();                          // 모델 1회 로드
  while (true) {
    std::shared_ptr<Request> request;
    {
      std::unique_lock<std::mutex> lock(mutex);
      changed.wait(lock, [this]{         // 큐에 일 생길 때까지 잠듦
        return environment_closing || !queue.empty() || close_requested; });
      if (environment_closing) break;
      if (!queue.empty()) { request = queue.front(); queue.pop_front(); }
      else if (close_requested) break;
    }
    // 디코드 → (ROI 크롭) → core->recognize()/detect() → 결과를 JS 스레드로
    post_completion(context, run_ocr(request));
  }
}

결과를 JS로 돌려주는 다리 — threadsafe function

워커 스레드에서 계산한 결과를 JS 스레드로 넘기는 건 까다롭다. JS 엔진(V8) 객체는 다른 스레드에서 만지면 안 되기 때문이다. light-ocr은 환경당 단 하나의 napi_threadsafe_function(완료 디스패처)을 두어, 어느 워커든 결과를 이 통로로 밀어 넣으면 안전하게 JS 스레드에서 Promise가 resolve된다. 놀지 않을 땐 이벤트 루프를 잡아 두지 않도록 unref 처리한다.

// 모듈 초기화: 환경당 완료 디스패처 1개 생성
napi_create_threadsafe_function(env, nullptr, nullptr, resource_name,
    kCompletionQueueCapacity /*64*/, 1, context.get(),
    finalize_dispatcher, nullptr, call_js, &context->dispatcher);
napi_unref_threadsafe_function(env, context->dispatcher);  // 유휴 시 루프 안 붙잡음

백프레셔·취소·메모리 회계까지

단순 비동기가 아니라 프로덕션급 흐름 제어가 들어 있다. 큐는 기본 4개(최대 64)로 경계가 있고(backpressure), 대기 중 입력 바이트가 기본 256MiB를 넘으면 거절한다. 각 요청은 네이티브 Promise + BigInt requestId를 돌려주고, JS의 AbortSignal로 native.cancel(requestId)를 불러 진행 중 작업을 취소할 수 있다. 이미지 스냅샷은 napi_adjust_external_memory로 회계 처리해 GC가 메모리 압력을 알게 한다.

// js/index.cjs — AbortSignal로 취소 가능한 Promise 래퍼
#recognize(nativeMethod, image, options) {
  const operation = this.#native[nativeMethod](image, nativeOptions); // {requestId, promise}
  return new Promise((resolve, reject) => {
    const onAbort = () => {
      try { this.#native.cancel(operation.requestId); } catch {}
      settle(reject, abortReason(signal));
    };
    operation.promise.then(v => settle(resolve, v),
                           e => settle(reject, normalizeNativeError(e)));
    if (signal) signal.addEventListener('abort', onAbort, { once: true });
  });
}

그 안에서 도는 OCR 파이프라인 — 검출 → 인식 → 디코드

실제 core->recognize() 내부는 고전적 2-스테이지 OCR이다. 글자가 어디 있는지 찾고(검출, DBNet), 그 자리를 잘라 무슨 글자인지 읽는다(인식, CRNN/SVTR + CTC).

로드 시점의 공급망 보안 — SHA-256 + ABI 계약

네이티브 바이너리·모델을 npm으로 배포하는 건 공급망 공격의 표적이 될 수 있다. light-ocr은 load-native.cjs가 로드 전에 runtime-descriptor.json(스키마 2.0)을 검증한다: 아티팩트마다 SHA-256 해시·바이트 수 대조, 경로 탈출·심볼릭 링크 거부, 그리고 JS가 계산한 정책과 네이티브가 내보낸 runtimeContract를 맞춰 보는 ABI 계약 핸드셰이크까지. "신뢰할 수 있는 바이너리만 로드"를 코드로 강제한다.

5디렉토리 구조 해부

구조가 말하는 핵심 세 가지. 첫째, C++ 코어(src/)와 Node 어댑터(bindings/node/)가 깔끔히 분리돼 있어, C++ 라이브러리만 떼어 다른 언어에 붙일 수도 있다. 둘째, src/inference/가 추상 인터페이스(backend.hpp) + 구체 구현(onnxruntime·coreml)으로 갈려 있어 가속기 추가가 쉽다. 셋째, 신생 레포치고 검증 자료(reports/·corpus/·fuzz)가 이례적으로 무겁다 — 품질에 진심이라는 신호다.

6학습 포인트 — 여기서 훔쳐올 설계

배울 것 ① — 교과서와 다른 N-API 비동기 패턴

이 레포 최고의 학습 자산. AsyncWorker/libuv 스레드풀 대신 엔진당 전용 스레드 + 참조 카운트된 단일 threadsafe function 디스패처를 쓰는 방식은, 오래 도는 C++ 작업을 JS에 노출하는 정교한 실전 레퍼런스다. 네이티브 Promise, BigInt requestId 취소, 경계 있는 FIFO 백프레셔, napi_adjust_external_memory 회계 — 하나하나가 프로덕션 네이티브 모듈의 필수 요소다.

배울 것 ② — 네이티브 모듈을 현대적으로 패키징하기

파사드 + 플랫폼별 optionalDependency 바이너리 + 별도 모델 패키지, 전부 프리빌트(node-gyp·binding.gyp 없이 CMake만), Electron용 delay-load 훅까지. 이는 "설치할 때 컴파일"하던 옛 방식과 극명히 대비되는, npm에 네이티브 코드를 배달하는 모범 청사진이다. C/C++/Rust로 짠 무언가를 JS 생태계에 팔고 싶은 사람에게 그대로 참고서가 된다.

배울 것 ③ — 추상 인터페이스로 백엔드를 갈아 끼우기

InferenceSession이라는 순수 추상 인터페이스 아래 ORT·Core ML 구현이 갈려 있고, execution.provider: 'auto'가 기기에 맞는 걸 골라 실패 시 CPU로 안전 강등한다. "하드웨어마다 다른 백엔드를, 상위 코드는 모르게 추상화하는" 이 구조는 플러그형 아키텍처의 좋은 표본이다.

배울 것 ④ — 성능을 얻되 정확성은 계약으로 지키기

WebGPU FP16로 5배 빨라지면서도 CPU FP32와 바이트 동일을 품질 게이트로 요구한 점은 인상적이다. GPU가 약한 연산은 CPU에 남기는 "경계 있는 CPU 파티션", 14장 이미지 전수 대조 — "빠른데 슬그머니 결과가 달라지는" 가속의 함정을 어떻게 규율하는지 보여 준다.

배울 것 ⑤ — 네이티브 배포의 공급망 보안

아티팩트별 SHA-256 검증, 버전 있는 디스크립터 스키마, 경로 탈출·심링크 방어, JS↔네이티브 ABI 계약 핸드셰이크. npm으로 신뢰 가능한 바이너리를 배포하는 법의 레퍼런스다. 여기에 예외 대신 Result<T>, noexcept 추론 경계, 오버플로 안전 checked_math까지 — 방어적 시스템 C++의 표본이기도 하다.

7시스템 / 실행 요구사항

실행 옵션이 이 라이브러리의 "손잡이"를 보여 준다. createEngine({ execution: { provider: 'auto'|'cpu'|'apple'|'webgpu', precision: 'auto'|'fp32'|'fp16', sessionFallback: 'error'|'cpu' } })로 가속을 세밀 제어하고, detection: { strategy: 'bounded'|'tiled' }로 고해상도 속 작은 글자를 타일 방식으로 잡는다. 인식은 recognitionBatchSize·recognitionScoreThreshold로, 리소스는 queueCapacity·maxPendingInputBytes로 조인다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 · 배포

• github.com/arcships/light-ocr — 원본 저장소(Apache-2.0)
• npm — @arcships/light-ocr — 파사드 패키지(프리빌트 + 모델 자동 선택)

핵심 배경 기술

• PaddleOCR — PP-OCRv6 모델 원본(검출·인식)
• ONNX Runtime · Node-API(N-API) 공식 문서
• WebGPU · Core ML — 하드웨어 가속 백엔드

C++ · 빌드 · OCR 이론

• OpenCV · CMake — 이미지 처리·네이티브 빌드
• DBNet 논문(Differentiable Binarization) · CTC 시각 해설(distill.pub)