Технічний гайд: Проєкт #1 — fine-tune MAMMAL на розчинності білка

Створено: 22 липня 2026. Перевірено по офіційному репозиторію BiomedSciAI/biomed-multi-alignment (клон, гілка main). Мета — довести перший портфоліо-проєкт до готового GitHub-репо: дообучити MAMMAL на задачі «розчинність білка», зробити baseline на ESM-2, чесно порівняти.

---

0. Що ми будуємо і чому саме це

Задача: передбачити, чи буде білок розчинним, лише за його амінокислотною послідовністю (бінарна класифікація: розчинний / нерозчинний).

Чому ця задача ідеальна для першого проєкту:

• У репозиторії MAMMAL є готовий приклад mammal/examples/protein_solubility — не треба вигадувати пайплайн з нуля.
• Дані завантажуються автоматично (код сам тягне їх при першому запуску) — не треба шукати датасет вручну.
• Вхід — білкова послідовність, тож природний baseline — ESM-2 (та сама «історія MAMMAL vs ESM», яку хоче побачити роботодавець).
• Бінарна класифікація легко оцінюється (accuracy, AUC).

Датасет: бенчмарк DeepSol (Khurana та ін., Bioinformatics 2018, 34(15):2605). Дані з Zenodo: https://zenodo.org/records/1162886. Код прикладу вантажить їх сам через wget у папку ./example_solubility_data.

Модель: чекпойнт ibm/biomed.omics.bl.sm.ma-ted-458m (458M параметрів, з HuggingFace).

---

1. Середовище (2 варіанти)

Варіант A — Google Colab (рекомендовано для старту)

Безкоштовний GPU (T4, 16 ГБ) вистачає для цієї задачі. Важливий нюанс нижче (розділ 5) — fine-tune треба запускати як скрипт через !python, а не в клітинці ноутбука (через DDP).

Варіант B — локально / хмарний GPU

Офіційна інструкція встановлення:

conda create -n mammal_env python=3.10 -y
conda activate mammal_env
conda install pytorch pytorch-cuda=12.1 -c pytorch -c nvidia

Вимоги: Python ≥ 3.10, PyTorch ≥ 2.0.

Встановлення пакета (обидва варіанти)

З PyPI (найпростіше):

pip install biomed-multi-alignment[examples]

Або з клону репозиторію (щоб мати приклади під рукою):

git clone https://github.com/BiomedSciAI/biomed-multi-alignment.git
pip install -e ./biomed-multi-alignment[examples]

Суфікс [examples] обов’язковий — він тягне залежності прикладів (зокрема wget для завантаження даних і fuse-med-ml).

На Colab: !pip install biomed-multi-alignment[examples] у першій клітинці. Перевір, що ввімкнено GPU: Runtime → Change runtime type → T4 GPU.

---

2. Крок «переконайся, що модель жива» (інференс)

Перш ніж дообучати — прогони інференс, щоб побачити, що модель і токенайзер вантажаться. Мінімальний приклад (з офіційного туторіалу), задача «розчинність»:

from mammal.model import Mammal
from mammal.keys import ENCODER_INPUTS_STR, CLS_PRED, SCORES
from fuse.data.tokenizers.modular_tokenizer.op import ModularTokenizerOp

# 1. завантажити модель і токенайзер
model = Mammal.from_pretrained("ibm/biomed.omics.bl.sm.ma-ted-458m").eval()
tokenizer_op = ModularTokenizerOp.from_pretrained("ibm/biomed.omics.bl.sm.ma-ted-458m")

Якщо це відпрацювало без помилок — середовище готове.

---

3. Fine-tuning (головний крок)

Точні команди (з README репозиторію)

Запуск дообучення з попередньо навченого MAMMAL:

python mammal/main_finetune.py --config-name config.yaml --config-path examples/protein_solubility

(запускати з кореня репозиторію / з папки mammal, залежно від встановлення; на Colab — через !python ...).

При першому запуску код сам завантажить дані у ./example_solubility_data.

Що всередині config (examples/protein_solubility/config.yaml) — ключові параметри

Параметр	Значення за замовч.	Що означає
model.pretrained_kwargs...	ibm/biomed.omics.bl.sm.ma-ted-458m	який чекпойнт дообучуємо
task...data_module_kwargs.batch_size	6	розмір батчу (зменш, якщо OOM)
protein_max_seq_length	1250	максимальна довжина білка
module.opt_callable.lr	1e-5	learning rate (AdamW)
lr_sch_callable	cosine annealing + warmup	розклад LR
best_epoch_source.monitor	validation.metrics.solubility_prediction_acc	за чим обирають кращу епоху
trainer.max_epochs	1000	стеля епох (кращу зберігає checkpoint)
trainer.devices	1	1 GPU
evaluate	false	режим тренування

Практичні override’и через Hydra (командний рядок)

Hydra дозволяє змінювати будь-який параметр прямо в команді. Для Colab/швидкого прогону:

python mammal/main_finetune.py --config-name config.yaml --config-path examples/protein_solubility \
  trainer.max_epochs=15 \
  task.data_module_kwargs.batch_size=4 \
  track_clearml.offline_mode=True

• trainer.max_epochs=15 — не жени до 1000; для портфоліо вистачить менше (кращу епоху збереже checkpoint).
• batch_size=4 (або 2) — якщо ловиш OOM на T4.
• track_clearml.offline_mode=True — щоб трекер ClearML не намагався логінитись у хмару (інакше може висіти/просити креденшали).

Результат тренування (ваги кращої епохи) з’явиться у папці mammal_solubility_finetune/ (ім’я з name у config), файл best_epoch.ckpt.

---

4. Оцінка та інференс своєї моделі

Оцінка на тесті (accuracy на тестовому датолоадері):

python mammal/main_finetune.py --config-name config.yaml --config-path examples/protein_solubility \
  evaluate=True \
  model.pretrained_kwargs.pretrained_model_name_or_path=<шлях_до_виводу>/best_epoch.ckpt

Інференс на одному білку:

python mammal/examples/protein_solubility/main_infer.py <шлях_до_виводу> <амінокислотна_послідовність>

Збережи метрику (accuracy; за бажання додай AUC) — це «число MAMMAL» для порівняння.

---

5. Головні підводні камені (обов’язково прочитати)

1. DDP у ноутбуці Colab не працює. Config використовує strategy: ddp_find_unused_parameters_true. PyTorch Lightning DDP не запускається всередині клітинки Jupyter/Colab. Рішення: запускай fine-tune як окремий процес — !python mammal/main_finetune.py ... (саме через !python, не імпортом у клітинці). Це працює на одному GPU коректно.
2. ClearML-трекер. За замовчуванням offline_mode: False — може просити креденшали або зависати. Додавай track_clearml.offline_mode=True в override.
3. OOM (брак пам’яті GPU). Якщо T4 не тягне — зменш batch_size до 4 або 2; за потреби protein_max_seq_length до 1000 (відкине найдовші білки).
4. Довге тренування. max_epochs: 1000 — це стеля, не план. Обмеж trainer.max_epochs (15–30) або розкоментуй limit_train_batches в config для швидкого димового прогону.
5. Сесія Colab гине через ~кілька годин. Зберігай best_epoch.ckpt на Google Drive (примонтуй Drive у Colab) — щоб не втратити результат.
6. Ім’я чекпойнта. У README подекуди трапляється скорочене ...bl.sm-ted-458 — канонічне повне ім’я на HuggingFace: ibm/biomed.omics.bl.sm.ma-ted-458m. Використовуй повне.

---

6. Baseline на ESM-2 (це і є «історія» проєкту)

Мета: показати, що ти розумієш, з чим порівнюєш. Baseline простий: беремо ту саму послідовність → ESM-2 ембединг → логістична регресія. Якщо MAMMAL б’є цей baseline — маєш сильну наративну лінію.

# pip install fair-esm scikit-learn torch pandas
import torch, esm, numpy as np
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, roc_auc_score

# 1. маленька ESM-2 модель (швидка, вистачає для baseline)
model, alphabet = esm.pretrained.esm2_t12_35M_UR50D()
bc = alphabet.get_batch_converter(); model.eval()

def embed(seqs):
    outs=[]
    for i in range(0,len(seqs),16):
        batch=[(str(j),s[:1022]) for j,s in enumerate(seqs[i:i+16])]
        _,_,toks=bc(batch)
        with torch.no_grad():
            rep=model(toks,repr_layers=[12])["representations"][12]
        # середнє по довжині (mean-pool) → 1 вектор на білок
        outs.append(rep.mean(1).cpu().numpy())
    return np.concatenate(outs)

# 2. train_seqs/train_y, test_seqs/test_y — з того ж датасету solubility
Xtr, Xte = embed(train_seqs), embed(test_seqs)
clf = LogisticRegression(max_iter=1000).fit(Xtr, train_y)
pred = clf.predict(Xte); proba = clf.predict_proba(Xte)[:,1]
print("ESM-2 baseline acc:", accuracy_score(test_y,pred), "AUC:", roc_auc_score(test_y,proba))

Дані для baseline бери ті самі, що завантажив приклад MAMMAL (папка example_solubility_data) — читаєш послідовності й мітки через Pandas. Так порівняння чесне (ті самі train/test).

---

7. Порівняння й візуалізація

• Зведи два-три числа в таблицю: MAMMAL (fine-tuned) vs ESM-2 + LogReg (accuracy, AUC).
• Зроби простий стовпчиковий графік (matplotlib).
• Напиши 3–4 речення висновку: яка модель краща, на скільки, і чому (MAMMAL дообучувався end-to-end під задачу; baseline використовує «заморожені» ембединги).

---

8. Оформлення репозиторію (те, що бачить роботодавець)

Структура:

protein-solubility-mammal/
├── README.md            # головне
├── requirements.txt
├── notebooks/
│   └── 01_finetune_and_baseline.ipynb
├── src/
│   ├── baseline_esm2.py
│   └── compare.py
└── results/
    └── mammal_vs_esm2.png

README має містити:

1. Одне речення: що це за проєкт.
2. Задача й датасет (DeepSol, посилання).
3. Підхід: fine-tune MAMMAL + baseline ESM-2.
4. Результат — таблиця + графік із цифрами.
5. Як відтворити (команди з цього гайду).
6. Висновки й чому саме так.
7. Подяка/посилання на MAMMAL і ESM.

---

9. Definition of done (коли проєкт «готовий»)

• MAMMAL дообучився, є best_epoch.ckpt і метрика на тесті.
• Побудований ESM-2 baseline на тих самих даних, є його метрика.
• Таблиця + графік порівняння.
• Публічний GitHub-репо з чистим README (задача → підхід → результат → як запустити).
• (Бонус) Перший PR у документацію MAMMAL, якщо натрапив на неточність.

---

Джерела

• Репозиторій MAMMAL — https://github.com/BiomedSciAI/biomed-multi-alignment (README, mammal/examples/protein_solubility/)
• Модель — https://huggingface.co/ibm/biomed.omics.bl.sm.ma-ted-458m
• Стаття MAMMAL — arXiv:2410.22367
• Бенчмарк розчинності (DeepSol) — Khurana та ін., Bioinformatics 2018, 34(15):2605 — https://academic.oup.com/bioinformatics/article/34/15/2605/4938490
• Дані — https://zenodo.org/records/1162886
• ESM (для baseline) — https://github.com/facebookresearch/esm