KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

marker

★ 38,787 Open GitHub ↗

높은 정확도로 PDF를 Markdown + JSON으로 빠르게 변환하세요

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Datalab Logo](data/images/datalab-logo.png)

# Datalab

**문서 인텔리전스를 위한 최고 수준(State of the Art)의 모델**

[![Code License](https://img.shields.io/badge/Code%20License-Apache%202.0-green.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Model License](https://img.shields.io/badge/Model%20License-OpenRAIL--M-blue.svg)](https://www.datalab.to/pricing)
[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/KuZwXNGnfH)

[![Homepage](https://img.shields.io/badge/Homepage-datalab.to-blue)](https://www.datalab.to)
[![Docs](https://img.shields.io/badge/Docs-Read%20the%20docs-blue)](https://documentation.datalab.to)
[![Public Playground](https://img.shields.io/badge/Playground-Try%20it-orange)](https://www.datalab.to/playground)

---

# Marker
Marker는 문서를 빠르고 정확하게 마크다운, JSON, 청크(chunk), HTML로 변환합니다.
- 모든 언어의 PDF, 이미지, PPTX, DOCX, XLSX, HTML, EPUB 파일 변환 지원
- 표, 서식, 수식, 인라인 수식, 링크, 참고 문헌, 코드 블록 포맷팅
- 이미지 추출 및 저장
- 머리글/바닥글 및 기타 불필요한 요소 제거
- 사용자 정의 포맷팅 및 로직으로 확장 가능
- LLM(및 사용자 정의 프롬프트)을 활용한 선택적 정확도 향상
- GPU, CPU, 또는 MPS 환경 지원

## Datalab의 관리형 플랫폼 이용하기
당사의 관리형 플랫폼은 최신 오픈소스 모델인 [Chandra](https://github.com/datalab-to/chandra)의 버전을 실행합니다. Marker보다 더 높은 정확도를 제공하며, 기본적으로 데이터가 보존되지 않고(zero data retention), SOC 2 Type 2 인증 및 맞춤형 BAA를 지원합니다.
대용량 워크로드 처리가 필요한 경우, 주당 10억 페이지 이상을 처리해 온 일괄 처리(batch processing) 서비스를 제공합니다. 인프라는 당사가 관리하므로 워크로드가 제 시간에 완료됩니다.
\*\*$5 무료 크레딧\*\*으로 시작해보세요 — [회원가입](https://www.datalab.to/?utm\_source=gh-marker).

## 성능
![](data/images/olmocr_bench.png)
Marker는 수식, 표, 다단 레이아웃, 스캔 문서, 까다로운 예외 케이스들을 포함하는 1,403개의 PDF로 구성된 서드파티 벤치마크인 [olmocr-bench](https://github.com/allenai/olmocr/tree/main/olmocr/bench)를 통해 측정됩니다. 균형(balanced) 모드는 전체 \*\*76.0%\*\*(디지털 생성 PDF의 경우 \*\*83.5%\*\*)의 점수를 기록하여 MinerU와 docling을 앞서고 훨씬 더 큰 VLM의 범위 내에 있으며, 빠른(fast) 모드는 레이아웃 및 텍스트 레이어 경로를 훨씬 저렴한 비용으로 실행합니다(OCR 없음 모드는 더욱 빠르게 실행됨). 점수는 olmocr-bench 전체 점수(8개 카테고리의 매크로 평균)입니다.
![](data/images/olmocr_digital.png)
전체 카테고리별 점수, 경쟁 비교, 자체 벤치마크 실행 방법에 대한 지침은 [아래](#benchmarks)를 참조하세요.

## 하이브리드 모드
최고의 정확도를 얻으려면 `--use\_llm` 플래그를 전달하여 marker와 함께 LLM을 사용하세요. 이를 통해 페이지 간 표 병합, 인라인 수식 처리, 표의 올바른 포맷팅, 양식에서 값 추출 등의 작업을 수행할 수 있습니다. Gemini, Claude, OpenAI 호환 모델, Azure, Vertex, OpenRouter 또는 Ollama 모델과 함께 작동합니다. 기본적으로 `gemini-3.5-flash`를 사용합니다. 자세한 내용은 [아래](#llm-services)를 참조하세요.

## 예제
| PDF | 파일 형식 | 마크다운 | JSON |
|-----|-----------|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| [Think Python](https://greenteapress.com/thinkpython/thinkpython.pdf) | 교과서 | [보기](https://github.com/VikParuchuri/marker/blob/master/data/examples/markdown/thinkpython/thinkpython.md) | [보기](https://github.com/VikParuchuri/marker/blob/master/data/examples/json/thinkpython.json) |
| [Switch Transformers](https://arxiv.org/pdf/2101.03961.pdf) | arXiv 논문 | [보기](https://github.com/VikParuchuri/marker/blob/master/data/examples/markdown/switch\_transformers/switch\_trans.md) | [보기](https://github.com/VikParuchuri/marker/blob/master/data/examples/json/switch\_trans.json) |
| [Multi-column CNN](https://arxiv.org/pdf/1804.07821.pdf) | arXiv 논문 | [보기](https://github.com/VikParuchuri/marker/blob/master/data/examples/markdown/multicolcnn/multicolcnn.md) | [보기](https://github.com/VikParuchuri/marker/blob/master/data/examples/json/multicolcnn.json) |

# 상업적 이용
코드는 \*\*Apache 2.0\*\* 라이선스로 배포되며 상업적 용도를 포함하여 자유롭게 사용할 수 있습니다. 모델 가중치는 수정된 AI Pubs Open Rail-M 라이선스를 사용합니다(연구, 개인 사용, 5백만 달러 미만의 투자/매출을 가진 스타트업은 무료). 이를 초과하여 모델 가중치를 상업적으로 이용하려면 [여기](https://www.datalab.to/pricing?utm\_source=gh-marker)의 요금 페이지를 방문하세요.

# 커뮤니티
향후 개발 방향에 대해서는 [Discord](https://discord.gg//KuZwXNGnfH)에서 논의합니다.

# 설치
Python 3.10 이상과 [PyTorch](https://pytorch.org/get-started/locally/)가 필요합니다.
설치 명령어:
```shell
pip install marker-pdf
```
PDF 이외의 문서에 marker를 사용하려면 다음 명령어로 추가 종속성을 설치해야 합니다.
```shell
pip install marker-pdf[full]
```

## 추론 백엔드 사전 요구 사항
Surya는 최초 사용 시 서버를 자동으로 실행하며, `vllm`(NVIDIA GPU) 또는 `llama.cpp`(CPU / Apple Silicon)가 필요합니다.
- \*\*NVIDIA GPU:\*\* [Docker](https://docs.docker.com/get-docker/) 및 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
- \*\*CPU / Apple Silicon:\*\* llama.cpp의 `llama-server` 바이너리:
```shell
brew install llama.cpp # macOS
# 또는 https://github.com/ggml-org/llama.cpp/releases 에서 릴리즈 다운로드
```

# 사용법
먼저 몇 가지 설정입니다:
- \*\*모드\*\* (`--mode balanced|fast`; 장치에 따라 기본값 설정 — GPU에서는 `balanced`, CPU/MPS에서는 `fast`):
- `balanced` (\*\*GPU\*\*에서 가장 좋음)는 레이아웃에 surya VLM을 사용하고, 인라인 수식을 OCR 처리하며, 임베디드 텍스트에 오류가 있는 경우 \*\*전체 페이지\*\*를 다시 OCR 처리합니다 — 최고 품질.
- `fast` (\*\*CPU\*\*에 최적화됨)는 경량 rf-detr 레이아웃 감지기를 사용하고, pdftext로 텍스트를 추출하며, VLM 사용을 최소화합니다: 수식, 손상되거나 빈 개별 블록의 정밀한 블록 수준 복구, 그리고 스캔되었거나 대부분 손상된 페이지만 대상으로 하는 단일 전체 페이지 패스. 수식이 없는 깨끗한 디지털 문서는 VLM 서버를 전혀 시작하지 않습니다.
- 표는 두 모드 모두 PDF 텍스트 레이어에서 재구성됩니다(스캔된 표는 전체 페이지 OCR에서 가져옴). 신뢰도가 낮은 재구성은 VLM으로 대체되며, balanced 모드에서 더 엄격한 기준이 적용됩니다.
- `--disable\_ocr`은 어떤 모드에서든 \*\*모든\*\* VLM 호출(수식 포함)을 끕니다 — 순수 텍스트 레이어 추출.
- Marker는 로컬 추론 서버(두 모드 모두에서 OCR용으로 사용되며, balanced 모드의 경우 레이아웃용으로도 사용됨)를 통해 단일 surya VLM을 거쳐 레이아웃, OCR 및 표 인식을 실행합니다. 서버는 최초 사용 시 자동으로 실행됩니다 - NVIDIA GPU에서는 vLLM (docker), 그 외 환경에서는 llama.cpp. `SURYA\_INFERENCE\_URL=http://host:port/v1`을 사용하여 이미 실행 중인 서버를 지정할 수도 있습니다.
- 유용한 서버 설정 (모든 surya 환경 변수): `SURYA\_INFERENCE\_BACKEND` (`vllm` 또는 `llamacpp`), `SURYA\_INFERENCE\_PARALLEL` (동시 요청 — 기본적으로 서버 용량에 맞게 자동 조절됨: vllm의 경우 GPU의 `max\_num\_seqs`, llama.cpp의 경우 보수적인 슬롯 수; 오버라이드하려는 경우에만 정수 설정), `SURYA\_INFERENCE\_KEEP\_ALIVE` (호출 사이에 서버 유지), `VLLM\_GPUS` (서버용 GPU 인덱스).
- 디지털 PDF를 포함하여 일부 PDF에는 잘못된 텍스트가 포함되어 있습니다. 모든 페이지에 OCR을 강제 적용하려면 `--force\_ocr`을 설정하고, 모든 디지털 텍스트를 유지하고 기존 OCR 텍스트를 제거하려면 `strip\_existing\_ocr`을 설정하세요.
- 인라인 수식은 balanced 모드에서 자동으로 LaTeX로 변환됩니다(`ocr\_inline\_math`); fast 모드에서는 동일한 결과를 얻으려면 `--force\_ocr` 또는 `--ocr\_inline\_math`를 설정하세요.

## 인터랙티브 앱
기본적인 옵션으로 marker를 대화형으로 시도해 볼 수 있는 streamlit 앱이 포함되어 있습니다. 다음 명령어로 실행하세요:
```shell
pip install -U streamlit streamlit-ace
marker\_gui
```

## 단일 파일 변환
```shell
marker\_single /path/to/file.pdf
```
PDF 또는 이미지를 전달할 수 있습니다.
옵션:
- `--mode [balanced|fast]`: 변환 모드 (위 참조). 장치별 기본값: GPU에서는 `balanced`, CPU/MPS에서는 `fast`.
- `--disable\_ocr`: VLM을 절대 호출하지 않음 - 순수 텍스트 레이어 추출 (수식 및 스캔된 페이지는 건너뜁니다).
- `--page\_range TEXT`: 처리할 페이지를 지정합니다. 쉼표로 구분된 페이지 번호 및 범위를 허용합니다. 예: `--page\_range "0,5-10,20"`은 0페이지, 5~10페이지, 20페이지를 처리합니다.
- `--output\_format [markdown|json|html|chunks]`: 출력 결과의 형식을 지정합니다.
- `--output\_dir PATH`: 출력 파일이 저장될 디렉토리입니다. settings.OUTPUT\_DIR에 지정된 값으로 기본 설정됩니다.
- `--paginate\_output`: `\n\n{PAGE\_NUMBER}` 뒤에 `-` \* 48, 그 후 `\n\n`을 사용하여 출력을 페이지별로 나눕니다.
- `--use\_llm`: LLM을 사용하여 정확도를 향상시킵니다. LLM 백엔드를 설정해야 합니다 - [아래](#llm-services)를 참조하세요.
- `--force\_ocr`: 추출 가능한 텍스트가 포함되어 있을 수 있는 페이지를 포함하여 전체 문서에 대해 OCR 처리를 강제합니다.
- `--block\_correction\_prompt`: LLM 모드가 활성화된 경우, marker의 출력을 수정하는 데 사용되는 선택적 프롬프트입니다. 출력에 적용하려는 사용자 정의 포맷팅이나 로직에 유용합니다.
- `--strip\_existing\_ocr`: 문서의 모든 기존 OCR 텍스트를 제거하고 surya로 다시 OCR을 수행합니다.
- `--redo\_inline\_math`: 가장 높은 품질의 인라인 수식 변환을 원할 경우 `--use\_llm`과 함께 이를 사용하세요.
- `--disable\_image\_extraction`: PDF에서 이미지를 추출하지 않습니다. `--use\_llm`도 함께 지정하면 이미지가 설명으로 대체됩니다.
- `--keep\_pageheader\_in\_output` / `--keep\_pagefooter\_in\_output`: 머리글/바닥글을 제거하는 대신 출력에 계속 유지합니다(기본적으로 제거됨).
- `--debug`: 추가 로깅 및 진단 정보를 위한 디버그 모드를 활성화합니다.
- `--processors TEXT`: 전체 모듈 경로를 쉼표로 구분하여 제공함으로써 기본 프로세서를 오버라이드합니다. 예: `--processors "module1.processor1,module2.processor2"`
- `--config\_json PATH`: 추가 설정이 포함된 JSON 설정 파일의 경로입니다.
- `config --help`: 사용 가능한 모든 빌더, 프로세서, 컨버터 및 이와 연관된 설정을 나열합니다. 이 값들은 marker 기본값을 추가로 조정하기 위한 JSON 설정 파일을 빌드하는 데 사용할 수 있습니다.
- `--converter\_cls`: `marker.converters.pdf.PdfConverter` (기본값) 또는 `marker.converters.table.TableConverter` 중 하나입니다. `PdfConverter`는 전체 PDF를 변환하고, `TableConverter`는 표만 추출하여 변환합니다.
- `--llm\_service`: `--use\_llm`이 전달된 경우 사용할 LLM 서비스입니다. 기본값은 `marker.services.gemini.GoogleGeminiService`입니다.
- `--help`: marker에 전달할 수 있는 모든 플래그를 확인합니다. (위에 나열된 것보다 훨씬 많은 옵션을 지원합니다)
OCR은 다국어 지원이 가능한 surya VLM을 통해 실행됩니다. 자세한 내용은 [surya README](https://github.com/datalab-to/surya)를 참조하세요. OCR이 필요 없는 경우, marker는 어떤 언어로든 작동할 수 있습니다.

## 여러 파일 변환
```shell
marker /path/to/input/folder
```
- `marker`는 위의 `marker\_single`과 동일한 모든 옵션을 지원합니다.
- `--workers`는 동시에 실행할 변환 작업자(worker) 수입니다. 기본적으로 자동 설정되지만, CPU 사용량이 늘어나는 대신 처리량을 늘리기 위해 값을 높일 수 있습니다. 모든 작업자는 부모 프로세스가 생성하는 단일 추론 서버를 공유합니다.
- 부모 프로세스는 전체 VLM 동시성을 자동으로 예산화합니다. 서버의 용량을 읽고 이를 작업자들에게 분할하므로(전체 진행 중인 요청 수 ≈ 1.5× 용량), 작업자를 추가해도 서버에 과도한 큐가 쌓이지 않습니다. 오버라이드하려는 경우에만 `SURYA\_INFERENCE\_PARALLEL`을 설정하세요.
- `--disable\_ocr`을 사용하면 추론 서버가 전혀 시작되지 않으며, 풀(pool)의 크기는 순수하게 CPU 코어에 의해 결정됩니다.
- `--skip\_existing`은 `--output\_dir`에 이미 출력이 있는 입력 파일을 건너뛰고(실행 재개), `--max\_files N`은 변환할 파일 수를 제한하며, `--disable\_multiprocessing`은 모든 것을 단일 프로세스에서 실행합니다.

### 배치 크기 치트 시트 (예: 1000개 문서)
- \*\*단일 GPU 머신\*\*: `marker /folder --output\_dir out` — 기본값으로 처리됨: 하나의 vllm 서버, CPU 크기의 작업자 풀, GPU에 예산화된 동시성. 주로 디지털 코퍼스에 대해 더 저렴하고 빠른 변환을 원한다면 `--mode fast`를 추가하세요.
- \*\*멀티 GPU 머신\*\*: 서버가 여러 GPU에 걸쳐 실행되는 동일한 단일 명령어: `VLLM\_GPUS=0,1,2,3 marker /folder ...`
- \*\*여러 머신\*\*: 파일 목록을 샤딩 — 노드당 `--num\_chunks  --chunk\_idx `를 사용하여 `marker`를 하나씩 실행합니다. 각 노드는 자체 서버를 생성합니다.
- \*\*CPU 전용 / VLM 없음\*\*: `marker /folder --disable\_ocr` (순수 텍스트 레이어 추출; 수식 및 스캔된 페이지는 건너뜁니다).

## Python에서 사용하기
전달할 수 있는 추가 인수에 대해서는 `marker/converters/pdf.py`의 `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)
```
`rendered`는 요청된 출력 유형에 따라 다른 속성을 가진 pydantic basemodel이 됩니다. 마크다운 출력(기본값)의 경우 `markdown`, `metadata`, `images` 속성을 갖게 됩니다. json 출력의 경우 `children`, `block\_type`, `metadata`를 갖게 됩니다.

### 사용자 정의 설정
`ConfigParser`를 사용하여 설정을 전달할 수 있습니다. 사용 가능한 모든 옵션을 보려면 `marker\_single --help`를 실행하세요.
```python
from marker.converters.pdf import PdfConverter
from marker.models import create\_model\_dict
from marker.config.parser import ConfigParser
config = {
"output\_format": "json",
"ADDITIONAL\_KEY": "VALUE"
}
config\_parser = ConfigParser(config)
converter = PdfConverter(
config=config\_parser.generate\_config\_dict(),
artifact\_dict=create\_model\_dict(),
processor\_list=config\_parser.get\_processors(),
renderer=config\_parser.get\_renderer(),
llm\_service=config\_parser.get\_llm\_service()
)
rendered = converter("FILEPATH")
```

### 블록 추출
각 도큐먼트는 하나 이상의 페이지로 구성됩니다. 페이지에는 블록이 포함되어 있으며, 블록은 그 자체로 다른 블록을 포함할 수 있습니다. 이러한 블록을 프로그래밍 방식으로 조작할 수 있습니다.
문서에서 모든 양식을 추출하는 예제입니다:
```python
from marker.converters.pdf import PdfConverter
from marker.models import create\_model\_dict
from marker.schema import BlockTypes
converter = PdfConverter(
artifact\_dict=create\_model\_dict(),
)
document = converter.build\_document("FILEPATH")
forms = document.contained\_blocks((BlockTypes.Form,))
```
블록 추출 및 조작에 대한 더 많은 예제는 프로세서(processors) 코드를 확인하세요.

## 기타 컨버터
다른 변환 파이프라인을 정의하는 다른 컨버터를 사용할 수도 있습니다:

### 표 추출
`TableConverter`는 표만 변환하고 추출합니다:
```python
from marker.converters.table import TableConverter
from marker.models import create\_model\_dict
from marker.output import text\_from\_rendered
converter = TableConverter(
artifact\_dict=create\_model\_dict(),
)
rendered = converter("FILEPATH")
text, \_, images = text\_from\_rendered(rendered)
```
이 컨버터는 PdfConverter와 동일한 모든 설정을 사용합니다. 레이아웃 감지를 피하고 대신 모든 페이지가 표라고 가정하려면 `force\_layout\_block=Table` 설정을 지정할 수 있습니다. 표는 HTML (`

`) 블록으로 출력되며, `output\_format=json`을 사용하면 페이지 바운딩 박스가 포함된 표 블록을 얻을 수 있습니다.
CLI를 통해 실행할 수도 있습니다:
```shell
marker\_single FILENAME --use\_llm --force\_layout\_block Table --converter\_cls marker.converters.table.TableConverter --output\_format json
```

### OCR 전용
OCR만 실행하려면 `OCRConverter`를 사용할 수도 있습니다. 개별 문자와 바운딩 박스를 유지하려면 `--keep\_chars`를 설정하세요(디지털 PDF 전용 - VLM을 거치는 페이지는 문자 박스 없이 블록 수준의 HTML을 반환합니다).
```python
from marker.converters.ocr import OCRConverter
from marker.models import create\_model\_dict
converter = OCRConverter(
artifact\_dict=create\_model\_dict(),
)
rendered = converter("FILEPATH")
```
이 컨버터는 PdfConverter와 동일한 모든 설정을 사용합니다.
CLI를 통해 실행할 수도 있습니다:
```shell
marker\_single FILENAME --converter\_cls marker.converters.ocr.OCRConverter
```

# 출력 형식
## 마크다운
마크다운 출력에는 다음이 포함됩니다:
- 이미지 링크 (이미지는 동일한 폴더에 저장됨)
- 포맷된 표
- 임베디드 LaTeX 수식 (`$$`로 감싸임)
- 코드는 삼중 백틱(triple backtick)으로 감싸임
- 각주용 위첨자

## HTML
HTML 출력은 마크다운 출력과 유사합니다:
- 이미지는 `img` 태그를 통해 포함됨
- 수식은 `` 태그로 감싸임
- 코드는 `pre` 태그에 포함됨

## JSON
JSON 출력은 트리 유사 구조로 구성되며, 리프(leaf) 노드는 블록이 됩니다. 리프 노드의 예로는 단일 목록 항목, 텍스트 단락, 또는 이미지가 있습니다.
출력은 리스트 형태이며, 각 리스트 항목은 페이지를 나타냅니다. 각 페이지는 내부 marker 스키마에서 하나의 블록으로 간주됩니다. 다양한 요소를 나타내기 위해 여러 유형의 블록이 존재합니다.
페이지에는 다음 키가 있습니다:
- `id` - 블록의 고유 ID.
- `block\_type` - 블록의 유형. 가능한 블록 유형은 `marker/schema/\_\_init\_\_.py`에서 확인할 수 있습니다. 작성 시점 기준으로 ["Line", "Span", "FigureGroup", "TableGroup", "ListGroup", "PictureGroup", "Page", "Caption", "Code", "Figure", "Footnote", "Form", "Equation", "Handwriting", "TextInlineMath", "ListItem", "PageFooter", "PageHeader", "Picture", "SectionHeader", "Table", "Text", "TableOfContents", "Document"] 등이 있습니다.
- `html` - 페이지의 HTML. 이는 자식 노드에 대한 재귀적 참조를 가짐에 유의하세요. 전체 HTML을 원할 경우 `content-ref` 태그를 자식 콘텐츠로 대체해야 합니다. 이에 대한 예제는 `marker/output.py:json\_to\_html`에서 확인할 수 있습니다. 해당 함수는 json 출력에서 단일 블록을 받아 HTML로 변환합니다.
- `polygon` - 페이지의 4개 모서리 폴리곤, (x1,y1), (x2,y2), (x3, y3), (x4, y4) 형식. (x1,y1)은 좌상단이며 좌표는 시계 방향으로 진행됩니다.
- `children` - 자식 블록들.
자식 블록에는 두 개의 추가 키가 있습니다:
- `section\_hierarchy` - 블록이 속한 섹션을 나타냄. `1`은 h1 태그를 나타내며, `2`는 h2를 나타내는 식입니다.
- `images` - base64로 인코딩된 이미지. 키는 블록 ID가 되며, 데이터는 인코딩된 이미지가 됩니다.
페이지의 자식 블록도 자체적인 자식을 가질 수 있습니다(트리 구조).
```json
{
"id": "/page/10/Page/366",
"block\_type": "Page",
"html": "",
"polygon": [[0.0, 0.0], [612.0, 0.0], [612.0, 792.0], [0.0, 792.0]],
"children": [
{
"id": "/page/10/SectionHeader/0",
"block\_type": "SectionHeader",
"html": "

# Supplementary Material for *Subspace Adversarial Training*

",
"polygon": [
[217.845703125, 80.630859375], [374.73046875, 80.630859375],
[374.73046875, 107.0],
[217.845703125, 107.0]
],
"children": null,
"section\_hierarchy": {
"1": "/page/10/SectionHeader/1"
},
"images": {}
},
...
]
}
```

## 청크 (Chunks)
청크 형식은 JSON과 유사하지만, 트리가 아닌 단일 리스트로 모든 것을 평탄화(flatten)합니다. 각 페이지의 최상위 블록만 나타납니다. 또한 내부에 각 블록의 전체 HTML이 포함되어 있으므로 재구성을 위해 트리를 탐색할 필요가 없습니다. 이는 RAG를 위한 유연하고 쉬운 청킹을 가능하게 합니다.

## 메타데이터
모든 출력 형식은 다음 필드를 포함하는 메타데이터 딕셔너리를 반환합니다:
```json
{
"table\_of\_contents": [
{
"title": "Introduction",
"heading\_level": 1,
"page\_id": 0,
"polygon": [...]
}
], // 계산된 PDF 목차
"page\_stats": [
{
"page\_id": 0,
"text\_extraction\_method": "pdftext",
"block\_counts": [("Span", 200), ...]
},
...
]
}
```

# LLM 서비스
`--use\_llm` 플래그와 함께 실행할 때 사용할 수 있는 서비스 선택지가 있습니다:
- `Gemini` - 기본적으로 Gemini 개발자 API를 사용합니다. 설정에 `--gemini\_api\_key`를 전달해야 합니다.
- `Google Vertex` - 더 안정적일 수 있는 Vertex를 사용합니다. `--vertex\_project\_id`를 전달해야 합니다. 사용하려면 `--llm\_service=marker.services.vertex.GoogleVertexService`로 설정하세요.
- `Ollama` - 로컬 모델을 사용합니다. `--ollama\_base\_url` 및 `--ollama\_model`을 설정할 수 있습니다. 사용하려면 `--llm\_service=marker.services.ollama.OllamaService`로 설정하세요.
- `Claude` - Anthropic API를 사용합니다. `--claude\_api\_key` 및 `--claude\_model\_name`을 설정할 수 있습니다. 사용하려면 `--llm\_service=marker.services.claude.ClaudeService`로 설정하세요.
- `OpenAI` - OpenAI 호환 엔드포인트를 지원합니다. `--openai\_api\_key`, `--openai\_model`, `--openai\_base\_url`을 설정할 수 있습니다. 사용하려면 `--llm\_service=marker.services.openai.OpenAIService`로 설정하세요.
- `Azure OpenAI` - Azure OpenAI 서비스를 사용합니다. `--azure\_endpoint`, `--azure\_api\_key`, `--deployment\_name`을 설정할 수 있습니다. 사용하려면 `--llm\_service=marker.services.azure\_openai.AzureOpenAIService`로 설정하세요.
- `OpenRouter` - [OpenRouter](https://openrouter.ai)의 OpenAI 호환 API를 사용합니다. `--openrouter\_api\_key` (또는 `OPENROUTER\_API\_KEY` 환경 변수), `--openrouter\_model` (기본값 `google/gemini-3.5-flash`), `--openrouter\_base\_url`을 설정할 수 있습니다. 사용하려면 `--llm\_service=marker.services.openrouter.OpenRouterService`로 설정하세요.
이러한 서비스에는 추가적인 선택적 설정이 있을 수 있으며, 클래스를 확인하여 볼 수 있습니다.

# 내부 구조
Marker는 확장하기 쉽습니다. marker의 핵심 단위는 다음과 같습니다:
- `Providers` (`marker/providers` 위치): PDF와 같은 소스 파일에서 정보를 제공합니다.
- `Builders` (`marker/builders` 위치): 프로바이더의 정보를 사용하여 초기 문서 블록을 생성하고 텍스트를 채웁니다.
- `Processors` (`marker/processors` 위치): 특정 블록을 처리합니다(예: 표 포맷터는 프로세서입니다).
- `Renderers` (`marker/renderers` 위치): 블록을 사용하여 출력을 렌더링합니다.
- `Schema` (`marker/schema` 위치): 모든 블록 유형에 대한 클래스입니다.
- `Converters` (`marker/converters` 위치): 전체 엔드투엔드 파이프라인을 실행합니다.
처리 동작을 커스터마이징하려면 `processors`를 오버라이드하세요. 새로운 출력 형식을 추가하려면 새로운 `renderer`를 작성하세요. 추가 입력 형식의 경우 새로운 `provider`를 작성하세요.
프로세서와 렌더러는 기본 `PDFConverter`에 직접 전달할 수 있으므로 자신만의 커스텀 처리를 쉽게 지정할 수 있습니다.

## API 서버
다음과 같이 실행할 수 있는 매우 간단한 API 서버가 있습니다:
```shell
pip install -U uvicorn fastapi python-multipart
marker\_server --port 8001
```
이렇게 하면 `localhost:8001`에서 액세스할 수 있는 FastAPI 서버가 시작됩니다(바인딩 주소를 변경하려면 `--host` 사용). `localhost:8001/docs`로 이동하여 엔드포인트 옵션을 확인할 수 있습니다.
다음과 같이 요청을 보낼 수 있습니다:
```python
import requests
import json
post\_data = {
'filepath': 'FILEPATH',
# 허용되는 파라미터: page\_range, mode, force\_ocr, paginate\_output, output\_format
}
requests.post("http://localhost:8001/marker", data=json.dumps(post\_data)).json()
```
서버는 위에 나열된 파라미터(`page\_range`, `mode`, `force\_ocr`, `paginate\_output`, `output\_format`)만 허용합니다. `--use\_llm` 하이브리드 경로와 `--disable\_ocr`은 API를 통해 노출되지 않습니다. 해당 기능들은 CLI나 Python API 또는 호스팅된 [Datalab API](https://www.datalab.to/plans)를 사용하세요.
이는 매우 견고한 API가 아니며 소규모 사용만을 위한 것입니다. 이 서버를 사용하고 싶지만 더 견고한 변환 옵션이 필요한 경우, 호스팅된 [Datalab API](https://www.datalab.to/plans)를 사용할 수 있습니다.

# 문제 해결
예상대로 작동하지 않을 때 유용할 수 있는 몇 가지 설정입니다:
- 정확도에 문제가 있는 경우 품질을 향상시키기 위해 `--use\_llm`을 설정하여 LLM을 사용해 보세요. 이를 작동시키려면 `GOOGLE\_API\_KEY`를 Gemini API 키로 설정해야 합니다.
- 텍스트가 깨져 보이는 경우 `force\_ocr`을 설정하세요. 문서가 다시 OCR 처리됩니다.
- `TORCH\_DEVICE` - 작은 로컬 모델(OCR 오류 감지)을 지정된 torch 장치로 강제로 지정하려면 이 값을 설정하세요. VLM은 추론 서버에서 실행되며, `SURYA\_INFERENCE\_BACKEND` / `VLLM\_GPUS`로 배치를 제어하세요.
- 메모리 부족(OOM) 오류가 발생하는 경우 작업자 수를 줄이세요. 긴 PDF를 여러 파일로 분할해 볼 수도 있습니다.

## 디버깅
디버그 모드를 활성화하려면 `debug` 옵션을 전달하세요. 감지된 레이아웃과 텍스트가 포함된 각 페이지의 이미지와 추가 바운딩 박스 정보가 포함된 json 파일이 출력됩니다.

# 벤치마크
## 전체 PDF 변환
변환 품질은 [olmocr-bench](https://github.com/allenai/olmocr/tree/main/olmocr/bench)를 사용하여 측정됩니다: 수식 렌더링, 표 구조, 읽기 순서, 머리글/바닥글, 오래된 스캔을 다루는 약 8,400개의 통과/실패 유닛 테스트가 포함된 1,403개의 PDF입니다. 전체 점수는 공식 olmocr-bench 체커를 사용하여 \*\*8개 카테고리의 매크로 평균\*\*(olmocr-bench 및 Chandra가 보고하는 방식과 일치)으로 계산됩니다.

### 경쟁 비교
전체 벤치마크에서의 품질 대 처리량 — 위쪽(더 높은 점수)과 오른쪽(더 빠른 속도)일수록 좋습니다. Marker(본 리포지토리)는 점수와 처리량 모두에서 MinerU와 docling을 \*\*동시에\*\* 능가합니다. balanced 모드는 MinerU보다 ~5배 더 많은 페이지/초를 처리하면서 Gemini/MinerU 품질과 일치하며, fast 모드는 약간의 품질을 희생하여 큰 속도 향상을 얻습니다.
![](data/images/olmocr_bench.png)
| 시스템 | 전체 | 디지털 전용 | 처리량\\* |
|---|---:|---:|---:|
| [Chandra 2](https://github.com/datalab-to/chandra) (호스팅) | 85.8 | — | — |
| Gemini Flash 3.5 (API) | 76.4 | 79.1 | — |
| \*\*Marker — balanced\*\* (GPU) | \*\*76.0\*\* | \*\*83.5\*\* | \*\*2.9 pg/s\*\* |
| MinerU — pipeline (GPU) | 72.7 | 83.3 | 0.54 pg/s |
| \*\*Marker — fast\*\* (GPU) | \*\*66.6\*\* | \*\*71.6\*\* | \*\*7.4 pg/s\*\* |
| docling (GPU) | 50.3 | 64.0 | 2.1 pg/s |
| \*\*Marker — fast, no OCR\*\* (CPU) | \*\*43.6\*\* | \*\*55.8\*\* | \*\*23.7 pg/s\*\* |
| liteparse (CPU) | 22.4 | 27.3 | 8.9 pg/s |
| liteparse, no OCR (CPU) | 20.4 | 25.0 | 1721 pg/s |
Chandra 2는 당사의 호스팅 모델이며(숫자는 [Chandra 리포지토리](https://github.com/datalab-to/chandra) 기준); Gemini Flash 3.5는 API를 통해; MinerU / docling / liteparse는 OSS 파이프라인입니다. 디지털 전용 = 스캔되지 않은 6개 카테고리에 대한 매크로 평균(대부분의 텍스트 레이어 도구가 더 높은 점수를 받는 하위 집합).
\\* 처리량은 단일 스트림 지연 시간이 아니라 배포와 관련된 수치인 단일 B200 호스트에서의 지속적인 \*\*동시(concurrent)\*\* 페이지/초입니다. 마커 패스트-노-OCR 및 라이트파스(설계상 CPU 전용)를 제외한 각 시스템은 고유한 병렬 처리(marker balanced/fast, MinerU, docling)로 GPU에서 실행됩니다. Chandra(호스팅)와 Gemini(API)에는 로컬 하드웨어 처리량이 없습니다. 단일 추론 서버를 공유하는 얇은 CPU 작업자로 구성된 Marker의 설계([처리량](#throughput) 참조) 덕분에 balanced와 같은 GPU 모드가 ~0.3 pg/s의 단일 스트림 속도가 아닌 ~2.9 pg/s를 유지할 수 있습니다.
이 표는 \*\*파이프라인 시스템\*\*을 비교합니다. PDF 텍스트 레이어를 읽고 선택적으로 OCR을 수행하는 marker를 MinerU의 \*\*파이프라인\*\* 백엔드 및 docling(마찬가지로 텍스트 레이어 + 선택적 OCR)과 비교합니다. 이것이 공정한 비교(apples-to-apples)이며, marker balanced가 점수와 처리량 모두에서 앞서고 있습니다. (docling은 기본 파이프라인을 실행합니다: 태생 디지털의 경우 텍스트 레이어, 이미지 영역의 경우 OCR; MinerU의 자체 VLM 백엔드는 더 높은 점수를 받지만 다른 전체 페이지 VLM 접근 방식입니다.)
문서에 \*\*전체 페이지 VLM OCR\*\*이 필요한 경우(수식이 많은 페이지, 스캔 문서, 가능한 가장 높은 정확도), 이는 텍스트 레이어 파이프라인과는 다른 도구입니다. [Chandra](https://github.com/datalab-to/chandra)(당사의 문서 VLM, 여기서 85.8) 또는 [surya](https://github.com/datalab-to/surya)(marker가 내부적으로 사용하는 OCR VLM)를 찾으세요. 둘 다 각 리포지토리에 자체 olmocr-bench 수치를 가지고 있습니다.
순위별 막대 차트로 나타낸 동일한 수치(모든 시스템에 걸친 점수; 로그 스케일에서의 로컬 시스템 처리량):
![](data/images/olmocr_scores_bar.png) ![](data/images/olmocr_throughput_bar.png)

### 디지털 생성 문서 전용, CPU 전용
디지털 생성 PDF만 있고 GPU가 없는 경우, 관련 비교 대상은 순수 CPU 텍스트 추출기입니다. Marker의 `fast --disable\_ocr`은 CPU에서 20M 레이아웃 모델을 실행하고 여전히 구조(열, 표, 머리글)를 읽어내므로 단순 텍스트 덤프보다 훨씬 높은 점수를 받습니다. 반면 liteparse(레이아웃 모델 없음)는 더 빠르지만 비선형적인 모든 요소에서 무너집니다.
![](data/images/olmocr_digital.png)

### 카테고리별 Marker 모드
| 카테고리 | balanced | fast | OCR 없음 |
|----------------------|----------|------|--------|
| arXiv math | 83.9 | 23.4 | 0.0 |
| Tables | 73.4 | 69.0 | 46.1 |
| Multi column | 76.6 | 76.0 | 67.0 |
| Headers & footers | 95.9 | 93.2 | 92.8 |
| Long tiny text | 71.3 | 68.3 | 43.2 |
| Old scans math | 63.8 | 59.8 | 0.0 |
| Old scans | 43.2 | 43.2 | 14.3 |
| Baseline | 99.7 | 99.9 | 85.9 |
| \*\*전체\*\* | \*\*76.0\*\* | \*\*66.6\*\* | \*\*43.6\*\* |
| \*\*전체 (디지털 생성 전용)\*\* | \*\*83.5\*\* | \*\*71.6\*\* | \*\*55.8\*\* |
참고 사항:
- 디지털 생성 전용에는 두 개의 스캔된 분할(old scans, old scans math)이 제외됩니다.
- fast 모드의 수식 점수가 낮은 것은 설계상의 이유입니다: VLM으로 OCR 처리하는 대신 PDF 텍스트 레이어에서 수식을 읽어오기 때문에 LaTeX 수준의 수식 테스트(arXiv math)에서는 대부분 누락됩니다. 수식이 많은 문서에는 balanced를 사용하세요.
- `--disable\_ocr`(OCR 없음)은 VLM을 전혀 호출하지 않습니다: 수식 점수는 0이며(수식에는 텍스트 레이어 LaTeX가 없음), 원시 텍스트 레이어의 깨진 수식 글리프도 일부 기본 점수를 깎아먹습니다. 순수 CPU 텍스트 레이어 경로입니다.

## 처리량
![](data/images/marker_throughput.png)

marker

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README