Doc Chunker

Doc Chunker is an optional DeepFellow component that turns diverse knowledge sources into clean, searchable text. It converts documents, presentations, spreadsheets, images, audio, and video into text and splits that text into chunks ready for embedding.

What You Can Convert

Doc Chunker handles a wide range of formats.

• Documents and Markup: pdf, docx, pptx, xlsx, html, md. OCR is enabled by default and extracts text from scanned PDFs and images embedded in documents.
• Legacy Office formats: doc, ppt, xls, odt, odp, ods, rtf. Doc Chunker converts these with LibreOffice before parsing.
• Images: png, jpg, jpeg, tiff, bmp. OCR reads text from the image. Optional image description adds a natural-language summary of the picture.
• Audio: mp3, wav, m4a, ogg, flac, opus, aac, wma. Doc Chunker transcribes speech to text through a speech-to-text model.
• Video: mp4, mkv, mov, avi, webm. Doc Chunker extracts the audio track and transcribes it.

Doc Chunker handles any other file type in two steps. First it tries to read the file as plain text. If that succeeds, the text becomes a document whose paragraphs are split on blank lines. If it fails, Doc Chunker falls back to Apache Tika, which is what happens with a format such as epub.

Install Doc Chunker

Install Doc Chunker from the Infra Web Panel as a model of the custom service.

Doc Chunker Settings

Installing the model exposes the Doc Chunker endpoint. DeepFellow Server reads the following settings to route vector store files through it.

Doc Chunker itself holds no model configuration, and every request names the model it needs. These settings are what DeepFellow Server puts into that request.

• doc_chunker_use: Whether to send files to Doc Chunker when you add them to a vector store. Set it to false to keep the built-in text extraction. Default true.
• doc_chunker_prefix: Endpoint prefix the server uses to reach Doc Chunker. It must match the prefix you set when you installed the model. Default doc_chunker.
• doc_chunker_picture_description_model: Vision-language model the server sends as the model parameter when it asks Doc Chunker to describe pictures. Default granite3.2-vision:2b.

All three are dynamic settings, so a change applies immediately and never needs a restart:

deepfellow server config set doc_chunker_use=true doc_chunker_prefix=doc_chunker

The Doc Chunker section of the Server Web Panel holds the first two. To change doc_chunker_picture_description_model, use PUT /admin/config.

Container Configuration

Set these environment variables on the Doc Chunker model in the Infra Web Panel.

Configuration Options

The Doc Chunker installation form exposes the following fields.

Processing

The defaults work for every format listed in What You Can Convert. Doc Chunker holds further timeouts for its Apache Tika and Docling backends, and the form leaves them at their defaults.

Chunk Size

A chunk holds at most MAX_TOKEN_COUNT tokens, which is 512. The install form doesn't expose this variable, so every chunk keeps that budget.

Doc Chunker fills 70 percent of the budget, 358 tokens, with text unique to the chunk, and spends the remaining 30 percent on overlap. The overlap runs forward: Doc Chunker takes whole sentences from the start of a chunk and appends them to the chunk before it. The earlier chunk grows, and the later one stays as it was. Each overlap also stays within about 30 percent of the length of the chunk it extends, so a short chunk grows by far less than the 153-token ceiling.

Doc Chunker overlaps only consecutive chunks of running text, so a table never bleeds into its neighbors.

Chunk boundaries are measured with the sentence-transformers/all-MiniLM-L6-v2 tokenizer, which is Docling's own default. The tokenizer is fixed, so its token counts differ from the ones your embedding model counts. Matching the two is planned work.

Inference Gateway

Image description and audio transcription both call an OpenAI-compatible inference gateway, so they share one address and one key. Point INFRA_API_URL at the gateway root, not at a specific endpoint. Doc Chunker appends /v1/chat/completions for image description and /v1/audio/transcriptions for transcription.

Without INFRA_API_URL, neither feature is available, and Doc Chunker rejects a request that needs one rather than returning a document without it.

Image Descriptions

Image description is opt-in per request. Pass describe_images=true and name the vision-language model with model. Both are required together: a request that asks for descriptions without a model is rejected with 422, and so is a request naming a model the gateway doesn't offer.

Doc Chunker describes every picture the document holds. There is no size threshold, so icons and logos are described too.

PICTURE_DESCRIPTION_CONCURRENCY bounds a single document, and Doc Chunker converts MAX_CONCURRENT documents at a time. The gateway therefore sees up to the product of the two, which is 8 requests with both at their defaults. Raise it for a gateway that takes the load.

Audio Transcription

For audio and video, transcription is the conversion: the transcript becomes the document's text. Name the speech-to-text model per request with model. It is required, so uploading audio or video without it is rejected with 422.

Doc Chunker splits the transcript on silence, and every piece keeps the time span it was spoken in. A silence longer than AUDIO_SILENCE_THRESHOLD always ends a chunk, so no chunk ever spans a pause.

Converted Documents

When Doc Chunker is active, adding a file to a vector store with POST /v1/vector_stores/{vector_store_id}/files converts the file through Doc Chunker first, and the vector store stores the chunks that come back.

DeepFellow keeps the converted document next to the file, under the path set by DF_FILESTORAGE_META_PATH, which defaults to storage/. Adding the same file again, or asking for its text later, reuses that document instead of converting the file a second time. A conversion that stopped halfway leaves nothing reusable behind, so the next request converts the file again.

POST /v1/metadata/expand, which extracts metadata fields from a document with an LLM, uses the same cache. When a requested field is not present in a document's embedded metadata, DeepFellow falls back to Doc Chunker to extract the document's text, converting the file if no conversion is cached yet. To have a vision model describe images during that fallback conversion, set image_processing_mode to description in the request body. The default value, ignore, skips image descriptions. The setting applies only when the fallback runs.

Call Doc Chunker Directly

For advanced use cases, call Doc Chunker through the /custom/doc_chunker endpoint without a vector store. The two operations are separate endpoints, and conversion never happens implicitly: POST /convert turns a file into a Docling document, and POST /chunk turns that document into chunks.

Address these calls to DeepFellow Server with your project API key. The server proxies them to Doc Chunker and supplies the Infra credentials itself, so your client never holds the Infra API key. See Custom Endpoints.

Convert a File

POST /custom/doc_chunker/convert accepts multipart/form-data with the file in the file field, and returns a ZIP archive named after the uploaded file.

The archive holds document.json always, assets/ when the document has pictures, and chunks.json when you pass chunk=true.

curl -X 'POST' \
  'https://deepfellow-server-host/custom/doc_chunker/convert?chunk=true' \
  -H 'Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY' \
  -F 'file=@report.pdf;type=application/pdf' \
  -o report.zip

import io
import json
import zipfile

import requests

with open("report.pdf", "rb") as f:
    response = requests.post(
        "https://deepfellow-server-host/custom/doc_chunker/convert",
        params={"chunk": "true"},
        files={"file": ("report.pdf", f, "application/pdf")},
        headers={"Authorization": "Bearer DEEPFELLOW-PROJECT-API-KEY"},
    )

with zipfile.ZipFile(io.BytesIO(response.content)) as archive:
    chunks = json.loads(archive.read("chunks.json"))

print(chunks)

import * as fs from 'fs';

const buffer = await fs.promises.readFile('report.pdf');
const formData = new FormData();
formData.append('file', new Blob([buffer], { type: 'application/pdf' }), 'report.pdf');

const response = await fetch('https://deepfellow-server-host/custom/doc_chunker/convert?chunk=true', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer DEEPFELLOW-PROJECT-API-KEY'
    },
    body: formData
});

const archive = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile('report.zip', archive);

Chunk a Document

POST /custom/doc_chunker/chunk accepts multipart/form-data with the document.json from a POST /convert archive in the file field, and returns JSON. It converts nothing and contacts no inference gateway, so it needs no model and leaves the document untouched. The assets aren't needed, because chunk content comes from the document's own text and metadata.

curl -X 'POST' \
  'https://deepfellow-server-host/custom/doc_chunker/chunk' \
  -H 'Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY' \
  -F 'file=@document.json;type=application/json'

The response holds the chunks and a total count.

{
    "chunks": [
        {
            "text": "Quarterly revenue grew by 12 percent compared to the previous period.",
            "meta": {
                "headings": ["Financial Summary"],
                "pages": [3],
                "bboxes": [{ "page": 3, "l": 72.0, "t": 120.5, "r": 540.0, "b": 200.3 }],
                "self_refs": ["#/texts/12"],
                "labels": ["text"]
            },
            "start_index": 0,
            "end_index": 69
        }
    ],
    "count": 1
}

Every key in meta is conditional, and a chunk carries only the ones that apply to it.

start_index and end_index are character offsets into the concatenation of the chunk texts, in the order Doc Chunker emitted them. They are not positions in the original file. Because the overlap extends the earlier chunk, one chunk's end_index reaches past the next chunk's start_index, and the difference is the length of the duplicated text, which is what you drop when you join chunks back together. To locate a chunk within the original document, use self_refs, bboxes, or pages.

Errors

Doc Chunker enforces no upload size limit of its own, so it never answers 413. The limit on the files you add to DeepFellow comes from DeepFellow Server.

Doc Chunker also exposes GET /custom/doc_chunker/health, which returns {"status": "ok"} when the service is ready. It returns 503 when one of the conversion backends has exited or a conversion has been running past its soft timeout. GET /custom/doc_chunker/version returns the version of the running container.