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 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 endpoint.
• Video: mp4, mkv, mov, avi, webm. Doc Chunker extracts the audio track and transcribes it.
• Other formats: Doc Chunker falls back to Apache Tika for any remaining file type it recognizes, such as epub or csv.

Install Doc Chunker

Install Doc Chunker from the Infra Web Panel as a model of the custom service. The general procedure matches the one in the Custom Models guide.

Enable Doc Chunker on the Server

Installing the model exposes the Doc Chunker endpoint. To make DeepFellow Server route vector store files through it, set the following environment variables on the server, then restart it.

Set each variable with deepfellow server env set:

deepfellow server env set DF_DOC_CHUNKER_USE 1
deepfellow server env set DF_DOC_CHUNKER_PREFIX doc_chunker

Configuration Options

The Doc Chunker installation form exposes the following fields.

Processing

• prefix: Endpoint prefix. Default doc_chunker.
• max_concurrent: Maximum number of files Doc Chunker converts in parallel. Default 2.
• document_timeout: Maximum time in seconds for a single conversion. Default 600.

Image Descriptions

To add natural-language descriptions of images and pictures, set picture_description_mode to one of the following values.

• disabled: No image descriptions. This is the default.
• preset: Use a Docling preset vision-language model. Set picture_description_preset to smolvlm, granite_vision, qwen, or pixtral. DeepFellow downloads the model from Hugging Face on the first request.
• local: Use any Hugging Face vision-language model. Set picture_description_repo to the repository ID, for example Qwen/Qwen2.5-VL-7B-Instruct.
• api: Use an external endpoint compatible with /v1/chat/completions. Set picture_description_api_url, picture_description_api_model, and, if required, picture_description_api_key.

Set picture_description_prompt to control how the model describes each image.

Audio Transcription

To transcribe audio and video, point Doc Chunker at a speech-to-text endpoint.

• audio_stt_api_url: A speech-to-text endpoint compatible with /v1/audio/transcriptions, for example your DeepFellow Speech to Text endpoint.
• audio_stt_api_model: The transcription model, for example Systran/faster-whisper-base.
• audio_stt_api_key: The API key for the endpoint, if required.
• audio_silence_threshold: The minimum duration of silence in seconds used to split audio into segments.

Metadata Cache

When Doc Chunker is active, adding a file to a vector store with POST /v1/vector_stores/{vector_store_id}/files sends the file to Doc Chunker, which returns a ZIP archive. DeepFellow saves the archive contents under the path set by DF_FILESTORAGE_META_PATH (defaults to storage/), in a per-file {file_id}_meta/ directory.

The archive contains:

• document.json: The converted document, in Docling format.
• chunks.json: The text chunks used for embedding.
• assets/: The images extracted from the document.

After unpacking the archive, DeepFellow writes a manifest.json file to the same directory to mark the conversion as complete.

Call Doc Chunker Directly

For advanced use cases, call Doc Chunker through the /custom/doc_chunker endpoint without a vector store. Send the file as multipart/form-data in the file field. The /custom/doc_chunker/chunks endpoint returns a ZIP archive that contains chunks.json with the extracted chunks, document.json with the parsed document, and an assets folder with extracted images.

curl -X 'POST' \
  'https://deepfellow-server-host/custom/doc_chunker/chunks' \
  -H 'Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY' \
  -F 'file=@report.pdf;type=application/pdf' \
  -o chunks.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/chunks",
        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/chunks', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer DEEPFELLOW-PROJECT-API-KEY'
    },
    body: formData
});

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

The chunks.json file inside the archive contains 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]
            }
        }
    ],
    "count": 1
}

To extract plain text instead of chunks, call /custom/doc_chunker/text. Set the image_processing_mode query parameter to ignore, base64, or description to control how the endpoint handles images.