문서를 텍스트로 바꾸는 일은 시작일 뿐입니다. PaddleOCR 3.x는 공식 문서에서 PDF와 이미지를 글자, 표, 문서 구조가 담긴 결과로 바꾸는 기능을 안내합니다. 다만 실제 업무에 쓰기 전에는 설치한 버전과 문서의 버전이 맞는지, 표와 읽는 순서가 유지되는지, 결과를 누가 원본과 대조할지를 따로 정해야 합니다. 이 글은 공식 저장소 문서와 PyPI 배포 정보(2026년 10월 9일 기준)를 바탕으로, PDF를 넣기 전에 점검할 순서를 정리했습니다.
이 글에서 제가 직접 PDF를 돌려 측정한 수치는 없습니다. 인식률이나 처리 시간 같은 숫자는 적지 않았고, 문서에 적힌 동작과 명령어만 옮겼습니다. 사용자 환경에서 달라질 수 있는 부분은 '가정'이라고 따로 표시했습니다.
어떤 도구인가
PaddleOCR은 PaddlePaddle 기반의 공개 OCR 프로젝트입니다. 저장소 소개 문서(README)에는 크게 세 갈래가 나옵니다. 첫째는 글자만 읽는 PP-OCR 계열이고, 현재 문서의 명령어 예시는 PP-OCRv6를 기준으로 합니다. 둘째는 복잡한 PDF와 이미지를 Markdown이나 JSON으로 바꾸는 PP-StructureV3입니다. 셋째는 문서 파싱용 시각-언어 모델인 PaddleOCR-VL 시리즈입니다. README는 PP-StructureV3가 PaddleOCR-VL 계열과 달리 표 셀 좌표, 글자 좌표 같은 세밀한 좌표 정보를 제공한다고 설명합니다.
이름이 같아도 세대가 다르면 코드가 다릅니다. 예전 2.x 예제의 함수와 옵션을 3.x에 그대로 붙이면 오류가 나거나, 오류 없이 다른 방식으로 동작할 수 있습니다. 그래서 첫 번째 기준은 '어느 버전의 문서를 보고 있는가'입니다.
문서 추출 전 확인할 3가지
- 버전 호환: 설치한 paddleocr 버전과 읽고 있는 문서가 같은 세대인지 확인합니다. 다른 세대의 인터페이스를 섞으면 결과를 비교하기도 어렵습니다.
- 표·레이아웃: 글자가 맞아도 열과 행, 머리글, 줄바꿈이 달라질 수 있습니다. 표는 텍스트 한 덩어리로만 보지 않습니다.
- 결과 검수: 실제 원본 페이지와 대조해 누락·순서·문단 경계를 확인합니다. 자동 추출 결과는 초안으로 쓰고, 그대로 최종 데이터로 넘기지 않습니다.
설치와 버전: 2026년 10월 기준으로 확인한 것
PyPI의 paddleocr 페이지 정보에 따르면 최신 배포판은 3.7.0이고, 2026년 6월 11일에 올라왔으며, Python 3.8 이상을 요구합니다. 다만 공식 설치 문서에는 문서 파싱(doc-parser), 정보 추출(ie), 문서 번역(trans), 전체 기능(all) 같은 선택 묶음이 Python 3.9 이상을 요구한다고 적혀 있습니다. 표와 레이아웃을 다루는 PP-StructureV3는 doc-parser 묶음에 들어가므로, Python 3.8을 쓰고 계시다면 먼저 버전부터 올려야 합니다.
설치는 두 단계입니다. 먼저 추론 엔진을 설치하고, 그다음 paddleocr를 설치합니다. 현재 빠른 시작 문서의 CPU 예시는 다음과 같습니다.
python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install "paddleocr[all]"문서는 PaddlePaddle로 추론할 때 PaddleOCR 3.x가 PaddlePaddle 3.0 이상에 의존한다고 밝힙니다. 또 설치 문서에는 PaddleOCR 3.5부터 추론 엔진을 PaddlePaddle과 Transformers 중에서 고르는 통합 설정을 쓴다고 나옵니다. 그래서 현재 명령어 예시에는 --engine paddle 또는 --engine transformers가 붙어 있습니다. 예전 블로그 글이나 영상의 명령어에는 이 옵션이 없을 수 있으니, 같은 결과가 나오지 않을 때는 먼저 이 부분을 의심해 보시기 바랍니다. GPU를 쓰려면 CUDA 버전에 맞는 별도 패키지가 필요하다고 문서가 안내하므로, 해당 환경은 공식 설치 문서를 따라야 합니다.
| 확인 항목 | 공식 문서에서 확인한 내용 | 제가 직접 해 본 것 |
|---|---|---|
| paddleocr 최신판 | PyPI 기준 3.7.0, Python 3.8 이상 | 없음(PyPI 정보만 확인) |
| 선택 묶음 요구 사항 | doc-parser, ie, trans, all은 Python 3.9 이상 | 없음(설치 문서만 확인) |
| PaddlePaddle 의존 | PaddleOCR 3.x는 PaddlePaddle 3.0 이상 필요 | 없음 |
| 추론 엔진 옵션 | 3.5부터 paddle과 transformers 중 선택 | 없음 |
PDF를 넣는 법: 명령어와 파이썬 코드
글자 읽기만 필요하다면 일반 OCR 명령을, 표와 구조까지 필요하다면 PP-StructureV3 명령을 씁니다. 공식 빠른 시작 문서의 형태는 다음과 같습니다.
paddleocr ocr -i ./input.pdf --engine paddle
paddleocr pp_structurev3 -i ./input.pdf --engine paddle위 두 줄은 문서의 이미지 예시에서 입력 파일만 PDF 경로로 바꾼 것입니다. 공식 문서의 입력 설명에는 이미지 파일 또는 PDF 파일의 로컬 경로, URL, 폴더 경로가 가능하다고 나옵니다. 단 한 가지 제한이 중요합니다. 폴더를 지정할 때 그 안의 PDF는 처리되지 않으며, PDF는 정확한 파일 경로로 지정해야 합니다. PDF를 여러 개 처리하려면 파일마다 반복 호출하는 방식으로 짜야 합니다.
파이썬 코드에서는 결과가 쪽마다 하나씩 나옵니다. 일반 OCR 결과 항목에는 page_index가 있어서, 입력이 PDF일 때 몇 번째 쪽인지 알려 줍니다. 쪽 번호가 필요하면 이 값을 쓰면 됩니다. PP-StructureV3 문서에는 PDF의 각 쪽이 따로 Markdown 파일로 저장되고, 전체를 한 파일로 합치려면 pipeline.concatenate_markdown_pages를 쓰라는 예제가 있습니다. 저장은 save_to_json, save_to_markdown 메서드로 하며, JSON 결과의 배열 값은 저장할 때 리스트로 바뀝니다.
문서 방향 분류(use_doc_orientation_classify), 문서 펼치기(use_doc_unwarping), 글줄 방향 분류(use_textline_orientation) 옵션도 있습니다. 공식 예제는 이 세 옵션을 모두 False로 두고 시작합니다. 스캔이 기울어졌거나 휜 문서라면 켜 볼 만하지만, 켜면 처리 단계가 늘어나는 것은 분명하므로 어느 쪽이 더 나은지는 가정이 아니라 사용자의 샘플로 비교해야 합니다.
PDF 유형별 점검표
PDF라고 해서 모두 같은 방식으로 다루면 안 됩니다. 아래 표는 문서에서 확인한 동작과 일반적인 PDF의 성질을 바탕으로, 시작 전에 무엇을 먼저 볼지 정리한 것입니다. '가정'이라고 적은 칸은 제가 공식 문서에서 확인한 사실이 아니라 일반적으로 예상되는 경우입니다.
| PDF 유형 | 먼저 볼 것 | 권장 시작점 | 검수할 항목 |
|---|---|---|---|
| 이미 글자가 선택되는 PDF(가정: 한글 등에서 내보낸 파일) | PDF 안에 글자 정보가 이미 있는지 확인 | PDF 안의 글자를 먼저 꺼내 보고, 모자란 부분에만 OCR 사용 | 줄바꿈, 하이픈, 머리글·바닥글 섞임 |
| 스캔 이미지 PDF | 해상도, 기울어짐, 그림자 | 일반 OCR로 시작하고 기울어진 쪽은 방향 옵션 비교 | 숫자, 고유명사, 흐린 글자 |
| 표가 많은 PDF(청구서, 명세서) | 표 선이 있는지, 셀이 병합되었는지 | pp_structurev3로 JSON과 Markdown 동시 저장 | 행·열 개수, 합계 검산, 병합 셀 |
| 두 단 논문·보고서 | 읽는 순서 | 구조 분석 결과의 블록 순서 확인 | 단 사이 문장 끊김, 각주 위치 |
| 수식이 많은 PDF | 수식 인식 옵션 사용 여부 | 구조 분석에서 수식 인식을 켠 상태와 끈 상태 비교 | 기호, 첨자, 분수 |
| 도장·서명이 있는 PDF | 인식 대상이 글자인지 도장인지 | 구조 분석의 도장 인식 설정 확인 | 겹친 글자, 가려진 숫자 |
| 한 폴더에 여러 PDF | 폴더 지정은 PDF에 안 통함 | 파일마다 반복 호출하는 스크립트 | 파일별 결과 이름 겹침 |
이 표에서 가장 먼저 쓸모를 보는 항목은 첫 줄입니다. 글자 정보가 이미 들어 있는 PDF를 이미지로 바꿔 다시 OCR하면 오히려 오타가 생길 수 있습니다. 이 부분은 PaddleOCR의 문서에서 확인한 사실이 아니라 일반적인 OCR 작업의 경험칙이므로 가정으로 둡니다. 작은 샘플 몇 쪽으로 두 방식을 비교해 보는 것이 가장 확실합니다.
표와 레이아웃을 따로 봐야 하는 이유
글자 하나하나를 읽는 정확도와, 표가 표로 복원되는 정확도는 다른 문제입니다. 일반 OCR 결과는 글줄의 좌표와 글자 목록이 중심이고, PP-StructureV3는 레이아웃 영역(본문, 제목, 이미지, 표 등)을 먼저 나눈 뒤 영역별로 처리합니다. 그래서 같은 쪽이라도 어느 명령을 쓰느냐에 따라 결과의 모양이 달라집니다.
점검은 세 단계면 충분합니다. 첫째, 원본 표의 행 수와 열 수를 세어 결과와 비교합니다. 둘째, 합계나 소계가 있다면 숫자를 다시 더해 봅니다. 셋째, 병합된 셀이나 줄바꿈이 있는 셀이 한 칸으로 합쳐지거나 두 칸으로 갈라지지 않았는지 확인합니다. 한 칸에 숫자가 두 개 들어 있는 경우가 가장 위험합니다. 눈으로는 그럴듯해 보이지만 나중에 엑셀로 옮길 때 열이 어긋납니다.
결과를 검수하는 방법
- 숫자와 고유명사만 뽑아 원본과 대조합니다. 가장 자주 틀리고 영향도 큽니다.
- 표는 행·열 개수를 세고 합계가 있으면 검산합니다.
- 페이지 순서와 읽는 순서가 맞는지 확인합니다. 두 단 문서는 왼쪽 단과 오른쪽 단이 섞이기 쉽습니다.
- 인식하지 못한 영역이 표시되는지 확인합니다. 조용히 넘어가는 도구와 흐름은 위험합니다.
- 결과 JSON에 쪽 번호(
page_index)가 남아 있는지 보고, 틀린 항목을 원본의 몇 쪽에서 찾을지 바로 알 수 있게 합니다.
OCR 도구를 서로 비교할 때는 언어 지원, 레이아웃 분석 범위, 실행 환경(내 컴퓨터에서 도는지, 외부 호출이 필요한지), 쪽당 처리 시간과 메모리를 같은 샘플로 비교해야 합니다. 한국어는 영어와 인식 특성이 다르므로 한글 표본을 반드시 넣어 보셔야 합니다. 공식 README는 PP-OCRv6가 한 모델로 50개 언어(중국어, 영어, 일본어와 라틴 문자 46개 언어)를 지원한다고 소개합니다. 한국어가 이 목록에 있는지는 제가 이번에 확인하지 못했으므로, 한글 문서를 다룬다면 언어 지원 문서를 따로 열어 보시기 바랍니다.
다른 OCR 서비스의 공식 문서와 견줄 때 보는 항목
PaddleOCR 하나만 보고 결정하기보다 다른 도구의 공식 설명과 같은 항목으로 견주면 판단이 쉬워집니다. 마이크로소프트의 Azure Document Intelligence 레이아웃 모델 문서는 광학 문자 인식(OCR)과 딥러닝 모델을 결합해 글자, 표, 선택 표시, 문서 구조를 추출한다고 소개합니다. 입력으로는 PDF와 JPEG·PNG·BMP·TIFF·HEIF 이미지, 워드·엑셀·파워포인트·HTML 문서를 받습니다. PDF와 TIFF는 최대 2,000쪽까지 처리하며, 파일 크기는 유료(S0) 등급 500MB, 무료(F0) 등급 4MB입니다. 무료 등급에서는 PDF의 처음 두 쪽만 처리되고, 암호가 걸린 PDF는 제출 전에 잠금을 풀어야 합니다. 결과에는 쪽 목록과 단락 역할(제목, 소제목, 각주, 머리글, 바닥글, 쪽 번호)이 함께 들어갑니다.
| 견줄 항목 | Azure Document Intelligence 공식 문서 | PaddleOCR에서 확인할 곳 |
|---|---|---|
| 입력 형식 | PDF·이미지·Office·HTML | 이미지와 PDF의 경로·URL·폴더(폴더 안 PDF는 처리 안 됨) |
| 분량 제한 | PDF·TIFF 2,000쪽, 등급별 파일 크기 제한 | 내 기기의 메모리와 처리 시간으로 직접 확인 |
| 암호 PDF | 잠금 해제 후 제출 | 위 문서에서는 별도 안내를 확인하지 못함 |
| 결과 구조 | 쪽, 단락 역할, 표를 구조화한 결과 | JSON·Markdown 저장, 쪽 번호(page_index) |
| 실행 위치 | 마이크로소프트 클라우드 서비스 | 내 컴퓨터에 설치해 실행 |
위 비교는 2026년 10월 18일 기준 마이크로소프트 공식 문서의 기재 내용입니다. 클라우드 서비스는 요금과 등급에 따라 제한이 달라지고 문서는 바뀔 수 있으므로, 실제로 쓰기 전에 현재 문서를 확인하세요. 민감한 문서는 외부 서비스로 전송되는지를 먼저 따져야 한다는 앞의 기준은 두 방식 모두에 똑같이 적용됩니다.
막히는 지점과 해결
| 증상 | 가능한 원인 | 확인 방법 |
|---|---|---|
| 옵션 이름이 없다는 오류 | 예전 글의 명령어나 다른 버전의 옵션 | pip show paddleocr로 버전을 보고 같은 버전의 공식 문서와 대조 |
| 표 분석 명령이 설치 단계에서 실패 | Python 3.8에서 선택 묶음을 설치(3.9 이상 필요) | Python 버전 확인 후 가상환경을 새로 만들어 재설치 |
| 폴더를 지정했는데 PDF 결과가 없음 | 폴더 안의 PDF는 지원하지 않음 | PDF 파일 경로를 하나씩 넘기는 반복문으로 변경 |
| 쪽마다 Markdown이 따로 생김 | PDF는 쪽 단위로 처리되는 것이 기본 | concatenate_markdown_pages로 합치기 |
| Transformers 엔진에서 일부 기능이 안 됨 | 문서가 일부 모델은 아직 지원 중이라고 안내함 | 빠른 시작 문서의 Transformers 예시 주석(수식 인식 끄기 등)을 확인 |
| 결과는 나왔는데 표가 어긋남 | 병합 셀, 표 선 없음, 해상도 낮음 | 해당 쪽만 이미지로 떼어 pp_structurev3로 다시 돌려 비교 |
다섯째 줄은 공식 빠른 시작 문서에 있는 내용입니다. PP-StructureV3를 Transformers 엔진으로 돌릴 때 일부 모델이 아직 지원 중이라 수식 인식을 끄고 무선 표 구조 인식 모델을 바꿔야 한다는 주석이 예시에 붙어 있습니다. 엔진을 바꾸면 같은 PDF라도 결과가 달라질 수 있으니, 엔진을 비교할 때는 한 번에 하나만 바꾸세요.
누구에게 맞나
스캔 문서, PDF, 영수증처럼 텍스트를 다시 활용해야 하는 작업에 맞습니다. 특히 같은 서식의 문서가 반복해서 들어오는 업무라면 한 번 점검표를 만들어 두고 계속 쓸 수 있습니다. 반대로 오류를 전혀 검토할 수 없는 업무, 예를 들어 금액이 곧바로 결제나 정산으로 이어지는 경우라면 자동 추출을 최종 값으로 쓰지 않는 편이 안전합니다. 개인 정보나 계약서처럼 민감한 문서는 외부 서비스로 보내는 방식인지, 내 컴퓨터에서 도는 방식인지를 먼저 구분하셔야 합니다. 공식 저장소는 내 컴퓨터에 설치해서 쓰는 방식을 안내하지만, 같은 프로젝트가 웹 서비스도 운영하므로 어느 쪽을 쓰는지 확인하시기 바랍니다.
시작 전에 정할 네 가지
| 항목 | 시작 전 결정 |
|---|---|
| 입력 | 공개해도 되는 샘플 3~5쪽으로 시작하고, 민감한 문서는 범위를 줄입니다. |
| 검토 | 숫자·표·고유명사는 원본을 읽을 사람이 확인합니다. |
| 기록 | 사용한 paddleocr 버전, 명령어, 옵션을 한 줄이라도 남깁니다. |
| 되돌리기 | 원본 PDF와 추출 결과를 따로 보관해 틀린 부분을 교정할 수 있게 합니다. |
기록은 복잡할 필요가 없습니다. 날짜, 버전, 명령어, 기대와 달랐던 한 가지를 남기면 업데이트 뒤 결과가 달라졌을 때 원인이 버전인지 옵션인지 입력 PDF인지 가려내기가 쉽습니다.
업데이트
이 글은 2026년 10월 9일에 PaddleOCR 공식 저장소의 README, 빠른 시작, 설치 문서, 일반 OCR·PP-StructureV3 사용 문서와 PyPI 배포 정보(2026년 10월 9일 기준)와 마이크로소프트 Document Intelligence 공식 문서(2026년 10월 18일 기준)를 바탕으로 갱신했습니다. 당시 PyPI 최신판은 3.7.0이었습니다. 버전과 명령어 옵션은 계속 바뀌므로, 실행 전에는 설치한 버전에 맞는 최신 안내를 우선하시기 바랍니다.
확인 자료
- Microsoft Learn: Document Intelligence 레이아웃 모델 (확인: 2026-10-18)
- PaddleOCR 공식 저장소(README)
- PaddleOCR 빠른 시작 문서
- PaddleOCR 3.x 설치 문서
- PP-StructureV3 사용 문서
- PyPI paddleocr 배포 페이지
확인 날짜: 2026-10-09