Hierarchical Text Summarization with LLM

Проект для иерархической суммаризации длинных текстов (например, книг) с использованием локальных LLM моделей через llama.cpp. Алгоритм разбивает текст на чанки, создает суммаризации, а затем рекурсивно объединяет их в связное повествование.

📋 Особенности

• Иерархическая суммаризация: Рекурсивное объединение суммаризаций для сохранения контекста
• Поддержка русского языка: Все промпты оптимизированы для русскоязычных текстов
• Очистка вывода: Удаление внутренних рассуждений модели и служебных тегов
• Проверка языка: Автоматическое обнаружение и исправление английских суммаризаций
• Логирование: Детальные логи процесса суммаризации
• Гибкая конфигурация: Настраиваемые параметры чанков, перекрытия и детализации

🛠️ Технологии

• Python 3.8+
• llama-cpp-python - для работы с GGUF моделями
• Regular Expressions - для очистки текста
• Grok/Gemma модели - предпочтительные модели для суммаризации

📁 Структура проекта

summarizer/
├── main.py                    # Основной скрипт суммаризации
├── README.md                  # Документация
├── requirements.txt           # Зависимости Python
├── example_config.py          # Пример конфигурации
├── Master_i_Margarita.txt     # Пример текста для суммаризации
├── Summary_Detailed.txt       # Детальный лог суммаризации (генерируется)
├── Output_summary.txt         # Итоговая суммаризация (генерируется)
└── hierarchical_log.txt       # Лог иерархического процесса (генерируется)

⚙️ Установка

1. Клонируйте репозиторий:

   git clone https://github.com/yourusername/text-summarizer.git
   cd text-summarizer

2. Установите зависимости:

   pip install -r requirements.txt

3. Установите llama-cpp-python:

   # Для CPU
   pip install llama-cpp-python
   
   # Для GPU (CUDA)
   CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python

📊 Требования к модели

Рекомендуемые модели (GGUF формат):

• Grok-3-reasoning-gemma3-12B-distilled-HF.Q8_0.gguf (используется в примере)
• Mixtral-8x7B-Instruct-v0.1-GGUF
• Llama-3-8B-Instruct-GGUF
• Любая модель с поддержкой чат-формата и русским языком

Скачайте модель и укажите путь к ней в коде.

🚀 Использование

Базовое использование

1. Подготовьте текстовый файл в кодировке UTF-8 или cp1251

2. Настройте путь к модели в скрипте:

   model_path = r"путь/к/вашей/модели.gguf"

3. Укажите путь к текстовому файлу:

   book_file = r"путь/к/вашей/книге.txt"

4. Запустите суммаризацию:

   python main.py

Настройка параметров

Основные параметры для настройки в функции main():

# Параметры модели
llm = Llama(
    model_path=model_path,
    chat_format="gemma",        # Или "chatml"
    n_ctx=32768,                # Контекстное окно
    n_threads=8,                # Количество потоков CPU
    n_gpu_layers=47,            # Слоев на GPU (0 для CPU)
    temperature=0.1,            # "Температура" генерации
    max_tokens=8192,            # Максимальное количество токенов
)

# Параметры суммаризации
chunk_size=3000                 # Размер чанка в символах
overlap_sentences=3            # Перекрытие между чанками
max_group_size=5               # Размер группы для иерархической суммаризации

📝 Формат вывода

Программа создает три файла:

1. Output_summary.txt - Итоговая суммаризация:

   • Общая сводка (10-20 предложений)
   • Иерархическая сводка
   • Суммаризации отдельных чанков

2. Summary_Detailed.txt - Детальный процесс:

   • Подробные суммаризации каждого чанка
   • Иерархические объединения
   • Промежуточные результаты

3. hierarchical_log.txt - Технический лог:

   • Структура рекурсивных вызовов
   • Количество обрабатываемых элементов на каждом уровне
   • Время выполнения

🔧 Функции

Основные функции

1. clean_model_output(text) - Очищает вывод модели от тегов <think>, <reasoning> и внутренних рассуждений

2. combine_into_narrative(llm, text_list) - Объединяет список текстов в связное повествование

3. chunk_text(text, chunk_size, overlap_sentences) - Разбивает текст на перекрывающиеся чанки

4. summarize_chunk(chunk, level, summary_file) - Суммаризирует один чанк с проверкой языка

5. hierarchical_summarize(summaries, max_group_size, level, ...) - Рекурсивная иерархическая суммаризация

Алгоритм работы

1. Загрузка и очистка текста
2. Разделение на чанки с перекрытием
3. Суммаризация каждого чанка с проверкой на русский язык
4. Иерархическое объединение суммаризаций (рекурсивно)
5. Создание финальной общей сводки
6. Сохранение результатов в три различных файла

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

# Быстрый старт с вашим текстом
book_file = "ваша_книга.txt"
model_path = "модели/grok-3.gguf"

# Запуск суммаризации
# Результаты будут в Output_summary.txt и Summary_Detailed.txt

🎯 Пример суммаризации романа "Мастер и Маргарита"

Итоговая суммаризация текста

Все рассуждения и теги удалены

---

Общая сводка (очищена от рассуждений)

Роман "Мастер и Маргарита" Михаила Булгакова — это уникальное произведение, объединяющее сатирическое изображение советской Москвы 1930-х годов с глубокими философскими и мистическими темами. В центре сюжета — прибытие таинственного Воланда, иностранного профессора черной магии, и его демонической свиты, включая эксцентричного Бегемота и остроумного Коровьева, которые сеют хаос и абсурд в столице: от провала театральных постановок до поджогов и финансовых махинаций.

Параллельно развивается трагическая история любви Маргариты к Мастеру, писателю, создавшему роман о Понтии Пилате, который подвергается гонениям за свои взгляды. Отчаявшись спасти любимого, Маргарита заключает сделку с Воландом и участвует в его мистическом бале, где проходит ряд испытаний, проверяющих её преданность и моральные принципы.

Вставная иерусалимская линия переносит читателя в древний Иерусалим, где рассказывается о последних днях жизни Иешуа Га-Ноцри (прототип Иисуса Христа) и внутреннем конфликте Понтия Пилата, римского прокуратора, мучимого совестью за приговор. Эта часть романа исследует темы веры, власти, предательства и поиска истины.

Сюжетные линии Москвы и Иерусалима переплетаются, отражая универсальные вопросы о добре и зле, свободе и контроле. Воланд, обличая человеческие пороки, в конечном итоге покидает Москву, предсказав грядущие разрушения, а Мастер и Маргарита обретают вечный покой в месте, где их любовь не знает границ, вместе с романом Мастера, который получает признание.

Ключевые персонажи, такие как Воланд, Мастер, Маргарита и Бегемот, воплощают разные аспекты человеческой природы и моральных дилемм. Роман оставляет читателя с чувством недоумения и заставляет задуматься о природе реальности, судьбы и вечных вопросах бытия. Булгаков мастерски сочетает юмор, сатиру и мистику, создавая многослойное произведение, которое можно интерпретировать на разных уровнях.

---

Иерархическая сводка (очищена от рассуждений)

Роман "Мастер и Маргарита" Михаила Булгакова — это многослойное произведение, сочетающее сатиру на советскую действительность 1930-х годов с мистикой и философскими размышлениями.

Сюжет разворачивается в Москве, где прибытие таинственного иностранца Воланда и его демонической свиты (включая Бегемота и Коровьева) приводит к хаосу и абсурдным событиям: от теастральных провалов и банковских беспорядков до пожаров и массовых арестов.

Параллельно развивается трагическая история любви Маргариты к писателю, Мастеру, автору романа о Понтии Пилате, что толкает её на участие в мистическом бале у Воланда и испытания, проверяющие её моральные принципы.

Вставная иерусалимская линия повествует о последних днях Иешуа Га-Ноцри и муках совести римского прокуратора Пилата, исследуя темы веры, власти и искупления.

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

---

Предварительные суммаризации чанков

Чанк 1: В жаркий майский вечер на Патриарших прудах в Москве встречаются председатель МАССОЛИТ Михаил Берлиоз и поэт Иван Бездомный, которые обсуждают вопросы веры и творчества. Они заходят в будочку, где покупают абрикосовый сок, и садятся на скамейку у пруда.

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

Разговор между писателями прерывается этим событием, которое становится началом череды загадочных происшествий. Текст, предположительно, является частью романа "Мастер и Маргарита" Михаила Булгакова, что подтверждается упоминанием рукописи и прижизненной редакции.

Чанк 2: [текст продолжается...]

---

⚠️ Ограничения и рекомендации

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

• Время выполнения: ~4-5 часов для книги на модели Grok-3 на видеокарте RTX3090ti 24Gb (зависит от длины текста)
• Память: Требуется достаточная VRAM/RAM для модели (12ГБ+ для 12B моделей)
• Оптимизация: Используйте квантованные модели (Q4_K_M, Q8_0) для лучшей производительности

Качество суммаризации

• Лучшие результаты с моделями, обученными на русском языке
• Размер чанка 2000-4000 символов оптимален для баланса контекста и детализации
• Перекрытие чанков (3-5 предложений) помогает сохранить контекст

Проблемы и решения

1. Английские суммаризации: Скрипт автоматически перегенерирует их на русском
2. Потеря контекста: Увеличьте перекрытие чанков и уменьшите max_group_size
3. Слишком общие суммаризации: Уменьшите temperature и увеличьте chunk_size

📈 Будущие улучшения

• Поддержка различных форматов входных файлов (PDF, EPUB, DOCX)
• Веб-интерфейс для удобного использования
• Пакетная обработка нескольких файлов
• Настройка параметров через конфигурационный файл
• Поддержка большего количества языков
• Экспорт в различные форматы (JSON, HTML, Markdown)
• Интеграция с Telegram

🤝 Вклад в проект

Приветствуются пул-реквесты и issues! Пожалуйста:

1. Форкните репозиторий
2. Создайте ветку для вашей функции (git checkout -b feature/AmazingFeature)
3. Закоммитьте изменения (git commit -m 'Add some AmazingFeature')
4. Запушьте в ветку (git push origin feature/AmazingFeature)
5. Откройте Pull Request

📄 Лицензия

Распространяется под лицензией MIT.

✨ Автор

Vad_neld
Telegram: @Vad_neld
E-mail: v.bel@list.ru

⭐ Если этот проект был полезен, поставьте звезду на GitHub!