scan4llm/installation.md

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

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

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

---

Шаг 1: Python 3.12 + venv + все зависимости

python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Важно: PaddlePaddle — версия 3.2.2 (3.3.1 содержит баг PIR/ONEDNN на CPU).

---

Шаг 2: llama-server (для Surya 2 на CPU)

Surya 2 использует llama.cpp сервер. Нужен бинарник llama-server:

mkdir -p ~/.local/bin

# Скачать последний релиз (URL обновить из https://github.com/ggml-org/llama.cpp/releases/latest)
curl -L "https://github.com/ggml-org/llama.cpp/releases/download/b10268/llama-b10268-bin-ubuntu-x64.tar.gz" \
  -o /tmp/llama.tar.gz

tar -xzf /tmp/llama.tar.gz -C /tmp/
cp /tmp/llama-b10268/llama-server /tmp/llama-b10268/lib*.so* ~/.local/bin/

export PATH="$HOME/.local/bin:$PATH"
llama-server --version  # проверка

---

Шаг 3: Конфигурация (.env)

cp .env.dist .env
# Отредактировать .env — вставить токены

Переменная	Назначение
OPENCODE_API_KEY	API-ключ OpenCode Go для VLM-корректора
HF_TOKEN	HuggingFace токен (read-only) для скачивания моделей
OCR_LOG_FILE	Путь к debug-логу (необязательно)

---

Шаг 4: Модели (загружаются автоматически при первом запуске)

При первом запуске скрипты скачают нужные модели. Для ускорения можно предварительно задать HF_TOKEN в .env.

Движок	Модели	Размер	Куда
PaddleOCR	PP-StructureV3 (ансамбль)	~2.5 GB	~/.paddlex/official_models/
Surya 2	surya-2.gguf + mmproj	~1.5 GB	HF Hub (кеш)
LLM	Qwen2.5-7B-Q4_K_M.gguf	~4.4 GB	~/.cache/llama_models/

---

Проверка

# Stage 1
python -m src.image_prepare --help

# Stage 2 — PaddleOCR
python -m src.image_ocr -i test.jpg --ocr-engine paddle

# Stage 2 — Surya
python -m src.image_ocr -i test.jpg --ocr-engine surya

# Stage 2 — с LLM-корректором
python -m src.image_ocr -i test.jpg --ocr-engine paddle --fix-by-llm

---

Разработка

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