> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Как работать с документами

> Руководство по чтению, извлечению и сохранению документов через Велес.

# Как работать с документами

Это руководство объясняет, как пользователь может работать с документами через Велеса: читать их, извлекать текст, пересказывать, сохранять в базу знаний проекта и потом искать по ним информацию.

***

## Что умеет Велес

Велес умеет:

* читать документы и вытаскивать из них текст;
* распознавать текст на сканах, фотографиях и скриншотах;
* пересказывать содержимое;
* извлекать таблицы и структуру документа в Markdown;
* сохранять распознанный документ в папку проекта в `docs/`, чтобы потом использовать его как документацию.

Проще говоря: вы можете отправить файл и попросить Велеса «прочитать», «пересказать», «извлечь главное» или «сохранить в документацию проекта».

***

## Какие форматы поддерживаются

Велес умеет работать не только с PDF.

Поддерживаются документы:

* PDF
* DOCX, DOC
* PPTX, PPT
* XLSX
* CSV
* TXT
* EPUB
* RTF
* ODT
* XML
* TEX
* IPYNB

Поддерживаются изображения:

* PNG
* JPG, JPEG
* AVIF
* TIFF
* GIF
* HEIC, HEIF
* BMP
* WebP

***

## Как попросить Велеса поработать с документом

Обычно достаточно отправить файл и написать, что именно вы хотите.

Примеры:

* «Прочитай этот PDF и кратко перескажи».
* «Извлеки текст из этого документа».
* «Посмотри таблицу в файле и выпиши основные цифры».
* «Прочитай этот скан договора и перечисли ключевые условия».
* «Сохрани этот документ в документацию проекта `sales`».
* «Распознай этот файл и положи его в `docs/finance`».

Вам не нужно вручную вызывать внутренний инструмент. Достаточно описать задачу человеческими словами.

***

## Что происходит после распознавания

Когда Велес читает документ, он превращает его содержимое в Markdown-текст. Это удобно, потому что такой текст:

* легче пересказывать;
* удобнее анализировать;
* можно сохранить в `docs/`;
* потом по нему можно искать информацию через умный поиск по документации.

Если вы просто попросили «прочитать» документ, Велес обычно вернёт текст, краткое содержание или нужные выводы в ответе.

Если вы попросили сохранить документ в `docs`, Велес обычно:

1. сначала распознаёт документ;
2. превращает его в `.md`;
3. сохраняет в `docs/<имя_проекта>/<имя_файла>.md`.

Это важно, потому что в `docs/` лучше хранить именно текстовые материалы, а не исходные PDF или сканы. Так Велес сможет потом нормально искать по ним информацию.

***

## Когда полезно сохранять документ в `docs`

Сохранять документ в `docs` особенно полезно, если это:

* спецификация;
* инструкция;
* договор или шаблон;
* коммерческое предложение;
* исследование;
* презентация;
* таблица с данными;
* любая справочная информация, к которой вы будете возвращаться позже.

После сохранения такой документ становится частью документации проекта и может пригодиться в следующих разговорах.

***

## Что лучше писать в запросе

Лучше всего работает конкретная формулировка.

Хорошие примеры:

* «Прочитай файл и сделай краткое содержание на русском».
* «Извлеки из документа только финансовые показатели».
* «Найди в договоре сроки оплаты и штрафы».
* «Сохрани эту презентацию в `docs/invest` и потом кратко опиши её».
* «Распознай таблицу из изображения и переведи её в Markdown».

Чем точнее задача, тем полезнее будет результат.

***

## Ограничения, о которых стоит знать

* Файл должен существовать и быть доступен Велесу.
* Очень большие файлы не обрабатываются: лимит около 50 МБ на один файл.
* Если документ очень длинный, Велес может показать в ответе только часть результата.
* Если документ был сохранён в `docs`, полный распознанный текст всё равно останется на диске, даже если ответ в чате был сокращён.
* Для распознавания документов должен быть настроен OCR-сервис. Если он не настроен, Велес сообщит об этом ошибкой.

***

## Что делать, если Велес не смог прочитать документ

Обычно причина одна из этих:

* формат файла не поддерживается;
* файл слишком большой;
* OCR не настроен;
* файл повреждён или недоступен.

В таких случаях лучше попробовать так:

* отправить PDF вместо редкого формата;
* уменьшить размер файла;
* прислать отдельные страницы или изображения;
* попросить сохранить документ в `docs`, если хотите работать с результатом позже;
* уточнить задачу: например, не «прочитай всё», а «найди в документе раздел про оплату».

***

## Полезные сценарии

### 1. Быстро прочитать документ

Отправьте файл и напишите:

«Кратко перескажи этот документ».

### 2. Достать важные пункты

Отправьте документ и попросите:

«Найди основные риски, сроки и обязательства».

### 3. Сохранить в базу знаний проекта

Если хотите, чтобы Велес мог вернуться к документу позже, напишите:

«Сохрани этот документ в `docs/legal`».

### 4. Обработать скан или фото

Можно отправить фото страницы, скриншот, снимок доски или скан и написать:

«Распознай текст на изображении и оформи аккуратно».

***

## Итог

Чтобы работать с документами, вам достаточно отправить файл и написать, что нужно сделать: прочитать, пересказать, извлечь данные или сохранить в `docs`.

Если документ важен для будущей работы, лучше сразу попросить сохранить его в папку проекта в `docs`. Тогда Велес сможет использовать этот материал позже как часть документации.