scan4llm/.ai/SKILLS.md

Наработанные навыки

OCR / PaddleOCR

• PP-StructureV3: конфигурация через YAML-файл, замена моделей распознавания (eslav_PP-OCRv5_mobile_rec для русского, PP-OCRv6_medium_rec для английского), смена детектора PP-OCRv5_server_det → PP-OCRv6_medium_det без апгрейда paddlepaddle
• Архитектура детекторов: DB (Differentiable Binarization) vs DB++ (RepLKFPN, ASF, DCN), PPLCNetV4, EncoderWithLightSVTR
• Модельный зоопарк: eslav vs cyrillic (обе mobile, разница ~1%), PP-OCRv6_medium_rec (46 латинских + CN/JP/EN, без кириллицы), PP-FormulaNet для формул, SLANeXt для таблиц
• Параметры детектора: thresh (порог карты вероятности), box_thresh (фильтр bbox), unclip_ratio (расширение контура), max_side_limit (обрезает upscale)
• Источники моделей: PaddlePaddle CDN, HuggingFace Hub, modelscope — fallback-цепочка в paddlex

Surya 2 / llama.cpp

• CPU-оптимизации: SURYA_INFERENCE_KEEP_ALIVE=true (-23s повторный старт), CTX_PER_SLOT=8192 (-30% RAM), PARALLEL=1 (-80% слотов), pre-scale=1056px (~96 DPI), -t 8 --threads-batch 8 (стабильная загрузка CPU)
• Health-check + retry: проверка http://host:port/health, пересоздание engine при падении llama-server, lru_cache.cache_clear() для сброса

OpenCV

• Unwarping: Canny → findContours → approxPolyDP → _order_points → getPerspectiveTransform → warpPerspective с порогом min_area ≥ 30% (чтобы не детектить внутренние таблицы как страницу)
• Denoising: fastNlMeansDenoisingColored — Non-Local Means. Полезен для шумных сканов, NOP для чистых. НЕ вреден для нейросетевого OCR
• Бинаризация: adaptiveThreshold (Gaussian, окно 31) вредна для нейросетевого OCR — жёсткие границы рвут буквы, создают ложные контуры. Нейросети обучены на естественных изображениях, не на бинарных
• Upscale: cv2.resize(INTER_CUBIC) бесполезен, если OCR-движок обрезает max_side_limit

Архитектура Python / SOLID

• Вынос общих моделей: ParsedBlock, OcrPageResult → отдельный models.py — 7 модулей отвязаны от paddle_engine
• Protocol → Callable: если Protocol никем не реализован — YAGNI. Callable[[ParsedBlock], None] проще
• lru_cache вместо глобальных синглтонов: @functools.lru_cache(maxsize=N) вместо _engine: X | None = None + global _engine
• idempotent env loader: load_env() с внутренним guard’ом — не нужны внешние _ENV_LOADED флаги
• Shared API client: call_qwen_vlm() + image_to_base64() в qwen_client.py — общий для OCR-движка и корректора

CLI / Typer

• Annotated-параметры: Annotated[Path, typer.Option("--input", "-i")] — минимум бойлерплейта
• Параметры по умолчанию: обязательные без default, опциональные с = None, булевы через --flag / --no-flag
• Collapsible --help в README: <details><summary>--help</summary>...</details>

pip / Управление зависимостями

• opencv конфликт: opencv-contrib-python и opencv-python-headless делят cv2/ — удаление одного ломает другой. Выбор: headless легче (-18 MB), без X11
• version pinning: paddlepaddle==3.2.2 (баг ONEDNN/PIR в 3.3.1), numpy<2.4 (paddlex ограничение), opencv-python-headless<5.0 (surya-ocr требует 4.11)
• pip freeze → ручной requirements.txt: 118 пакетов → 14 (только прямые зависимости)

Многоформатный вывод

• JSON → LaTeX: 3 формата (Paddle parsing_res_list, Surya blocks[].html, Qwen blocks[].content), автоопределение по структуре
• JSON → HTML + MathJax: единый шаблон HTML_TEMPLATE, CDN MathJax 3, $$...$$ для display-формул
• Таблицы: HTML <table> → LaTeX tabular, Markdown |...| → HTML <table>

Документирование

• Аудит SOLID/DRY/KISS/YAGNI: дважды за проект, фиксация нарушений с severity и планом исправления
• История экспериментов: stage2_results.md — 16 вариантов, маркировка ✅/❌/⚠️, причина решения
• Модельный инвентарь: какие модели установлены, размер, назначение, какие можно удалить

Удалённое за ненадобностью

Что	Причина
LLM-корректор (Qwen2.5-7B, 4.4 GB)	Галлюцинации, слепой, большой
Binarization (adaptive threshold)	Вредна для нейросетевого OCR
Upscale ×2	max_side_limit=4000 съедает
surya2html.py, tex2html.py	Дубликаты json_to_latex.py
100+ пакетов в requirements.txt	Транзитивные зависимости pip freeze
2.2 GB мёртвых моделей	Неиспользуемые v5 и cyrillic