Перший інструмент механістичної інтерпретованості для українських великих мовних моделей (проект у розробці...)

MamayScope — це дослідницька платформа для аналізу латентних просторів моделі MamayLM за допомогою розріджених автоенкодерів (Sparse Autoencoders). Система дозволяє витягувати активації residual потоку, тренувати SAE, знаходити інтерпретовані фічі та автоматично розмічати їх через LLM (OpenRouter).

Великі мовні моделі — чорні скриньки. Вони генерують текст, але ми не розуміємо як і чому. Механістична інтерпретованість — це напрямок, який досліджує внутрішні механізми нейромереж на рівні окремих компонентів.

Проблема: на момент створення MamayScope не існувало жодного інструменту механістичної інтерпретованості для українських LLM. Жодних натренованих SAE, жодних словників фіч, жодних адаптованих пайплайнів.

Рішення: MamayScope — end-to-end система, що покриває весь цикл: від збору активацій до інтерактивного перегляду розмічених фіч.

Плагін-бібліотека для vLLM, що дозволяє інспектувати внутрішні стани трансформера під час інференсу:

• ResidualStreamWorker — перехоплює залишковий потік через PyTorch forward hooks
• ProbeHookQKWorker — захоплює Q/K вектори з голів уваги
• SteerActivationWorker — модифікує активації для activation steering
• PluginRegistry — модульна архітектура з реєстром компонентів

Комунікація між процесами відбувається через змінні середовища (VLLM_HOOK_DIR, VLLM_HOOK_FLAG, VLLM_RUN_ID), оскільки воркери vLLM працюють у окремих підпроцесах.

Пайплайн-фреймворк, побудований на композиції асинхронних кроків PipelineStep:

Source → Processor → Processor → Sink

Кожен крок приймає dict, трансформує його та передає далі. PipelineExecutor оркеструє послідовне виконання.

CachedActivationsConfig → SAELensTrainer → ModelFileSink → HuggingFaceHubSink

• Словник: 16 384 фічі, вхідна розмірність: 3 584
• Hook point: blocks.33.hook_resid_post (residual потік шару 33)
• L1-регуляризація для розрідженості
• Інтеграція з Weights & Biases для логування
• Автоматичний push на Hugging Face Hub

ParquetConversationSource → MamayActivationProcessor → SaeFeatureEncodeProcessor → FeatureOccurrenceIndex → OpenRouterLabeling

• HTTP-запити до vLLM-MamayHook API для отримання активацій
• Кодування через SAE з вирівнюванням токенізації
• Побудова індексу входжень фіч
• Автоматична анотація через LLM (OpenRouter API)

Наразі корпус акцинтований на політичну тематику, проте має бути розширений до всіх тем.

LAPA HuggingFace → ParquetTextBatchSource → UkrainianPoliticalKeywordFilter → TextCorpusParquetSink

• 200+ ключових слів для фільтрації політичного дискурсу
• NFC-нормалізація та case-folding
• Шардований Parquet-вихід

Модель опублікована: mechark/MamaySAE

Аналіз 205 розмічених фіч виявив семантично значущі концепції:

Приклади:

• Feature 2569 — «Геополітичний дискурс та міжнародне право» (активується на текстах про суверенітет, міжнародні договори, територіальну цілісність)
• Feature 1115 — «Російські пропагандистські наративи» (виділяє маніпулятивну риторику, whataboutism, дезінформаційні кліше)
• Feature 6606 — «Дискурс причин та наслідків війни 2014 року» (фокус на хронології подій Майдану, анексії Криму)
• Feature 1621 — «Хронологія та документальна верифікація» (дати, номери резолюцій, посилання на офіційні документи)

# Клонування
git clone <repo-url>
cd MamayScope

# Встановлення залежностей (потрібен uv)
uv sync

# Запуск API сервера для збору активацій
uv run -m src.api.main

# Тренування SAE (smoke test)
uv run -m src.pipelines.saelens_sae_training_pipeline \
  --config configs/saelens_sae_trainer_smoke.yaml

# Повне тренування SAE
uv run -m src.pipelines.saelens_sae_training_pipeline \
  --config configs/saelens_sae_trainer_full.yaml

# Пайплайн розмітки нейронів
uv run -m src.pipelines.neuron_labeling_pipeline

# Побудова індексу фіч та автоматична розмітка
uv run -m src.scripts.build_feature_occurrence_index_and_labeler \
  --skip-llm --max-rows 1000

# Генерація HTML-браузера фіч
uv run -m src.scripts.build_feature_label_browser

Основні змінні середовища:

MamayScope/
├── src/
│   ├── api/                # FastAPI — ендпоінт /activations
│   ├── core/               # Налаштування
│   ├── pipelines/
│   │   ├── base.py         # Абстрактний PipelineStep
│   │   ├── pipeline_executor.py
│   │   ├── sources/        # Джерела даних (Parquet, HF, YAML)
│   │   ├── processors/     # Активації, SAE-кодування
│   │   └── sinks/          # Parquet, JSONL, HF Hub
│   ├── scripts/            # CLI-утиліти
│   ├── services/           # HookedMamayService, OpenRouter
│   └── schemas/            # Pydantic-моделі
├── configs/                # YAML-конфігурації тренування
├── docs/                   # Документація (українською)
└── tests/

MIT