File Types, Docling, and Image Handling

Step 2 of the wizard asks three questions that are easy to answer carelessly: which file types this Topic accepts, whether Docling is involved, and what happens to pictures. This page explains why each choice matters.

Why defining file types precisely actually matters

It is tempting to tick every box "just in case". There are two reasons not to.

A file type you did not enable is refused right away, at upload time, with a clear message. A file type you did enable but cannot process is refused later, after the upload has started, with a less specific error. Examples are Documents ticked with no Docling server that can be reached, or Images ticked with a model that cannot read pictures. If you tick only what you really plan to upload, a confusing failure in the middle of an upload becomes a clear message at the start.

Every ticked type adds a requirement to the rest of the Topic. Documents need a Docling server for as long as the Topic exists. Images need a model that can read pictures. If you tick a box you do not need, the Topic depends on one more server, even if you never upload that kind of file.

The rule is simple: tick exactly the types your real content is made of. If you only ever upload .txt and .md files, leave Documents and Images unticked. You gain nothing by allowing more, and the Topic has one fewer server that must stay reachable.

Structured data — JSON, XML, YAML, TOML, CSV, TSV — is not one of these three checkboxes. It is recognised by its file ending and split into records automatically, whatever File Types you tick. There is nothing to set. See the glossary.

What role Docling plays

Docling turns PDF, Office documents and scanned pages into clean text before anything else happens. Cutting into pieces, extraction and embedding all work on Docling’s text, never on the original file. Without a Docling server that can be reached, such a file is refused.

A Docling server is required in two cases. Either one makes the Docling picker appear and become mandatory:

  • Documents is ticked among the File Types. Uploaded PDF and Office files need converting.

  • Allow binary documents as chat attachments is ticked. A user who attaches a PDF or Office file to a chat question needs the same conversion, on the fly, before that message is answered.

Next to the server picker you find:

  • Timeout (min). It applies to one whole document, not to a single text piece. It protects you against a long scanned PDF on a slow server. The range is 1 to 120 minutes. If you leave it empty, the global default is used, and the field shows that value. Higher: big documents succeed, but a stuck upload fails later. If the Docling server itself stops earlier, the wizard warns you. Raise the limit under Admin → Docling Servers then.

  • Docling Settings (advanced). A text with comments (JSON with // lines) for how Docling reads files, for example text recognition in scans (OCR), languages and tables. The template switches nothing on. Remove the // in front of a setting to use it. The settings are sent with every upload and re-upload. A change applies to the next upload and needs no restart. Files already uploaded stay as they are until you upload them again. The settings do not apply to files that users attach in the chat.

A misspelt setting name in Docling Settings is not reported. The upload runs with Docling’s default for that setting, and no error is shown. Check the spelling of every setting you remove the // from.

If you never plan to upload documents, leave Documents unticked. The Topic then has one fewer external server it depends on. That is worth doing even if a Docling server is available.

Text files and image files do not go through Docling. Text files are read directly, and images go to the model that describes pictures.

Pictures: during upload and in the chat

These are two separate settings. They both concern pictures and sit close together on step 2. But they apply at different moments, and one does not switch on the other.

Pictures found during upload Images attached to a chat message

When it applies

A picture inside a converted document, or an image file that you upload on its own

A user attaches an image to a question in the chat window

Setting

Pictures in documents and uploaded pictures: Ignore, Extract entities, or Picture in the graph

Allow images as chat attachments (its own checkbox)

Which model sees it

The Image Describer Model (its own role)

The Topic’s Language Model, directly. Never the Image Describer Model

What happens with the result

A text description is written and becomes part of the searchable graph, for good

The image goes to the Language Model for that one question only. Nothing about it is stored in the graph

What it needs

A model in the Image Describer role that can read images

A Language Model that can read images. The wizard does not check this for you

So ticking "Images" as a file type and choosing a picture option only makes uploaded pictures searchable. It does not decide whether a user may hand the chat a photo. That is the separate Allow images as chat attachments checkbox. It works even if pictures in uploads are set to Ignore.

The three options for pictures during upload

The picture settings appear only when Documents or Images is ticked. Otherwise no picture can arrive, and pictures are ignored.

Option What happens When to choose it

Ignore

Pictures are skipped. Facts that are shown only in pictures cannot be found

Your pictures carry no facts (logos, decoration). Not offered while Images is a file type, because an uploaded image file needs an entry of its own

Extract entities

The description is read like normal text, and entities are taken from it. This often adds entities that appear nowhere else in your documents. Pictures are not stored and not shown in answers

You want the facts of a picture in the graph, but you do not need to show the picture

Picture in the graph (default)

Each picture becomes its own entry in the graph, connected to the entities it shows. Recommended

You want answers that can also show the picture. Two extra choices: Store picture in the database (default on) and Show pictures in answers (default on, needs storing)

Under Picture in the graph: if you store pictures, an answer can show a picture and name it as a source by its caption. If you do not, answers name only the document that the picture came from. Show pictures in answers only changes the chat. You can switch it at any time without uploading again.

Why the Image Describer role is different

Every other optional model role (Extraction, Deduplication, Community Report, Router, Follow-up) works like this: if you tick Use the topic’s Language Model, the Topic quietly uses the Language Model’s own server. There is nothing more to set.

Picture description has no such fallback inside the container. It needs the full address of a model that can read images. This has two effects:

  • If you tick Use the topic’s Language Model for this role, the Topic uses the Language Model of step 1 for describing pictures. That model must be able to read images. The wizard does not check this. If it cannot, the upload of pictures fails or gives poor descriptions.

  • You can choose any model that can read images, from any provider. There is no list of providers that are excluded. If your Language Model cannot read images, pick a separate model here.

The wizard does not check that the Language Model can read pictures. This applies to the ticked Image Describer role and to Allow images as chat attachments. If the model cannot read images, picture descriptions come out poor or fail, and attached images are not understood. Nothing checks this for you. Choose a model that can read images before you enable either setting.

See Models and their roles for how this role differs from the other seven.

The Picture Description Timeout limits how long describing one picture may take. Empty uses the global default.

Related