Як mintbot працює з файлами¶

Коли ви надсилаєте своєму агенту mintbot фотографію, документ, голосове повідомлення, таблицю, знімок екрана чи PDF — через Telegram, вебпанель або API, — файл зберігається на власному VPS вашого агента і більше ніде. Він лишається там стільки, скільки ви захочете, а LLM отримує робочу копію, підготовлену спеціально для нього.

Це непомітне архітектурне рішення з вагомими наслідками. Його варто розібрати докладно: саме тут mintbot найбільше відрізняється від масових ШІ-чатів.

Схема: завантажений файл зберігається як оригінал на VPS вашого агента; адаптер, вибраний за типом файлу, робить робочу копію для LLM — Оригінал лишається на вашому VPS недоторканим — модель бачить лише робочу копію, зроблену для неї.

Шлях файлу від початку до кінця¶

Файл потрапляє на VPS агента. PDF, перетягнутий у вебпанель, іде просто на ваш VPS. Фото чи файл, надісланий у Telegram, бот mintbot забирає з Telegram і одразу передає на ваш VPS — файл лише проходить транзитом і ніколи не зберігається централізовано. Локальний API агента перевіряє сигнатуру файлу (magic bytes), щоб з’ясувати, що це за файл насправді (телефони й браузери напрочуд часто вказують хибний тип), обчислює хеш SHA-256 і записує файл у /var/lib/mintbot-agent/uploads/<shard>/<sha256>.<ext>. До локального каталогу додається запис із джерелом (telegram / panel / api), ID того, хто завантажив, MIME-типом і початковою назвою файлу. Якщо надіслати той самий файл двічі, він однаково збережеться лише один раз.

Якщо розмова ведеться в проєкті, агент також кладе копію в теку uploads/ цього проєкту, щоб працювати з файлом поруч з рештою проєкту.
Оригінал недоторканний. Відтепер ніщо всередині mintbot не змінює збережений файл. Адаптери, що готують його для LLM, створюють лише робочі копії — зменшені JPEG, декодований текст. Оригінал, байт у байт, лишається на диску, доки ви його не видалите. Немає центрального сховища, немає таймера зберігання, немає витоків між агентами: VPS кожного агента знає лише про файли свого власника.

Модель отримує версію, підготовлену для неї. Коли агент показує файл LLM, невеликий диспетчер вибирає потрібний адаптер за MIME-типом і розширенням:

Адаптер	Що обробляє	Що отримує модель
Зображення	JPG, PNG, WebP, GIF, HEIC (iPhone), AVIF, TIFF, BMP	Зменшується до 1568 px за довшою стороною, перекодовується в JPEG q85 і вбудовується просто в запит. Декодування відбувається в окремому короткоживучому процесі з лімітом пам’яті, розрахованим під ваш VPS, тож величезне фото не може сповільнити агента
PDF	`.pdf` до 32 МБ	Вбудовується як повноцінний PDF — Claude сам читає текст і верстку. Більший PDF лишається на диску, і агент сам витягує з нього текст (наприклад, за допомогою `pdftotext`)
Текст	`.txt`, `.md`, `.csv`, `.json`, `.yaml`, `.svg`, вихідний код (`.py`, `.js`, `.ts`, `.go`, `.rs`, …), журнали, диффи	Декодується як UTF-8 (із запасним варіантом latin-1) і вбудовується до 500 КБ; довший файл обрізається на цій межі, повний оригінал лишається на диску
Аудіо	`.mp3`, `.ogg`, `.opus`, `.m4a`, `.wav`, `.flac`, `.aac`	Голосові повідомлення з Telegram і з мікрофона панелі надходять уже розшифрованими. Аудіофайл поки не розшифровується автоматично — агент отримує його розташування та інструкції й розшифровує його, коли ви попросите
Відео	`.mp4`, `.mov`, `.webm`, `.mkv`, `.avi`	Поки не обробляється автоматично. На ваше прохання агент встановлює `ffmpeg` (заздалегідь сказавши, скільки місця на диску він займе) і сам витягує кадри чи звукову доріжку
Документи Office	`.docx`, `.xlsx`, `.pptx`, старіші `.doc` / `.xls` / `.ppt`, `.odt`, `.ods`, `.odp`	Поки не обробляються автоматично. На ваше прохання агент встановлює невелику бібліотеку для читання й витягує текст
Невідомий	Усе інше	Нотатка з назвою, типом, розміром і розташуванням файлу на диску плюс його перші байти в шістнадцятковому вигляді — цього досить, щоб модель розпізнала файл і за потреби відкрила його своїми інструментами

Кожна робоча копія кешується поруч з оригіналом як <sha256>.cache/v<N>.json, тож коли моделі наступного разу знадобиться цей файл, він завантажиться миттєво. Коли адаптер змінюється, кеш перебудовується сам.

Жодних URL з обмеженим терміном дії в контексті моделі. Коли зображення чи PDF іде до LLM, воно вбудовується в той самий запит — жодних URL, які згодом можуть повернути 404, жодних підписаних посилань із терміном дії. Там, де моделі потрібне лише посилання, це внутрішня адреса https://agent<id>.<domain>/<panel_token>/api/local/uploads/<upload_id>/raw — вона захищена токеном панелі вашого агента й дійсна, доки файл лежить на диску.

Чому це краще за масові ШІ-чати¶

Коли ви завантажуєте фотографію в ChatGPT або PDF у Claude.ai, файл потрапляє до сховища провайдера, прив’язується до цієї розмови, і коли він зникне, вирішує політика зберігання провайдера. Через якийсь час файлу вже немає, навіть якщо саму розмову, де він був, ви ще бачите. Перехід до іншого провайдера означає почати все з нуля.

Поширена пастка Telegram-ботів добре показує різницю. Telegram зберігає постійний file_id для кожної фотографії, але посилання на завантаження, яке отримує бот, гарантовано працює лише близько години. Боти, що зберігають тільки це посилання, на вчорашнє фото повертають 404. mintbot копіює файл до архіву вашого агента щойно той надходить, — а якщо ви відповісте на старіше фото, знову завантажить його за постійним file_id. Відтоді фото — ваше.

З такого устрою випливають три речі:

Файли належать вам, а не провайдеру LLM. Перейдете наступного місяця з Claude на GPT — історія файлів переїде разом з вами недоторканою, бо вона лежить на вашому VPS, а не у сховищі провайдера.
До питання можна повернутися пізніше. «Три місяці тому ми розбирали договір — порівняй його з цією новою редакцією» спрацює, бо оригінал досі на диску. У масовому чаті старий файл на той час зазвичай уже видалено.
Модель завжди отримує ту версію, з якою їй найзручніше працювати. Мультимодальні моделі отримують зменшений JPEG, текстові — UTF-8, моделі, що читають PDF, — повноцінний PDF. З телефона можна завантажити HEIC, і все просто працює — декодер зображень підключає HEIF-плагін Pillow, а перевірка сигнатури виявляє телефони, що помилково позначають файл як application/octet-stream.

Де керувати файлами¶

У вебпанелі агента є файловий менеджер: Налаштування → Файловий менеджер. Він показує весь VPS агента; архів завантажень у /var/lib/mintbot-agent/uploads/ — це та частина, яку наповнюють ваші розмови. Там можна:

Переглядати теки, звантажувати, перейменовувати, переміщувати й видаляти файли
Створювати теки
Перетягувати нові файли — вони вивантажуються частинами, до 4 ГБ на файл
Редагувати невеликі текстові файли (до 1 МБ) просто в браузері

Обмеження розміру: файл, прикріплений у чаті, може мати до 500 МБ; Telegram дозволяє ботам отримувати файли лише до 20 МБ; Файловий менеджер приймає до 4 ГБ на файл. Далі єдине обмеження — ваш диск: mintbot завжди лишає трохи вільного місця, щоб сервер працював далі. Якщо диск заповниться, агент повідомить про це й дасть пряме посилання на Файловий менеджер, щоб ви звільнили місце, — або просто попросіть агента видалити старі файли.

Видалення файлу у Файловому менеджері стирає його з диска, і агент більше не зможе показати його LLM. Саме це робить оригінал «вашим»: видалити його можете лише ви.

Підсумок¶

Більшість ШІ-чатів ставляться до ваших файлів як до одноразового контексту розмови. mintbot ставиться до них як до ваших даних — вони зберігаються на вашому VPS, належать вам і на запит перетворюються саме на ту форму, яка потрібна моделі цієї миті. На цьому фундаменті збудовано чимало найцікавіших можливостей mintbot.