Распознавание форматов файлов¶

Обзор¶

tg-note теперь поддерживает автоматическое распознавание и обработку различных форматов файлов с помощью библиотеки Docling. Когда вы отправляете файл боту, система автоматически извлекает текстовое содержимое и интегрирует его в вашу базу знаний.

Поддерживаемые форматы¶

Документы¶

PDF (.pdf) - PDF документы с текстом и изображениями
Word (.docx) - Microsoft Word документы
PowerPoint (.pptx) - Microsoft PowerPoint презентации
Excel (.xlsx) - Microsoft Excel таблицы

Текстовые файлы¶

Markdown (.md) - Markdown файлы
HTML (.html) - HTML документы
Plain Text (.txt) - Обычные текстовые файлы

Изображения¶

JPEG (.jpg, .jpeg) - JPEG изображения
PNG (.png) - PNG изображения
TIFF (.tiff) - TIFF изображения

Как это работает¶

Автоматическая обработка¶

Отправьте файл боту (как вложение или пересланное сообщение)
Бот скачивает файл во временную директорию
Docling обрабатывает файл и извлекает текстовое содержимое
Содержимое добавляется к тексту сообщения для анализа агентом
Результат сохраняется в базу знаний

Пример использования¶

# Просто отправьте файл боту
# Бот автоматически:
# 1. Определит формат файла
# 2. Извлечет содержимое
# 3. Проанализирует с помощью AI агента
# 4. Сохранит в базу знаний с правильной структурой

Архитектура¶

Компоненты¶

FileProcessor (src/processor/file_processor.py)
Управляет обработкой файлов
Интеграция с Docling
Скачивание файлов из Telegram
Временное хранилище файлов
ContentParser (src/processor/content_parser.py)
Расширен методом parse_group_with_files()
Интегрирует содержимое файлов с текстом сообщения
Поддерживает асинхронную обработку
BotHandlers (src/bot/handlers.py)
Использует новый метод для обработки файлов
Поддерживает документы и фотографии
Автоматическая очистка временных файлов

Процесс обработки¶

┌─────────────────┐
│ Telegram Message│
│   with File     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Bot Handlers   │
│ (download file) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ File Processor  │
│   (Docling)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Content Parser  │
│ (merge content) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Agent      │
│  (analysis)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Knowledge Base  │
│    (save)       │
└─────────────────┘

Установка¶

Требования¶

Docling автоматически устанавливается как зависимость:

# Установка с Poetry
poetry install

# Или с pip
pip install -r requirements.txt

Проверка установки¶

Чтобы проверить, что Docling установлен правильно:

from src.processor.file_processor import FileProcessor

processor = FileProcessor()
if processor.is_available():
    print("Docling доступен!")
    print(f"Поддерживаемые форматы: {processor.get_supported_formats()}")
else:
    print("Docling недоступен")

Примеры использования¶

Обработка PDF документа¶

1. Отправьте PDF файл боту
2. Бот ответит: "🔄 Обрабатываю сообщение..."
3. После обработки вы получите уведомление с деталями:
   ✅ Сообщение успешно обработано и сохранено!
   📁 Файл: research-paper-2024-10-04.md
   📂 Категория: science/research
   🏷 Теги: pdf, research, ai

Обработка изображения с текстом¶

1. Отправьте изображение (например, скриншот или фото документа)
2. Docling извлечет текст с изображения
3. Текст будет проанализирован и сохранен в базу знаний

Пакетная обработка файлов¶

1. Отправьте несколько файлов подряд
2. Бот сгруппирует их (в течение 30 секунд)
3. Все файлы будут обработаны и объединены в одну заметку

Обработка ошибок¶

Неподдерживаемый формат¶

Если файл не поддерживается, бот: - Все равно попытается извлечь текст (если это возможно) - Обработает остальное содержимое сообщения - Не прервет обработку всего сообщения

Ошибка обработки файла¶

В случае ошибки при обработке файла: - Ошибка логируется в журнал - Пользователь получает уведомление (опционально) - Остальное содержимое сообщения все равно обрабатывается

Временные файлы¶

Система автоматически: - Создает временные директории для файлов - Очищает файлы после обработки - Обрабатывает исключения при очистке

Настройки¶

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

Таймаут для группировки сообщений¶

# config.yaml
MESSAGE_GROUP_TIMEOUT: 30  # секунды

Это влияет на то, как долго бот ждет перед обработкой группы файлов.

Расширенное использование¶

Программный доступ¶

Вы можете использовать FileProcessor напрямую в своем коде:

from pathlib import Path
from src.processor.file_processor import FileProcessor

async def process_my_file():
    processor = FileProcessor()

    if not processor.is_available():
        print("Docling недоступен")
        return

    result = await processor.process_file(Path("my_document.pdf"))

    if result:
        print(f"Извлечено {len(result['text'])} символов")
        print(f"Метаданные: {result['metadata']}")
        print(f"Текст: {result['text'][:100]}...")

Интеграция с агентами¶

Содержимое файлов автоматически добавляется к контексту для AI агентов:

# В content_parser.py
content = await self.content_parser.parse_group_with_files(group, bot=self.bot)

# content['text'] теперь содержит:
# - Текст сообщения
# - Содержимое всех прикрепленных файлов
# - Метаданные файлов

Производительность¶

Оптимизация¶

Асинхронная обработка: Все операции с файлами выполняются асинхронно
Временные файлы: Файлы хранятся временно и автоматически удаляются
Параллельная обработка: Несколько файлов в одном сообщении обрабатываются последовательно, но эффективно

Ограничения Telegram¶

Максимальный размер файла: 20 МБ (для ботов)
Файлы хранятся на серверах Telegram ограниченное время
Скорость скачивания зависит от сети

Отладка¶

Логирование¶

Включите подробное логирование для отладки:

# config.yaml
LOG_LEVEL: DEBUG

Это покажет: - Процесс скачивания файлов - Результаты обработки Docling - Ошибки и предупреждения - Операции очистки

Проверка работы Docling¶

import logging
logging.basicConfig(level=logging.DEBUG)

from src.processor.file_processor import FileProcessor

processor = FileProcessor()
print(f"Docling доступен: {processor.is_available()}")
print(f"Поддерживаемые форматы: {processor.get_supported_formats()}")

Известные проблемы¶

Большие файлы: Очень большие файлы (>10 МБ) могут требовать больше времени для обработки
Изображения низкого качества: OCR может не работать идеально на изображениях низкого качества
Сложная верстка: Некоторые PDF с сложной версткой могут требовать дополнительной обработки

Поддержка¶

Для получения помощи: - 📖 Документация - 🐛 Сообщить об ошибке - 💬 Обсуждения

Roadmap¶

Планируемые улучшения: - ✅ Базовая поддержка файлов (реализовано) - 🚧 Поддержка аудио и видео файлов - 📋 Улучшенное извлечение таблиц - 📋 Поддержка архивов (.zip, .tar.gz) - 📋 Batch processing для множества файлов - 📋 Кэширование обработанных файлов