scan4llm/installation.md

Установка окружения

Системные требования

• OS: Linux (x86_64)
• CPU: 8+ ядер (рекомендуется)
• RAM: 16+ GB (32 GB для LLM-корректора)
• Диск: 10+ GB свободного места

---

Шаг 1: Python 3.12 + venv

python3 -m venv .venv
source .venv/bin/activate

---

Шаг 2: Stage 1 — разрезание изображений

pip install opencv-python-headless typer

Зависимости: opencv-python-headless, numpy, typer, ruff (dev).

Проверка:

python -m src.image_split --help

---

Шаг 3: Stage 2 — OCR (PaddleOCR)

pip install paddlepaddle==3.2.2
pip install paddleocr pyyaml

Модели загружаются автоматически при первом запуске в ~/.paddlex/official_models/ (~2.5 GB).

Проверка:

python -m src.image_to_latex --help

---

Шаг 4 (опционально): LLM-корректор (Qwen2.5-7B)

pip install llama-cpp-python

Модель загружается из HuggingFace при первом запуске (~4.4 GB):

# Автоматически при первом --llm, или вручную:
curl -L "https://huggingface.co/bartowski/Qwen2.5-7B-Instruct-GGUF/resolve/main/Qwen2.5-7B-Instruct-Q4_K_M.gguf" \
  -o ~/.cache/llama_models/Qwen2.5-7B-Instruct-Q4_K_M.gguf

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

python -m src.image_to_latex -i page.jpg --llm

---

Шаг 5 (опционально): VLM-корректор (Qwen3.8 Max)

Требуется подписка OpenCode Go. Токен записать в .env:

echo 'OPENCODE_API_KEY=sk-...' > .env
echo 'HF_TOKEN=hf_...' >> .env

.env уже добавлен в .gitignore.

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

python -m src.image_to_latex -i page.jpg --vlm

---

Шаг 6 (опционально): Surya 2

Surya 2 требует отдельного venv из-за конфликтов зависимостей с PaddleOCR.

# Установка llama-server (CPU-версия)
mkdir -p ~/.local/bin
curl -L "${URL}" -o /tmp/llama.tar.gz
tar -xzf /tmp/llama.tar.gz -C /tmp/
cp /tmp/llama-*/llama-server /tmp/llama-*/lib*.so* ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

# Установка пакетов (в основном venv — конфликтует с PaddleOCR)
pip install surya-ocr torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install "opencv-python-headless==4.11.0.86" "pillow<11" transformers platformdirs

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

python -m src.image_to_latex -i page.jpg --ocr-engine surya

---

Шаг 7: Разработка

pip install ruff pytest
ruff check src/ tests/
python -m pytest tests/ -v

---

Структура моделей (локально)

~/.paddlex/official_models/          PaddleOCR (~2.5 GB)
~/.cache/llama_models/               LLM (~4.4 GB)
/tmp/hf_cache/                       Surya 2 (~1.5 GB, HuggingFace)