Чистый Python-компилятор для локальной вики: замена LLM-агентов без токенов

Андрей Отинов -

Сцена: небольшая команда разработчиков хранит свои заметки в наборе разрозненных markdown‑файлов. Чтобы быстро находить нужную информацию, они пробовали «LLM‑вики» — скрипт, который каждый раз вызывает большой языковой модель, генерирует ссылки и переписывает страницы. Через несколько дней выяснилось, что каждый запрос стоит токены, а результаты меняются от запуска к запуску.

Источник: towardsdatascience.com

Факт: автор проекта заменил весь агентный пайплайн на чистый Python‑скрипт, который за один запуск превращает папку с исходными файлами в связную, проверенную вики без единого обращения к внешним сервисам.

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

Что проверить: стоит ли сейчас попробовать такой детерминированный компилятор вместо текущего LLM‑решения? Какие ограничения есть у инструмента и как быстро его протестировать в своей инфраструктуре?

Что репозиторий действительно даёт команде

  • Полный код без зависимостей. Всё работает на стандартной библиотеке Python — не требуется pip install.
  • Детерминированный результат. При одинаковом наборе входных файлов получаем точно такой же набор готовых markdown‑страниц, что упрощает контроль качества и откат изменений.
  • Четыре простых шага.
  • Поиск шаблонов (регулярные выражения) извлекает из каждого файла название, алиасы и дату.
  • Построение карты ссылок (граф упоминаний) определяет, где в тексте упоминаются другие заметки.
  • Создание разделов (перезапись) генерирует машинные части страниц, оставляя вручную написанные фрагменты нетронутыми.
  • Проверка целостности (линтер) ищет битые [[ссылки]] и страницы без входящих ссылок.
  • Тестовый набор из 17 юнит‑тестов гарантирует, что каждый из четырёх шагов работает корректно.
  • Бенчмарки показывают, что даже при 5 000 файлов процесс укладывается в несколько секунд на обычном ноутбуке.

Эти свойства позволяют использовать компилятор как надёжный «строительный блок» в любой локальной системе знаний.

Где он может вписаться в рабочий AI‑процесс

  • Замена LLM‑агента. Вместо многократных запросов к модели, компилятор выполняет один предсказуемый проход, после чего можно подключить уже готовый набор страниц к другим инструментам (поиск, чат‑боты, аналитика).
  • Интеграция в CI/CD. Поскольку скрипт не требует внешних сервисов, его легко добавить в пайплайн сборки: при каждом коммите в папку notes/ автоматически генерируется актуальная вики.
  • Локальная первая RAG‑архитектура. Если требуется быстрый доступ к контексту без обращения к облаку, сгенерированные markdown‑страницы могут стать «документами» для собственного векторного индекса, но без необходимости встраивать LLM‑генерацию.
  • Гибкость настройки. Пользователь может отключить проверку линтера (--no-lint) или изменить правила поиска, не меняя остальной код.

Таким образом, компилятор служит «детерминированным ядром», вокруг которого можно построить любые дополнительные AI‑слои, если они действительно нужны.

Как протестировать без превращения в игрушку

  1. Склонировать репозиторий
    bash git clone https://github.com/Emmimal/wiki-compiler.git cd wiki-compiler python init.py # ничего не устанавливает, просто проверяет окружение
  2. Подготовить небольшую папку raw_notes/ с несколькими .txt‑файлами, где в начале указаны Title:, Aliases: и Date: (как описано в README).
  3. Запустить компиляцию
    bash python compiler.py raw_notes/ compiled_wiki/ Вы увидите количество сгенерированных страниц, количество битых ссылок и количество «осиротевших» страниц.
  4. Запустить тесты
    bash python -m unittest tests -v Все 17 тестов должны пройти без ошибок — это подтверждает, что каждый шаг работает как задумано.
  5. Провести быстрый бенчмарк (опционально)
    bash python benchmark.py --files 100 --files 1000 --files 5000 Сравните время выполнения на вашей машине с результатами автора (секунды ≈ 0.5 – 2 с).

Чек‑лист для первой недели

✅ Что проверить
1 Репозиторий успешно склонирован и python init.py отработал без ошибок.
2 В папке raw_notes/ есть минимум три файла с корректным заголовком, алиасами и датой.
3 После compiler.py получены одинаковые результаты при повторных запусках (детерминированность).
4 Тестовый набор tests прошёл полностью (17/17).
5 Бенчмарк показывает время выполнения в пределах 1‑2 секунд для 100 файлов.
6 Нет битых ссылок и «осиротевших» страниц в отчёте линтера.

Если хотя бы один пункт не выполнен, стоит проверить формат исходных файлов или обратить внимание на известные баги, описанные в статье (проблемы масштабирования графа и недоучёт одиночных страниц).

Какие риски проверять перед внедрением

  • Требуемый формат входных файлов. Скрипт ожидает .txt‑файлы с метаданными (Title:, Aliases:, Date:). Любой отклонение приводит к пропуску информации.
  • Ограничения масштабирования. Автор отметил, что построение графа ссылок плохо масштабируется при очень больших коллекциях (десятки тысяч файлов). Для таких объёмов может потребоваться оптимизация или альтернативный подход.
  • Отсутствие лицензии. В репозитории лишь файл LICENSE без указаний, что может вызвать юридические вопросы при коммерческом использовании.
  • Отсутствие поддержки LLM‑функций. Если ваша команда всё ещё нуждается в генеративных подсказках (например, автодополнение текста), компилятор их не предоставляет.
  • Скрытые зависимости в окружении. Хотя код использует только стандартную библиотеку, он требует Python ≥ 3.8; старые версии могут не работать.

Оценив эти пункты, можно решить, подходит ли инструмент для вашего проекта или нужен более гибкий гибридный подход.

Какое решение принять дальше

  1. Пилотный запуск — выберите одну небольшую подсистему (например, документацию продукта) и примените компилятор к её заметкам.
  2. Сравните затраты. Подсчитайте, сколько токенов стоило бы использовать прежний LLM‑агент, и сравните с нулевыми расходами на текущий скрипт.
  3. Оцените качество. Проверьте, насколько полученная вики удовлетворяет требованиям команды (полнота ссылок, отсутствие битых ссылок).
  4. Примите решение. Если пилот показал экономию и стабильность, разверните компилятор на всю базу знаний; иначе, оставьте LLM‑агент только для тех задач, где нужна генерация текста.

Таким образом, вы получаете конкретный план действий, который можно выполнить уже на этой неделе.

Источники

Что почитать дальше