Transformer

README.md

@@ -16,7 +16,7 @@
 [видео CodeParade](https://youtu.be/5dd8_N_nKRI). Текущая версия существенно
 расширяет исходную реализацию: добавлены CUDA FP32-поиск, CPU/DD-верификация,
 продолжаемые checkpoint, многотопологический планировщик, MAP-Elites/CEM,
-нейросетевая подсказка и локальный долговременный ML-датасет.
+online-MLP, общий Set Transformer ranker и локальный долговременный ML-датасет.
 
 ## Критерии результата
 
@@ -53,6 +53,11 @@ double-double (`WideReal`, примерно 31 десятичный знак).
   в FP32 и проверяется заново.
 - Нейросеть является только источником предложений. Она не может заменить точную
   CPU/DD-проверку или отключить базовую долю независимого поиска.
+- Общий для 59 топологий Set Transformer ранжирует только управляемую часть
+  injected-пула. Из 64 seed-кандидатов 48 по-прежнему формируются MAP-Elites,
+  CEM и независимым поиском, 4 управляемых seed остаются контрольными без
+  ранжирования, и только 12 выбираются трансформером. Повреждённая,
+  несовместимая или неутверждённая модель автоматически отключается.
 
 Штраф вырождения намеренно мягкий. По умолчанию полностью учитывается худший из
 барьеров определителя, короткого ребра, малого угла поворота и чрезмерного размера;
@@ -67,13 +72,18 @@ double-double (`WideReal`, примерно 31 десятичный знак).
 - `projects/Szilassi` — основной CLI-поиск;
 - `projects/PolyhedronGui` — Windows GUI для штатного CUDA-поиска;
 - `projects/VerifyCpp` — отдельная проверка OBJ-кандидатов;
+- `projects/TransformerTrainingExport` — потоковый read-only экспорт размеченных
+  trajectory из immutable `.sztd` для обучения;
 - `src/NeighborlyCore` — геометрия, точные предикаты и общие типы;
 - `src/CudaSearch` — FP32 CUDA backend и диагностический CPU stub;
 - `src/Checkpoint` — CRC-защищённые поколения checkpoint;
 - `src/SearchArchive` — mergeable MAP-Elites delta-файлы;
 - `src/OnlineSurrogate` — локальная online residual-MLP модель;
 - `src/TrainingArchive` — локальный долговременный ML-датасет и crash recovery;
+- `src/TransformerRanker` — нативный FP32 inference общей transformer-модели;
 - `tests/TrainingArchiveSelfTest` — тест формата, CRC, WAL, восстановления и лимита;
+- `tests/TransformerRankerSelfTest` — тест features, формата модели, CRC и fallback;
+- `tools/train_transformer.py` — CUDA/PyTorch-обучение и публикация модели;
 - `data` — описание топологий и входные модели;
 - `results/topologies` и `results/showcases` — сохранённые исследовательские модели;
 - `results/search` — продолжаемое геометрическое состояние поиска;
@@ -93,6 +103,10 @@ CMake; проекты Visual Studio можно собирать по отдел
   и Blackwell `sm_120`;
 - Eigen 3.4.0 уже находится в `external/eigen-3.4.0`.
 
+Для самого поиска Python не нужен. Для переобучения трансформера дополнительно
+нужны Python 3.12, NumPy и CUDA-сборка PyTorch. Эти зависимости устанавливаются
+в локальную `.venv` и не входят в штатный exe.
+
 Без CUDA проект собирает диагностический stub. Запуск с `--cuda` в такой сборке
 завершается с понятной ошибкой и не переключается на CPU незаметно.
 
@@ -112,6 +126,8 @@ ctest --test-dir build/vs2026 -C Release --output-on-failure
 - `polyhedron_gui.exe` — GUI;
 - `verify_cpp.exe` — проверка OBJ;
 - `training_archive_selftest.exe` — regression/self-test локального ML-архива.
+- `transformer_training_export.exe` — потоковый экспорт trajectory;
+- `transformer_ranker_selftest.exe` — regression/self-test transformer runtime.
 
 Для сборки без CUDA используется отдельный каталог:
 
@@ -128,7 +144,9 @@ cmake --build build/cpu --config Release
 msbuild projects\Szilassi\Szilassi.vcxproj /m /p:Configuration=Release /p:Platform=x64
 msbuild projects\PolyhedronGui\PolyhedronGui.vcxproj /m /p:Configuration=Release /p:Platform=x64
 msbuild projects\VerifyCpp\VerifyCpp.vcxproj /m /p:Configuration=Release /p:Platform=x64
+msbuild projects\TransformerTrainingExport\TransformerTrainingExport.vcxproj /m /p:Configuration=Release /p:Platform=x64
 msbuild tests\TrainingArchiveSelfTest\TrainingArchiveSelfTest.vcxproj /m /p:Configuration=Release /p:Platform=x64
+msbuild tests\TransformerRankerSelfTest\TransformerRankerSelfTest.vcxproj /m /p:Configuration=Release /p:Platform=x64
 ```
 
 Вывод этих проектов находится в `build/msbuild/bin/x64/Release`.
@@ -207,9 +225,11 @@ leaderboard восстанавливается при следующем зап
 
 - `results/search/runs/<UUID>/training` — `.sztd` shards и активный WAL;
 - `results/search/topology_N/neural` — online-модель `.szonn` и служебные receipts;
+- `results/search/neural/transformer` — immutable поколения `.sztf`, активная
+  `current.sztf` и отчёты обучения;
 - временные варианты этих файлов и marker достижения лимита.
 
-`.gitignore` исключает каталоги `training`, `neural`, все `.sztd/.szonn` и их
+`.gitignore` исключает каталоги `training`, `neural`, все `.sztd/.szonn/.sztf` и их
 временные варианты. Не используйте `git add -f` для этих путей.
 
 Schema v3 сохраняет пригодные для последующего обучения факты: каждый успешный и
@@ -221,8 +241,8 @@ WAL имеет CRC и durable commit boundary. После сбоя питани
 отбрасывается, а подтверждённые записи сохраняются. Завершённые shards immutable.
 
 Общий локальный лимит ML-кэша равен ровно `200000000000` байт (200 GB, не GiB).
-В расчёт входят существующие neural-файлы, резерв 59 финальных моделей и временный
-файл атомарной замены. При достижении лимита:
+В расчёт входят существующие neural-файлы, резерв 59 online-моделей, transformer
+generation/current и временные файлы атомарной замены. При достижении лимита:
 
 - новые обучающие записи больше не создаются;
 - online-обучение замораживается;
@@ -232,6 +252,60 @@ WAL имеет CRC и durable commit boundary. После сбоя питани
 
 Лимит рассчитан для одного поискового процесса в одном checkout.
 
+## Обучение трансформера
+
+Transformer обучается на GPU, но штатный поиск выполняет его маленький FP32
+inference на CPU, не отнимая CUDA-ресурсы у геометрических цепочек. Основные labels
+берутся только из `InjectedTrajectory`: `SeedProposal` без результата считается
+неизвестным, а не неудачным исходом.
+
+Тренер сначала фиксирует список завершённых `.sztd`, проверяет их CRC штатным C++
+reader и создаёт временный бинарный snapshot. Активный WAL и shards, появившиеся
+после начала обучения, в этот snapshot не входят и попадут в следующее
+переобучение. Поэтому накопление архива можно продолжать; временный snapshot после
+успеха или ошибки удаляется, если не указан `--keep-snapshot`.
+
+Первичная настройка локального окружения:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install numpy
+.\.venv\Scripts\python.exe -m pip install torch==2.13.0 `
+  --index-url https://download.pytorch.org/whl/cu130
+```
+
+Обучение на текущих четырёх независимых seed-run:
+
+```powershell
+.\scripts\TrainTransformer.bat
+```
+
+Скрипт проверяет `torch.cuda.is_available()` и пропускает Python-окружения с
+CPU-only PyTorch. Если CUDA-Python не находится автоматически, его можно указать
+без изменения файлов проекта:
+
+```powershell
+$env:SZILASSI_PYTHON = "C:\path\to\python.exe"
+.\scripts\TrainTransformer.bat
+```
+
+Train/validation/test делятся целыми run UUID, а не случайными соседними
+записями. Модель публикуется только после проверки AP, Brier и top-decile uplift
+на отдельных запусках. Затем deployment-ensemble заново обучается на всех четырёх
+run и атомарно публикуется как `results/search/neural/transformer/current.sztf`.
+Предыдущие `model_<digest>.sztf` не переписываются, а идентификатор загруженного
+поколения сохраняется в `run.tsv` и algorithm fingerprint обучающих записей.
+
+При будущем переобучении на всём накопившемся архиве, включая новые run:
+
+```powershell
+.\scripts\TrainTransformer.bat --deployment-all-runs
+```
+
+После публикации достаточно снова нажать `Запустить поиск`. Сбор `.sztd`, online-MLP,
+MAP-Elites/CEM, CUDA-поиск и CPU/DD-проверка продолжают работать независимо от
+наличия transformer-модели.
+
 ## Работа на нескольких компьютерах
 
 Для параллельного исследования задавайте непересекающиеся диапазоны топологий.
@@ -255,6 +329,8 @@ git rm -r --cached --ignore-unmatch -- `
   ":(glob)results/search/**/*.sztd.*" `
   ":(glob)results/search/**/*.szonn" `
   ":(glob)results/search/**/*.szonn.*" `
+  ":(glob)results/search/**/*.sztf" `
+  ":(glob)results/search/**/*.sztf.*" `
   ":(glob)results/search/**/TRAINING_DATA_LIMIT_REACHED_REWRITE_REQUIRED.tsv"
 ```
 
@@ -277,6 +353,10 @@ git ls-files -ci --exclude-standard -- results/search
 detection, частичные WAL, recovery после сбоя, immutable publication и точную границу
 200 GB.
 
+`TransformerRankerSelfTest` проверяет byte-exact размер модели, единую нормализацию
+features, batch inference, CRC, отклонение повреждённой модели и сохранение
+последней валидной модели при неудачной загрузке.
+
 Запуск через CTest:
 
 ```powershell