FANTA на Hugging Face Hub

В модельном репозитории лежит тот же набор файлов, что и в этом проекте в корне: fanta/ (код), train_fanta.py, scripts/ и т.д. Веса чекпоинтов выкладываются внутрь каталога fanta/, по пути:

fanta/<пресет>/checkpoint-<шаг>/

Пример: fanta/fanta-1b/checkpoint-1000/ (внутри — config.json, model*.safetensors и индекс при шардировании).

---

Архитектура FANTA

FANTA (Fusion Attention Network for Temporal Anomalies) — одна сеть для многомерных временных рядов: на вход подаётся окно длины T с F признаками (тензор B×T×F). Модель одновременно учится предсказывать следующий шаг по каждому признаку и оценивать аномальность в каждой временной точке (бинарная голова на метках).

Важно: ускорение за счёт linear attention. Каждый слой — гибрид полного внимания O(T²) и линейного внимания O(T) (feature map elu + 1). За счёт линейной ветки длинные окна обрабатываются существенно быстрее и дешевле по памяти, а gate-механизм сам выбирает, где опираться на «точное» внимание, а где — на «длинное». Это ключевой элемент производительности FANTA на длинных последовательностях.

Поток данных

flowchart TB
  IN["Вход: окно B × T × F"]
  STEM["Линейная проекция F → d_model, синусoidal PE, dropout"]
  ENC["Стек из N блоков HybridAttentionBlock"]
  FUS["LayerStackFusion: последние K слоёв → одно представление d_model"]
  REG["Голова регрессии: следующий шаг по признакам"]
  ERR["Абсолютная ошибка прогноза + скрытое состояние"]
  ANOM["Cross-attention + MLP → логиты аномалии T−1"]
  AUX["Опционально: aux-голова"]
  IN --> STEM --> ENC --> FUS
  FUS --> REG
  FUS --> ERR --> ANOM
  FUS --> AUX

Гибридное внимание в каждом слое

В HybridAttentionBlock два параллельных пути над одним и тем же представлением после LayerNorm:

• Полное внимание — классический multi-head scaled dot-product attention (глобальный контекст по времени, сложность O(T²)).
• Линейное внимание (для ускорения) — основная ветка для длинных окон: O(T) по длине последовательности за счёт feature map elu + 1 и рекуррентной формы (KᵀV) по времени. Квадратичный рост не возникает, что критично при seq_len ≥ 512–1024 и глубоких стек-конфигурациях (fanta-5b+).

Выходы двух веток взвешиваются поэлементно через sigmoid-gate от конкатенации [x, full, linear]: модель сама выбирает баланс между «точным» и «длинным» вниманием — в регионах, где важна глобальная связь, работает full attention, а общий поток по времени дешёво обрабатывает линейная ветка. Дальше — стандартный FFN (расширение dim_feedforward, GELU) с остатком.

Зачем именно linear attention, а не только full?

• Память и время на слое — линейно по T, а не квадратично → можно брать длиннее окна без взрыва затрат.
• Линейное внимание особенно хорошо описывает плавные долгосрочные зависимости во временных рядах, тогда как full attention точнее на локальных резких перепадах. Гибрид совмещает оба эффекта.
• На A100 для seq_len=512 и fanta-1b ветка linear заметно снижает время шага и потребление VRAM по сравнению с чистым full-attention вариантом эквивалентной ширины.

Слияние слоёв (fusion)

Последние K матриц скрытых состояний (форма B×L×K×d) сшиваются в LayerStackFusion: сначала линейная проекция из K·d в d, затем один слой multi-head self-attention по времени и небольшой FFN. Так фиксируется совместная информация нескольких глубин стека.

Головы задач

Компонент	Назначение
Регрессия	Линейный слой d_model → F: для шага t предсказывается наблюдение в t+1 (обучение — MSE с истинным следующим шагом).
Аномалия	По ошибке прогноза (модуль разности предсказания и правды) и скрытому состоянию строится пара key/value, MultiheadAttention с запросом из скрытого ряда, затем классификатор → логиты бинарной аномалии на T−1 позициях (BCE с метками).
Aux (опционально)	Дополнительный линейный выход и слабый штраф за стабильность представлений.

Функция потерь при обучении

Суммарно: MSE по регрессии + вес anomaly_loss_weight на BCE по аномалиям + коэффициент на вспомогательную голову. Лоссы считаются в float32 для численной устойчивости при обучении в bf16.

Масштабы (пресеты)

Пресеты fanta-1b … fanta-8b задают ширину d_model, число слоёв N, голов и размер FFN (по порядку величины как у крупных языковых моделей). Конкретное число параметров зависит от F и конфигурации.

---

Установка (для пользователя)

Нужны Python 3.10+ и Git LFS (для больших файлов), если клонируете через git.

Вариант A: скачать через CLI (рекомендуется)

Установите Hugging Face CLI: curl -LsSf https://hf.co/cli/install.sh | bash

export HF_REPO_ID="Saintghetto17/FANTA"   # замените на свой репозиторий
mkdir -p fanta-hub && hf download "$HF_REPO_ID" --repo-type model --local-dir ./fanta-hub
cd fanta-hub
python3 -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -r requirements-fanta.txt

Добавьте корень скачанной папки в PYTHONPATH, чтобы импортировался пакет fanta:

export PYTHONPATH="$(pwd):${PYTHONPATH}"

Вариант B: git clone

git clone https://huggingface.co/Saintghetto17/FANTA fanta-hub
cd fanta-hub
git lfs pull
pip install -r requirements-fanta.txt
export PYTHONPATH="$(pwd):${PYTHONPATH}"

---

Загрузка весов в код

Из локальной папки после hf download (путь к чекпоинту относительно корня репозитория):

from fanta.modeling_fanta import FantaForPredictionAndAnomaly

ckpt = "fanta/fanta-1b/checkpoint-1000"  # подставьте свой пресет и шаг
model = FantaForPredictionAndAnomaly.from_pretrained(ckpt)
model.eval()

Напрямую с Hub без полного клона каталога (скачиваются только файлы чекпоинта):

REPO = "Saintghetto17/FANTA"
SUB = "fanta/fanta-1b/checkpoint-1000"

model = FantaForPredictionAndAnomaly.from_pretrained(
    REPO,
    subfolder=SUB,
    trust_remote_code=True,
)
model.eval()

trust_remote_code=True нужен, если класс модели подгружается с репозитория; при работе только из локальной копии с выставленным PYTHONPATH часто достаточно первого варианта.

---

Обучение после скачивания

Нужны данные в формате unified/ (Parquet), их в модельный репозиторий обычно не кладут — готовьте локально (скрипт unify_datasets.py в исходном проекте).

export PYTHONPATH="$(pwd):${PYTHONPATH}"
python train_fanta.py --preset fanta-1b --train_glob "unified/*_train.parquet" --schema_json unified/schema.json

Или ./scripts/train.sh из корня скачанной копии.

---

Шардирование больших чекпоинтов (~8 ГБ → 8 × ~1 ГБ)

Один файл model.safetensors на ~8 ГБ неудобно заливать. Разделите веса 8 шардов с помощью скрипта (использует HF API, без ручной резки):

cd fanta-hub  # или корень этого проекта
export PYTHONPATH="$(pwd):${PYTHONPATH}"
python3 scripts/reshard_checkpoint.py runs/checkpoint-5000 runs/checkpoint-5000-sharded --max_shard_size 1GB

В итоге в runs/checkpoint-5000-sharded/ будут:

config.json
model-00001-of-00008.safetensors
model-00002-of-00008.safetensors
...
model-00008-of-00008.safetensors
model.safetensors.index.json

Залейте папку на Hub:

HF_REPO_ID=Saintghetto17/FANTA \
./scripts/push_checkpoint_to_hf.sh runs/checkpoint-5000-sharded fanta/fanta-1b/checkpoint-5000

Как пользователю собрать шарды

Ничего руками собирать не нужно. Hugging Face / safetensors читают model.safetensors.index.json и при загрузке автоматически собирают тензоры из всех шардов:

from fanta.modeling_fanta import FantaForPredictionAndAnomaly

model = FantaForPredictionAndAnomaly.from_pretrained("fanta/fanta-1b/checkpoint-5000")
model.eval()

Скачать с Hub только нужный чекпоинт (все шарды сразу) в локальную папку:

hf download Saintghetto17/FANTA --repo-type model \
  --include "fanta/fanta-1b/checkpoint-5000/*" \
  --local-dir ./fanta-hub

Проверить целостность (должны быть непустыми и соответствовать index.json):

ls -lh fanta-hub/fanta/fanta-1b/checkpoint-5000/model-*.safetensors
python3 -c "import json; j=json.load(open('fanta-hub/fanta/fanta-1b/checkpoint-5000/model.safetensors.index.json')); print('shards:', sorted(set(j['weight_map'].values())))"

Если по какой-то причине у вас один model.safetensors и вы хотите получить шардированный вид (или наоборот), используйте тот же reshard_checkpoint.py — он сохраняет в любой размер через HF API. «Склеивать» руками (cat) ничего не требуется.

---

Выгрузка на Hub (для автора репозитория)

См. scripts/push_to_hf.sh (код) и scripts/push_all_to_hf.sh (код + чекпоинты из runs/ в fanta/<пресет>/...).

Перед первым разом: hf auth login.

Ускорение загрузки на Hub

Упирается в канал и клиент. Варианты:

1. hf_transfer (Rust, многопоточный upload) — обычно самый простой прирост:

   pip install 'huggingface_hub[hf_transfer]'
   export HF_HUB_ENABLE_HF_TRANSFER=1
   hf upload --repo-type model Saintghetto17/FANTA \
     runs/checkpoint-5000-sharded \
     fanta/fanta-1b/checkpoint-5000
   

   На широком канале — заметно быстрее; на слабом / домашнем интернете пользы может не быть.

2. Заливать папку целиком (как выше), а не файлы по одному. Клиент сам использует внутренний пул потоков для одного коммита.

3. Параллельные процессы по шардам (когда много шардов и хороший uplink):

   JOBS=4 HF_REPO_ID=Saintghetto17/FANTA \
   ./scripts/push_checkpoint_parallel.sh \
     runs/checkpoint-5000-sharded \
     fanta/fanta-1b/checkpoint-5000
   

   Количество одновременных заливок — через JOBS (по умолчанию 4). Эта команда стартует независимые hf upload на каждый файл; каждый шард — отдельный коммит в репо.

4. При обрыве просто повторите ту же команду — hf upload дозальёт недостающее (шарды небольшие, перезалить отдельный шард дёшево).

Если канал сам по себе узкий — ни один из способов не даст качественного прироста; в этом случае имеет смысл запускать загрузку с сервера с быстрым исходящим каналом.