Docling

원문 보기 위키 갱신 2026.10.11

Docling (camel-docling)

Docling 컴포넌트는 IBM의 Docling AI 문서 파서를 활용해서 문서를 변환하고 처리하게 해 줘요. PDF, Word 문서, PowerPoint 프레젠테이션 같은 다양한 문서 포맷을 Markdown, HTML, JSON, 일반 텍스트 같은 구조화된 포맷으로 바꿔 주는 강력한 도구죠. CLI 모드와 docling-serve API 모드 두 가지로 동작하고, 변환부터 메타데이터 추출, 청킹까지 폭넓은 연산을 지원해요.

출처: 문서

본문

Camel 4.15부터 지원

컨슈머와 프로듀서를 모두 지원해요

Docling 컴포넌트는 IBM의 Docling AI 문서 파서를 사용해 문서를 변환하고 처리할 수 있게 해 줘요. Docling은 PDF, Word 문서, PowerPoint 프레젠테이션 등 다양한 문서 포맷을 Markdown, HTML, JSON, 일반 텍스트 같은 구조화된 포맷으로 파싱하고 변환할 수 있는 강력한 Python 라이브러리예요.

Maven 사용자라면 이 컴포넌트를 위해 pom.xml에 다음 의존성을 추가해야 해요:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-docling</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

전제 조건 (Prerequisites)

이 컴포넌트는 두 가지 동작 모드를 지원해요:

CLI 모드 (기본값): pip으로 시스템에 Docling을 설치해야 해요:
```
pip install docling
```
API 모드: 실행 중인 docling-serve 인스턴스가 필요해요. 컴포넌트는 docling-serve와 통신하기 위해 공식 docling-java 라이브러리를 사용하고, 네이티브 비동기 지원이 더해진 견고한 API 통합을 제공해요. docling-serve는 다음과 같이 실행할 수 있어요:
```
# Install docling-serve
pip install docling-serve

# Run docling-serve
docling-serve --host 0.0.0.0 --port 5001
```
Docker로 실행할 수도 있어요:
```
docker run -p 5001:5001 ghcr.io/docling-project/docling-serve:latest
```

URI 형식 (URI format)

docling:operation[?options]

여기서 operation은 수행할 문서 처리 연산을 나타내요.

지원 연산 (Supported Operations)

컴포넌트는 다음 연산들을 지원해요:

Operation	Description
`CONVERT_TO_MARKDOWN`	문서를 Markdown 포맷으로 변환해요 (기본값)
`CONVERT_TO_HTML`	문서를 HTML 포맷으로 변환해요
`CONVERT_TO_JSON`	문서를 JSON 포맷으로 변환해요. API 모드와 CLI 모드 모두에서 `DoclingDocument` 객체(`ai.docling.core.DoclingDocument`)를 반환해요.
`EXTRACT_TEXT`	문서에서 일반 텍스트 내용을 추출해요
`EXTRACT_STRUCTURED_DATA`	테이블 구조 인식을 기본으로 활성화해서 구조화된 데이터를 추출해요. API 모드와 CLI 모드 모두에서 `DoclingDocument` 객체를 반환해요. 추가 인리치먼트 기능(코드, 수식, 그림 분류)은 설정으로 활성화할 수 있어요.
`EXTRACT_METADATA`	문서 메타데이터(제목, 저자, 페이지 수, 생성 날짜 등)를 추출해요
`SUBMIT_ASYNC_CONVERSION`	비동기 변환을 제출하고 태스크 ID를 반환해요 (docling-serve 전용)
`CHECK_CONVERSION_STATUS`	비동기 변환 태스크의 상태를 확인해요 (docling-serve 전용)
`CHUNK_HYBRID`	HybridChunker로 문서를 청킹해요 — 토큰 인식과 구조 인식을 함께 해요 (docling-serve 전용)
`CHUNK_HIERARCHICAL`	HierarchicalChunker로 문서를 청킹해요 — 구조 인식 (docling-serve 전용)

옵션 설정 (Configuring Options)

Camel 컴포넌트는 서로 다른 두 단계로 설정해요:

component level
endpoint level

컴포넌트 옵션 설정 (Configuring Component Options)

컴포넌트 레벨에서는 엔드포인트들이 이어서 물려받는 일반적이고 공유되는 설정을 해요. 가장 상위의 설정 레벨이죠.

예를 들어 컴포넌트에는 보안 설정, 인증용 자격 증명, 네트워크 연결 URL 같은 것들이 있을 수 있어요.

컴포넌트에 따라 옵션이 몇 개뿐인 것도 있고 아주 많은 것도 있어요. 컴포넌트는 보통 널리 쓰이는 기본값이 미리 설정되어 있어서, 몇 가지 옵션만 설정하거나 아예 하나도 건드리지 않아도 되는 경우가 많아요.

컴포넌트는 다음 방법으로 설정할 수 있어요:

Component DSL
설정 파일 (application.properties, *.yaml 파일 등)
Java 코드에서 직접

엔드포인트 옵션 설정 (Configuring Endpoint Options)

엔드포인트는 옵션이 많아서 설정에 시간을 더 쓰게 될 거예요. 이 옵션들이 엔드포인트가 원하는 일을 하도록 커스터마이즈해 줘요. 옵션은 엔드포인트가 컨슈머(from)로 쓰이는지, 프로듀서(to)로 쓰이는지, 둘 다인지에 따라 분류되기도 해요.

엔드포인트 설정은 대부분 엔드포인트 URI에 _path_와 query 파라미터로 바로 하는 경우가 많아요. Endpoint DSL과 DataFormat DSL을 쓰면 자바에서 엔드포인트와 데이터 포맷을 _타입 세이프_하게 설정할 수도 있어요.

옵션을 설정할 때 좋은 습관은 Property Placeholders를 사용하는 거예요.

프로퍼티 플레이스홀더는 이런 장점이 있어요:

하드코딩된 URL, 포트 번호, 민감한 정보 같은 설정값 사용을 막아 줘요.
설정을 코드 밖으로 분리할 수 있게 해 줘요.
코드가 더 유연하고 재사용하기 쉬워져요.

다음 두 섹션에서 모든 옵션을 나열해요. 먼저 컴포넌트 옵션, 그다음 엔드포인트 옵션 순서예요.

컴포넌트 옵션 (Component Options)

Docling 컴포넌트는 아래 나열된 옵션들을 지원해요.

Name	Description	Default	Type
configuration (common)	Docling 엔드포인트의 설정이에요.		DoclingConfiguration
contentInBody (common)	출력 파일의 내용을 교환 바디에 담고, 출력 파일은 삭제해요.	false	boolean
doclingServeUrl (common)	docling-serve API URL이에요 (예: http://localhost:5001).	http://localhost:5001	String
enableOCR (common)	스캔 문서에 대한 OCR 처리를 활성화해요.	true	boolean
includeLayoutInfo (common)	바운딩 박스가 함께 담긴 레이아웃 정보를 보여 줘요.	false	boolean
ocrLanguage (common)	OCR 처리에 사용할 언어 코드예요.	en	String
operation (common)
필수 수행할 연산이에요.

Enum values:

CONVERT_TO_MARKDOWN
CONVERT_TO_HTML
CONVERT_TO_JSON
EXTRACT_TEXT
EXTRACT_STRUCTURED_DATA
SUBMIT_ASYNC_CONVERSION
CHECK_CONVERSION_STATUS
BATCH_CONVERT_TO_MARKDOWN
BATCH_CONVERT_TO_HTML
BATCH_CONVERT_TO_JSON
BATCH_EXTRACT_TEXT
BATCH_EXTRACT_STRUCTURED_DATA
EXTRACT_METADATA
CHUNK_HYBRID
CHUNK_HIERARCHICAL

인증 스킴이에요 (BEARER, API_KEY, NONE).

Enum values:

NONE
BEARER
API_KEY

| NONE | AuthenticationScheme | | authenticationToken (security) | docling-serve API 인증용 토큰이에요 (베어러 토큰 또는 API 키). | | String | | inputBaseDirectory (security) | 설정하면, 정규화를 마친 뒤의 모든 로컬 입력 파일 경로가 이 디렉터리 안쪽에 있어야 해요. CamelDoclingInputFilePath 헤더, 파일 경로 메시지 바디, 배치 연산이 쓰는 경로에 적용돼요. 비워 두면 디렉터리 제한이 적용되지 않아요. | | String | | maxFileSize (security) | 처리할 파일의 최대 크기(바이트)예요. | 52428800 | long | | oauthProfile (security) | OAuth 2.0 Client Credentials 그랜트로 액세스 토큰을 얻기 위한 OAuth 프로필 이름이에요. 설정하면 구성된 아이덴티티 프로바이더에서 토큰을 받아 authenticationToken으로 사용해요. 클래스패스에 camel-oauth가 필요해요. | | String | | outputBaseDirectory (security) | 설정하면, docling CLI에 넘기는 출력 디렉터리가 정규화를 마친 뒤 이 디렉터리 안쪽에 있어야 해요. CamelDoclingOutputFilePath 헤더에 적용돼요. 검사는 어휘적으로 이뤄지고 심볼릭 링크를 해석하지 않는다는 점이 inputBaseDirectory와 같아요. 비워 두면 디렉터리 제한이 적용되지 않고 헤더 값만 정규화돼요. | | String |

엔드포인트 옵션 (Endpoint Options)

Docling 엔드포인트는 다음 URI 문법으로 설정해요:

docling:operationId

다음 path 및 query 파라미터를 사용해요:

경로 파라미터 (Path Parameters)

Name	Description	Default	Type
operationId (common)	필수 연산 식별자예요.		String

쿼리 파라미터 (Query Parameters)

Name	Description	Default	Type
contentInBody (common)	출력 파일의 내용을 교환 바디에 담고, 출력 파일은 삭제해요.	false	boolean
doclingServeUrl (common)	docling-serve API URL이에요 (예: http://localhost:5001).	http://localhost:5001	String
enableOCR (common)	스캔 문서에 대한 OCR 처리를 활성화해요.	true	boolean
includeLayoutInfo (common)	바운딩 박스가 함께 담긴 레이아웃 정보를 보여 줘요.	false	boolean
ocrLanguage (common)	OCR 처리에 사용할 언어 코드예요.	en	String
operation (common)
필수 수행할 연산이에요.

Enum values:

CONVERT_TO_MARKDOWN
CONVERT_TO_HTML
CONVERT_TO_JSON
EXTRACT_TEXT
EXTRACT_STRUCTURED_DATA
SUBMIT_ASYNC_CONVERSION
CHECK_CONVERSION_STATUS
BATCH_CONVERT_TO_MARKDOWN
BATCH_CONVERT_TO_HTML
BATCH_CONVERT_TO_JSON
BATCH_EXTRACT_TEXT
BATCH_EXTRACT_STRUCTURED_DATA
EXTRACT_METADATA
CHUNK_HYBRID
CHUNK_HIERARCHICAL

| CONVERT_TO_MARKDOWN | DoclingOperations | | outputFormat (common) | 문서 변환의 출력 포맷이에요. | markdown | String | | useDoclingServe (common) | CLI 명령 대신 docling-serve API를 사용해요. | false | boolean | | sendEmptyMessageWhenIdle (consumer) | 폴링 컨슈머가 아무 파일도 폴링하지 않았을 때, 이 옵션을 켜면 대신 빈 메시지(바디 없음)를 보내게 해 줘요. | false | boolean | | bridgeErrorHandler (consumer (advanced)) | 컨슈머를 Camel 라우팅 에러 핸들러(Error Handler)에 브리지할 수 있게 해 줘요. 즉, Camel 컨슈머가 들어오는 메시지를 집어 올리는 동안 등에서 예외가 발생하면(가능한 경우), 그 예외를 메시지로 처리해서 라우팅 에러 핸들러가 다루게 돼요. 중요: 이것은 서드파티 컴포넌트가 예외가 던져졌을 때 Camel에 알릴 수 있도록 허용하는 경우에만 가능해요. 일부 컴포넌트는 내부에서만 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 Camel 컴포넌트를 개선해서 서드파티 컴포넌트에 연결(hook)해 이를 가능하게 만들 수도 있어요. 기본으로 컨슈머는 org.apache.camel.spi.ExceptionHandler로 예외를 처리하는데, WARN 또는 ERROR 레벨로 로그를 남기고 무시해요. | false | boolean | | exceptionHandler (consumer (advanced)) | 컨슈머가 커스텀 ExceptionHandler를 쓰게 할 수 있어요. bridgeErrorHandler 옵션이 활성화되어 있으면 이 옵션은 사용되지 않는다는 점에 주의하세요. 기본으로 컨슈머는 예외를 처리하는데, WARN 또는 ERROR 레벨로 로그를 남기고 무시해요. | | ExceptionHandler | | exchangePattern (consumer (advanced)) |

컨슈머가 교환(exchange)을 만들 때 교환 패턴을 설정해요.

Enum values:

InOnly
InOut

컨슈머가 폴링할 때 시작/완료 로그 한 줄을 남겨요. 이 옵션으로 그 로그의 레벨을 설정할 수 있어요.

Enum values:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

initialDelay와 delay 옵션의 시간 단위예요.

Enum values:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

인증 스킴이에요 (BEARER, API_KEY, NONE).

Enum values:

NONE
BEARER
API_KEY

메시지 헤더 (Message Headers)

Docling 컴포넌트는 아래 나열된 메시지 헤더(들)를 지원해요:

Name	Description	Type
CamelDoclingOperation (common) Constant: `OPERATION`	수행할 연산이에요.	DoclingOperations
CamelDoclingOutputFormat (common) Constant: `OUTPUT_FORMAT`	변환의 출력 포맷이에요.	String
CamelDoclingInputFilePath (common) Constant: `INPUT_FILE_PATH`	입력 파일 경로 또는 내용이에요.	String
CamelDoclingOutputFilePath (common) Constant: `OUTPUT_FILE_PATH`	결과를 저장할 출력 파일 경로예요.	String
CamelDoclingProcessingOptions (common) Constant: `PROCESSING_OPTIONS`	추가 처리 옵션이에요.	Map
CamelDoclingEnableOCR (common) Constant: `ENABLE_OCR`	OCR 처리를 포함할지 여부예요.	Boolean
CamelDoclingOCRLanguage (common) Constant: `OCR_LANGUAGE`	OCR 처리에 사용할 언어예요.	String
CamelDoclingCustomArguments (common) Constant: `CUSTOM_ARGUMENTS`	Docling에 넘길 커스텀 명령줄 인자예요.	List
CamelDoclingUseAsyncMode (common) Constant: `USE_ASYNC_MODE`	비동기 변환 모드를 사용해요 (엔드포인트 설정을 재정의해요).	Boolean
CamelDoclingAsyncPollInterval (common) Constant: `ASYNC_POLL_INTERVAL`	비동기 변환 상태 폴링 간격(밀리초)이에요.	Long
CamelDoclingAsyncTimeout (common) Constant: `ASYNC_TIMEOUT`	비동기 변환 완료를 기다리는 최대 시간(밀리초)이에요.	Long
CamelDoclingTaskId (common) Constant: `TASK_ID`	비동기 변환 상태를 확인할 태스크 ID예요.	String
CamelDoclingBatchSize (common) Constant: `BATCH_SIZE`	이 연산의 배치 크기를 재정의해요.	Integer
CamelDoclingBatchParallelism (common) Constant: `BATCH_PARALLELISM`	이 연산의 배치 병렬도를 재정의해요.	Integer
CamelDoclingBatchFailOnFirstError (common) Constant: `BATCH_FAIL_ON_FIRST_ERROR`	이 연산의 배치 첫-에러-실패 설정을 재정의해요.	Boolean
CamelDoclingBatchTimeout (common) Constant: `BATCH_TIMEOUT`	이 연산의 배치 타임아웃을 밀리초 단위로 재정의해요.	Long
CamelDoclingBatchTotalDocuments (common) Constant: `BATCH_TOTAL_DOCUMENTS`	배치에 담긴 문서의 총 개수예요.	Integer
CamelDoclingBatchSuccessCount (common) Constant: `BATCH_SUCCESS_COUNT`	배치에서 성공적으로 처리된 문서 수예요.	Integer
CamelDoclingBatchFailureCount (common) Constant: `BATCH_FAILURE_COUNT`	배치에서 실패한 문서 수예요.	Integer
CamelDoclingBatchProcessingTime (common) Constant: `BATCH_PROCESSING_TIME`	배치의 총 처리 시간(밀리초)이에요.	Long
CamelDoclingBatchSplitResults (common) Constant: `BATCH_SPLIT_RESULTS`	하나의 BatchProcessingResults 대신 배치 결과를 개별 교환으로 나눠요.	Boolean
CamelDoclingMetadataPageCount (common) Constant: `METADATA_PAGE_COUNT`	문서의 페이지 수예요.	Integer
CamelDoclingMetadataTitle (common) Constant: `METADATA_TITLE`	문서 제목이에요.	String
CamelDoclingMetadataLanguage (common) Constant: `METADATA_LANGUAGE`	문서 언어 코드예요.	String
CamelDoclingMetadataDocumentType (common) Constant: `METADATA_DOCUMENT_TYPE`	문서 타입/포맷이에요.	String
CamelDoclingMetadataFormat (common) Constant: `METADATA_FORMAT`	문서 포맷(MIME 타입)이에요.	String
CamelDoclingMetadataFileSize (common) Constant: `METADATA_FILE_SIZE`	파일 크기(바이트)예요.	Long
CamelDoclingMetadataFileName (common) Constant: `METADATA_FILE_NAME`	파일 이름이에요.	String
CamelDoclingMetadataRaw (common) Constant: `METADATA_RAW`	Map으로 담긴 원시 메타데이터 필드예요.	Map
CamelDoclingChunkingTokenizer (common) Constant: `CHUNKING_TOKENIZER`	하이브리드 청킹용 토크나이저예요 (예: sentence-transformers/all-MiniLM-L6-v2).	String
CamelDoclingChunkingMaxTokens (common) Constant: `CHUNKING_MAX_TOKENS`	하이브리드 청킹에서 청크당 최대 토큰 수예요.	Integer
CamelDoclingChunkingMergePeers (common) Constant: `CHUNKING_MERGE_PEERS`	하이브리드 청킹에서 피어 청크를 병합할지 여부예요.	Boolean

사용법 (Usage)

입력 타입 (Input Types)

컴포넌트는 메시지 바디에서 다음 입력 타입들을 받아들여요:

String - 문서 내용이에요. 엔드포인트가 옵트인할 때만 위치로 읽혀요 - 아래 입력 소스를 참고하세요
byte[] - 바이너리 문서 내용이에요
File - 파일 객체예요
InputStream - 문서 데이터를 담은 입력 스트림이에요

배치 연산의 바디는 파일 경로의 List<String>이나 String[], List<File>이나 File[], 또는 디렉터리 경로 String 하나일 수도 있어요.

입력 소스 (Input Sources)

String 바디는 애매해요: 문서 그 자체일 수도, 가져올 URL일 수도, 읽을 경로일 수도 있거든요. 기본으로 컴포넌트는 이를 문서로 취급하고, 두 가지 위치 해석은 명시적으로 활성화해야 해요:

Option	Default	Effect when enabled
`allowUrlSource`	`false`	`http://` 또는 `https://`로 시작하는 바디가, 가져올 원격 URL로 Docling에 넘겨져요.
`allowFilePathSource`	`false`	`/`로 시작하거나 `\`를 포함하는 바디가 로컬 파일시스템에서 읽혀요. 배치 연산이 받아들이는 디렉터리-또는-파일 `String` 바디 하나도 여기에 해당해요.
`inputBaseDirectory`	(none)	설정하면, 정규화를 마친 뒤의 모든 로컬 입력 경로가 이 디렉터리 안쪽에 있어야 해요. `CamelDoclingInputFilePath` 헤더, 파일 경로 바디, 배치 연산이 쓰는 경로에 적용돼요.
`outputBaseDirectory`	(none)	설정하면, docling CLI에 넘기는 출력 디렉터리가 정규화를 마친 뒤 이 디렉터리 안쪽에 있어야 해요. `CamelDoclingOutputFilePath` 헤더에 적용돼요.

두 옵션 모두 기본값으로 두면, URL도 경로도 아닌 바디는 임시 파일로 쓰여서 문서 내용으로 변환돼요. 예전과 똑같이 동작하는 거죠.

CamelDoclingInputFilePath 헤더는 라우트가 주는 명시적인 "문서는 여기 있다" 신호라서, allowFilePathSource 없이도 계속 동작해요. 다만 inputBaseDirectory가 설정되어 있으면 그 제한은 그대로 받아요. File, byte[], InputStream, 그리고 배치 연산이 쓰는 명시적 경로 컬렉션 같은 타입이 정해진 바디들은 애매하지 않아서 마찬가지로 영향을 받지 않아요.

CLI의 --output 디렉터리를 고르는 CamelDoclingOutputFilePath 헤더는 어휘적으로 정규화되고, outputBaseDirectory가 설정되어 있으면 그 디렉터리 안쪽으로 한정돼요. 정규화는 무조건 적용되고, outputBaseDirectory가 없으면 트래버설 세그먼트가 없는 헤더 값은 그대로 쓰여요. 포함 여부 검사는 어휘적으로 이뤄지고 심볼릭 링크를 해석하지 않아요 (inputBaseDirectory와 같아요).

// the body is the document itself - no opt-in needed
from("direct:content")
    .to("docling:convert?operation=CONVERT_TO_MARKDOWN");

// the body is a path, confined to /var/docs
from("direct:paths")
    .to("docling:convert?operation=CONVERT_TO_MARKDOWN&allowFilePathSource=true&inputBaseDirectory=/var/docs");

출력 동작 (Output Behavior)

컴포넌트 동작은 contentInBody 설정 옵션에 따라 달라져요:

contentInBody=true일 때 (기본값: false): 변환된 내용이 교환 바디에 담기고, 출력 파일은 자동으로 삭제돼요
contentInBody=false일 때: 생성된 출력 파일의 파일 경로가 교환 바디로 반환돼요

예제 (Examples)

Markdown으로 기본 문서 변환하기

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_MARKDOWN")
    .to("file:///data/output");

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
        - to:
            uri: file:///data/output

바디에 내용을 담아 HTML로 변환하기

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_HTML?contentInBody=true")
    .process(exchange -> {
        String htmlContent = exchange.getIn().getBody(String.class);
        // Process the HTML content
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_HTML
            parameters:
              contentInBody: true
        - process:
            ref: "htmlProcessor"

문서에서 구조화된 데이터 추출하기

docling-serve API 모드를 쓰면, EXTRACT_STRUCTURED_DATA가 테이블 구조 인식을 기본으로 활성화한 채 DoclingDocument 객체를 반환해요. CLI 모드에서는 JSON 출력이 DoclingDocument로 파싱돼요.

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:EXTRACT_STRUCTURED_DATA?useDoclingServe=true&contentInBody=true")
    .process(exchange -> {
        DoclingDocument doc = exchange.getIn().getBody(DoclingDocument.class);

        // Access tables extracted from the document
        List<DoclingDocument.TableItem> tables = doc.getTables();
        for (DoclingDocument.TableItem table : tables) {
            DoclingDocument.TableData data = table.getData();
            log.info("Table: {}x{}", data.getNumRows(), data.getNumCols());
        }
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:EXTRACT_STRUCTURED_DATA
            parameters:
              useDoclingServe: true
              contentInBody: true
        - process:
            ref: "structuredDataProcessor"

OCR을 끄고 변환하기

CLI 모드에서는 enableOCR=false를 쓰세요. API 모드에서 enableOCR=false를 설정하면 서버에 doOcr(false)가 전달돼요. API 모드 제어에는 doOcr 프로퍼티를 직접 쓸 수도 있어요.

// CLI mode
from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_MARKDOWN?enableOCR=false")
    .to("file:///data/output");

// API mode
from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_MARKDOWN?useDoclingServe=true&doOcr=false&contentInBody=true")
    .to("file:///data/output");

# CLI mode
- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
            parameters:
              enableOCR: false
        - to:
            uri: file:///data/output

# API mode
- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
            parameters:
              useDoclingServe: true
              doOcr: false
              contentInBody: true
        - to:
            uri: file:///data/output

OCR과 페이지 헤더/푸터

Docling은 OCR을 수행하는 동안 페이지 헤더와 푸터(페이지 번호, 저작권 문구, 반복 제목, 각주 등)를 인식해서, docling의 FURNITURE 콘텐츠 레이어에서 페이지 _furniture_로 분류해요.

Docling의 Markdown, 텍스트, HTML 내보내기는 기본으로 BODY 레이어만 담아요. 그래서 OCR 엔진이 제대로 읽었더라도 헤더·푸터 텍스트는 변환 출력에서 빠져요. useDoclingServe=true를 쓸 때는 docling-serve가 콘텐츠 레이어 선택 옵션을 노출하지 않기 때문에, 컴포넌트가 현재 FURNITURE 레이어를 포함할 수 없어요. 이 내용은 docling-serve#271에서 추적 중이에요.

헤더로 처리 제어하기

from("file:///data/documents?include=.*\\.pdf")
    .setHeader("CamelDoclingOperation", constant(DoclingOperations.CONVERT_TO_HTML))
    .setHeader("CamelDoclingEnableOCR", constant(true))
    .setHeader("CamelDoclingOCRLanguage", constant("es"))
    .to("docling:CONVERT_TO_MARKDOWN")  // Operation will be overridden by header
    .to("file:///data/output");

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - setHeader:
            name: "CamelDoclingOperation"
            expression:
              constant:
                expression: "CONVERT_TO_HTML"
        - setHeader:
            name: "CamelDoclingEnableOCR"
            expression:
              constant:
                expression: true
        - setHeader:
            name: "CamelDoclingOCRLanguage"
            expression:
              constant:
                expression: "es"
        - to:
            uri: docling:CONVERT_TO_MARKDOWN  # Operation will be overridden by header
        - to:
            uri: file:///data/output

커스텀 인자로 처리하기

from("file:///data/documents?include=.*\\.pdf")
    .process(exchange -> {
        List<String> customArgs = Arrays.asList("--verbose", "--preserve-tables");
        exchange.getIn().setHeader("CamelDoclingCustomArguments", customArgs);
    })
    .to("docling:CONVERT_TO_MARKDOWN")
    .to("file:///data/output");

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - setHeader:
            name: "CamelDoclingCustomArguments"
            expression:
              method:
                ref: "customArgsBean"
                method: "createCustomArgs"
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
        - to:
            uri: file:///data/output

커스텀 인자 검증

CamelDoclingCustomArguments 헤더로 커스텀 CLI 인자를 넘길 때, 컴포넌트는 알려진 docling CLI 플래그의 **allowlist(허용 목록)**를 강제해요. 다음 플래그만 허용돼요:

Category	Allowed flags
입력/출력 포맷	`--from`, `--to`
파이프라인	`--pipeline`, `--vlm-model`, `--asr-model`
OCR	`--ocr`, `--no-ocr`, `--force-ocr`, `--no-force-ocr`, `--ocr-engine`, `--ocr-lang`, `--psm`
테이블	`--tables`, `--no-tables`, `--table-mode`
PDF	`--pdf-backend`, `--pdf-password`
인리치먼트	`--enrich-code`, `--no-enrich-code`, `--enrich-formula`, `--no-enrich-formula`, `--enrich-picture-classes`, `--no-enrich-picture-classes`, `--enrich-picture-description`, `--no-enrich-picture-description`, `--enrich-chart-extraction`, `--no-enrich-chart-extraction`
출력 포매팅	`--image-export-mode`, `--show-layout`, `--no-show-layout`
고급	`--headers`, `--artifacts-path`, `--enable-remote-services`, `--no-enable-remote-services`, `--allow-external-plugins`, `--no-allow-external-plugins`, `--show-external-plugins`, `--no-show-external-plugins`, `--document-timeout`, `--device`, `--num-threads`, `--page-batch-size`
디버그	`--verbose`, `-v` / `-vv` / `-vvv`, `--debug-visualize-cells`, `--no-debug-visualize-cells`, `--debug-visualize-ocr`, `--no-debug-visualize-ocr`, `--debug-visualize-layout`, `--no-debug-visualize-layout`, `--debug-visualize-tables`, `--no-debug-visualize-tables`
성능	`--abort-on-error`, `--no-abort-on-error`, `--profiling`, `--no-profiling`, `--save-profiling`, `--no-save-profiling`
정보	`--version`, `--help`, `--logo`

출력 디렉터리는 프로듀서가 관리하기 때문에 --output (-o) 플래그는 허용되지 않아요. 대신 CamelDoclingOutputFilePath 헤더나 엔드포인트 설정을 사용하세요. 그 헤더는 정규화되고, outputBaseDirectory가 설정되어 있으면 그 디렉터리 안쪽으로 한정돼요 (위의 보안 옵션을 참고하세요).

그리고 다음은 거절돼요:

셸 메타문자: ;, |, ` , $() — ProcessBuilder가 해석하지 않더라도 다층 방어 차원에서 차단돼요.
경로 트래버설: ../, ..\, 그리고 정규화 후 트래버설로 해석되는 경로.
알 수 없는 플래그: 위 allowlist에 없는 모든 플래그.

문서 메타데이터 추출하기

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:EXTRACT_METADATA")
    .process(exchange -> {
        DocumentMetadata metadata = exchange.getIn().getBody(DocumentMetadata.class);

        // Access metadata fields
        String title = metadata.getTitle();
        String documentType = metadata.getDocumentType();
        Integer pageCount = metadata.getPageCount();
        String format = metadata.getFormat();

        log.info("Document: {} ({}), Pages: {}, Format: {}",
            title, documentType, pageCount, format);

        // Metadata is also available in headers
        String titleFromHeader = exchange.getIn().getHeader("CamelDoclingMetadataTitle", String.class);
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:EXTRACT_METADATA
        - log:
            message: "Document: ${header.CamelDoclingMetadataTitle} (${header.CamelDoclingMetadataDocumentType})"
        - log:
            message: "Pages: ${header.CamelDoclingMetadataPageCount}"
        - process:
            ref: "metadataProcessor"

모든 필드로 메타데이터 추출하기

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:EXTRACT_METADATA?includeRawMetadata=true")
    .process(exchange -> {
        DocumentMetadata metadata = exchange.getIn().getBody(DocumentMetadata.class);

        log.info("Page Count: {}", metadata.getPageCount());

        // Raw metadata from parser
        Map<String, Object> rawMetadata = metadata.getRawMetadata();
        log.info("Raw metadata: {}", rawMetadata);
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:EXTRACT_METADATA
            parameters:
              includeRawMetadata: true
        - process:
            ref: "fullMetadataProcessor"

메타데이터 기반으로 문서 라우팅하기

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:EXTRACT_METADATA")
    .choice()
        .when(simple("${header.CamelDoclingMetadataPageCount} > 100"))
            .log("Large document with ${header.CamelDoclingMetadataPageCount} pages")
            .to("file:///data/large-docs")
        .when(simple("${header.CamelDoclingMetadataLanguage} == 'fr'"))
            .log("French document")
            .to("file:///data/french-docs")
        .otherwise()
            .to("file:///data/other-docs")
    .end();

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:EXTRACT_METADATA
        - choice:
            when:
              - expression:
                  simple:
                    expression: "${header.CamelDoclingMetadataPageCount} > 100"
                steps:
                  - log:
                      message: "Large document with ${header.CamelDoclingMetadataPageCount} pages"
                  - to:
                      uri: file:///data/large-docs
              - expression:
                  simple:
                    expression: "${header.CamelDoclingMetadataLanguage} == 'fr'"
                steps:
                  - log:
                      message: "French document"
                  - to:
                      uri: file:///data/french-docs
            otherwise:
              steps:
                - to:
                    uri: file:///data/other-docs

헤더 없이 메타데이터 추출하기

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:EXTRACT_METADATA?includeMetadataInHeaders=false")
    .process(exchange -> {
        DocumentMetadata metadata = exchange.getIn().getBody(DocumentMetadata.class);

        // All metadata is in the body object only
        // Headers are not populated with metadata fields
        log.info("Metadata: {}", metadata);
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:EXTRACT_METADATA
            parameters:
              includeMetadataInHeaders: false
        - process:
            ref: "metadataBodyProcessor"

바디 내용 vs 파일 경로 출력

// Get content directly in body (file is automatically deleted)
from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_MARKDOWN?contentInBody=true")
    .process(exchange -> {
        String markdownContent = exchange.getIn().getBody(String.class);
        log.info("Converted content: {}", markdownContent);
    });

// Get file path (file is preserved)
from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_MARKDOWN?contentInBody=false")
    .process(exchange -> {
        String outputFilePath = exchange.getIn().getBody(String.class);
        log.info("Output file saved at: {}", outputFilePath);
    });

# Get content directly in body (file is automatically deleted)
- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
            parameters:
              contentInBody: true
        - process:
            ref: "contentProcessor"

# Get file path (file is preserved)
- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
            parameters:
              contentInBody: false
        - process:
            ref: "filePathProcessor"

프로세서 빈 예제 (Processor Bean Examples)

YAML DSL을 사용할 때, 위 예제에서 쓴 프로세서 참조는 Spring 빈으로 구현하면 돼요:

Java 전용: Spring 빈 Processor 구현체

@Component("htmlProcessor")
public class HtmlProcessor implements Processor {
    @Override
    public void process(Exchange exchange) throws Exception {
        String htmlContent = exchange.getIn().getBody(String.class);
        // Process the HTML content
        log.info("Processing HTML content of length: {}", htmlContent.length());
    }
}

@Component("structuredDataProcessor")
public class StructuredDataProcessor implements Processor {
    private static final Logger log = LoggerFactory.getLogger(StructuredDataProcessor.class);

    @Override
    public void process(Exchange exchange) throws Exception {
        DoclingDocument doc = exchange.getIn().getBody(DoclingDocument.class);
        log.info("Document schema: {}, tables: {}", doc.getSchemaName(), doc.getTables().size());
    }
}

@Component("contentProcessor")
public class ContentProcessor implements Processor {
    private static final Logger log = LoggerFactory.getLogger(ContentProcessor.class);

    @Override
    public void process(Exchange exchange) throws Exception {
        String markdownContent = exchange.getIn().getBody(String.class);
        log.info("Converted content: {}", markdownContent);
    }
}

@Component("filePathProcessor")
public class FilePathProcessor implements Processor {
    private static final Logger log = LoggerFactory.getLogger(FilePathProcessor.class);

    @Override
    public void process(Exchange exchange) throws Exception {
        String outputFilePath = exchange.getIn().getBody(String.class);
        log.info("Output file saved at: {}", outputFilePath);
    }
}

@Component("customArgsBean")
public class CustomArgsBean {
    public List<String> createCustomArgs() {
        return Arrays.asList("--verbose", "--preserve-tables");
    }
}

문서 청킹 (Document Chunking)

컴포넌트는 docling-serve를 통한 문서 청킹을 지원해요. 문서를 RAG(Retrieval-Augmented Generation) 파이프라인, 벡터 데이터베이스, 기타 NLP 워크플로우에 적합한 의미 있는 청크로 나눠 주는 거죠. 단순 텍스트 분할과 달리 docling 청킹은 구조를 인식해요 — 문서의 제목, 문단, 테이블을 존중하죠 — 그리고 하이브리드 청커는 토큰도 인식해서, 청크가 모델 토큰 한도 안에 들어가도록 해 줘요.

참고 두 청킹 연산 모두 useDoclingServe=true가 필요해요. Docling CLI는 청킹을 명령으로 노출하지 않아요 — 청킹은 docling-serve REST API로만 가능해요.

CHUNK_HYBRID은 HybridChunker를 사용해요. 구조와 토큰을 모두 인식하죠. 문서 구조를 존중하면서 각 청크가 설정 가능한 토큰 한도 안에 머물도록 해 줘요. 고정 토큰 윈도우를 가진 임베딩 모델을 쓰는 RAG 파이프라인에 가장 잘 맞아요. chunkingTokenizer, chunkingMaxTokens, chunkingMergePeers 옵션으로 설정하세요 (위의 엔드포인트 옵션 표를 참고하세요).

CHUNK_HIERARCHICAL은 HierarchicalChunker를 사용해요. 구조만 인식하죠. 토큰 한도를 강제하지 않으면서 문서 구조 경계(섹션, 문단)에서 나눠요. 완전한 구조 단위를 보존하는 게 청크 크기보다 중요할 때 가장 좋아요.

contentInBody=true이면 교환 바디가 List<Chunk>(ai.docling.serve.api.chunk.response.Chunk)로 설정돼서, Camel의 .split(body()) EIP에 바로 쓸 수 있어요. 각 Chunk 객체는 다음을 제공해요:

text — 청크 텍스트 내용
chunkIndex — 문서에서의 0 기준 위치
filename — 원본 문서 파일 이름
headings — 이 청크로 이어지는 제목 문자열 목록
pageNumbers — 이 청크가 걸쳐 있는 페이지 번호 목록
captions — 캡션 목록 (예: 테이블이나 그림 캡션)
numTokens — 토큰 수 (하이브리드 청커만)

contentInBody=false이면 전체 ChunkDocumentResponse가 반환돼요.

기본 청킹 (Basic Chunking)

from("file:///data/documents?include=.*\\.pdf")
    .setHeader("CamelDoclingInputFilePath", simple("${file:absolute.path}"))
    .to("docling:CHUNK_HYBRID?" +
        "useDoclingServe=true&" +
        "contentInBody=true&" +
        "chunkingTokenizer=sentence-transformers/all-MiniLM-L6-v2&" +
        "chunkingMaxTokens=128&" +
        "chunkingMergePeers=true")
    .split(body())
        .log("Chunk ${body.chunkIndex}: ${body.text}")
    .end();

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - setHeader:
            name: CamelDoclingInputFilePath
            expression:
              simple:
                expression: "${file:absolute.path}"
        - to:
            uri: docling:CHUNK_HYBRID
            parameters:
              useDoclingServe: true
              contentInBody: true
              chunkingTokenizer: "sentence-transformers/all-MiniLM-L6-v2"
              chunkingMaxTokens: 128
              chunkingMergePeers: true
        - split:
            expression:
              simple:
                expression: "${body}"
            steps:
              - log:
                  message: "Chunk ${body.chunkIndex}: ${body.text}"

RAG 파이프라인을 위한 청킹 (Chunking for RAG Pipelines)

흔한 사용 사례는 문서를 청킹하고, 임베딩을 생성하고, 벡터 데이터베이스에 저장하는 거예요:

from("direct:ingest-pdf")
    .setHeader("CamelDoclingInputFilePath", header("pdfFilePath"))
    .to("docling:CHUNK_HYBRID?" +
        "useDoclingServe=true&" +
        "contentInBody=true&" +
        "chunkingTokenizer={{embedding.tokenizer}}&" +
        "chunkingMaxTokens={{embedding.max-tokens}}&" +
        "chunkingMergePeers=true")
    .split(body())
        .setBody(simple("${body.text}"))
        .to("openai:embeddings?embeddingModel={{embedding.model}}")
        // store embedding in vector database
        .to("direct:store-embedding")
    .end();

- route:
    id: ingest-pdf
    from:
      uri: direct:ingest-pdf
      steps:
        - setHeader:
            name: CamelDoclingInputFilePath
            expression:
              simple:
                expression: "${header.pdfFilePath}"
        - to:
            uri: docling:CHUNK_HYBRID
            parameters:
              useDoclingServe: true
              contentInBody: true
              chunkingTokenizer: "{{embedding.tokenizer}}"
              chunkingMaxTokens: "{{embedding.max-tokens}}"
              chunkingMergePeers: true
        - split:
            expression:
              simple:
                expression: "${body}"
            steps:
              - setBody:
                  expression:
                    simple:
                      expression: "${body.text}"
              - to:
                  uri: openai:embeddings
                  parameters:
                    embeddingModel: "{{embedding.model}}"
              - to:
                  uri: direct:store-embedding

계층적 청킹 (Hierarchical Chunking)

토큰 한도 없이 완전한 구조 단위를 보존하고 싶을 때 계층적 청킹을 사용하세요:

from("file:///data/documents?include=.*\\.pdf")
    .setHeader("CamelDoclingInputFilePath", simple("${file:absolute.path}"))
    .to("docling:CHUNK_HIERARCHICAL?" +
        "useDoclingServe=true&" +
        "contentInBody=true")
    .split(body())
        .log("Section [${body.headings}] page ${body.pageNumbers}: ${body.text}")
    .end();

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - setHeader:
            name: CamelDoclingInputFilePath
            expression:
              simple:
                expression: "${file:absolute.path}"
        - to:
            uri: docling:CHUNK_HIERARCHICAL
            parameters:
              useDoclingServe: true
              contentInBody: true
        - split:
            expression:
              simple:
                expression: "${body}"
            steps:
              - log:
                  message: "Section [${body.headings}] page ${body.pageNumbers}: ${body.text}"

고급 처리 옵션 (Advanced Processing Options (API Mode))

docling-serve API 모드(useDoclingServe=true)를 사용할 때, 컴포넌트는 서버가 문서를 처리하는 방식을 제어하는 고급 처리 옵션을 노출해요. 이 옵션들은 docling-serve API로 직접 전달되고, OCR·테이블 인식·인리치먼트 기능·출력 포매팅을 세밀하게 제어하게 해 줘요.

OCR 옵션 (OCR Options)

Parameter	Default	Description
`doOcr`	not set	docling-serve API 모드에서 OCR 처리를 활성화해요. 설정하지 않으면 서버가 자체 기본값을 사용해요. OCR을 명시적으로 끄려면 `enableOCR`을 `false`로 설정하세요.
`forceOcr`	not set	디지털 문서(선택 가능한 텍스트가 있는 문서)라도 OCR 처리를 강제해요.
`ocrEngine`	not set	사용할 OCR 엔진이에요. 지원 값: `AUTO`, `EASYOCR`, `OCRMAC`, `RAPIDOCR`, `TESSEROCR`, `TESSERACT`.

참고 enableOCR과 ocrLanguage 설정은 주로 CLI 모드용이에요. API 모드에서는 doOcr로 OCR 동작을 명시적으로 제어하세요. doOcr이 설정되지 않으면 서버가 자체 기본값을 사용해요. enableOCR=false로 설정하면 OCR을 끄도록 서버에 doOcr(false)가 전달돼요.

테이블·구조 옵션 (Table and Structure Options)

Parameter	Default	Description
`doTableStructure`	not set	테이블 구조 인식을 활성화해요. `EXTRACT_STRUCTURED_DATA` 연산에서는 자동으로 활성화돼요.
`tableMode`	not set	테이블 구조 인식 모드예요. 지원 값: `ACCURATE`, `FAST`.
`tableCellMatching`	not set	더 나은 셀 경계 감지를 위해 테이블 셀 매칭 후처리를 활성화해요.

인리치먼트 옵션 (Enrichment Options)

Parameter	Default	Description
`doCodeEnrichment`	not set	문서 처리에서 코드 인리치먼트를 활성화해요. Identifies and annotates code blocks.
`doFormulaEnrichment`	not set	문서 처리에서 수식 인리치먼트를 활성화해요. Detects and processes mathematical formulas.
`doPictureClassification`	not set	그림 분류(예: 차트, 사진, 다이어그램)를 활성화해요. 서버에 추가 ML 모델이 필요할 수 있어요.
`doPictureDescription`	not set	그림 설명 생성을 활성화해요. 서버에 비전 언어 모델(VLM)이 필요할 수 있어요.

파이프라인·출력 옵션 (Pipeline and Output Options)

Parameter	Default	Description
`pipeline`	not set	사용할 처리 파이프라인이에요. 지원 값: `ASR`, `STANDARD`, `VLM`.
`pdfBackend`	not set	PDF 파싱 백엔드예요. 지원 값: `DLPARSE_V1`, `DLPARSE_V2`, `DLPARSE_V4`, `PYPDFIUM2`.
`includeImages`	not set	변환 출력에 이미지를 포함해요.
`imageExportMode`	not set	참조된 이미지의 내보내기 모드예요. 지원 값: `EMBEDDED`, `PLACEHOLDER`, `REFERENCED`.
`imagesScale`	not set	내보낸 이미지의 배율 팩터예요 (예: 두 배 해상도는 `2.0`).
`mdPageBreakPlaceholder`	not set	markdown 출력에서 페이지 나눔 자리표(placeholder) 문자열이에요.
`abortOnError`	not set	부분 결과로 계속 진행하는 대신, 에러가 나면 처리를 중단해요.
`documentTimeout`	not set	문서 처리 타임아웃(초, 서버 쪽 타임아웃)이에요.

예제: 고급 처리 설정 (Example: Advanced Processing Configuration)

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:EXTRACT_STRUCTURED_DATA?" +
        "useDoclingServe=true&" +
        "doOcr=true&" +
        "ocrEngine=TESSERACT&" +
        "doTableStructure=true&" +
        "tableMode=ACCURATE&" +
        "doCodeEnrichment=true&" +
        "pdfBackend=DLPARSE_V4&" +
        "processTimeout=120000&" +     // 2 minutes for complex PDFs
        "contentInBody=true")
    .process(exchange -> {
        DoclingDocument doc = exchange.getIn().getBody(DoclingDocument.class);
        // Process the structured document
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:EXTRACT_STRUCTURED_DATA
            parameters:
              useDoclingServe: true
              doOcr: true
              ocrEngine: "TESSERACT"
              doTableStructure: true
              tableMode: "ACCURATE"
              doCodeEnrichment: true
              pdfBackend: "DLPARSE_V4"
              processTimeout: 120000
              contentInBody: true
        - process:
            ref: "structuredDataProcessor"

DoclingDocument 반환 타입 (DoclingDocument Return Type)

docling-serve API 모드를 사용하면, CONVERT_TO_JSON과 EXTRACT_STRUCTURED_DATA 연산이 원시 JSON 문자열 대신 DoclingDocument 객체(ai.docling.core 패키지)를 반환해요. 이 객체는 문서 구조에 타입 세이프하게 접근하게 해 줘요.

from("file:///data/documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_JSON?" +
        "useDoclingServe=true&" +
        "contentInBody=true")
    .process(exchange -> {
        DoclingDocument doc = exchange.getIn().getBody(DoclingDocument.class);

        // Access document structure
        String schemaName = doc.getSchemaName();

        // Access tables
        List<DoclingDocument.TableItem> tables = doc.getTables();
        for (DoclingDocument.TableItem table : tables) {
            DoclingDocument.TableData data = table.getData();
            int rows = data.getNumRows();
            int cols = data.getNumCols();
            log.info("Table: {}x{}", rows, cols);
        }

        // Access pictures
        List<DoclingDocument.PictureItem> pictures = doc.getPictures();
        log.info("Found {} pictures", pictures.size());
    });

- route:
    from:
      uri: file:///data/documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_JSON
            parameters:
              useDoclingServe: true
              contentInBody: true
        - process:
            ref: "doclingDocumentProcessor"

비동기 변환 소비하기 (Consuming asynchronous conversions)

SUBMIT_ASYNC_CONVERSION으로 변환을 제출한 뒤 CHECK_CONVERSION_STATUS를 손으로 폴링하는 대신, docling: 컨슈머가 각 비동기 변환을 이벤트 기반으로, 끝나는 즉시 내보낼 수 있어요:

// submit conversions asynchronously; each returns a task id and runs in the background
from("direct:submit")
    .to("docling:convert?useDoclingServe=true&operation=SUBMIT_ASYNC_CONVERSION");

// the consumer emits one exchange per completed task; the path ("onComplete") is still the required operationId,
// but the consumer ignores the operation — it always drains the component's completed tasks
from("docling:onComplete?useDoclingServe=true&delay=5000")
    .to("mock:done");

컨슈머는 같은 컴포넌트에서 SUBMIT_ASYNC_CONVERSION으로 제출된 태스크를 훑으면서, 각 태스크가 완료될 때마다 교환(exchange)을 하나씩 내보내요:

성공한 변환은 변환된 내용을 메시지 바디로 실어요 — 태스크가 제출될 때 쓰인 outputFormat(CamelDoclingOutputFormat 헤더 또는 제출한 엔드포인트의 outputFormat)으로 추출돼요. docling-serve가 요청된 포맷만 반환하기 때문이에요 — 그리고 CamelDoclingTaskId 헤더에 태스크 ID가 담겨요;
실패한 변환은 근본 예외와 함께 교환을 완료해서, 라우트의 onException 메커니즘이 적용돼요.

예약 폴링 컨슈머라서, 폴링 간격과 다른 스케줄러 옵션들(delay, initialDelay, useFixedDelay, …)은 평소처럼 엔드포인트에 설정해요.

참고 컨슈머는 컴포넌트 전체의 태스크를 가져가요. 어떤 엔드포인트, 경로, 옵션이 제출했든 상관없어요. docling 컴포넌트당 컨슈머는 최대 하나만 실행하세요 — 두 번째 컨슈머가 같은 태스크를 두고 경쟁하고, 완료된 태스크는 먼저 가져간 컨슈머가 내보내요.

컨슈머가 완료된 태스크를 공유 레지스트리에서 제거하기 때문에, 같은 컴포넌트에서 손으로 CHECK_CONVERSION_STATUS 폴링하는 것과 섞어 쓰지 마세요: 컨슈머가 태스크를 가져간 뒤에는, 그 ID로 나중에 상태를 확인해도 로컬에서 더 이상 찾을 수 없고 서버로 폴백하는데, 서버는 로컬 태스크 ID를 모르거든요.

대기 중인 태스크는 컴포넌트의 인메모리 맵에 살아 있고, 같은 CamelContext에서만 보여요. 영속화되지 않아서 — 재시작하면 사라지고, 컨텍스트를 멈추면 아직 진행 중인 변환도 취소돼요.

에러 처리 (Error Handling)

컴포넌트는 다양한 에러 시나리오를 다뤄요:

파일 크기 한도 초과: maxFileSize보다 큰 파일은 거절돼요
프로세스 타임아웃: 오래 걸리는 변환은 processTimeout 밀리초 후에 종료돼요
잘못된 파일 포맷: 지원하지 않는 파일 포맷은 처리 에러로 이어져요
Docling을 찾을 수 없음: Docling 설치가 없으면 시작이 실패해요 (CLI 모드)
연결 에러: docling-serve API 모드를 사용할 때 API 엔드포인트 연결 실패는 에러로 이어져요
인증 에러: 잘못되었거나 없는 인증 자격 증명은 docling-serve API의 401 Unauthorized 에러로 이어져요

성능 고려 사항 (Performance Considerations)

프로세스 타임아웃: processTimeout 설정(기본값: 30000ms / 30초)은 CLI 서브프로세스 타임아웃과 docling-serve API 모드의 HTTP 읽기 타임아웃을 모두 제어해요. OCR이나 인리치먼트 처리가 필요한 복잡한 PDF 문서라면 이 값을 늘리세요 (예: 2분이면 processTimeout=120000).
OCR 처리는 스캔 문서의 처리 시간을 크게 늘려요.
docling-serve API 모드를 사용할 때는 contentInBody=true를 써서 결과를 바디로 바로 받는 것을 고려하세요.
maxFileSize 설정은 리소스 고갈을 막는 데 도움이 돼요.
API 모드 vs CLI 모드: docling-serve API 모드는 영속적인 서버 인스턴스를 유지하기 때문에, 대량 문서 처리에서 보통 더 나은 성능과 리소스 활용도를 보여 줘요.
비동기 모드: 큰 문서나 대량 처리에서는 useAsyncMode=true를 켜서 Camel 스레드 풀이 막히는 걸 막으세요. 컨슈머 컴포넌트는 처리 스레드를 풀어 둔 채 docling-serve API에 완료 상태를 폴링해요.
비동기 설정: 문서 크기와 처리 요구 사항에 맞춰 asyncPollInterval(기본 2000ms)과 asyncTimeout(기본 300000ms/5분)을 조정하세요.
배치 처리: 여러 문서를 처리할 때 비동기 모드는 더 나은 병렬화를 가능하게 해요. Camel이 결과를 폴링하는 동안 docling-serve 인스턴스가 여러 문서를 동시에 처리할 수 있거든요.
인리치먼트 기능: doPictureClassification이나 doPictureDescription 같은 고급 옵션을 켜면 서버에 추가 ML 모델이 필요할 수 있고, 처리 시간이 늘어날 수 있어요.

하위 페이지 (Sub-Pages)

특정 기능의 자세한 내용은 다음을 참고하세요:

Batch Processing - 배치 연산, 큐 기반 처리, 에러 처리, 결과 분할
Asynchronous Processing - 비동기 모드, 커스텀 타임아웃, 폴링 패턴, 병렬 처리
Using Docling-Serve API - 원격 API 사용, URL 처리, 인증 방법

HTTP 클라이언트 설정 (HTTP Client Configuration)

docling-serve API 모드를 사용할 때, 컴포넌트는 내부적으로 Java 내장 HttpClient를 쓰는 docling-java 라이브러리를 사용해요. HTTP 클라이언트는 합리적인 기본값으로 설정되고, 연결 관리는 라이브러리가 알아서 처리해요.

타임아웃 설정 (Timeout Configuration)

Parameter	Default	Description
`processTimeout`	30000	동기 API 호출의 HTTP 읽기 타임아웃(밀리초)이에요. CLI 서브프로세스 타임아웃으로도 쓰여요. 크거나 복잡한 문서라면 늘리세요 (예: 2분이면 120000).
`asyncPollInterval`	2000	비동기 태스크 상태를 확인할 때의 폴링 간격(밀리초)이에요.
`asyncTimeout`	300000	비동기 변환 완료를 기다리는 최대 시간(밀리초, 5분)이에요.
`asyncTaskTtl`	86400000	대기 중인 비동기 변환 태스크의 TTL(밀리초, 24시간)이에요. 이보다 오래된 태스크는 누수를 막기 위해 메모리에서 자동으로 제거돼요. 백그라운드 정리 작업이 주기적으로 돌면서 만료된 항목을 지워요.

중요 기본 processTimeout인 30초는 복잡한 PDF 문서, 특히 OCR이나 인리치먼트 옵션이 켜져 있을 때는 부족할 수 있어요. PDF 파일을 실제 운영에서 쓴다면 processTimeout을 최소 120000(2분)으로 늘리는 것을 고려하세요.

설정 예제 (Configuration Examples)

장시간 문서 처리 (Long-Running Document Processing)

처리가 오래 걸리는 큰 문서라면 비동기 타임아웃을 늘리세요:

from("file:///data/large-documents?include=.*\\.pdf")
    .to("docling:CONVERT_TO_MARKDOWN?" +
        "useDoclingServe=true&" +
        "useAsyncMode=true&" +
        "asyncPollInterval=5000&" +      // Check every 5 seconds
        "asyncTimeout=600000&" +          // 10 minutes timeout
        "contentInBody=true")
    .to("file:///data/output");

- route:
    from:
      uri: file:///data/large-documents
      parameters:
        include: ".*\\.pdf"
      steps:
        - to:
            uri: docling:CONVERT_TO_MARKDOWN
            parameters:
              useDoclingServe: true
              useAsyncMode: true
              asyncPollInterval: 5000
              asyncTimeout: 600000
              contentInBody: true
        - to:
            uri: file:///data/output

모범 사례 (Best Practices)

큰 문서에는 비동기 모드를 사용하세요: 처리가 오래 걸릴 수 있는 문서에는 useAsyncMode=true를 켜세요. docling-java 라이브러리가 폴링을 알아서 처리해요.
폴링 간격을 적절히 조정하세요: 대량 처리 시나리오에서는 asyncPollInterval을 늘려서 폴링 오버헤드를 줄이세요. 대화형 사용 사례에서는 짧은 간격이 더 빠른 피드백을 줘요.
적절한 타임아웃을 설정하세요: 예상되는 가장 큰 문서 크기에 맞춰 asyncTimeout을 조정하세요. 기본 5분이면 대부분의 문서에 적합해요.
로깅으로 모니터링하세요: DEBUG 레벨 로깅으로 API 호출과 비동기 태스크 상태를 모니터링하세요.

더 알아보기 (Learn more)

Batch Processing — 배치 연산, 큐 기반 처리, 에러 처리, 결과 분할
Asynchronous Processing — 비동기 모드, 커스텀 타임아웃, 폴링 패턴, 병렬 처리
Using Docling-Serve API — 원격 API 사용, URL 처리, 인증 방법
IBM Docling — Docling 문서 파서 저장소
docling-java — docling-serve 통신용 공식 Java 클라이언트
docling-serve#271 — FURNITURE 콘텐츠 레이어 노출 이슈

CLI 모드로 가볍게 시작하든 docling-serve API 모드로 확장하든, 위 본문의 옵션 표와 예제가 출발점이 돼 줄 거예요. 대량 문서를 다루기 전에는 타임아웃 설정과 모범 사례 섹션을 꼭 확인하세요.

Docling

Docling (camel-docling)

본문

전제 조건 (Prerequisites)

URI 형식 (URI format)

지원 연산 (Supported Operations)

옵션 설정 (Configuring Options)

컴포넌트 옵션 설정 (Configuring Component Options)

엔드포인트 옵션 설정 (Configuring Endpoint Options)

컴포넌트 옵션 (Component Options)

엔드포인트 옵션 (Endpoint Options)

경로 파라미터 (Path Parameters)

쿼리 파라미터 (Query Parameters)

메시지 헤더 (Message Headers)

사용법 (Usage)

입력 타입 (Input Types)

입력 소스 (Input Sources)

출력 동작 (Output Behavior)

예제 (Examples)

Markdown으로 기본 문서 변환하기

바디에 내용을 담아 HTML로 변환하기

문서에서 구조화된 데이터 추출하기

OCR을 끄고 변환하기

OCR과 페이지 헤더/푸터

헤더로 처리 제어하기

커스텀 인자로 처리하기

커스텀 인자 검증

문서 메타데이터 추출하기

모든 필드로 메타데이터 추출하기

메타데이터 기반으로 문서 라우팅하기

헤더 없이 메타데이터 추출하기

바디 내용 vs 파일 경로 출력

프로세서 빈 예제 (Processor Bean Examples)

문서 청킹 (Document Chunking)

기본 청킹 (Basic Chunking)

RAG 파이프라인을 위한 청킹 (Chunking for RAG Pipelines)

계층적 청킹 (Hierarchical Chunking)

고급 처리 옵션 (Advanced Processing Options (API Mode))

OCR 옵션 (OCR Options)

테이블·구조 옵션 (Table and Structure Options)

인리치먼트 옵션 (Enrichment Options)

파이프라인·출력 옵션 (Pipeline and Output Options)

예제: 고급 처리 설정 (Example: Advanced Processing Configuration)

DoclingDocument 반환 타입 (DoclingDocument Return Type)

비동기 변환 소비하기 (Consuming asynchronous conversions)

에러 처리 (Error Handling)

성능 고려 사항 (Performance Considerations)

하위 페이지 (Sub-Pages)

HTTP 클라이언트 설정 (HTTP Client Configuration)

타임아웃 설정 (Timeout Configuration)

설정 예제 (Configuration Examples)

장시간 문서 처리 (Long-Running Document Processing)

모범 사례 (Best Practices)

더 알아보기 (Learn more)

함께 읽는 실무 이야기