Вложения: отправка, скачивание и распознавание
Отправляйте и скачивайте вложения MAX, извлекайте текст: локальные программы, инструменты агента и явно включённые API OCR.
Здесь можно выбрать, как отправить или скачать вложение, узнать, какие файлы CLI читает
сам, какие зависимости нужны и когда стоит поручить чтение агенту или внешней модели.
После извлечения текст можно сохранить для поиска: content: найдёт исходное сообщение.
Отправка передаёт файл в чат, скачивание сохраняет его байты, а распознавание получает содержимое для чтения и поиска. Это разные возможности: XLSX можно передать и скачать, хотя встроенный механизм извлечения пока не читает её ячейки.
Что можно отправить
Таблица описывает выбор типа вложения в CLI. Приём конкретного файла и его обработка зависят также от MAX. Отправка идёт только по явной команде; извлечение текста ничего не отправляет в чат.
--voice — отдельный путь для голосового сообщения в Ogg Opus, а не для произвольного аудио.
У личного аккаунта голосовое отправляется отдельно, без текста и других вложений. Картинки
распознаются по расширению и при --file; --as-file здесь меняет способ отправки видео,
но не превращает такую картинку в документ. Подробнее: отправка и боты.
Что можно скачать
Этот раздел относится к личному аккаунту. Скачивание сохраняет байты, не распознаёт текст и не конвертирует документ в другой формат.
max messages download "Учебная группа" 204 --output-dir ./files --json
max attachments list --chat "Учебная группа" --needs-text --jsonСохранённый localPath доступен на машине, где работает CLI. Путь сам по себе не передаёт
файл удалённому агенту: ему нужен доступ к этому файлу или отдельная передача байтов.
Как читается содержимое
По умолчанию сканы и фотографии читает агент своими средствами. attachments extract --ocr
явно включает API для массового распознавания. Без этого флага извлечение не вызывает модель.
Проверить наличие флага в установленной версии можно через max attachments extract --help.
| Формат | Программно, локально | Явный API: extract --ocr | Когда нужен агент |
|---|---|---|---|
| TXT, MD, MARKDOWN, CSV, TSV, JSON, LOG | Читает UTF-8 как текст, без дополнительных пакетов | Остаётся локальное чтение | Агент определяет кодировку и преобразует её в UTF-8; встроенное автоматическое определение пока отсутствует |
Другие файлы с MIME text/* или application/json | Читает UTF-8 как текст | Остаётся локальное чтение | Если MIME не указан и расширение не поддерживается, нужен внешний читатель |
| DOCX | Извлекает текст через mammoth | Остаётся локальное чтение | Картинки внутри документа и точная вёрстка не распознаются этим извлечением |
| PDF с текстовым слоем | Извлекает текст через unpdf | Читает текстовые страницы локально | Проверка порядка колонок, таблиц и точности извлечённого текста |
| PDF со сканами или со смешанными страницами | Без текста — needs-agent; у смешанного PDF обычное извлечение читает имеющийся текстовый слой | Читает текст страниц; страницы без текста преобразует в изображения через unpdf и @napi-rs/canvas, затем распознаёт моделью | Обычный путь для сканов; также недоступный движок, ограничения или неудачный API |
| JPG, JPEG, PNG, WEBP | needs-agent | Отправляет поддерживаемое изображение vision-модели | По умолчанию агент читает сам |
| GIF, HEIC, TIF, TIFF, BMP | needs-agent, без встроенного преобразования | Автоматический OCR этих форматов не поддерживается | Агенту нужна подходящая программа просмотра или преобразование в PNG/JPEG/WEBP |
| DOC, PPT, XLS | Нет встроенного читателя старых бинарных форматов | Не добавляет читатель этих форматов | Преобразовать установленным офисным приложением, затем прочитать текст или страницы |
| ODT, ODS, XLSX, PPTX | Нет отдельного встроенного механизма извлечения | Не добавляет читатель этих форматов | Прочитать специальной библиотекой либо экспортировать документ, листы или слайды доступным инструментом |
| RTF | Нет отдельного встроенного механизма извлечения | Не добавляет читатель RTF | Преобразовать через программу, которая понимает команды RTF и кодировку |
| EPUB | Нет отдельного встроенного механизма извлечения | Не добавляет читатель EPUB | Прочитать главы в порядке книги через EPUB-инструмент |
| ZIP | Не обходит содержимое архива | Не распознаёт архив | Просмотреть список файлов, распаковать нужные и обработать каждый по его формату |
| Голосовое сообщение | Отдельная локальная модель речи: messages transcribe | Этот OCR не распознаёт речь | Настроить модель и язык; см. распознавание голосовых |
| Другие файлы аудио, видео, анимации, стикеры | Не читаются механизмом извлечения текста вложений | Не распознаются этим OCR | Для произвольного аудио нужны доступный инструмент речи и подходящий формат; для видео — звук или отдельные кадры |
CSV и JSON здесь становятся поисковым текстом, а не структурированными таблицами в базе. HTML/XML с текстовым MIME читаются как исходный текст, не как страница в браузере. PDF/DOCX сохраняют извлечённый текст, а не исходную вёрстку. OCR может ошибаться в цифрах, порядке чтения и оформлении; важные данные нужно сверять с оригиналом.
Голосовые обрабатываются отдельно от документов: модель речи скачивается один раз, затем работает локально. Команды, выбор языка и ограничения описаны в распознавании голосовых.
Какие зависимости нужны
| Задача | Пакет |
|---|---|
| Читать текстовый слой PDF | unpdf |
| Читать текст DOCX | mammoth |
| Преобразовать страницы PDF в изображения для API OCR | unpdf с поддержкой рендеринга и @napi-rs/canvas |
| Прочитать поддерживаемое изображение через API | PDF/Word-пакеты не нужны; нужен настроенный vision-совместимый API |
| Агент читает файл своими средствами и сохраняет текст | Эти пакеты CLI не обязательны; агенту нужен свой способ открыть файл |
Пакеты необязательны и не устанавливаются автоматически с CLI. engine-missing означает,
что нужный пакет отсутствует или не может загрузиться. Это не отказ AI-модели.
unpdf читает PDF и его текстовый слой, но сам не выполняет OCR скана.
Установите пакет в окружение, из которого его может загрузить CLI. Для глобальной установки через npm в одном префиксе:
npm install -g unpdf mammoth @napi-rs/canvasДля локальной установки добавьте нужные пакеты в тот же проект. При использовании другого
менеджера пакетов глобальная установка в соседнее окружение не гарантирует доступность:
после установки повторите извлечение и проверьте, исчез ли engine-missing.
Для рендеринга проверены unpdf 1.8.1 и @napi-rs/canvas 1.0.10; старый unpdf может читать
текст, но не предоставлять необходимые функции рендеринга.
Агент: прочитать и сохранить
max attachments list --chat "Учебная группа" --needs-text --json
# Агент открывает localPath, читает все страницы и сохраняет буквальный текст в scan.txt.
max attachments text set "Учебная группа" 204 --attachment 1 --text-file ./scan.txt --json
max messages search 'content:умножение' --chat "Учебная группа" --offline --json--attachment нумеруется с 1. Сохраняйте исходный язык и порядок страниц, не подменяйте
расшифровку кратким пересказом. Не помечайте весь PDF прочитанным, если обработана одна страница.
Агентский текст защищён от перезаписи автоматическим извлечением.
Что именно делает агент
Агент не умеет автоматически открыть любой файл. Ему нужны доступ к localPath, программа
для чтения или преобразования формата и, для изображений, модель с возможностью зрения.
Он выбирает доступный способ, проверяет полноту результата и сохраняет текст через text set.
| Исходный файл | Как агент может получить текст |
|---|---|
| Текст в другой кодировке | Проверить маркер кодировки или использовать определение кодировки; преобразовать доступным инструментом, затем проверить читаемость |
| PDF с текстом | Использовать доступный читатель PDF, например pdftotext; сверить порядок колонок и таблиц |
| Скан PDF | Узнать число страниц, преобразовать каждую страницу в изображение, например pdftoppm; прочитать все изображения моделью со зрением |
| DOCX/ODT и презентация | Прочитать через библиотеку или установленное офисное приложение; при необходимости экспортировать страницы для визуальной проверки |
| Таблица | Прочитать каждый лист через библиотеку либо экспортировать листы в CSV; сохранить названия листов и строки, проверить числа и формулы |
| EPUB | Прочитать список глав и их HTML в порядке книги; простая распаковка не гарантирует правильный порядок |
| ZIP | Просмотреть содержимое; выбрать нужные файлы и применить к ним соответствующий способ чтения |
Это примеры возможных инструментов, а не программы, которые CLI устанавливает за агента. Если нужного средства нет, агент должен сообщить о неполной обработке. Удалённому агенту нужна передача самого файла; строка пути не решает эту задачу.
От чего зависит качество
| Способ | Что влияет на результат |
|---|---|
| Программное чтение текста | Правильная кодировка, полнота текстового слоя, поддержка формата, порядок абзацев/колонок/ячеек; текст внутри картинки так не читается |
| Агент с доступными инструментами | Всё перечисленное выше, качество его vision-модели, разрешение изображений, доступ ко всем страницам, ограничения контекста и тщательность проверки |
| API OCR | Выбранная vision-модель, разрешение и качество скана, язык, мелкий шрифт, поворот, таблицы и рукописный текст; одинаковая обработка большого числа файлов помогает повторяемости, но не гарантирует точность |
API не обязательно точнее агента: они могут использовать похожие модели. Его преимущество здесь — управляемая очередь, параллельная обработка и повторное использование результатов. Агент может сочетать точное программное чтение с визуальной проверкой сложных мест. Для цифрового документа сначала стоит получить исходный текст, а не распознавать его картинку. Числа, имена и важные таблицы при любом OCR нужно сверять с оригиналом.
API: явно выбранная массовая обработка
Внешняя модель может прочитать текст в поддерживаемых изображениях и на страницах
сканированного PDF. CLI отправляет ей изображение каждой нужной страницы, получает буквальный
текст и сохраняет его в том же индексе content:. PDF со слоем текста и DOCX остаются
программным чтением; выбор API не добавляет поддержку старых Office-форматов или ZIP.
Для запуска нужны vision-модель, её endpoint и ключ API. Пошаговая настройка OpenAI,
Anthropic и совместимого сервера, хранение ключа и выбор назначения models.ocr описаны
в руководстве по внешним моделям. После настройки:
max attachments extract --chat "Учебная группа" --ocr --concurrency 4 --limit 20 --jsonПовтор использует хеш файла и цель модели; хороший сохранённый текст остаётся при ошибке,
отмене или неполном ответе. Агентский текст не перезаписывается. Изображения и страницы
сканов уходят провайдеру только по явному --ocr; вызовы оплачиваются по его условиям.
--offline --ocr несовместимы; автоматического перехода от агента к API нет.
Лимит извлечения файла — 50 MiB; локальный текст ограничен 2 миллионами символов.
API OCR принимает PDF до 20 страниц, изображения до 4 MiB и 20 миллионов пикселей
(не более 8000 пикселей по каждой стороне). Число параллельных файлов — 1–8, по умолчанию 4;
страницы одного файла идут последовательно. По умолчанию API обрабатывает до 100 файлов,
--limit принимает 1–500. Для продолжения используйте возвращённый cursor.
При ответе провайдера 429 дальнейшие API-вызовы этого запуска прекращаются без повторов.
Команда возвращает статусы и ссылки на сообщения, а не полный текст распознавания.
Скачивание, извлечение и поиск подробнее описаны в поиске. Описание соответствует исходному коду CLI; наличие команды не означает, что каждый возможный файл данного формата проверен на реальном MAX.