Docling Convert Action
Provided by: "Apache Software Foundation"
Support Level for this Kamelet is: "Preview"
Turns each document, such as a PDF, an office document or an HTML page, into Markdown, HTML or plain text with Docling, keeping its headings, lists and tables.
Use it to get well-structured text out of documents before an AI step, for example in front of langchain4j-ingest-sink to load them into a vector store. For plain text without a Docling server, use tika-extract-text-action.
Input: the document, as bytes, a stream, a file or text. The header named in documentIdHeader (by default CamelLangChain4jIngestDocumentId) is the id of the document, if any; it is kept for langchain4j-ingest-sink further on.
Output: the body is the document as Markdown, as text, or as HTML or plain text with operation. The headers of the message are kept.
Good to know: to use a Docling Serve server, which is the usual setup, set both useDoclingServe to true and doclingServeUrl; otherwise it runs the docling command-line program, which must be installed on the machine of the integration. A server started with an API key needs authenticationScheme set to API_KEY and the key in authenticationToken. A conversion that takes longer than processTimeout, 30 seconds when it is not set, fails the message; the first conversion after a Docling Serve server starts, and a large PDF on a server without a GPU, can take longer than that. The text in images, such as scanned pages, is read with OCR unless enableOcr is false. With maxDocumentSize, a larger document fails the message without being sent.
Configuration Options
The following table summarizes the configuration options available for the docling-convert-action Kamelet:
| Property | Name | Description | Type | Default | Example |
|---|---|---|---|---|---|
Authentication Scheme | How to send Enum values: * API_KEY * BEARER | string | |||
Authentication Token | The API key or token to log in to the Docling Serve server with, sent as | string | |||
Docling Serve URL | The address of a Docling Serve server, starting with | string | http://docling-serve:5001 | ||
Document ID Header | The name of the header that holds the id of the document, such as its file name. The id is kept for | string | CamelLangChain4jIngestDocumentId | CamelFileName | |
Document Timeout | How long the Docling Serve server may work on one document, in seconds. When the time is up, the server stops, and the body holds only the part of the document it converted, without failing the message. Only used with Docling Serve. When it is not set, the server uses its own limit. | integer | 120 | ||
Enable OCR | If false, the text in images, such as the pages of a scanned PDF, is not read (OCR, optical character recognition), which is faster, and a scanned page gives no text. If true, OCR is asked for, in | boolean | |||
Force OCR | If true, every page is read with OCR, even a page that holds text, whose text is then replaced by what OCR reads. Use it for a PDF whose text layer is wrong. Only used with Docling Serve. | boolean | |||
Max Document Size | The largest document to convert, in bytes. A larger document fails the message without being converted. 0, the default, means no limit. | integer | 0 | 10485760 | |
OCR Engine | The OCR engine that reads the images, which must be installed on the Docling Serve server, else the message fails; Enum values: * AUTO * EASYOCR * RAPIDOCR * TESSERACT * TESSEROCR * OCRMAC | string | |||
OCR Language | The language of the text in images, as a code that the OCR engine knows, such as | string | de | ||
Operation | What the document is turned into. Enum values: * CONVERT_TO_MARKDOWN * CONVERT_TO_HTML * EXTRACT_TEXT | string | CONVERT_TO_MARKDOWN | ||
Process Timeout | How long to wait for a document to be converted, in milliseconds. A slower conversion fails the message. With Docling Serve, it is how long to wait for the answer of the server. When it is not set, 30000 (30 seconds) is used, which is often too short for a large PDF. | integer | 300000 | ||
Use Docling Serve | If true, the documents are converted by the Docling Serve server at | boolean |
Dependencies
At runtime, the docling-convert-action Kamelet relies upon the presence of the following dependencies:
-
camel:docling
-
camel:kamelet
-
camel:bean
Camel JBang usage
Prerequisites
-
You’ve installed JBang.
-
You have executed the following command:
jbang app install camel@apache/camel Supposing you have a file named route.yaml with this content:
- route:
from:
uri: "kamelet:timer-source"
parameters:
period: 10000
message: 'test'
steps:
- to:
uri: "kamelet:docling-convert-action"
parameters:
.
.
.
- to:
uri: "kamelet:log-sink" You can now run it directly through the following command
camel run route.yaml Docling Convert Action Kamelet Description
Docling Serve
Set useDoclingServe to true and doclingServeUrl to the address of a Docling Serve server, such as one started from the quay.io/docling-project/docling-serve image. Without them, the Kamelet runs the docling command-line program on the machine of the integration.
A server started with an API key, in the DOCLING_SERVE_API_KEY environment variable, answers Unauthorized to any request without it. Set authenticationScheme to API_KEY and the key in authenticationToken: it is sent in the X-Api-Key header. For a server behind a gateway that asks for a token in the Authorization header, set authenticationScheme to BEARER instead.
Timeouts
processTimeout is how long the Kamelet waits for the answer of the server, in milliseconds, 30000 when it is not set. A server without a GPU can take longer than that for the first document after it starts, while it loads its models, and for a large PDF: the message then fails. Set it to a few minutes for such a server.
documentTimeout is how long the server may work on one document, in seconds. When the time is up, the body holds only the part of the document converted so far, and the message does not fail.
OCR
OCR (optical character recognition) reads the text in images, such as the pages of a scanned PDF.
| Option | Effect with Docling Serve |
|---|---|
| The server decides; the Docling Serve image reads the images. |
| The images are not read, which is faster. A scanned page gives no text. |
| The images are read, in the language of |
| A code the OCR engine knows, such as |
| Every page is read with OCR, and its text layer is replaced, for a PDF whose text layer is wrong. |
| The engine, which must be installed on the server. |
Example
The following route converts the PDF files of a directory with a Docling Serve server that has an API key, reading scanned pages in German, and writes each one as Markdown to another directory.
- route:
from:
uri: "kamelet:langchain4j-ingest-file-source"
parameters:
directory: "/data/scans"
include: "**/*.pdf"
steps:
- to:
uri: "kamelet:docling-convert-action"
parameters:
useDoclingServe: true
doclingServeUrl: "http://docling-serve:5001"
authenticationScheme: API_KEY
authenticationToken: "{{docling.api.key}}"
processTimeout: 300000
enableOcr: true
ocrLanguage: de
- to:
uri: "file:/data/scans-markdown"
parameters:
fileName: "$\{file:name.noext}.md"