pdf-inspector PDF OCR 연동 안내서 2026

첫 단계에서 pdf-inspector PDF OCR 사전 검사를 넣으십시오. 텍스트형 PDF는 원문 추출로 보내고, 스캔형 PDF는 OCR로 보내며, 혼합형 PDF는 페이지별 분기를 우선합니다. 운영 환경에서는 유형 이름만 저장하지 말고 신뢰 정보, 실패 원인, 재처리 경로와 사람 검수 지점까지 함께 설계해야 합니다.

이 글은 계약서, 보고서, 논문을 대량 처리하는 백엔드 개발자에게 적합합니다. RAG 문서 파이프라인에서 OCR을 기본 동작이 아니라 조건부 작업으로 바꾸려는 AI 엔지니어도 대상입니다. 원격 개발 환경에서 배치 처리량을 시험하려는 팀은 마지막의 확장 판단 기준을 확인하면 됩니다.

마지막 업데이트: 2026년 8월 10일. 프로젝트 저장소의 현재 README, 파이썬 문서, 예제와 최신 변경 기록을 다시 확인한 뒤 작성했습니다. 인터페이스와 분류 필드는 변경될 수 있으므로 배포 직전에 공식 문서를 다시 확인해야 합니다.

시작 전에 처리 결과부터 고정합니다

PDF 유형 검사를 붙이기 전에 하류 시스템이 무엇을 소비하는지 정해야 합니다. 단순 텍스트가 필요한지, 마크다운이 필요한지, 페이지 구조와 표가 필요한지, 아니면 OCR 좌표까지 필요한지에 따라 같은 분류 결과도 연결 방식이 달라집니다.

처리 경로는 다음처럼 나누는 편이 실무적입니다.

• 텍스트형: 원본 텍스트와 위치 정보를 우선 추출합니다. OCR은 기본 경로에서 제외합니다.
• 스캔형: 페이지 이미지를 OCR 작업으로 보냅니다. OCR 결과에는 페이지 번호와 품질 정보를 붙입니다.
• 혼합형: 텍스트가 있는 페이지는 원문 추출로 처리하고, 텍스트가 없는 페이지는 OCR로 보냅니다.
• 판정 오류형: 암호화, 손상, 빈 페이지, 비정상 글꼴, 읽을 수 없는 객체가 있으면 격리 큐로 이동합니다.

공식 설명에 따르면 pdf-inspector는 텍스트형, 스캔형, 이미지형, 혼합형을 구분하고 신뢰 값과 OCR이 필요한 페이지 정보를 반환하도록 설계되어 있습니다. 다만 이 값은 OCR 품질 자체를 보증하는 점수가 아닙니다. 문서의 글자 인식률과 표 복원 품질은 별도 검증 대상입니다. 공식 저장소의 분류 설명을 기준으로 하되, 실제 배포판의 반환 구조를 다시 확인하십시오.

첫 시간에는 최소 연결만 검증합니다

첫 번째 확인: 공식 예제와 현재 설치 방식을 맞춥니다

현재 저장소의 파이썬 시작 예제는 maturin을 사용해 개발 빌드를 만든 뒤 process_pdf를 호출하는 형태입니다. 따라서 문서에 없는 패키지 설치 명령이나 임의의 함수 이름을 운영 코드에 먼저 넣지 않는 것이 좋습니다.

pip install maturin
maturin develop --release

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")

print(result.pdf_type)
print(result.markdown)

위 예제에서 확인할 값은 pdf_type과 markdown입니다. 공식 문서에는 유형 값의 예로 text_based, scanned, image_based, mixed가 제시되어 있습니다. 다만 실제 반환 객체의 추가 속성은 사용 중인 커밋과 바인딩 버전에 맞춰 확인해야 합니다. 공식 파이썬 문서를 기준으로 최소 호출을 먼저 검증하십시오.

두 번째 확인: 서로 다른 샘플로 분류를 확인합니다

최소 검증에는 다음 두 파일이 필요합니다.

1. 복사 가능한 글자가 포함된 텍스트형 PDF
2. 페이지 전체가 이미지인 스캔 PDF

가능하면 여기에 텍스트 페이지와 이미지 페이지만 섞은 혼합형 PDF도 추가하십시오. 결과가 성공했다는 사실보다 pdf_type이 예상과 같은지, 마크다운이 비어 있지 않은지, 페이지 순서가 유지되는지를 확인해야 합니다.

pdf-inspector는 PDF의 텍스트 연산자와 이미지 연산자를 살펴 유형을 나누는 방식입니다. 따라서 화면에서 글자가 보인다고 해서 반드시 추출 가능한 텍스트가 있는 것은 아닙니다. 글꼴 인코딩이 깨졌거나 글자가 이미지로만 들어간 파일은 별도 회귀 샘플로 남겨야 합니다. 공식 저장소는 깨진 글꼴 인코딩을 OCR 회귀 대상으로 표시할 수 있다고 설명합니다.

둘째 단계에서 배치 작업의 경계를 정합니다

단일 파일 호출이 확인되면 곧바로 동시 실행 수를 높이지 마십시오. 먼저 입력 큐, 작업 상태, 시간 제한, 결과 저장 위치를 나눠야 합니다.

권장 상태는 다음과 같습니다.

• received: 파일 수신 완료
• inspecting: PDF 유형 검사 중
• native_extract: 원문 추출 중
• ocr_pending: OCR 대기 중
• manual_review: 사람 검수 대기
• completed 또는 failed: 최종 처리 상태

각 작업에는 최소한 다음 메타데이터를 저장해야 합니다.

• 파일 해시
• 파일 크기와 페이지 수
• 검사 시 사용한 프로젝트 버전
• 분류 결과와 신뢰 정보
• OCR로 넘긴 페이지
• 제한 시간 초과 여부
• 실패 원인과 재처리 횟수

파일 이름만 키로 사용하면 같은 이름의 새 파일이 기존 결과를 덮어쓸 수 있습니다. 반대로 해시와 검사 버전을 함께 저장하면 버전 업그레이드 뒤 동일 파일을 다시 비교할 수 있습니다.

동시성은 CPU와 메모리만 보고 정하지 마십시오. OCR 엔진, 임시 이미지 파일, 네트워크 대기, 결과 저장소의 쓰기 속도가 함께 제한됩니다. 첫 배치에서는 보수적인 동시성으로 시작하고, 검사 단계와 OCR 단계의 대기열을 분리하십시오. 검사 작업이 빠르더라도 OCR 작업이 막히면 전체 큐가 가득 찰 수 있습니다.

셋째 단계에서 PDF 유형별 회귀 경로를 붙입니다

텍스트형은 원문 추출을 우선합니다

텍스트형 PDF는 원문 추출을 먼저 시도합니다. pdf-inspector는 위치 정보를 활용한 텍스트 추출과 마크다운 변환을 제공하며, 표와 다단 구성도 처리 대상으로 설명하고 있습니다. 그러나 이 기능이 모든 문서의 표 구조를 보존한다는 뜻은 아닙니다. RAG에 넣을 문서라면 표 셀 순서, 제목 계층, 페이지 경계를 별도 샘플로 확인하십시오. 공식 마크다운 처리 설명을 참고할 수 있습니다.

추출 결과가 비어 있거나 글자가 깨지면 즉시 성공 처리하지 마십시오. 글꼴 인코딩 오류, 문자 매핑 문제, 읽기 순서 오류일 수 있으므로 OCR 회귀 경로로 보냅니다.

스캔형은 OCR 전처리 뒤 실행합니다

스캔 PDF는 OCR 엔진에 바로 넣기보다 페이지 방향, 해상도, 빈 페이지, 기울기와 암호화 상태를 먼저 검사하십시오. 이 단계가 빠지면 빈 페이지가 정상 문서처럼 저장되거나, OCR 실패가 원본 문제인지 엔진 문제인지 구분되지 않습니다.

OCR 결과에는 원본 파일 해시, 페이지 번호, OCR 엔진 버전, 언어 설정, 품질 판정값을 함께 저장하십시오. 나중에 OCR 엔진을 바꿀 때 같은 페이지를 다시 비교할 수 있어야 합니다.

혼합형은 페이지 단위 분기를 먼저 평가합니다

혼합형 PDF를 무조건 전체 OCR로 보내면 이미 추출 가능한 페이지까지 다시 처리하게 됩니다. 공식 저장소에는 OCR이 필요한 페이지 목록을 활용한 페이지별 경로가 설명되어 있습니다. 공식 스마트 PDF 라우팅 설명을 기준으로 페이지별 경로를 설계할 수 있습니다.

다만 페이지별 결과를 합치는 후처리가 복잡하면 전체 OCR이 더 안전할 수 있습니다. 다음 결정 조건을 운영 규칙으로 고정하십시오.

결정 조건 목록: 페이지별 OCR과 전체 OCR 선택 기준

• [ ] 페이지별 텍스트와 OCR 결과를 합칠 수 있다면 페이지별 OCR을 선택합니다.
• [ ] 문서 전체의 레이아웃과 순서가 핵심이면 전체 OCR 후보로 비교합니다.
• [ ] 유형 결과가 낮거나 파일 구조에 오류가 있으면 격리 후 재검사로 보냅니다.
• [ ] 계약 금액, 표, 법률 조항처럼 누락 비용이 크면 사람 검수 샘플을 의무화합니다.
• [ ] 하류 시스템이 페이지 번호와 결과 출처를 보존하지 못하면 전체 처리 방식을 먼저 시험합니다.
• [ ] 같은 샘플에서 병합 결과가 기준 품질을 넘지 못하면 페이지별 분기를 중단하고 전체 OCR로 회귀합니다.

이 목록은 단순한 개발 편의보다 결과 소비 방식에 맞춰 선택하기 위한 도구입니다. 혼합형 PDF를 자동으로 한 경로에 넣기 전에 최소 샘플로 두 방식을 모두 실행하고, 누락 페이지와 구조 보존 결과를 비교하십시오.

자주 묻는 질문

PDF가 OCR이 필요한지 자동으로 판단하려면 어떻게 합니까?

파일 수신 후 바로 OCR을 실행하지 말고 pdf-inspector로 유형을 먼저 기록합니다. 텍스트형은 원문 추출, 스캔형은 OCR, 혼합형은 페이지별 처리를 기본값으로 둡니다. 결과가 비어 있거나 오류가 발생하면 성공 큐가 아니라 격리 큐로 보내야 합니다.

혼합형 PDF는 전체 OCR과 페이지별 OCR 중 무엇이 낫습니까?

하류 시스템이 페이지 단위 결과를 합칠 수 있다면 페이지별 OCR이 합리적입니다. 반대로 문서 전체 순서와 레이아웃이 중요하거나 병합 로직이 불안정하면 전체 OCR을 별도 후보로 시험해야 합니다. 한 번의 성공 여부가 아니라 누락률과 구조 보존 결과로 선택하십시오.

기존 파이썬 서비스에는 어떤 방식으로 연결합니까?

공식 파이썬 바인딩의 최소 예제처럼 process_pdf를 호출하고 pdf_type, markdown을 확인하면 됩니다. 운영 서비스에서는 호출 결과만 반환하지 말고 파일 해시, 검사 버전, 재처리 이유를 함께 저장하십시오. 이렇게 해야 같은 입력을 새 버전에서 다시 비교할 수 있습니다.

PDF 유형 검사에 실패하면 어디로 보내야 합니까?

암호화, 손상, 빈 페이지, 깨진 글꼴이 의심되면 격리 큐로 보내십시오. 복호화와 무결성 확인 뒤 다시 검사하고, 계속 실패하면 OCR 또는 사람 검수로 보냅니다. 이 파일들을 일반 실패와 섞으면 실제 데이터 품질 문제를 찾기 어려워집니다.

넷째 단계에서 운영 승인 기준을 만듭니다

프로그램이 결과를 반환하는지만 확인하면 부족합니다. 사람이 라벨링한 샘플을 만들고 다음 항목을 비교해야 합니다.

• PDF 유형이 실제 파일 상태와 맞는가
• 텍스트형 문서의 추출 결과가 검색 가능한가
• 혼합형 문서에서 OCR 대상 페이지가 빠지지 않았는가
• 표와 다단 문서의 읽기 순서가 유지되는가
• 암호화와 손상 파일이 정상 문서로 저장되지 않는가
• 실패한 작업을 원본 해시로 다시 실행할 수 있는가

운영 대시보드에는 전체 처리량보다 분류별 비율을 먼저 표시하십시오. 텍스트형 비율이 갑자기 낮아지거나 OCR 회귀율이 높아지면 입력 문서 구성 또는 라이브러리 변경을 의심할 수 있습니다. 함께 볼 항목은 유형별 처리 시간, OCR 대기 시간, 실패 원인, 수동 검수 비율, 재처리 횟수입니다.

프로젝트 저장소에는 공식 비교 자료도 포함되어 있지만, 그 수치는 특정 데이터셋과 특정 실행 환경에서 나온 결과입니다. 저장소에 공개된 비교는 200개 PDF와 특정 애플 실리콘 환경을 대상으로 하며, 버전과 실행 조건도 함께 제시합니다. 따라서 그 결과를 네 문서의 고정 성능으로 해석하지 말고, 동일한 샘플과 동일한 평가 방식으로 다시 측정해야 합니다. 공식 비교 결과를 확인하십시오.

업그레이드 때는 다음 순서를 지키십시오.

1. 현재 버전으로 기준 샘플을 실행합니다.
2. 새 버전으로 같은 파일을 실행합니다.
3. 유형 결과와 OCR 대상 페이지를 비교합니다.
4. 마크다운, 표, 페이지 경계를 비교합니다.
5. 차이가 허용 범위를 넘으면 배포를 멈춥니다.

최신 변경 사항은 공식 릴리스 기록에서 확인하십시오. 디버깅 로그가 필요하면 저장소의 디버깅 문서를 함께 검토해야 합니다.

확장 전에는 샘플링과 환경을 먼저 결정합니다

현재 환경이 단일 개발 노트북이라면 대량 OCR과 동시성 검증을 같은 장비에서 끝내기 어렵습니다. 특히 임시 이미지 파일, OCR 엔진, 결과 저장소를 함께 실행하면 개발 중에는 통과한 작업이 배치에서 지연될 수 있습니다.

다음 조건이면 먼저 샘플링하십시오.

• 아직 유형별 오류 원인을 모를 때
• 혼합형 문서의 페이지 병합 로직이 완성되지 않았을 때
• OCR 엔진과 언어 설정을 확정하지 않았을 때
• 사람 검수 기준이 정해지지 않았을 때

다음 조건을 모두 만족하면 확장을 검토할 수 있습니다.

• 기준 샘플의 분류 결과가 안정적일 때
• 실패 파일이 격리 큐로 분리될 때
• 유형별 처리 시간과 OCR 대기 시간이 기록될 때
• 새 버전 회귀 실행을 자동화했을 때
• 하류 RAG 또는 검색 시스템이 빈 결과를 감지할 때

원격 환경에서 파이썬 서비스와 배치 큐를 시험하려면 맥 미니 렌탈 한국 안내와 맥 지원 안내를 함께 확인할 수 있습니다. 다만 물리 장치 접근이나 장기간 고정 부하가 필요하다면 직접 서버를 운영하는 편이 맞을 수 있습니다.

현재 방식이 모든 PDF를 OCR로 보내는 구조라면 처리 대기와 임시 저장 공간 부담이 커지고, 텍스트형 문서의 원래 구조를 불필요하게 이미지 결과로 바꿀 수 있습니다. 반대로 단일 개발 장비에서만 처리하면 동시성, 임시 저장 공간, 재처리 큐를 검증하기 어렵습니다. 이런 경우에는 먼저 pdf-inspector를 앞단에 두고 작은 샘플로 분류와 회귀를 확인한 뒤, 필요한 기간만 Kvmkit의 원격 맥 환경에서 배치 처리와 납품 방식을 시험하는 편이 더 현실적입니다.

자주 묻는 질문