Knowledge Base Upload

Supported formats

You can upload to the knowledge base:

• MD;
• MDC;
• TXT;
• DOCX;
• PDF;
• CSV;
• XLSX;
• PNG, JPEG, GIF, WebP, BMP, SVG, AVIF images;
• ZIP.

A ZIP archive up to 500 MB is imported as folders and files from the archive. If the archive is larger than 500 MB, the cabinet will show a size error.

CSV and XLSX

CSV and XLSX on the "Upload" tab are saved as knowledge base documents: rows and sheets are converted to text/Markdown so the agent can search their content like a regular material.

If you need an editable sheet with rows, columns, import, and separate agent permissions for changing tables, use the "Table" tab instead of a regular file upload.

ZIP archives

ZIP is useful for moving a whole documentation structure: folders, Markdown files, documents, tables, and images. During import, the archive is placed under a root folder named after the ZIP file; if the archive already contains that root folder, an extra duplicated root is not created.

Archive limits:

• ZIP size - up to 500 MB;
• total uncompressed size - up to 500 MB;
• one file inside the archive - up to 25 MB;
• up to 6000 entries, up to 3000 files, and up to 2000 folders;
• path depth - up to 12 levels;
• path segment length - up to 255 characters.

Service files such as __MACOSX, .DS_Store, and Thumbs.db are skipped. Unsafe paths, paths that are too deep, and unsupported files should not be included in the imported structure.

Markdown images and links

Images can be uploaded as separate files or placed in a ZIP next to Markdown. Archives support PNG, JPEG, GIF, WebP, BMP, SVG, and AVIF. After upload, these images become separate knowledge base materials and can be used in Markdown preview.

If Markdown links to a file from the same knowledge base, for example ![Diagram](assets/schema.png) or [PDF](docs/rules.pdf), the cabinet tries to connect that link with the uploaded material. This lets Markdown preview show images and helps the agent understand that the instruction also has a related file.

Image recognition during upload

The upload form lets you choose an image recognition mode for search:

• “Estimate first” — inspect the selected files without importing them and show the image count, approximate time, and cost for every mode. Estimation does not charge credits;
• “Do not recognize” — upload files without AI image analysis;
• “Only without a Markdown description” — recognize images without a caption or nearby Markdown text and skip unchanged images that were already recognized;
• “Only unrecognized” — ignore Markdown captions but reuse existing AI descriptions for images with the same content;
• “Re-recognize all” — process every image again, even when an AI description already exists.

For every mode except Do not recognize, select the AI description language: RU or EN. This controls the language of text added to the search context and does not change the source file's language.

After the estimate, select one of the four upload modes. You do not need to select the file or ZIP again. If you select a mode directly, the cabinet starts uploading without another confirmation.

The generated AI description is stored separately and does not change the source Markdown. Search uses both the Markdown text and the image description. An identical image in one knowledge base is recognized once by content; if several Markdown files reference it, the description helps find every related instruction. A separately uploaded image without Markdown also becomes searchable after recognition.

Recognition runs in the background. The time and credit values shown before start are approximate. Estimation itself neither reserves nor charges anything; actual credits are calculated for completed AI calls.

How to upload

1. Select the Settings gear button to the right of the project name, then open Knowledge Base under Project data.
2. Click Add.
3. Select the Upload tab.
4. In the upload form, drag files to the highlighted area or select them on your computer.
5. Check the selected files, choose an image recognition mode, and, when recognition is enabled, select the description language: RU or EN.
6. If you selected “Estimate first,” click “Estimate” and choose a suitable mode from the result.
7. Click Upload.

Background loading

After start, the background upload panel shows:

• current file;
• stage "Uploading", "Saving" or "Creating files from the archive";
• number of processed files inside the archive;
• percentage of progress;
• result "Upload completed" or "Upload with error".

The arrow button collapses or expands the operation details. After uploading finishes, the cross button removes it from the panel; the uploaded materials remain in the knowledge base.

Transfer of a regular file to the server runs in the current session. Once the file is saved and appears in the knowledge base with the Processing status, you may close the page: text extraction and search indexing continue on the server. A short service restart does not require another upload because unfinished processing resumes automatically.

A ZIP has two stages. While the browser is sending the archive to the server, the cabinet is temporarily blocked on mobile. Once the server accepts the ZIP and Creating files from the archive begins, you can continue working or close the page; the server completes the import independently.

While a material has the Processing status, it is not yet included in knowledge-base search or used by the agent in replies. Wait for a ready status. Upload the file again only after a Processing error, not because the page was reloaded or the service restarted temporarily.

If you reload the page or return to the cabinet later in the same browser, the panel finds the accepted server operation and resumes displaying its progress. You do not need to select the ZIP again. Select it again only when the transfer stopped before the server accepted the archive and the cabinet explicitly reports this.

Conflicts and import summary

If the selected folder already contains a material with the same name, the cabinet shows a conflict and offers to upload the new material under another name, replace the existing material, or cancel the import. For folders, check what exactly will be replaced so you do not accidentally remove needed nested materials. When a conflict occurs during background processing, the same actions remain available after a page reload.

After a successful import, the cabinet shows a summary: which root folder was created, how many folders and files were added, which materials were replaced or renamed, and how many files are still waiting for text extraction.

Frequent errors

• “The file could not be uploaded. Check your connection and try again” - there may be a network problem or a temporary failure.
• “The server returned an incorrect response after uploading” - refresh the material list and check whether the file appeared before starting another upload.
• “The archive upload stopped before the server accepted the file” - select the same ZIP and start the upload again.
• “The archive could not be processed” - the server ended the operation with an error; review the details, fix the reported file or structure, and retry the import.
• “Processing” hangs for a long time - the file is saved, but its text is still being extracted or indexed; it is not included in search or agent replies until this completes.
• "Processing error" - the text could not be prepared; it is worth checking the format, size and contents of the file.

If upload fails

For a single file, retry the upload and check its size. For large sets, use a ZIP up to 500 MB and follow the archive limits; if the structure is too large, split it into several archives. Do not upload a ZIP again after the server accepts it: reload the page and wait for the recovered status. Select the archive again only after a message that the server did not accept it, or after a completed failure when the required materials are absent.