meta-spider

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

Вместо текстовой рефлексии («подумай ещё раз») meta-spider читает скрытые состояния модели, сжимает их в когнитивные токены и впрыскивает обратно через гейтированное перекрёстное внимание (cross-attention). Базовая модель остаётся замороженной; обучается только тонкая обвязка (~2% параметров). Результат — селективное предсказание: модель воздерживается на вопросах, где ошиблась бы.

Установка

meta-spider требует Python 3.10+, PyTorch и Transformers. Квантованные базы (nf4/int8) дополнительно требуют bitsandbytes.

Четыре пакета, каждый в своей папке внутри meta-spider-framework/: meta-core (примитивы инференса — чистое ядро, не зависит ни от чего), meta-agent (агентный рантайм → Core), meta-loom (обучение + оценка → Core + Agent), meta-deploy (деплой в llama.cpp → Core). Прод-инференс ставит только meta-core.

# editable-установка из исходников
git clone <repo> && cd meta-spider-framework
pip install -e meta-core -e meta-agent -e meta-loom   # или только meta-core для инференса
pip install -e meta-deploy                            # опц.: экспорт в llama.cpp (GGUF-сайдкар)

# зависимости рантайма
pip install transformers datasets accelerate
pip install bitsandbytes  # опц.: nf4/int8 квантованные базы

Быстрый старт

Загрузите замороженную базу, привяжите обученный Doubter (Скептик) и генерируйте. Двухпроходный механизм пайплайн обрабатывает автоматически.

from meta_core import MetaSpiderConfig, MetaSpiderPipeline, Doubter

cfg = MetaSpiderConfig(
    model_name="google/gemma-2-2b-it",
    device="cuda", dtype="float16",
    quantization="nf4",                # 4-битная замороженная база (влезает в малые GPU)
    target_layers=[10,14,18,22,25],   # откуда читаются активации
    cross_attn_layers=[6,12,18,24],   # куда впрыскиваются когнитивные токены
)
pipe = MetaSpiderPipeline.from_pretrained(cfg)
pipe.attach(Doubter.from_checkpoint("doubter.pt"))

print(pipe.generate("What is the capital of France?"))
# → "The capital of France is Paris."
print(pipe.generate("Who wrote the 1953 novel 'A Kid for Two Farthings'?"))
# → "I'm not confident enough to answer this question accurately."

Размерности (hidden_dim, num_layers) определяются автоматически из базы. Выбор слоёв принимает явные списки или пресеты "all" / "late".

Как это работает

Один запуск = два прямых прохода одной замороженной модели.

Проход 1 (чтение): текст → замороженная LLM → хуки ловят hidden state последнего токена
                   → когнитивный энкодер → когнитивные токены (по одному на слой) → буфер
Проход 2 (запись): текст + впрыснутые когнитивные токены через гейтированный cross-attention
                   → замороженная LLM генерирует ответ (или честный отказ)

При обучении добавляется обратный проход: функция потерь — обычная языковая кросс-энтропия на таргете, а градиенты текут назад сквозь замороженную базу к энкодеру и cross-attention. База — пассивный передатчик: её веса не обновляются, но вычислительный граф сквозь неё существует. По сути сама базовая модель и есть функция потерь для обвязки.

Длинная генерация: AGC

На длинной генерации впрыснутая неуверенность самоусиливается — живой residual всё сильнее тянется к когнитивным токенам по мере роста дрейфа — и модель может уйти в петлю отказа. AGC (Automatic Gain Control, термин из схемотехники) это гасит: коэффициент α = floor + (1−floor)·e^(−шаг/τ) стартует с максимума и убывает к floor, доливая против «стока», — сомнение держится на ровном setpoint, а не убегает. Это opt-in — валидированный режим коротких генераций не трогается.

Архитектура: четыре пакета

Фреймворк — это четыре pip-пакета внутри meta-spider-framework/, у каждого одна задача и чистый граф зависимостей — ставите только то, что нужно.

граф зависимостей (стрелка = «зависит от»):
meta-core   →  (ничего)                # чистое ядро; прод-инференс = только оно
meta-agent  →  meta-core
meta-loom   →  meta-core + meta-agent  # Loom использует Agent для агентной оценки
meta-deploy →  meta-core               # экспорт обвязки → llama.cpp (GGUF-сайдкар)

Подробнее ниже: Core — в Компонентах ядра / Конфигурации; Loom — в Обучении / Оценке; Agent — в агентной части Оценки; Deploy — см. README пакета meta-deploy (metadeploy export + патч llama.cpp). Опциональный зонтичный шим meta_spider ре-экспортирует имена Core+Loom для обратной совместимости.

Компоненты ядра

Конфигурация

MetaSpiderConfig

DoubterConfig

TrainerConfig

Обучение Скептика

Обучение в две стадии: один раз собрать активации (они кэшируются), затем обучить обвязку. Запустить можно двумя способами — через CLI (рекомендуется) или Python API.

CLI — три стадии, один манифест

CLI metaloom разбивает конвейер на collect → train → eval, связанные манифестом run.json (модель · слои · датасет). collect его пишет; train, eval, meta-agent и metadeploy читают через --run-dir — флаги не приходится дублировать.

metaloom collect --run-dir runs/my --model-name Qwen/Qwen2.5-0.5B-Instruct \
                 --dataset mmlu --target-layers late --encoder-type selective --mcq-direct
metaloom train   --run-dir runs/my --epochs 6
metaloom eval    --run-dir runs/my

Python API

from meta_core import Doubter, DoubterConfig
from meta_loom import ActivationDatasetCollector, Trainer, TrainerConfig

# 1. Сбор активаций (прямой проход Pass-1 + флаг оракула pass1_correct)
collector = ActivationDatasetCollector(pipe, max_new_tokens=50,
                                       check_correctness=check_fn)
samples = collector.collect(questions, ground_truths)
ActivationDatasetCollector.save(samples, "dataset.pt")

# 2. Обучение обвязки (база остаётся замороженной)
doubter = Doubter(DoubterConfig(encoder_type="selective"))
pipe.attach(doubter)
trainer = Trainer(doubter, pipe, TrainerConfig(
    epochs=10, batch_size=2, grad_accumulation=16,
    learning_rate=2e-4, gate_lr_multiplier=5.0,
    pretrain_projectors=True,   # обязательно для selective-энкодера
))
trainer.train(train_samples, val_samples=val_samples)
doubter.save_checkpoint("doubter.pt")

Оценка и метрики

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

from meta_loom import BaselineComparison, QABenchmark, BenchmarkTask

bench = QABenchmark(name="test", tasks=tasks, scoring="custom")
report = BaselineComparison(pipe, bench, max_tokens=80).run()
print(report.summary())

Для агентной оценки (многошаговое использование инструментов) AgentComparison гоняет честную петлю база-против-Скептика через Meta-Agent (нативный формат tool-calling, не самодельный ReAct) и выдаёт pass-rate плюс счётчики спасённых/сломанных.

Агентный рантайм

Запустить обученную обвязку в агентной петле — инструменты, история и калиброванное решение: ответить, что-то найти или отказаться. Рантайм тонкий: добавляет агентный слой (петля, инструменты), а не вторую копию двухпроходного ядра.

meta-agent run --run-dir runs/my "What is the capital of France?"
# читает run.json (модель, слои, чекпойнт) — руками ничего вбивать не надо

Нативный tool-use, а не самодельный ReAct

Живые instruct-модели не держат текстовый протокол «Action: tool[arg]» — дописывают фейковый Observation и не останавливаются. Поэтому промпт строится через собственный apply_chat_template(tools=…) модели, а вывод парсится в её нативном тул-формате (<function=…> / JSON).

Деплой в llama.cpp

Обвязка полностью отделима от замороженной базы, поэтому обученный Скептик работает на CPU через llama.cpp — без GPU и PyTorch на инференсе.

1. Экспортируйте обвязку в GGUF-сайдкар (веса энкодера + cross-attention).
2. База работает как квантованный GGUF (напр. Q4_K_M).
3. Мета-адаптер впрыскивает когнитивные токены на хуке control-vector; двухпроходный драйвер снимает активации, гоняет энкодер, затем генерирует с впрыском.
4. Опциональное динамическое обновление переэнкодирует когнитивные токены во время длинных генераций (по гейту косинусной близости).

metadeploy export --run-dir runs/my            # обвязка → doubter_sidecar.gguf

# двухпроходный инференс в форке llama.cpp (CPU, без PyTorch):
META_SIDECAR=doubter_sidecar.gguf META_LAYERS=16,17,18,19,20,21,22,23 \
META_PROMPT="What is the capital of France?" \
  ./build/bin/llama-meta-generate -m base.Q4_K_M.gguf -c 2048 -t 4

Сборка форка и примера llama-meta-generate — по README пакета meta-deploy (llama_patch/ к базе llama.cpp b9619).

Справочник API

CLI

• metaloom collect|train|eval --run-dir <dir> — конвейер обучения; стадии связаны манифестом run.json
• meta-agent run --run-dir <dir> "вопрос" — агентный / чат-рантайм (читает манифест)
• metadeploy export --run-dir <dir> — экспорт обвязки в GGUF-сайдкар для llama.cpp

Pipeline

• MetaSpiderPipeline.from_pretrained(cfg) — загрузка + заморозка базы, инициализация коллектора.
• .attach(modifier) / .detach(modifier) / .detach_all()
• .generate(prompt, max_new_tokens=…, dynamic_refresh=False) — двухпроходный инференс.

Модификатор

• Doubter(DoubterConfig) — собрать новую обвязку.
• Doubter.from_checkpoint(path) / .save_checkpoint(path)

Обучение

• ActivationDatasetCollector(pipe, …).collect(questions, ground_truths)
• Trainer(doubter, pipe, TrainerConfig).train(train, val_samples=…)

Оценка

• BaselineComparison(pipe, benchmark).run() → ComparisonReport (селективный QA)
• AgentComparison(pipe, doubter=…, …).run(tasks) → агентная оценка через Meta-Agent
• QABenchmark, BenchmarkTask, AgentTask
• harness.classify_action(text) → "confirm" | "correct" | "refuse"

ЧаВо

Делает ли это модель умнее?

Нет. Знаний не добавляет — выводит наружу уже существующий внутренний сигнал неуверенности, чтобы модель отвечала, когда уверена, и отказывалась, когда нет. Превращает «ответить наугад» в «ответить, когда уверен».

Какие базовые модели поддерживаются?

Любая HF decoder-LM — Llama, Gemma (2/3/4), Qwen, Mistral, GPT-2. Поиск слоёв независим от семейства, включая вложенные мультимодальные конфиги.

Насколько велика обвязка?

~2% от базы (напр. ~188M на 8B-модели). База никогда не обновляется.

Можно ли обучать на маленькой GPU?

Да — используйте quantization="nf4" + gradient_checkpointing=True. Градиенты всё равно текут сквозь замороженную 4-битную базу к обвязке.

Переносится ли обвязка между моделями?

Нет. Она калибрована под распределение активаций одной модели. Если приклеить base-обученного Скептика к instruct-версии (или другой модели), скрытые состояния уйдут в OOD и генерация сломается — нужно переобучить на активациях целевой модели.

Что на очень длинных генерациях?

Сигнал неуверенности может самоусилиться и зациклиться. Включите AGC (см. Как это работает), чтобы держать его на setpoint.