Веб-система для генерации и анализа белковых структур. Пользователь задаёт параметры; латентная диффузионная модель формирует структурное латентное представление, структурный декодер восстанавливает по нему трёхмерную структуру в формате PDB; результат сохраняется и доступен в личном кабинете.
Проект выполнен как выпускная квалификационная работа (МГТУ им. Н. Э. Баумана, 2026): исследование латентной диффузии в структурном пространстве белка, доведённое до сервиса. Генеративное ядро построено на двух адаптированных внешних компонентах — автокодировщике SALAD и латентной диффузии DiMA; что именно изменено, описано в разделе «Использованные компоненты и вклад автора».
- Обзор
- Результаты
- Целевая аудитория и назначение
- Использованные компоненты и вклад автора
- Лицензии и сторонний код
- Возможности
- Интерфейс
- Архитектура
- Пайплайн обучения
- Воспроизводимость
- Требования
- Установка
- Переменные среды
- Запуск
- Тесты
- Структура репозитория
Проект решает задачу генеративного дизайна белков: получить трёхмерную структуру заданной длины, не имея её природного прообраза. Вместо ручного перебора конформаций пользователь задаёт параметры в браузере, а генеративная модель выдаёт готовую структуру в формате PDB за десятки секунд.
В основе — латентная диффузия. Генерация идёт не в сырых координатах атомов, а в структурных латентах автокодировщика SALAD: геометрия белкового остова уже заложена в связку энкодера и декодера, поэтому диффузионной модели не нужно напрямую задавать инвариантность к поворотам и переносам или контролировать координатные ограничения на каждом шаге. Модель порождает латент белка нужной длины, а декодер восстанавливает по нему полноценную 3D-структуру. Такой подход даёт качество выше, чем у генерации «в координатах»: mmFID 1.03 млн против 3.27 млн у Proteina 60M notri при сопоставимой скорости.
Модель доведена до полноценного веб-приложения: регистрация и личный кабинет, проекты как рабочие пространства для серии экспериментов, постановка генерации в очередь, хранение результатов и просмотр структур в браузере через встроенный Mol* viewer. Сценарий сквозной — от входа до готовой структуры с метриками и выгрузкой в PDB/FASTA, в одном интерфейсе.
Финальное сравнение проводилось по mmFID, млн: чем ниже значение, тем ближе распределение сгенерированных структур к референсному набору.
Базовая модель Proteina: статья Proteina: Scaling Flow-based Protein Structure Generative Models, репозиторий NVIDIA-BioNeMo/proteina. Числа Proteina ниже не перенесены из статьи напрямую: структуры были сгенерированы автором с использованием публичной реализации и опубликованных весов Proteina, а затем пересчитаны тем же mmFID-пайплайном, что и итоговая модель: тот же диапазон длин 128-254, тот же референсный набор, тот же экстрактор признаков и тот же размер оценочной выборки. Сравнение дополнительно опирается на близкую природу данных: итоговая модель обучалась с использованием AFDB, и Proteina также публикуется как модель, обученная на AFDB. Так результат не смешивает метрики из разных статей и показывает качество в одном оценочном протоколе.
| Модель / конфигурация | mmFID, млн ↓ | Комментарий |
|---|---|---|
| Разработанная модель: AFDB -> PDB+AFDB, cosine | 1.03 | финальная конфигурация системы |
| AFDB latent, cosine | 0.86 | лучший отдельный mmFID, но хуже итоговый баланс переносимости и устойчивости |
| Proteina 60M, notri | 3.27 | пересчитано тем же mmFID-протоколом |
| Proteina 200M, notri | 3.56 | пересчитано тем же mmFID-протоколом |
| Proteina 200M, tri | 3.63 | пересчитано тем же mmFID-протоколом |
| Random values | 29.00 | случайный базовый уровень финального протокола |
Финальная конфигурация выбрана не только по одному числу mmFID. Для веб-системы важны также переносимость между AFDB и PDB, устойчивость декодировщика к шуму и поведение латентных представлений при интерполяции: структура должна не только выглядеть хорошо в метрике, но и стабильно декодироваться в PDB для пользовательского сценария.
Примеры сгенерированных структур:
Целевая аудитория MVP — студенты, исследователи и ML-инженеры, которые работают с protein design и хотят быстро проверять идеи без ручной сборки разрозненных скриптов. Типичный сценарий: задать длину белка, получить PDB, увидеть базовые метрики, открыть структуру в 3D и сохранить результат в рамках проекта.
Проблема, которую закрывает система: исследовательская модель сама по себе редко достаточна для практической работы. Нужен воспроизводимый контур вокруг неё: запуск, хранение параметров, история результатов, визуальная проверка и экспорт.
Продуктовые гипотезы MVP:
- единый интерфейс сокращает путь от генерации до визуальной проверки структуры;
- хранение результатов в проектах снижает риск потерять параметры эксперимента;
- 3D-просмотр и экспорт PDB/FASTA делают модель полезной не только в notebook, но и в рабочем процессе исследователя.
Генеративное ядро опирается на два внешних проекта; оба адаптированы под задачу генерации структур (а не последовательностей). Здесь — что взято и что изменено.
Внешние компоненты (с благодарностью авторам):
- SALAD — структурный автокодировщик белкового остова. Оригинал: github.com/mjendrusch/salad.
- DiMA — латентная диффузия для генерации белков (ICML'25). Оригинал: github.com/MeshchaninovViacheslav/DiMA.
Что сделано в этой работе (хронология):
- Автокодировщик (SALAD). Адаптированы загрузчики и конвейер данных; обучение в
нескольких режимах (PDB / AFDB / смешанное / предобучение на AFDB с дообучением на
смеси PDB+AFDB); увеличено число соседей в геометрическом внимании; латент 320 на
остаток. Выбор конфигурации — по реконструкции, поведению латента при
интерполяции и устойчивости декодера к шуму. Итог: RMSD Cα 0.121 на AFDB.
Детали и команды —
в
SaladEncoderTraining/README.md. - Диффузия (DiMA). Латентное пространство заменено с эмбеддингов белковой языковой
модели на структурные латенты автокодировщика; модель переобучена в нём. Шумовое
расписание заменено с
tan-10на косинусное — оно согласуется с областью устойчивого декодирования и снизило mmFID для обеих проверенных конфигураций. Детали — вDiMA_structure/README.md. - Информационная система. Полностью авторская: FastAPI + Celery/Redis + SQLite,
React + Mol*, личный кабинет, проекты, очередь генерации, метрики, 3D-просмотр
(
inf_sys_for_prot_gen/). - Оценка. Сравнение с Proteina: сэмплы Proteina были сгенерированы отдельно и пересчитаны тем же mmFID-пайплайном. Финальный результат: 1.03 млн против 3.27 млн у Proteina 60M notri.
- AI-инструменты в разработке. Cursor использовался как постоянная среда ассистированной разработки; Claude, Codex и GPT — для ревью кода, черновиков MVP-компонентов, диагностики конфигов, анализа дополнительных результатов и поиска справочной информации. Научная постановка, выбор данных, обучение моделей, интерпретация метрик и финальные инженерные решения оставались за автором.
README в каталогах
DiMA_structure/иSaladEncoderTraining/— технические инструкции по обучению/инференсу соответствующих компонентов; в начале каждого указано происхождение и внесённые изменения.
Авторский код информационной системы и конкурсной интеграции распространяется по
Apache-2.0, см. LICENSE. Сторонние компоненты сохраняют собственные
лицензии и атрибуцию:
- SALAD — Apache-2.0, оригинал: mjendrusch/salad,
локальная лицензия:
SaladEncoderTraining/SaladTraining/LICENSE. - DiMA — MIT, оригинал: MeshchaninovViacheslav/DiMA,
локальная лицензия:
DiMA_structure/LICENCE. - Proteina не входит в кодовую базу проекта и используется только как базовая модель для оценки; её репозиторий распространяется по NVIDIA License с ограничением на non-commercial research/evaluation use.
- Mol* используется как браузерный viewer структур; пакет
molstar5.5.0 указан вpackage-lock.jsonс лицензией MIT.
Краткая сводка вынесена в THIRD_PARTY_LICENSES.md.
- Генерация структуры по длине. Задаётся имя и длина цепи (50–254 остатка), модель возвращает 3D-структуру и последовательность.
- Загрузка своих PDB. Готовую структуру можно загрузить и анализировать в том же интерфейсе наравне со сгенерированными.
- Проекты. Эксперименты группируются в проекты с описанием и параметрами — удобно вести несколько линий дизайна параллельно.
- Асинхронная очередь. Генерация выполняется воркером Celery через Redis, интерфейс не блокируется; при отсутствии очереди backend считает синхронно.
- Метрики структуры. Для каждой структуры считаются длина, число атомов и цепей, радиус инерции (Rg), статистики CA-CA расстояний, время генерации.
- 3D-просмотр и выгрузка. Просмотр в Mol* viewer, экспорт в PDB и FASTA.
- Светлая и тёмная темы.
Рабочая панель — личный кабинет и список проектов:
Рабочее пространство проекта: параметры, список структур с метриками, переходы к генерации и загрузке:
Форма генерации — имя и длина цепи:
Просмотр результата в Mol* viewer: 3D-структура, характеристики и последовательность в FASTA:
Дополнительные экраны (вход, регистрация, светлая тема, создание проекта, загрузка PDB) — в каталоге
docs/images/.
Система состоит из трёх компонентов, связанных в единый поток генерации:
| Компонент | Каталог | Назначение |
|---|---|---|
| Информационная система | inf_sys_for_prot_gen/ |
Веб-приложение: React, FastAPI, SQLite, Celery, Redis |
| Модель генерации | DiMA_structure/ |
Латентная диффузия; запускается через generate_structure.py |
| Декодер структуры | SaladEncoderTraining/SaladTraining/ |
Декодер SALAD; импортируется моделью через PYTHONPATH |
Последовательность вызовов при генерации:
React (frontend)
-> FastAPI (inf_sys_for_prot_gen/backend/main.py)
-> Celery worker + Redis (backend/celery_worker.py)
-> backend/services/protein_generation.py
-> backend/integrations/dima_client.py
-> DiMA_structure/generate_structure.py
-> DiMA (диффузия) + SALAD (декодер структуры)
Если Redis и Celery не запущены, backend выполняет генерацию синхронно.
Раздел выше описывает инференс. Обучение состоит из двух стадий — сначала автокодировщик структуры, затем диффузия в его латентном пространстве:
PDB / AFDB (исходные структуры)
→ препроцессинг: PDB/CIF → NPZ, кластеризация, исключение валидации
(SaladEncoderTraining/SaladTraining/data/allpdb/{pdb2npz,cif2npz}.py)
→ обучение автокодировщика (SALAD)
предобучение на AFDB: training/train_structure_autoencoder_afdb.py
дообучение на смеси: training/train_structure_autoencoder_mixed.py
→ оценка автокодировщика: evaluating/eval_structure_autoencoder*.py
→ кодирование структур в латенты + статистики нормализации
(DiMA_structure: src.datasets.salad_outs_to_dt, src.preprocessing.calculate_statistics_salad)
→ обучение диффузии (DiMA): DiMA_structure/train_diffusion.py (косинусное расписание)
→ оценка генерации по mmFID
→ инференс: DiMA_structure/generate_structure.py → PDB
Выбор конфигурации автокодировщика и шумового расписания, а также численные
результаты (RMSD Cα 0.121, mmFID 1.03 млн против 3.27 млн у Proteina 60M notri) описаны в разделе
«Использованные компоненты и вклад автора». Команды обучения и оценки с
пояснением флагов — в SaladEncoderTraining/README.md
и DiMA_structure/README.md.
- Окружение — единое conda-окружение
vkrизDiMA_structure/environment.yamlплюс пины изsetup/conda_setup.md(Python 3.10, PyTorch 2.5.1, JAX 0.5.0, numpy 1.26.1, pandas 2.1.2, protobuf 3.20.3, setuptools 69.5.1, mlflow 2.14.1). - Сид — фиксированный
seed: 42(конфиги диффузии и обучение автокодировщика). - Логирование экспериментов — MLflow и TensorBoard; конфигурация обучения
диффузии управляется через Hydra (
DiMA_structure/src/configs/), что позволяет повторять прогоны по сохранённому конфигу. - Конфигурация генерации — пути к весам и параметры заданы переменными среды (см. «Переменные среды»), а не правкой кода.
- Ограничение — веса, полные PDB/AFDB-датасеты и промежуточные латенты не хранятся в git из-за размера и условий распространения. Репозиторий фиксирует код, конфиги, протокол оценки и структуру артефактов; для точного воспроизведения генерации нужны внешние чекпоинты, перечисленные ниже.
- GPU NVIDIA с поддержкой CUDA 12.
condaиmamba.- Node.js 20 (устанавливается через conda на шаге установки).
Полная пошаговая инструкция приведена в setup/conda_setup.md. Ниже дана краткая
последовательность; выполнять установку следует по setup/conda_setup.md.
Два способа: контейнеры (быстрый старт) или ручная установка в conda.
Поднимает все сервисы (backend, Celery, Redis, frontend) одной командой:
docker compose up --buildUI — http://localhost:3000, API — http://localhost:8000. Образ собирается по
Dockerfile и повторяет шаги setup/conda_setup.md. Для реальной генерации нужен GPU
NVIDIA (nvidia-container-toolkit) и веса моделей: раскомментируйте блоки deploy.resources
и монтирование каталога с чекпоинтами в docker-compose.yml. Без GPU и весов поднимается
рабочий веб-интерфейс (регистрация, проекты, загрузка PDB, просмотр), кроме самой генерации.
Все компоненты используют одно окружение conda с именем vkr
(Python 3.10, PyTorch 2.5.1, JAX 0.5.0).
# 1. Базовое окружение из conda-спецификации DiMA
mamba env create -f DiMA_structure/environment.yaml -n vkr
conda activate vkr
# 2. Python-зависимости DiMA (torch, biopython, flax, gemmi и др.)
# 3. JAX CUDA 12 версии 0.5.0
# 4. dm-haiku 0.0.14, flexloop
# 5. Зависимости backend (шаг 7 в setup/conda_setup.md)
# 6. Node.js 20 и зависимости frontend (npm install)
# 7. Фиксация версий: numpy 1.26.1, pandas 2.1.2, protobuf 3.20.3, setuptools 69.5.1
# 8. mlflow 2.14.1, redis-serverШаги 2–8 приведены полностью и в требуемом порядке в setup/conda_setup.md.
Установленное окружение vkr соответствует этой инструкции.
Переменные перечислены в inf_sys_for_prot_gen/dima_conda_vars.txt и загружаются
в окружение vkr как постоянные. При развёртывании на другой машине достаточно
заменить в этом файле абсолютные пути на свои (каталог установки проекта) и
переприменить переменные командой ниже:
conda activate vkr
mapfile -t VARS < <(grep -vE '^\s*(#|$)' inf_sys_for_prot_gen/dima_conda_vars.txt)
conda env config vars set -n vkr "${VARS[@]}"
conda deactivate && conda activate vkrОсновные переменные: DIMA_REPO_DIR, DIMA_GENERATE_SCRIPT,
DIMA_STRUCTURE_DECODER_PATH, DIMA_STATISTICS_PATH, DIMA_CHECKPOINTS_PREFIX,
DIMA_CHECKPOINT_NAME, SALAD_ROOT, PYTHONPATH, REDIS_URL.
UPLOAD_DIR задаёт каталог для загруженных пользователем PDB-файлов
(по умолчанию inf_sys_for_prot_gen/uploads). Значение абсолютное и имеет
приоритет над путём из config.py, поэтому при развёртывании его также следует
указать под свой каталог установки.
Веса моделей в репозитории не хранятся (исключены .gitignore как тяжёлые
артефакты). Пустые каталоги под них оставлены с файлом .gitkeep, чтобы структура
сохранялась после клонирования; нужные файлы кладутся в них вручную. При генерации
используются три файла в DiMA_structure/src/checkpoints/:
| Файл | Размер | Назначение |
|---|---|---|
dima-salad-ft200k-400000.pth |
506 МБ | Веса диффузионной модели DiMA |
checkpoint-200000.jax |
35 МБ | Декодер SALAD |
encodings-afdb_prime_finetune_checkpoint-200000.pth |
4 КБ | Статистики нормализации |
Все веса задаются переменными окружения, а не правкой config.yaml. Поля
decoder_checkpoints_folder и statistics_folder из config.yaml при веб-генерации
не используются: dima_client.py перекрывает их через оверрайды Hydra, которые
имеют приоритет над значениями из yaml.
| Что меняется | Переменная | Значение |
|---|---|---|
| Диффузионные веса DiMA | DIMA_CHECKPOINTS_PREFIX + DIMA_CHECKPOINT_NAME |
имя подпапки и номер шага, не путь |
Декодер SALAD (.jax) |
DIMA_STRUCTURE_DECODER_PATH |
абсолютный путь к файлу |
Статистики (.pth) |
DIMA_STATISTICS_PATH |
абсолютный путь к файлу |
Диффузионный чекпоинт задаётся не путём, а парой prefix + name; файл должен
физически находиться по адресу:
DiMA_structure/checkpoints/diffusion_checkpoints/<DIMA_CHECKPOINTS_PREFIX>/<DIMA_CHECKPOINT_NAME>.pth
Декодер и статистики указываются абсолютным путём в произвольном расположении.
Порядок применения изменений:
# 1. изменить значения в источнике
inf_sys_for_prot_gen/dima_conda_vars.txt
# 2. переприменить переменные в окружение vkr
conda activate vkr
mapfile -t VARS < <(grep -vE '^\s*(#|$)' inf_sys_for_prot_gen/dima_conda_vars.txt)
conda env config vars set -n vkr "${VARS[@]}"
conda deactivate && conda activate vkr
# 3. перезапустить backend и Celery (переменные читаются из окружения при старте)Файл dima_conda_vars.txt во время работы не читается; он служит только источником
для команды conda env config vars set.
Запускаются четыре процесса, каждый в отдельном терминале; в каждом терминале
предварительно выполняется conda activate vkr.
# 1. Backend (FastAPI), API на http://localhost:8000
cd inf_sys_for_prot_gen
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
# 2. Frontend (React), интерфейс на http://localhost:3000
cd inf_sys_for_prot_gen/frontend
HOST=0.0.0.0 npm start
# 3. Redis (брокер для асинхронной генерации)
redis-server --port 6379
# 4. Celery worker
cd inf_sys_for_prot_gen
celery -A backend.celery_worker.celery worker \
--loglevel=info --concurrency=1 --prefetch-multiplier=1 -OfairBackend покрыт тестами API (health-проверки, регистрация/авторизация, проекты, изоляция доступа между пользователями). Они не требуют GPU и ML-стека:
pip install -r inf_sys_for_prot_gen/backend/requirements.txt pytest httpx
cd inf_sys_for_prot_gen
python -m pytestЛинт и тесты также прогоняются в CI (.github/workflows/ci.yml) на каждый push и PR.
ML_Contest_2026/
├── README.md
├── Dockerfile, docker-compose.yml контейнеризация всех сервисов
├── ruff.toml конфигурация линтера
├── .github/workflows/ci.yml CI: линт backend + тесты + сборка frontend
├── inf_sys_for_prot_gen/ информационная система (веб-приложение)
│ ├── backend/ FastAPI, Celery, integrations/dima_client.py
│ │ ├── requirements.txt runtime-зависимости backend
│ │ └── tests/ тесты API (pytest)
│ ├── frontend/ React и Mol* viewer
│ ├── dima_conda_vars.txt переменные среды (локальный, в .gitignore)
│ └── docs/ схемы архитектуры (.drawio)
├── DiMA_structure/ диффузионная генерация
│ ├── generate_structure.py точка входа, вызываемая backend
│ ├── train_diffusion.py обучение диффузии
│ ├── src/ код DiMA, configs/ (Hydra)
│ ├── checkpoints/, src/checkpoints/ каталоги под веса (.gitkeep; веса не в git)
│ └── environment.yaml conda-спецификация окружения vkr
├── SaladEncoderTraining/ автокодировщик структуры (на базе SALAD)
│ ├── SaladTraining/ modules/ (импортируются DiMA), training/, evaluating/
│ └── models/ каталог под веса (.gitkeep; веса не в git)
└── setup/
└── conda_setup.md пошаговая инструкция по установке