높은 정확도로 빠르게 PDF를 Markdown으로 변환하는 기술

 (github.com/VikParuchuri)
2P by GN⁺ | ★ favorite | 댓글 1개
  • Marker는 PDF뿐 아니라 이미지, PPTX, DOCX, XLSX, HTML, EPUB 문서를 Markdown, JSON, chunks, HTML로 빠르고 정확하게 변환하는 문서 지능 도구임
  • 표, 양식, 수식, 인라인 수학, 링크, 참조, 코드 블록을 포맷하고, 이미지 추출·저장과 머리말/꼬리말 같은 아티팩트 제거를 지원함
  • 정확도를 높이려면 --use_llm로 LLM을 함께 사용할 수 있으며, 기본값은 gemini-2.0-flash이고 Gemini, Ollama, Claude, OpenAI, Azure OpenAI 등을 선택 가능함
  • 벤치마크에서 Marker는 단일 PDF 페이지 기준 평균 2.83837초, 휴리스틱 점수 95.6709, LLM 점수 4.23916을 기록했고, H100 배치 모드에서는 25 pages/second 처리량을 예상함
  • Python 3.10+와 PyTorch가 필요하며, 코드는 GPL, 모델 가중치는 수정된 AI Pubs OpenRAIL-M 라이선스로 연구·개인 사용·$2M 미만 스타트업에는 무료 조건이 적용됨

Marker가 변환하는 문서와 출력

  • Marker는 문서를 Markdown, JSON, chunks, HTML로 변환함
  • 입력 형식은 PDF, 이미지, PPTX, DOCX, XLSX, HTML, EPUB를 포함하며 모든 언어 문서를 처리함
  • 문서 요소 처리 범위:
    • 표, 양식, 수식, 인라인 수학
    • 링크, 참조, 코드 블록
    • 이미지 추출과 저장
    • 머리말, 꼬리말, 기타 아티팩트 제거
  • 자체 포맷팅과 로직으로 확장할 수 있음
  • JSON 스키마를 주면 구조화 추출을 수행할 수 있으며 이 기능은 beta임
  • GPU, CPU, MPS에서 동작함

Datalab 관리형 플랫폼

  • Datalab 관리형 플랫폼은 최신 오픈소스 모델 Chandra를 실행함
  • Chandra는 Marker보다 높은 정확도를 제공한다고 소개되며, 기본값으로 데이터 보존이 없고 SOC 2 Type 2와 커스텀 BAA를 제공함
  • 고용량 워크로드용 배치 처리 서비스는 주당 200M+ 페이지를 처리한 적이 있음
  • 가입 시 $5 무료 크레딧을 제공하며, 공개 플레이그라운드도 제공함
  • 상업적 self-hosting에는 라이선스가 필요하며, 온프레미스 라이선스는 별도 문의 대상임

성능과 LLM 하이브리드 모드

  • Marker는 Llamaparse, Mathpix 같은 클라우드 서비스와 다른 오픈소스 도구 대비 우호적인 벤치마크 결과를 제시함
  • README의 전체 성능 결과는 단일 PDF 페이지를 직렬 실행한 기준임
  • 배치 모드에서는 더 빠르며, H100에서 25 pages/second 처리량이 예상됨
  • 최고 정확도를 위해 --use_llm 플래그로 LLM을 함께 사용할 수 있음
    • 페이지를 넘어가는 표 병합
    • 인라인 수학 처리
    • 표 포맷팅 개선
    • 양식에서 값 추출
  • LLM 하이브리드 모드는 Marker 단독 또는 Gemini Flash 단독보다 표 벤치마크 정확도가 높음

설치와 기본 사용법

  • Python 3.10+와 PyTorch가 필요함
  • PDF 중심 설치: 
    pip install marker-pdf
  • PDF 외 문서 형식을 처리하려면 추가 의존성을 설치함 
    pip install marker-pdf[full]
  • 단일 파일 변환: 
    marker_single /path/to/file.pdf
  • 폴더 단위 다중 파일 변환: 
    marker /path/to/input/folder
  • 여러 GPU에서 변환: 
    NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out
    • NUM_DEVICES는 사용할 GPU 수이며 2 이상이어야 함
    • NUM_WORKERS는 GPU당 병렬 프로세스 수임

주요 CLI 옵션

  • --page_range TEXT: 처리할 페이지 번호와 범위를 지정함
  • --output_format [markdown|json|html|chunks]: 출력 형식을 지정함
  • --output_dir PATH: 출력 파일 저장 디렉터리를 지정함
  • --paginate_output: 페이지 번호와 구분선을 넣어 출력함
  • --use_llm: LLM으로 정확도를 높임
  • --force_ocr: 전체 문서에 OCR을 강제 적용하며, 인라인 수학도 적절히 포맷함
  • --block_correction_prompt: LLM 모드에서 Marker 출력 보정용 프롬프트를 지정함
  • --strip_existing_ocr: 기존 OCR 텍스트를 제거하고 surya로 다시 OCR함
  • --redo_inline_math: --use_llm과 함께 인라인 수학 변환 품질을 높임
  • --disable_image_extraction: PDF에서 이미지를 추출하지 않음
  • --converter_cls: 기본 marker.converters.pdf.PdfConverter 또는 표 전용 marker.converters.table.TableConverter를 선택함
  • --llm_service: --use_llm 사용 시 LLM 서비스를 지정하며 기본값은 marker.services.gemini.GoogleGeminiService임
  • --workers: 동시 변환 워커 수를 지정함
    • 워커당 최대 5GB VRAM, 평균 3.5GB VRAM을 사용함

Python API와 내부 블록 조작

  • PdfConverter로 Python에서 직접 변환할 수 있음 
    from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

converter = PdfConverter(
    artifact_dict=create_model_dict(),
)
rendered = converter("FILEPATH")
text, _, images = text_from_rendered(rendered)
  • Markdown 출력의 rendered는 markdown, metadata, images 속성을 가짐
  • JSON 출력의 rendered는 children, block_type, metadata를 가짐
  • ConfigParser로 출력 형식, 프로세서, 렌더러, LLM 서비스 등을 구성할 수 있음
  • 문서는 페이지와 블록의 트리로 구성되며, 페이지는 다시 블록을 포함할 수 있음
  • contained_blocks를 사용해 양식 같은 특정 블록만 프로그램적으로 추출할 수 있음

변환기 종류

  • PdfConverter: 전체 PDF를 변환하는 기본 변환기임
  • TableConverter: 표만 추출하고 변환함
    • force_layout_block=Table을 지정하면 레이아웃 감지를 피하고 모든 페이지를 표로 가정함
    • output_format=json을 쓰면 셀 bounding box도 얻을 수 있음
  • OCRConverter: OCR만 실행함
    • --keep_chars를 설정하면 개별 문자와 bounding box를 유지함
  • ExtractionConverter: beta 상태의 구조화 추출 변환기임
    • 먼저 LLM 서비스 설정이 필요함
    • JSON 출력으로 추출값을 반환함
    • 이전 실행의 original_markdown을 existing_markdown로 넘기면 문서 재파싱을 건너뛸 수 있음

출력 형식

  • Markdown 출력:
    • 이미지 링크
    • 포맷된 표
    • $$로 감싼 LaTeX 수식
    • triple backticks 코드 블록
    • 각주용 superscript
  • HTML 출력:
    • img 태그 이미지
    • <math> 태그 수식
    • pre 태그 코드
  • JSON 출력:
    • 페이지를 리스트로 표현하고, 각 페이지는 내부 Marker 스키마의 블록임
    • id, block_type, html, polygon, children 키를 가짐
    • 자식 블록은 section_hierarchy, images를 추가로 가짐
    • 블록 구조는 트리 형태임
  • Chunks 출력:
    • JSON과 비슷하지만 모든 것을 단일 리스트로 평탄화함
    • 각 블록의 전체 HTML을 포함해 RAG용 청킹에 유연하게 쓸 수 있음
  • 모든 출력 형식은 metadata를 반환함
    • 계산된 PDF 목차인 table_of_contents
    • 페이지별 텍스트 추출 방식과 블록 수를 담은 page_stats

지원 LLM 서비스

  • --use_llm 사용 시 선택 가능한 서비스:
    • Gemini: 기본적으로 Gemini developer API를 사용하며 --gemini_api_key가 필요함
    • Google Vertex: --vertex_project_id가 필요하며 marker.services.vertex.GoogleVertexService를 지정함
    • Ollama: 로컬 모델을 사용하며 --ollama_base_url, --ollama_model을 설정함
    • Claude: --claude_api_key, --claude_model_name을 설정함
    • OpenAI: OpenAI 호환 엔드포인트를 지원하며 --openai_api_key, --openai_model, --openai_base_url을 설정함
    • Azure OpenAI: --azure_endpoint, --azure_api_key, --deployment_name을 설정함

내부 구조와 확장 포인트

  • Marker는 딥러닝 모델 파이프라인으로 동작함
    • 텍스트 추출, 필요 시 OCR 수행
    • 페이지 레이아웃 감지와 읽기 순서 탐지
    • 각 블록 정리와 포맷팅
    • 필요 시 LLM으로 품질 개선
    • 블록 결합과 전체 텍스트 후처리
  • OCR과 레이아웃 관련 단계는 surya를 사용함
  • 수식 관련 포맷팅에는 texify가 사용됨
  • 핵심 구성 요소:
    • Providers: PDF 같은 소스 파일에서 정보를 제공함
    • Builders: 초기 문서 블록을 만들고 텍스트를 채움
    • Processors: 표 포맷터처럼 특정 블록을 처리함
    • Renderers: 블록을 출력 형식으로 렌더링함
    • Schema: 모든 블록 타입의 클래스
    • Converters: 전체 end-to-end 파이프라인을 실행함
  • 처리 동작을 바꾸려면 processors를 재정의함
  • 새 출력 형식은 새 renderer를 작성해 추가함
  • 새 입력 형식은 새 provider를 작성해 추가함

API 서버와 배포

  • 간단한 FastAPI 서버를 실행할 수 있음 
    pip install -U uvicorn fastapi python-multipart
marker_server --port 8001
  • 서버는 localhost:8001에서 접근 가능하며, localhost:8001/docs에서 endpoint 옵션을 볼 수 있음
  • 이 API 서버는 견고한 API가 아니며 소규모 사용만 의도함
  • 더 견고한 변환 옵션이 필요하면 호스팅된 Datalab API를 사용할 수 있음
  • 배포 예시는 Modal을 통한 웹 엔드포인트 배포를 포함함

문제 해결

  • 정확도 문제가 있으면 --use_llm으로 LLM을 사용함
    • 이 경우 Gemini API 키를 GOOGLE_API_KEY로 설정해야 함
  • 깨진 텍스트가 보이면 force_ocr로 문서를 다시 OCR함
  • TORCH_DEVICE로 사용할 torch 디바이스를 강제 지정할 수 있음
  • 메모리 부족 오류가 나면 워커 수를 줄이거나 긴 PDF를 여러 파일로 나눌 수 있음
  • debug 옵션은 감지된 레이아웃과 텍스트가 포함된 페이지 이미지, bounding box 정보가 있는 JSON 파일을 저장함

벤치마크 결과

  • 전체 PDF 변환 벤치마크는 common crawl에서 단일 PDF 페이지를 추출해 만든 benchmark set을 사용함
  • 점수는 ground truth 텍스트 세그먼트와 정렬하는 휴리스틱, 그리고 LLM-as-judge 방식으로 계산함
  • 전체 PDF 변환 결과:
    • marker: 평균 시간 2.83837, 휴리스틱 95.6709, LLM 4.23916
    • llamaparse: 평균 시간 23.348, 휴리스틱 84.2442, LLM 3.97619
    • mathpix: 평균 시간 6.36223, 휴리스틱 86.4281, LLM 4.15626
    • docling: 평균 시간 3.69949, 휴리스틱 86.7073, LLM 3.70429
  • marker와 docling은 H100에서 실행됐고, llamaparse와 mathpix는 클라우드 서비스를 사용함
  • 긴 PDF 처리량 벤치마크는 Think Python을 사용함
    • marker: 페이지당 0.18초
    • 문서당 43.42초
    • VRAM 3.17GB
    • H100에서 22개 개별 프로세스를 실행할 수 있어 122 pages/second 처리량이 예상됨
  • 표 변환 벤치마크는 FinTabNet test split의 HTML 표현을 비교함
    • marker: 평균 점수 0.816, 총 99 tables
    • marker w/use_llm: 평균 점수 0.907, 총 99 tables
    • gemini: 평균 점수 0.829, 총 99 tables
  • FinTabNet과 레이아웃 모델의 감지 방식 차이 때문에 ground truth와 정렬할 수 없는 표는 필터링함

한계와 라이선스

  • PDF는 다루기 까다로운 형식이라 Marker가 항상 완벽하게 동작하지는 않음
  • 알려진 한계:
    • 중첩 표와 양식이 있는 매우 복잡한 레이아웃은 동작하지 않을 수 있음
    • 양식 렌더링이 잘 되지 않을 수 있음
  • --use_llm과 --force_ocr 플래그를 넘기면 이런 문제 대부분을 해결할 수 있음
  • 모델 가중치는 수정된 AI Pubs OpenRAIL-M 라이선스를 사용함
    • 연구, 개인 사용, funding/revenue가 $2M 미만인 스타트업에는 무료임
  • 코드는 GPL 라이선스임
  • 더 넓은 상업 라이선스나 GPL 요구사항 제거는 pricing page 대상임

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • repo 전반에서 Nougat과 비교하는 방식은 조금 헷갈림
    Nougat은 학술 문서용으로 특화 학습된 모델이고, Nougat이 최고의 OCR 모델이라고 주장된 적은 없다고 봄. 벤치마크에서도 arXiv 문서에서는 Nougat 정확도가 더 높다고 되어 있음. 또 marker가 Nougat보다 수식을 덜 변환한다고 하면서 속도 비교를 Nougat과 하는 것도, 학술 문서용 모델이라는 점 때문에 아쉬움
    수학이 들어간 PDF를 OCR하려면 Nougat은 꼭 써볼 만함. Python 패키지로 설치가 쉽고, 한 번의 명령으로 수식·텍스트·표 등을 .mmd 파일로 추출함. 개인 용도로는 속도도 괜찮아서, 4년 된 i5 노트북에서 CPU만으로 6쪽 문서를 변환하는 데 약 30초 걸렸음

    • 두 대상을 비교한다고 해서 기존 대상이 최고라고 홍보됐다는 뜻은 아님
      새 도구를 익숙한 대상과 나란히 놓고 보기 위한 방식일 뿐임. 말한 것처럼 Nougat은 설치와 실행이 쉬우니 비교 대상으로 삼는 게 자연스러움. 비교에 더 많은 라이브러리가 들어가면 당연히 더 좋고 유용할 것
    • RPG 룰북 PDF는 Nougat이 얼마나 잘 처리할지 궁금함
      RPG 책 일부를 Markdown으로 옮기는 데 도움이 되는 OCR 모델을 찾고 있음. 가능하면 굵게나 기울임 같은 강조도 그대로 옮겨지면 좋겠음
      텍스트, 숫자, 수학 기호 조합은 기술·학술 문서와 비슷해 보이지만, 이상한 서식, 여백의 텍스트 박스, 많은 도표가 자주 섞여 있음
    • 작성자임. 내 사용 사례는 과학 PDF 대량 변환이라서 Nougat이 가장 좋은 해법이었고, 그래서 기본 비교 대상으로 삼았음
      아래쪽에는 단순 텍스트 추출과도 비교해 두었음. Nougat은 훌륭한 모델이고 많은 PDF를 잘 변환하지만, 더 빠르고 더 일반화 가능한 것을 원했음
    • PDF 안의 표 형태인 재무제표 추출을 하고 싶은데, Nougat이 그런 용도에도 적합할까?

  • 이런 도구의 영향을 과소평가하면 안 됨. “읽기에는 좋지만 배포에는 나쁜” 형식에 갇힌 엄청난 지식을 풀어내는 일이기 때문임
    정말 기대됨. 파이프라인을 만들면 좋겠음: 모든 PDF → 전부 Markdown으로 변환 → 전부 archive.org에 보관

    • 보관 목적이라면 그 파이프라인은 적절하지 않아 보임. 더 나은 순서는 모든 PDF → 원본 보관 → Markdown 변환일 것
      이렇게 하면 버그가 고쳐지고 개선이 생길 때마다 변환을 다시 돌릴 수 있음. 보통 기록 보존에서는 원본 자료에 최대한 가까운 형태로 저장하는 것을 선호함. 이후의 모든 변환은 데이터 손실만 만들 수 있기 때문임
    • PDF는 사실 배포 형식으로 훌륭함
      최종 사용자가 보는 문서를 생성하는 데 쓴 원시 데이터를 원하는 형식으로 보이지 않게 포함할 수 있음. 예를 들어 PrinceXML로 HTML을 렌더링해 PDF를 만든다면, 모든 텍스트·그래프·차트 등을 생성하는 데 쓴 원본 JSON을 PDF 안에 넣을 수 있음. 물론 대부분은 실제로 그렇게 하지 않지만, 그건 명세의 잘못이 아님
    • 작성자임. 이 도구를 만든 이유 중 하나가 바로 이것임
      https://github.com/VikParuchuri/libgen_to_txt도 참고할 만함. 아직 marker와 통합하지는 않았고, 현재는 단순 텍스트 추출을 사용함
    • 이런 종류의 도구에는 수요가 엄청남. 특히 다양한 형태의 PDF 문서가 많은 대형 조직에서 관심이 클 수밖에 없음
      필요나 사용 사례의 일부만 다루더라도, 제대로 동작한다면 매우 유용할 것
    • 접근성 측면에서도 쓸모가 많음
      PDF 접근성을 제대로 맞추는 일은 엄청난 작업이고, 설령 맞춰도 사용자가 쓰는 PDF 뷰어가 필요한 표준을 지원하지 않을 가능성이 큼

  • 주말에 직접 써봐야겠음
    선택 가능한 텍스트가 없도록 OCR이 안 되어 있거나, 되어 있어도 품질이 좋지 않은 출처 불명의 RPG PDF 스캔본을 자주 손으로 옮겨 적음
    복사·붙여넣기 오류를 고치거나 OCR로 텍스트화한 뒤 오류를 고치는 것보다 그냥 직접 타이핑하는 게 말 그대로 더 빠를 때가 있음
    공식 PDF여도 서식이 자주 망가져서 단어 사이에 이중·삼중 공백이나 탭이 들어가곤 함. 제대로 쓸 수 있다면 시간을 정말 많이 아껴줄 듯함

    • 나도 이 사용 사례를 염두에 두고 있었음. 책 한 권으로 이미 시도해 봤지만 결과가 그리 좋지는 않았음
      표와 텍스트 박스가 많이 망가졌음. 표를 스크린샷으로 찍어 ChatGPT에 붙여 넣어 Markdown 표 변환을 시키면 꽤 좋은 결과가 나왔음. “행별로 읽어라. 열 머리글은 X, Y, Z다. X는 텍스트, Y는 숫자, Z는 단어다” 같은 식으로 조금 프롬프트를 주면 불규칙한 표도 처리할 수 있었음
    • RPG 관련 자료 중에는 물리 매체로 나온 적도 없고, 지식재산권상 고아가 된 자료가 정말 많아서 바로 그 생각이 들었음

  • 요즘 Tesseract OCR은 어느 정도 괜찮은가? 예전에 써봤을 때는 AWS, Azure, GCP의 온라인 OCR보다 한참 못했음

    • 최근 업데이트가 꽤 있었고, git에는 Tesseract 5가 의존성으로 언급되어 있음. 마지막으로 써봤을 때보다 꽤 나아졌을 가능성이 큼
      https://github.com/tesseract-ocr/tesseract/releases
      결국 사용 사례에 따라 다를 듯함. 이런 개인 작업에는 충분할 가능성이 높고, 사용자 정보나 신용카드 같은 것도 필요 없음
    • 생각보다 훌륭했고, 브라우저 내 성능도 인상적이었음
      다만 해상도에 매우 민감함. 이미지가 어느 크기 이하로 내려가면 사람이 보기에는 충분히 읽히는데도 Tesseract 출력은 엉망이 됐음
    • 전처리가 꽤 많이 필요함. GCP 솔루션만 써봤는데, 내 경험상 그쪽이 더 나았음
    • 꽤 최근에 써봤는데 아주 기본적인 이미지에서도 실패했음
      iOS Vision API도 시도했지만 역시 실패함. 테스트 케이스는 책 페이지를 선명하게 찍은 사진이었음

  • 작성자에게 질문: 왜 Markdown인가? 이 도구의 어려운 부분은 PDF를 높은 정확도로 파싱하는 것이지, 그 뒤에 어떤 형식으로 내보내는지는 아닌 것 같음
    그래서 사용자가 출력 형식을 선택할 수 있으면 좋겠음. 정확도 높은 PDF 파서가 있다면 EPUB 생성에 쓰고 싶음

    • 구조적 마크업을 최대한 보존하는 어떤 종류의 마크업은 필요함
      대학 출판부에서 전자책을 관리하는데, 변환을 기다리는 오래된 목록이 많고 그중 상당수는 옛 인쇄본의 페이지 스캔만 남아 있음. EPUB으로 제공하려면 장 구분, 제목, 표, 차트, 수식, 인용문 등이 어디 있는지 알아야 함. 외주 업체가 해줄 수는 있지만, 어떤 책들은 판매 수익보다 변환 비용이 더 큼. 일부라도 직접 할 수 있으면 좋겠음
    • 중간 형식은 선택적으로 다른 형식으로 변환할 수 있는 일반 텍스트에 가까워야 한다는 데 동의함
      다만 여기서는 Markdown이 중간 형식으로 쓰이는 것 같음. 일반 텍스트에 가깝지만 단순한 레이아웃 정보는 보존할 수 있음. 실제로는 Markdown 출력을 받아 원하는 최종 출력 형식으로 변환하는 도구에 연결해서 쓸 것 같음
    • Markdown을 고른 이유는 수식, 표, 굵게/기울임 정보, 제목을 보존하고 싶었기 때문임
      수식은 $/$$로 감쌀 수 있음. EPUB 출력은 아직 살펴보지 않았지만, 이런 요구 때문에 일반 텍스트는 제외됐음

  • 아직 좋은 해법을 못 찾은 특이한 용도가 있음: 건설 문서 읽기임
    도면은 항상 PDF로 오는데, DXF(AutoCAD) 파일을 파싱할 때 훨씬 잘 됐음. 하지만 내가 현장 총괄 시공자여도 건축가에게 DXF를 보내 달라고 받는 게 항상 쉽지는 않음

  • 긴 글은 주로 전자책 리더로 읽음
    PDF, 특히 다단 레이아웃은 Amazon Kindle이나 Pocketbook의 기본 기능으로는 악몽에 가까움. 이 도구가 읽기 경험을 꽤 개선해 줄 것 같음

  • 좋은 작업임
    Nougat 출력에서 보이는 환각은 어디서 오는 건지 궁금했음. Think Python 예제의 Nougat 출력을 훑어보면 무슨 말인지 알 수 있음
    다시 보니 LLM을 거친다고 되어 있어서, 환각은 예상 가능한 일이었음

    • 이런 도구는 텍스트나 서식의 환각률이 꼼꼼한 독자가 문서를 반복해서 읽을 때의 실수율보다 낮아질 때까지는 위험하다고 봄
      그 수준은 거의 0에 가깝고, 용도에 따라서는 실제로 0이어야 할 수도 있음. 정확한 문서 내용이 중요하지 않은 경우라면 대체로 괜찮겠지만, 누구에게도 현재나 미래에 중요하지 않으면서도 PDF보다 접근성이 높아야 하는 문서가 대량으로 존재하는 경우는 흔치 않을 것 같음

  • OneNote에서 내 노트를 옮겨오는 데 도움이 될 만한 도구처럼 보임

  • 꽤 흥미로움. repo에 변환 전후 예시를 몇 개 추가하면 좋을 듯함
    어떤 종류의 PDF에 맞춰 조정하고 있는지 궁금함. 손글씨 주석은 어떻게 처리하나?

답변달기