NotebookLlaMa🦙

Форк проекта notebookllama с упором на локальный запуск (без платных облачных LLM по умолчанию), улучшенный вывод майндмэпов и быстрый hybrid‑режим.

Исходный проект: github.com/run-llama/notebookllama

---

Требования

• Python 3.10+ (рекомендуется 3.13+)
• Docker и Docker Compose (для PostgreSQL и других сервисов)
• Ollama (для локальной LLM обработки) - установка
• Рекомендуется создать виртуальное окружение и установить зависимости (pip install -r requirements.txt).
• Для более надёжного извлечения текста из PDF установите pdfplumber (опционально).

На macOS / Linux можно установить uv по инструкции проекта; для Windows следуйте официальной документации uv.

---

Быстрый старт (PowerShell)

1. Создайте и активируйте виртуальное окружение, затем установите зависимости:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Создайте файл .env с настройками PostgreSQL:

# Скопируйте .env.example или создайте вручную
# Минимальные настройки:
pgql_user=postgres
pgql_psw=postgres
pgql_db=notebookllama

3. Запустите локальные сервисы (PostgreSQL, Jaeger, Adminer):

docker compose up -d

4. Установите и запустите Ollama (если еще не установлен):

# Скачайте Ollama с https://ollama.ai и установите
# Затем скачайте модель:
ollama pull mistral
# Или другую модель:
ollama pull llama3.1:8b

5. Запустите Streamlit (рекомендуется запускать как модуль):

$env:PYTHONPATH = 'src'
$env:PGCLIENTENCODING = 'UTF8'
python -m streamlit run src/notebookllama/Home.py

Откройте http://localhost:8501/ в браузере.

---

Try it — короткая сводка

В PowerShell (в корне репозитория):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
docker compose up -d
ollama pull mistral  # если еще не установлена
$env:PYTHONPATH = 'src'
$env:PGCLIENTENCODING = 'UTF8'
python -m streamlit run src/notebookllama/Home.py

---

Выбор модели Ollama

В sidebar (левая панель) приложения доступен выбор модели Ollama для обработки документов:

• Ollama Model Settings — выбор модели для основной обработки (summaries, mind maps, Q&A)
• Доступные модели загружаются автоматически из вашей установки Ollama
• По умолчанию используется mistral, но можно выбрать любую установленную модель

Важно: Модели Ollama используются для качественной обработки документов. HuggingFace модели в sidebar — это только fallback на случай, если Ollama недоступен.

---

Hybrid режим: быстрый extractive + фоновый LLM‑рефайн

Режим "hybrid" показывает мгновенный extractive‑результат (локальный, быстрый) и одновременно запускает фоновый LLM‑рефайн для более структурированного и подробного вывода.

Основные элементы:

• UI-кнопка: "Extractive + LLM refine" — показывает extractive сразу и запускает рефайн в фоне.
• Sidebar опция: "Always use extractive by default (fast)" — при включении обычная обработка будет выполнять только extractive путь.
• Sidebar опция: "Auto-apply LLM refine result when ready" — при включении refined результат автоматически заменит extractive вывод; иначе появится превью с кнопками "Apply" / "Dismiss".

Техническая заметка: фоновая задача записывает результат в временный JSON‑файл; основной поток UI периодически проверяет этот файл и аккуратно применяет результат в session_state — это снижает риск гонок между потоками.

---

Sidebar — настройки моделей

Ollama Model Settings

• Ollama Model (for document processing) — выбор модели Ollama для обработки документов
• Модели загружаются автоматически из вашей установки Ollama
• Используется для генерации summaries, mind maps, Q&A

HuggingFace Fallback Settings

Панель слева позволяет настроить поведение fallback‑модели HuggingFace (если Ollama недоступен), выбрать модель, предзагрузить её и задать параметры генерации (temperature, max_tokens, top_k, top_p, do_sample).

Рекомендация для быстрых CPU‑тестов: модель distilgpt2, temperature=0.0, max_tokens=256, do_sample=false.

---

База данных PostgreSQL

Приложение использует PostgreSQL для хранения обработанных документов. База данных создается автоматически при первом запуске Docker контейнера.

Настройки подключения

Настройки указываются в файле .env:

pgql_user=postgres
pgql_psw=postgres
pgql_db=notebookllama

Просмотр данных

Для просмотра данных в базе можно использовать:

• Adminer (веб-интерфейс): http://localhost:8080
  • Система: PostgreSQL
  • Сервер: postgres (или localhost)
  • Пользователь: postgres
  • Пароль: postgres
  • База данных: notebookllama

Важно

• База данных создается автоматически с кодировкой UTF8
• Таблицы создаются автоматически при первом использовании
• Все данные обрабатываются с правильной кодировкой UTF-8

---

Исправления и улучшения

Исправления кодировки UTF-8

• Добавлена обработка ошибок кодировки при чтении файлов
• Улучшена работа с PostgreSQL (явная установка UTF-8 кодировки)
• Исправлена обработка BOM в файлах
• Добавлена переменная окружения PGCLIENTENCODING=UTF8

Выбор модели Ollama

• Добавлен выбор модели Ollama в sidebar
• Все запросы к Ollama используют выбранную модель
• Автоматическая загрузка списка доступных моделей

Улучшения подключения к базе данных

• Безопасная обработка данных при чтении из PostgreSQL
• Автоматическое создание базы данных с правильной кодировкой
• Обработка ошибок подключения с повторными попытками

---

Примечания по конфигурации

• Параметры LLM/тасков можно указать в config.yaml или через переменные окружения.
• Если используете облачные сервисы, добавьте соответствующие ключи в .env (HUGGINGFACE_API_KEY, LLAMACLOUD_API_KEY и т.д.).
• Переменная окружения OLLAMA_MODEL устанавливается автоматически при выборе модели в sidebar.

---

Решение проблем

Ошибка "Ollama seems unreachable"

1. Убедитесь, что Ollama запущен: ollama serve
2. Проверьте доступность: curl http://localhost:11434/api/tags
3. Если Ollama не запущен, запустите его и обновите страницу в браузере

Ошибка "UnicodeDecodeError"

• Убедитесь, что база данных создана с кодировкой UTF8
• Проверьте, что переменная PGCLIENTENCODING=UTF8 установлена
• Пересоздайте базу данных: docker compose down → удалите том instrumentation_pgdata → docker compose up -d

Плохое качество результатов

• Убедитесь, что используете LLM режим, а не только extractive
• Выключите опцию "Always use extractive by default (fast)" в sidebar
• Используйте кнопку "Process Document" для полной LLM обработки
• Или используйте "Extractive + LLM refine" для hybrid режима

---

Лицензия

Проект распространяется под лицензией MIT. Подробнее: ./LICENSE