Skip to main content
Tilnote
T
tilnote
책에 포함된 노트AlphaFold 실전 사용법: 서열 준비부터 구조 해석, AlphaFold 3와 재현 가능한 보고까지

로컬에서 AlphaFold 2 설치하고 실행하기

Views 54약 11분생성형 AI 활용
Summary

로컬 설치는 AlphaFold를 "한 번 써 보는 단계"에서 "내 연구실의 계산 도구로 운영하는 단계"로 옮기는 일입니다. 앞 장들에서 다룬 ColabFold와 AlphaFold Server는 시작하기 쉽고 편리합니다. 하지만 같은 단백질을 seed만 바꿔 반복 실행하거나, 수십 개의 변이체를 한꺼번에 돌리거나, 외부 서버에 올리기 어려운 서열을 다루거나, 데이터베이스 버전과 실행 조건을 정확히 통제해야 한다면 결국 로컬 설치가 필요해집니다.

이 장에서는 Ubuntu 계열 Linux 시스템에서 Docker와 NVIDIA GPU를 이용해 AlphaFold 2를 설치하고, 단일 단백질 예측인 monomer와 단백질 복합체 예측인 multimer를 실행하는 흐름을 다룹니다. 여기서 말하는 "로컬"은 개인 워크스테이션일 수도 있고, 연구실 서버일 수도 있습니다. 핵심은 세 가지입니다. 첫째, GPU가 Docker 컨테이너 안에서 보이는지 확인해야 합니다. 둘째, AlphaFold 코드와 Docker 이미지는 비교적 금방 준비되지만, 유전 데이터베이스는 매우 크고 오래 걸립니다. 셋째, 실행 명령에서 fasta_paths, max_template_date, model_preset, db_preset, data_dir, output_dir를 정확히 지정해야 합니다.

로컬에서 AlphaFold 2 설치하고 실행하기

로컬 설치가 필요한 순간

ColabFold로 단백질 하나를 예측해 보고 구조를 눈으로 확인하는 정도라면 로컬 AlphaFold 2는 과한 선택일 수 있습니다. 로컬 설치의 진짜 장점은 편의성이 아니라 통제력입니다. 같은 입력을 같은 데이터베이스 버전으로 반복 실행할 수 있고, 계산이 중간에 끊겨도 다시 이어서 계획을 세울 수 있으며, 출력 파일 전체를 내 저장소 안에 보관할 수 있습니다.

예를 들어 어떤 효소의 활성 부위 주변 40개 변이를 모두 비교한다고 해 봅시다. 웹 기반 도구에서는 입력을 하나씩 넣고 결과를 내려받는 과정이 금세 지루해집니다. 반면 로컬 설치에서는 FASTA 파일을 여러 개 준비하고, 셸 스크립트나 작업 스케줄러로 차례대로 실행할 수 있습니다. 단백질 복합체도 마찬가지입니다. A-B, A-C, B-C, A-B-C 조합을 비교하려면 수동 클릭보다 자동화가 훨씬 안전합니다.

또 하나의 중요한 이유는 데이터 통제입니다. AlphaFold 2는 서열 데이터베이스와 구조 템플릿 데이터베이스를 검색해 MSA, 즉 다중서열정렬을 만들고 알려진 구조를 참고합니다. 따라서 어느 시점의 데이터베이스를 사용했는지에 따라 결과가 조금씩 달라질 수 있습니다. 논문이나 보고서에서 재현 가능성을 강조해야 한다면, "어떤 프로그램을 썼는가"만큼 "어떤 데이터베이스를 썼는가"도 중요합니다.

공식 AlphaFold 저장소도 Linux, Docker, NVIDIA Container Toolkit, 유전 데이터베이스, 모델 파라미터를 준비한 뒤 run_docker.py로 실행하는 방식을 기본 설치 흐름으로 안내합니다.1 이 장의 목표는 그 공식 흐름을 실전 작업 순서로 풀어 쓰는 것입니다.

시작 전에 현실적인 하드웨어 계산하기

AlphaFold 2 로컬 설치에서 가장 자주 생기는 착각은 "GPU만 있으면 되겠지"입니다. 실제로는 저장공간, CPU, 메모리, 네트워크가 모두 중요합니다. 딥러닝 추론 자체는 GPU가 맡지만, 그 전에 MSA와 템플릿 검색을 해야 합니다. 이 단계는 CPU와 디스크 입출력에 크게 의존합니다.

공식 문서 기준으로 full 데이터베이스의 다운로드 크기는 약 556GB이고, 압축을 푼 뒤 전체 크기는 약 2.62TB입니다.2 운영체제, Docker 이미지, 임시 파일, 출력 파일까지 생각하면 "2.5TB 디스크가 있다"는 말은 아슬아슬합니다. 실제 운영용이라면 최소 3TB 이상, 가능하면 4TB 이상의 빠른 SSD 또는 NVMe를 권합니다. HDD에서도 이론적으로는 돌아갈 수 있지만, MSA 검색이 긴 터널을 걸어가는 것처럼 느려질 수 있습니다.

GPU 메모리는 예측 가능한 단백질 길이에 직접적인 영향을 줍니다. 작은 단백질 하나라면 12GB 또는 16GB GPU에서도 성공할 수 있지만, 긴 단백질이나 복합체는 금방 한계에 닿습니다. GPU 메모리 사용량은 대체로 잔기 수가 늘어날수록 급격히 커지며, 큰 단백질에서는 단일 GPU 메모리를 쉽게 초과할 수 있습니다.3 연구실 서버를 새로 맞춘다면 VRAM이 넉넉한 GPU를 우선 고려해야 합니다.

실무적으로는 다음 정도를 기준선으로 잡으면 좋습니다.

  • 짧은 monomer 몇 개를 테스트하려면 NVIDIA GPU, 32GB RAM, 수백 GB 이상의 여유 공간이 있는 reduced_dbs 구성이 출발점이 될 수 있습니다.

  • full 데이터베이스를 쓰려면 데이터 전용으로 약 2.6TB 이상이 필요하고, 출력과 임시 파일을 고려해 3TB 이상을 확보하는 편이 안전합니다.

  • 반복 실행과 multimer 예측을 자주 한다면 64GB 이상의 RAM, 빠른 SSD, 많은 CPU 코어, 24GB 이상의 GPU VRAM이 체감 차이를 크게 만듭니다.

여기서 reduced_dbs는 작은 BFD 데이터베이스를 사용해 속도와 저장공간 부담을 낮추는 설정입니다. 대신 먼 친척 서열을 덜 찾을 수 있으므로, 특히 동족체가 적은 단백질이나 복합체에서는 full 데이터베이스가 더 유리할 수 있습니다.

Ubuntu에서 Docker와 NVIDIA GPU 확인하기

AlphaFold 2의 공식 Docker 실행 방식은 "호스트 시스템은 Linux이고, 실제 프로그램은 컨테이너 안에서 실행되는 구조"입니다. 컨테이너는 계산 환경을 박스째로 고정해 주는 기술입니다. 내 Ubuntu에 어떤 Python 패키지가 깔려 있든, AlphaFold 컨테이너 안에는 AlphaFold가 기대하는 프로그램들이 들어 있습니다. 덕분에 설치 충돌을 크게 줄일 수 있습니다.

먼저 Ubuntu 시스템에서 NVIDIA 드라이버가 정상적으로 설치되어 있어야 합니다. 터미널에서 다음을 실행합니다.

nvidia-smi

GPU 이름, 드라이버 버전, CUDA 버전, 메모리 사용량이 표 형태로 나오면 첫 번째 관문은 통과입니다. 여기서부터 중요한 점은 "호스트에서 GPU가 보이는 것"과 "Docker 컨테이너 안에서 GPU가 보이는 것"은 다르다는 사실입니다. AlphaFold는 컨테이너 안에서 실행되므로 Docker가 GPU를 넘겨받을 수 있어야 합니다.

Docker Engine을 설치한 뒤에는 현재 사용자가 sudo 없이 Docker를 실행할 수 있도록 docker 그룹에 들어가 있는지 확인하는 것이 좋습니다. Ubuntu에서 흔히 쓰는 흐름은 다음과 같습니다.

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# Docker Engine 설치는 배포판과 시점에 따라 명령이 달라질 수 있으므로
# 운영 서버에서는 Docker 공식 문서의 Ubuntu 설치 절차를 확인하는 것이 안전합니다.

sudo usermod -aG docker $USER
newgrp docker

docker run --rm hello-world

hello-world가 정상적으로 실행되면 Docker 자체는 움직입니다. 이제 NVIDIA Container Toolkit을 설치해야 합니다. 이것은 Docker 컨테이너가 NVIDIA GPU를 사용할 수 있게 연결해 주는 다리입니다. NVIDIA 문서는 Docker Engine, NVIDIA 드라이버, NVIDIA Container Toolkit을 준비하고, 컨테이너에서 nvidia-smi가 실행되는지 확인하라고 안내합니다.4

설치 후에는 다음 명령으로 컨테이너 안에서 GPU가 보이는지 확인합니다.

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

또는 환경에 따라 다음처럼 실행할 수도 있습니다.

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

성공하면 호스트에서 보았던 것과 비슷한 GPU 표가 출력됩니다. 이 순간이 중요합니다. AlphaFold 설치 문제처럼 보이는 오류 중 상당수는 사실 이 단계에서 이미 결정됩니다. 컨테이너 안에서 nvidia-smi가 보이지 않으면 AlphaFold 이미지를 빌드하기 전에 NVIDIA 드라이버, Docker, NVIDIA Container Toolkit 설정부터 고쳐야 합니다.

AlphaFold 저장소 내려받기와 Docker 이미지 빌드

GPU 확인이 끝났다면 AlphaFold 코드를 내려받습니다. 공식 저장소는 DeepMind의 AlphaFold 2 inference pipeline을 제공합니다. 저장소 이름은 시기에 따라 deepmind/alphafold 또는 google-deepmind/alphafold로 보일 수 있지만, 현재는 GitHub에서 공식 저장소로 연결됩니다.1

작업 디렉터리를 하나 정하고 다음을 실행합니다.

mkdir -p ~/software
cd ~/software

git clone https://github.com/google-deepmind/alphafold.git
cd alphafold

만약 위 주소가 환경에 따라 실패한다면 다음 주소를 시도할 수 있습니다.

git clone https://github.com/deepmind/alphafold.git
cd alphafold

이제 Docker 이미지를 빌드합니다.

docker build -f docker/Dockerfile -t alphafold .

이 명령은 현재 AlphaFold 소스 코드와 Dockerfile을 사용해 alphafold라는 이름의 이미지를 만듭니다. 이미지는 한 번 만들어 두면 계속 재사용합니다. 코드 버전을 업데이트하거나 Dockerfile이 바뀌었을 때만 다시 빌드하면 됩니다.

빌드 중 GPG 키 오류나 CUDA 저장소 서명 오류가 날 수 있습니다. 이런 오류는 AlphaFold 자체 알고리즘 문제가 아니라 Docker 이미지가 기반 패키지를 가져오는 과정에서 생기는 환경 문제입니다. 공식 저장소도 특정 NVIDIA CUDA 저장소 키 오류에 대한 우회 방법을 별도로 안내합니다.1 이런 경우에는 오류 메시지의 NO_PUBKEY, InRelease, not signed 같은 단어를 그대로 검색해 현재 저장소의 issue나 NVIDIA 문서에서 최신 해결책을 확인하는 편이 좋습니다.

마지막으로 run_docker.py가 필요로 하는 Python 패키지를 설치합니다. 시스템 Python을 어지럽히고 싶지 않다면 가상환경을 하나 만드는 것이 안전합니다.

python3 -m venv ~/venvs/alphafold-runner
source ~/venvs/alphafold-runner/bin/activate
pip install --upgrade pip
pip install -r docker/requirements.txt

이 가상환경은 AlphaFold 딥러닝 계산 환경이 아닙니다. 계산은 Docker 컨테이너 안에서 일어납니다. 여기의 Python 패키지는 Docker를 호출하는 run_docker.py를 실행하기 위한 얇은 조종석에 가깝습니다.

데이터베이스 다운로드: 가장 오래 걸리는 설치 단계

코드와 Docker 이미지는 준비가 비교적 빠릅니다. 진짜 설치는 데이터베이스 다운로드입니다. AlphaFold 2는 서열의 진화적 정보를 찾기 위해 여러 대형 데이터베이스를 검색합니다. full 데이터베이스에는 BFD, MGnify, PDB70, PDB mmCIF, PDB seqres, UniRef30, UniProt, UniRef90 등이 포함됩니다. 이 중 PDB seqres와 UniProt은 특히 AlphaFold-Multimer 실행에 필요합니다.2

먼저 다운로드 도구를 설치합니다.

sudo apt update
sudo apt install -y aria2 rsync

그다음 데이터베이스를 둘 디렉터리를 정합니다. 매우 중요합니다. 이 디렉터리는 AlphaFold 저장소 안에 만들면 안 됩니다. 저장소 안에 거대한 데이터베이스를 넣으면 Docker 이미지 빌드 때 빌드 컨텍스트가 비정상적으로 커져 시간이 크게 늘어날 수 있습니다. 예를 들어 별도 디스크가 /data에 마운트되어 있다면 다음처럼 둡니다.

sudo mkdir -p /data/alphafold
sudo chown -R $USER:$USER /data/alphafold

export DOWNLOAD_DIR=/data/alphafold/databases
mkdir -p $DOWNLOAD_DIR

full 데이터베이스를 내려받으려면 AlphaFold 저장소 루트에서 다음을 실행합니다.

cd ~/software/alphafold
scripts/download_all_data.sh $DOWNLOAD_DIR > download.log 2> download_all.log &

이 명령은 백그라운드에서 실행됩니다. 다운로드 로그는 다음처럼 확인합니다.

tail -f download.log
tail -f download_all.log

공식 문서 기준 full 데이터베이스는 다운로드만 약 556GB, 압축 해제 후 약 2.62TB입니다.2 네트워크가 빠른 기관망에서도 몇 시간 안에 끝난다고 장담하기 어렵고, 일반적인 연구실 회선에서는 하루 이상 걸릴 수 있습니다. 중간에 실패하면 로그를 보고 해당 스크립트를 다시 실행해야 할 수 있습니다. 이 단계에서는 조급해하지 않는 것이 좋습니다. AlphaFold 로컬 설치의 절반은 기다림입니다.

reduced_dbs를 사용하려면 다음처럼 실행합니다.

scripts/download_all_data.sh $DOWNLOAD_DIR reduced_dbs > download_reduced.log 2> download_reduced_all.log &

reduced_dbs는 full 데이터베이스 대신 작은 BFD를 사용합니다. 저장공간과 검색 시간이 줄어드는 대신, full 데이터베이스만큼 넓은 서열 공간을 탐색하지 못합니다. 처음 설치를 검증할 때는 reduced로 빠르게 테스트하고, 실제 연구용 실행은 full로 전환하는 전략도 좋습니다.

다운로드가 끝난 뒤에는 대략 다음과 같은 디렉터리가 있어야 합니다.

$DOWNLOAD_DIR/
  bfd/              # full_dbs에서 사용
  small_bfd/        # reduced_dbs에서 사용
  mgnify/
  params/
  pdb70/
  pdb_mmcif/
  pdb_seqres/       # multimer에 필요
  uniref30/
  uniprot/          # multimer에 필요
  uniref90/

권한 문제도 흔한 함정입니다. 데이터베이스 파일을 root로 내려받았거나, 여러 사용자가 공유하는 서버에서 권한이 제한되어 있으면 MSA 도구가 "파일을 못 읽는다"는 말을 친절하게 하지 않고 이상한 외부 프로그램 오류로 멈출 수 있습니다. 문제가 의심되면 다음처럼 읽기 권한을 정리합니다.

chmod -R 755 $DOWNLOAD_DIR

공식 문서도 다운로드 디렉터리와 데이터셋 권한이 맞지 않으면 MSA 도구에서 불투명한 오류가 날 수 있다고 경고합니다.2

run_docker.py의 핵심 인자 이해하기

이제 실행 명령을 볼 차례입니다. AlphaFold Docker 실행은 결국 python3 docker/run_docker.py에 여러 옵션을 넘기는 방식입니다. 많은 옵션이 있지만, 처음에는 여섯 개만 정확히 이해하면 됩니다.

--fasta_paths는 예측할 서열 FASTA 파일의 경로입니다. 하나의 FASTA 파일을 줄 수도 있고, 쉼표로 구분해 여러 파일을 줄 수도 있습니다. 다만 처음에는 한 파일씩 실행하는 편이 오류를 찾기 쉽습니다.

--max_template_date는 템플릿 검색에 사용할 PDB 구조의 최신 날짜 제한입니다. 예를 들어 이미 2023년에 공개된 구조를 대상으로 벤치마크를 하면서 그 구조가 템플릿으로 들어가면 공정하지 않습니다. 이때 --max_template_date=2022-01-01처럼 설정해 그 이후 공개 구조를 템플릿에서 제외할 수 있습니다. 단순한 실무 예측이라면 현재 날짜보다 충분히 뒤의 날짜를 쓰는 경우도 있지만, 재현성과 누출 방지를 생각하면 연구 목적에 맞춰 신중히 정해야 합니다.

--model_preset은 어떤 모델 계열을 쓸지 정합니다. 단일 사슬이면 보통 monomer 또는 monomer_ptm, 복합체면 multimer를 사용합니다. monomer_ptm은 PAE와 pTM 같은 전역 신뢰도 정보를 함께 얻고 싶을 때 유용합니다. 복합체에서는 반드시 multimer를 선택해야 ipTM과 사슬 간 배치 평가를 제대로 활용할 수 있습니다.

--db_preset은 데이터베이스 선택입니다. full_dbs는 full 데이터베이스를 사용하고, reduced_dbs는 작은 데이터베이스 구성을 사용합니다. full은 느리고 무겁지만 더 풍부한 MSA를 만들 가능성이 있습니다. reduced는 빠르고 가볍지만 어려운 표적에서는 정보가 부족할 수 있습니다.

--data_dir는 방금 받은 데이터베이스의 상위 디렉터리입니다. 이 경로 아래에 bfd, params, pdb_mmcif, uniref90 같은 디렉터리가 있어야 합니다.

--output_dir는 결과를 저장할 디렉터리입니다. 반드시 쓰기 권한이 있어야 하며, 가능하면 절대경로를 쓰는 것이 안전합니다. AlphaFold는 이 안에 FASTA 이름에 해당하는 하위 디렉터리를 만들고, ranked_0.pdb, ranking_debug.json, result_model_*.pkl, timings.json, msas/ 등을 저장합니다. 결과 파일의 의미는 앞 장에서 이미 읽는 법을 익혔으니, 여기서는 "어디에 생기는지"만 정확히 잡으면 됩니다.

공식 실행 예시는 FASTA 경로, 템플릿 날짜, 데이터베이스 디렉터리, 출력 디렉터리를 넘겨 run_docker.py를 실행하는 형태를 사용합니다.1

첫 monomer 예측 실행하기

먼저 아주 짧은 단일 단백질로 설치가 제대로 되었는지 확인해 봅시다. 작업 디렉터리를 만들고 FASTA 파일을 작성합니다.

mkdir -p ~/af2_jobs/monomer_test
cd ~/af2_jobs/monomer_test

cat > target_monomer.fasta <<'EOF'
>test_monomer
MKTAYIAKQRQISFVKSHFSRQDILDLICENSD
EOF

FASTA 형식은 단순합니다. >로 시작하는 한 줄은 이름이고, 그 아래가 아미노산 서열입니다. 공백, 숫자, 특수문자가 섞이지 않도록 주의합니다. 실제 연구에서는 UniProt 등에서 가져온 canonical sequence인지, signal peptide나 transmembrane region을 포함할지, fragment인지 등을 앞 장의 기준에 따라 확인해야 합니다.

이제 실행합니다.

cd ~/software/alphafold

export DOWNLOAD_DIR=/data/alphafold/databases
export OUTPUT_DIR=/data/alphafold/runs/monomer_test
mkdir -p $OUTPUT_DIR

python3 docker/run_docker.py \
  --fasta_paths=/home/$USER/af2_jobs/monomer_test/target_monomer.fasta \
  --max_template_date=2022-01-01 \
  --model_preset=monomer_ptm \
  --db_preset=full_dbs \
  --data_dir=$DOWNLOAD_DIR \
  --output_dir=$OUTPUT_DIR

처음 실행은 오래 걸릴 수 있습니다. MSA 검색, 템플릿 검색, 모델 컴파일, 추론, relaxation이 차례로 진행됩니다. 특히 작은 단백질에서는 실제 추론보다 준비와 컴파일 시간이 더 눈에 띌 수 있습니다. 반대로 큰 단백질에서는 MSA 검색과 추론 시간이 모두 길어집니다.

결과는 보통 다음 위치에 생깁니다.

/data/alphafold/runs/monomer_test/test_monomer/
  ranked_0.pdb
  ranked_1.pdb
  ranked_2.pdb
  ranked_3.pdb
  ranked_4.pdb
  ranking_debug.json
  timings.json
  result_model_*.pkl
  msas/

ranked_0.pdb가 가장 높은 신뢰도로 순위가 매겨진 모델입니다. 다만 앞 장에서 강조했듯이 1등 구조만 보고 끝내면 안 됩니다. ranking_debug.json을 보고 모델 간 점수 차이가 큰지 확인하고, pLDDT와 PAE를 함께 읽어야 합니다. 특히 monomer_ptm을 사용하면 PAE 해석이 가능해 도메인 간 상대 배치 판단에 유리합니다.

만약 full 데이터베이스 설치가 아직 끝나지 않았고 reduced 데이터베이스만 준비했다면 명령에서 --db_preset=reduced_dbs로 바꿉니다.

python3 docker/run_docker.py \
  --fasta_paths=/home/$USER/af2_jobs/monomer_test/target_monomer.fasta \
  --max_template_date=2022-01-01 \
  --model_preset=monomer_ptm \
  --db_preset=reduced_dbs \
  --data_dir=$DOWNLOAD_DIR \
  --output_dir=$OUTPUT_DIR

단, reduced로 얻은 결과가 낮은 신뢰도를 보인다고 해서 단백질이 정말 무질서하다고 바로 결론 내리면 안 됩니다. MSA가 빈약해서 그럴 수도 있습니다. 중요한 표적은 full 데이터베이스로 다시 돌려 비교하는 것이 좋습니다.

multimer 예측은 FASTA부터 다르다

단백질 복합체 예측은 명령 하나만 바꾸는 작업처럼 보이지만, 실제로는 입력의 의미가 달라집니다. monomer에서는 FASTA 안에 단일 사슬 하나를 넣습니다. multimer에서는 함께 접힐 사슬들을 같은 FASTA 파일 안에 여러 entry로 넣습니다.

예를 들어 A와 B 두 단백질의 이합체를 예측하려면 다음처럼 작성합니다.

mkdir -p ~/af2_jobs/multimer_test
cd ~/af2_jobs/multimer_test

cat > target_multimer.fasta <<'EOF'
>chain_A
MKTAYIAKQRQISFVKSHFSRQDILDLICENSD
>chain_B
GSHMRYKVEELSKNYHLENEVARLKKLVGER
EOF

중요한 점은 chain_A, chain_B라는 이름 자체가 구조의 체인 ID를 직접 강제하는 것은 아니라는 것입니다. 하지만 사람이 읽고 추적하기 쉽게 의미 있는 이름을 붙이는 습관은 매우 중요합니다. 같은 단백질 두 개로 homodimer를 예측하려면 같은 서열을 두 번 넣습니다.

>chain_A
AAAA...
>chain_B
AAAA...

"서열 하나를 넣고 homodimer라고 알아서 판단해 주겠지"라고 기대하면 안 됩니다. AlphaFold-Multimer에게 두 사슬을 예측하라고 말하려면 FASTA에 두 entry가 있어야 합니다.

multimer 실행에서는 --model_preset=multimer를 사용합니다.

cd ~/software/alphafold

export DOWNLOAD_DIR=/data/alphafold/databases
export OUTPUT_DIR=/data/alphafold/runs/multimer_test
mkdir -p $OUTPUT_DIR

python3 docker/run_docker.py \
  --fasta_paths=/home/$USER/af2_jobs/multimer_test/target_multimer.fasta \
  --max_template_date=2022-01-01 \
  --model_preset=multimer \
  --db_preset=full_dbs \
  --data_dir=$DOWNLOAD_DIR \
  --output_dir=$OUTPUT_DIR

AlphaFold-Multimer는 단백질 복합체 예측을 위해 확장된 모델입니다. 공식 저장소도 Multimer 구현을 제공하지만, monomer 시스템만큼 항상 안정적이라고 기대해서는 안 된다고 설명합니다.1 복합체에서는 "각 사슬이 예쁘게 접혔는가"보다 "사슬 사이 배치와 interface를 믿을 수 있는가"가 더 중요합니다. 따라서 결과를 볼 때는 pLDDT만 보지 말고 ipTM, 사슬 간 PAE, seed 반복성, 생물학적 맥락을 함께 봐야 합니다.

multimer는 추가 데이터베이스 의존성도 있습니다. PDB seqres와 UniProt은 AlphaFold-Multimer에 필요합니다.2 full 데이터베이스를 download_all_data.sh로 받았다면 함께 준비되지만, 오래된 설치나 수동 다운로드 환경에서는 이 두 항목이 빠져 있을 수 있습니다. multimer 실행에서 데이터베이스 경로 오류가 난다면 pdb_seqres/와 uniprot/ 존재 여부를 먼저 확인하세요.

model_preset 선택: monomer, monomer_ptm, multimer

model_preset은 AlphaFold가 어떤 목적의 모델을 사용할지 정하는 스위치입니다. 실무에서 가장 자주 만나는 선택지는 세 가지입니다.

  • monomer는 단일 단백질 구조 예측에 쓰는 기본 계열입니다.

  • monomer_ptm은 단일 단백질 예측이지만 pTM과 PAE 같은 전역 신뢰도 정보를 함께 얻고 싶을 때 유용합니다.

  • multimer는 여러 단백질 사슬을 동시에 넣어 복합체를 예측할 때 사용합니다.

처음 배우는 독자에게는 monomer_ptm과 multimer를 기본 작업horse로 추천합니다. monomer_ptm은 약간의 차이는 있더라도 PAE를 함께 볼 수 있어 구조 해석이 훨씬 편합니다. 도메인 두 개가 각각 잘 접혔지만 서로의 위치가 흔들리는 경우, pLDDT만으로는 그 불확실성을 놓치기 쉽습니다. PAE는 바로 그 도메인 간 상대 배치를 읽는 데 도움을 줍니다.

복합체는 반드시 multimer로 실행해야 합니다. 여러 서열을 FASTA에 넣고도 model_preset=monomer로 실행하면 의도한 복합체 예측이 되지 않습니다. 반대로 단일 서열 하나를 multimer로 돌리는 것도 일반적인 사용법이 아닙니다. 입력과 모델 목적을 맞추는 것이 첫 번째 품질 관리입니다.

AlphaFold 2.2 이후 multimer에서는 모델당 여러 예측을 만들 수 있는 옵션도 도입되었습니다. 예를 들어 --num_multimer_predictions_per_model 값을 늘리면 같은 모델 계열에서도 다른 무작위성으로 더 많은 후보 구조를 얻을 수 있습니다.5 다만 후보가 많아질수록 계산 시간과 출력 파일도 늘어납니다. 복합체가 어렵고 interface가 불안정할 때는 유용하지만, 모든 작업에 무작정 크게 설정할 필요는 없습니다.

예를 들어 모델당 3개씩 후보를 만들고 싶다면 다음처럼 추가합니다.

python3 docker/run_docker.py \
  --fasta_paths=/home/$USER/af2_jobs/multimer_test/target_multimer.fasta \
  --max_template_date=2022-01-01 \
  --model_preset=multimer \
  --db_preset=full_dbs \
  --data_dir=$DOWNLOAD_DIR \
  --output_dir=$OUTPUT_DIR \
  --num_multimer_predictions_per_model=3

이렇게 얻은 여러 구조는 "가장 높은 점수 하나를 고르는" 용도로만 보지 말고, interface가 반복해서 나타나는지 확인하는 데 써야 합니다. 좋은 복합체 예측은 대개 여러 seed나 여러 모델에서 비슷한 접촉면을 반복해서 보여 줍니다. 반대로 매번 다른 면으로 들러붙는다면, 그 상호작용은 계산적으로도 불안정하다는 신호일 수 있습니다.

db_preset 선택: 빠른 길과 넓은 길

db_preset은 AlphaFold가 MSA를 만들 때 어느 규모의 데이터베이스를 검색할지 결정합니다. full_dbs는 넓은 길입니다. 시간이 오래 걸리고 저장공간을 많이 쓰지만, 더 많은 서열 정보를 찾을 가능성이 있습니다. reduced_dbs는 빠른 길입니다. 설치와 실행이 가볍지만, 어려운 표적에서는 MSA 정보가 부족할 수 있습니다.

처음 설치 검증에는 reduced_dbs가 좋습니다. "Docker가 실행되는가, GPU가 보이는가, 결과 디렉터리가 만들어지는가"를 확인하는 데 full 데이터베이스가 꼭 필요하지는 않습니다. 하지만 연구용 최종 결과, 특히 다음과 같은 경우에는 full_dbs를 권합니다.

  • 동족체가 적거나 진화 정보가 부족할 것으로 예상되는 단백질을 다룰 때

  • 단백질 복합체에서 사슬 간 공진화 신호를 최대한 활용하고 싶을 때

  • 논문, 보고서, 특허 등에서 재현 가능한 조건을 명확히 남겨야 할 때

여기서 공진화 신호란 서로 상호작용하는 잔기들이 진화 과정에서 함께 변하는 경향을 말합니다. AlphaFold는 이런 패턴을 이용해 멀리 떨어진 서열 정보에서 가까운 3차원 접촉을 추론합니다. 데이터베이스가 풍부할수록 이런 단서가 많아질 수 있습니다.

다만 full이 항상 더 좋은 구조를 보장하는 것은 아닙니다. 데이터베이스 버전, 템플릿 포함 여부, 단백질의 생물학적 상태, 무질서 영역, 복합체의 일시적 상호작용 여부가 모두 영향을 줍니다. db_preset은 품질을 올리는 마법 버튼이 아니라 정보 검색의 폭을 정하는 버튼입니다.

max_template_date는 왜 중요한가

max_template_date는 초보자가 가볍게 넘기기 쉬운 옵션이지만, 연구에서는 매우 중요합니다. AlphaFold는 PDB에 있는 알려진 구조를 템플릿으로 참고할 수 있습니다. 이것은 장점이지만, 검증 상황에서는 함정이 됩니다.

예를 들어 어떤 단백질의 실험 구조가 2024년에 공개되었고, 여러분이 AlphaFold 예측이 그 구조를 얼마나 잘 맞히는지 평가한다고 해 봅시다. 이때 max_template_date를 2026년으로 두면 AlphaFold가 이미 공개된 정답 구조나 매우 가까운 구조를 템플릿으로 볼 수 있습니다. 그러면 "예측을 잘했다"기보다 "정답지를 봤다"에 가까운 상황이 됩니다.

따라서 벤치마크나 논문 재현에서는 실험 구조 공개일보다 이전 날짜를 설정해야 합니다.

--max_template_date=2022-01-01

반대로 실제 연구에서 가장 좋은 모델을 얻고 싶은 목적이라면 최신 템플릿을 활용하는 것이 합리적일 수 있습니다. 단, 보고할 때는 날짜를 반드시 적어야 합니다. max_template_date는 결과의 해석 조건입니다. 실험 노트에 pH와 온도를 적듯이, AlphaFold 실행 노트에는 이 날짜를 적어야 합니다.

반복 실행과 대량 예측을 위한 기본 스크립트

로컬 설치의 장점은 자동화에서 빛납니다. 같은 설정으로 여러 FASTA를 돌리려면 셸 스크립트를 만들어 두는 것이 좋습니다. 예를 들어 ~/af2_jobs/run_one_monomer.sh를 다음처럼 작성할 수 있습니다.

#!/usr/bin/env bash
set -euo pipefail

FASTA=$1
NAME=$(basename "$FASTA")
NAME=${NAME%.*}

AF2_REPO=/home/$USER/software/alphafold
DATA_DIR=/data/alphafold/databases
OUT_DIR=/data/alphafold/runs/${NAME}

mkdir -p "$OUT_DIR"
cd "$AF2_REPO"

python3 docker/run_docker.py \
  --fasta_paths="$FASTA" \
  --max_template_date=2022-01-01 \
  --model_preset=monomer_ptm \
  --db_preset=full_dbs \
  --data_dir="$DATA_DIR" \
  --output_dir="$OUT_DIR"

실행 권한을 줍니다.

chmod +x ~/af2_jobs/run_one_monomer.sh

이제 FASTA 하나를 다음처럼 실행할 수 있습니다.

~/af2_jobs/run_one_monomer.sh /home/$USER/af2_jobs/inputs/protein_001.fasta

여러 파일을 순서대로 돌리려면 다음처럼 합니다.

for fasta in /home/$USER/af2_jobs/inputs/*.fasta; do
  ~/af2_jobs/run_one_monomer.sh "$fasta"
done

단, 한 대의 워크스테이션에서 여러 AlphaFold 작업을 동시에 돌리는 것은 조심해야 합니다. AlphaFold의 단일 예측은 보통 하나의 GPU를 사용하도록 설계되어 있으며, 한 예측을 여러 GPU에 자동 분산해 빠르게 만드는 방식이 아닙니다.6 GPU가 두 개라면 두 작업을 각각 다른 GPU에 배정해 동시에 실행할 수는 있지만, 같은 GPU에 여러 작업을 겹쳐 돌리면 메모리 부족이 쉽게 납니다.

특정 GPU만 사용하려면 run_docker.py에 --gpu_devices를 줄 수 있습니다.

python3 docker/run_docker.py \
  --fasta_paths=/path/to/protein_001.fasta \
  --max_template_date=2022-01-01 \
  --model_preset=monomer_ptm \
  --db_preset=full_dbs \
  --data_dir=/data/alphafold/databases \
  --output_dir=/data/alphafold/runs/protein_001 \
  --gpu_devices=0

다른 터미널에서는 --gpu_devices=1로 두 번째 GPU를 사용할 수 있습니다. 물론 CPU, RAM, 디스크 입출력도 함께 소모되므로, GPU 수만 보고 무한히 병렬화하면 오히려 전체가 느려질 수 있습니다.

실행 중 무엇을 보고 있어야 하나

AlphaFold를 처음 로컬에서 돌리면 터미널 로그가 폭포처럼 흐릅니다. 모든 줄을 이해할 필요는 없습니다. 대신 큰 단계만 보면 됩니다. 대체로 MSA 검색, 템플릿 검색, feature 생성, 모델 추론, relaxation, 결과 저장 순서로 진행됩니다.

실행 중 GPU가 쓰이는지 확인하려면 다른 터미널에서 다음을 봅니다.

watch -n 2 nvidia-smi

처음 MSA 검색 단계에서는 GPU 사용률이 낮을 수 있습니다. 이때 "GPU가 놀고 있으니 실패한 것 아닌가?"라고 걱정하지 않아도 됩니다. MSA와 템플릿 검색은 CPU와 디스크가 주로 일하는 단계입니다. 나중에 모델 추론에 들어가면 GPU 메모리 사용량과 연산 사용률이 올라갑니다.

CPU와 디스크 상태도 확인할 수 있습니다.

htop
iotop

iotop은 별도 설치가 필요할 수 있습니다. 대형 데이터베이스를 HDD에 두었을 때 작업이 느려지는 이유를 보면 대개 디스크 입출력이 병목입니다. SSD 권장이 단순한 사치가 아니라는 사실을 여기서 체감하게 됩니다.

timings.json도 유용합니다. 예측이 끝난 뒤 이 파일을 보면 각 단계에 걸린 시간이 기록됩니다. 어떤 단백질은 MSA가 대부분의 시간을 먹고, 어떤 단백질은 모델 추론이나 relaxation이 오래 걸립니다. 대량 예측 계획을 세울 때는 몇 개의 대표 단백질을 먼저 돌려 timings.json을 보고 전체 시간을 추정하는 편이 좋습니다.

relaxation은 꼭 해야 할까

AlphaFold 출력에는 unrelaxed 구조와 relaxed 구조가 있습니다. relaxation은 OpenMM/AMBER를 이용해 원자 간 충돌이나 측쇄 기하를 조금 더 물리적으로 다듬는 후처리입니다. 구조의 큰 접힘을 새로 예측하는 단계가 아니라, 이미 나온 모델을 정리하는 단계에 가깝습니다.

최신 AlphaFold 2 계열에서는 relaxation 관련 옵션이 버전에 따라 --models_to_relax=best, all, none처럼 관리됩니다. 일부 문서와 예전 스크립트에서는 --run_relax 같은 이전 인자를 볼 수 있으므로, 사용 중인 저장소 버전에서 python3 docker/run_docker.py --help 또는 관련 실행 도움말을 확인하는 것이 안전합니다. AlphaFold 2.3.2 이후에는 relaxation 인자 명칭 변화가 언급되어 왔습니다.5

실무적으로는 다음처럼 생각하면 됩니다. 전체 fold, 도메인 배치, interface 후보를 빠르게 비교하는 단계에서는 relaxation을 생략하거나 best 모델만 relaxation해도 충분한 경우가 많습니다. 반대로 분자 치환, 측쇄 충돌 검토, 결합 부위 주변 원자 배치 확인처럼 기하가 중요한 작업에서는 relaxed 모델을 보는 편이 좋습니다.

Docker 실행에서 GPU relaxation을 지원하는 환경이라면 다음 옵션을 추가할 수 있습니다.

--use_gpu_relax=True

다만 relaxation은 구조 신뢰도를 마법처럼 올려 주지 않습니다. 낮은 pLDDT 영역을 relaxation했다고 갑자기 믿을 수 있는 helix가 되는 것은 아닙니다. relaxation은 "예측의 확신"을 바꾸는 단계가 아니라 "예측된 원자 배치의 거친 부분"을 다듬는 단계입니다.

monomer와 multimer 결과를 다르게 해석하기

로컬 실행 자체는 명령어 문제이지만, 실행 후 판단은 생물학 문제입니다. monomer에서는 먼저 pLDDT와 PAE를 봅니다. 단일 도메인 단백질이라면 전체 pLDDT가 높고 PAE가 낮은지 확인합니다. 여러 도메인이 연결된 단백질이라면 각 도메인 내부는 믿을 만하지만 도메인 간 상대 위치는 불확실할 수 있습니다. 이때 ranked_0.pdb 하나를 전체적으로 신뢰하면 안 됩니다.

multimer에서는 더 조심해야 합니다. 각 사슬의 pLDDT가 높아도 interface가 틀릴 수 있습니다. 복합체에서는 ipTM, 사슬 간 PAE, 반복 실행에서 interface가 재현되는지, 알려진 기능 부위와 충돌하지 않는지, 세포 내 위치와 stoichiometry가 맞는지를 함께 봐야 합니다. AlphaFold-Multimer 결과는 "이 복합체가 반드시 존재한다"는 증거가 아니라 "이런 결합 배치가 구조적으로 가능해 보인다"는 가설입니다.

앞 장에서 이미 살펴본 것처럼 무질서 꼬리나 짧은 motif가 가짜 접착제처럼 작동할 때가 있습니다. 로컬 설치를 하면 이런 문제를 더 잘 다룰 수 있습니다. 꼬리를 자른 construct, 도메인만 남긴 construct, 상호작용 후보 motif를 변형한 construct를 여러 개 만들어 비교할 수 있기 때문입니다. 로컬 AlphaFold 2의 진짜 힘은 단일 예측이 아니라 이런 실험 설계형 반복 실행에서 나옵니다.

실패했을 때 먼저 확인할 체크포인트

AlphaFold 로컬 설치는 구성요소가 많아서 오류도 다양합니다. 하지만 대부분은 몇 가지 범주로 나뉩니다. 긴 오류 메시지를 보기 전에 다음 순서로 확인하면 시간을 많이 아낄 수 있습니다.

  • nvidia-smi가 호스트에서 실행되는지, 그리고 docker run --rm --gpus all ... nvidia-smi가 컨테이너 안에서도 실행되는지 확인합니다.

  • $DOWNLOAD_DIR 아래에 params, pdb_mmcif, uniref90, mgnify, uniref30, bfd 또는 small_bfd가 있는지 확인합니다.

  • multimer라면 pdb_seqres/pdb_seqres.txt와 uniprot/uniprot.fasta가 있는지 확인합니다.

  • --db_preset=full_dbs를 쓰면서 full BFD가 없거나, --db_preset=reduced_dbs를 쓰면서 small BFD가 없지 않은지 확인합니다.

  • --output_dir가 절대경로이고 현재 사용자가 쓸 수 있는 위치인지 확인합니다.

  • FASTA 파일에 이상한 문자, 빈 서열, 중복 header, Windows 줄바꿈 문제가 없는지 확인합니다.

"파일을 찾을 수 없다"는 오류는 대개 경로 문제입니다. Docker에서는 호스트의 경로를 컨테이너에 마운트해서 사용하므로, 상대경로보다 절대경로가 안전합니다. "No space left on device"는 출력 디렉터리뿐 아니라 Docker 임시 공간이나 데이터베이스가 있는 파일시스템이 찼을 때도 생깁니다. "HHblits failed", "Jackhmmer failed" 같은 오류는 데이터베이스 권한, 경로, 디스크 공간 문제에서 비롯되는 경우가 많습니다.

GPU 메모리 부족은 더 정직합니다. 보통 로그에 out of memory 또는 resource exhausted가 보입니다. 이때는 더 짧은 construct로 나누거나, multimer 조합을 줄이거나, relaxation을 줄이거나, 더 큰 VRAM의 GPU에서 실행해야 합니다. 긴 단백질과 큰 복합체는 단순히 기다리면 해결되는 문제가 아닐 때가 많습니다.

설치를 연구 기록으로 남기기

로컬 설치를 마쳤다면 마지막으로 해야 할 일은 기록입니다. AlphaFold는 클릭 한 번으로 끝나는 도구가 아니라, 데이터베이스와 코드와 파라미터가 함께 움직이는 계산 실험입니다. 나중에 같은 결과를 재현하려면 다음 정보를 남겨야 합니다.

  • AlphaFold git commit 또는 release 버전

  • Docker 이미지 빌드 날짜와 이미지 이름

  • 모델 파라미터 다운로드 날짜

  • 데이터베이스 다운로드 날짜와 db_preset

  • max_template_date, model_preset, num_multimer_predictions_per_model, relaxation 설정

  • GPU 모델, 드라이버 버전, 주요 실행 시간

가장 간단한 방법은 실행 디렉터리에 run_command.txt를 저장하는 것입니다.

cat > /data/alphafold/runs/monomer_test/run_command.txt <<'EOF'
python3 docker/run_docker.py \
  --fasta_paths=/home/user/af2_jobs/monomer_test/target_monomer.fasta \
  --max_template_date=2022-01-01 \
  --model_preset=monomer_ptm \
  --db_preset=full_dbs \
  --data_dir=/data/alphafold/databases \
  --output_dir=/data/alphafold/runs/monomer_test
EOF

그리고 버전도 함께 저장합니다.

cd ~/software/alphafold
git rev-parse HEAD > /data/alphafold/runs/monomer_test/alphafold_git_commit.txt
nvidia-smi > /data/alphafold/runs/monomer_test/nvidia_smi.txt
docker image ls alphafold > /data/alphafold/runs/monomer_test/docker_image.txt

이 작은 습관이 나중에 큰 차이를 만듭니다. 석 달 뒤 같은 단백질을 다시 돌렸는데 결과가 조금 다르다면, 서열이 달라진 것인지, 데이터베이스가 달라진 것인지, 모델 버전이 달라진 것인지 추적할 수 있어야 합니다.

로컬 AlphaFold 2를 잘 쓰는 감각

로컬 설치는 처음에는 거대한 성문처럼 보입니다. Docker, GPU, CUDA, 데이터베이스, FASTA, 모델 옵션이 한꺼번에 몰려오기 때문입니다. 하지만 한 번 길을 뚫고 나면 작업 방식이 달라집니다. 단백질 하나를 예측하는 사용자가 아니라, 가설을 구조 모델로 검토하는 운영자가 됩니다.

중요한 것은 모든 옵션을 외우는 것이 아닙니다. 먼저 GPU가 Docker 안에서 보이는지 확인합니다. 그다음 데이터베이스를 올바른 위치에 준비합니다. 그다음 FASTA를 정확히 쓰고, monomer인지 multimer인지에 맞춰 model_preset을 고릅니다. 마지막으로 db_preset, max_template_date, output_dir를 기록합니다. 이 뼈대만 단단하면 나머지 고급 옵션은 필요할 때 하나씩 얹을 수 있습니다.

다음 단계에서는 더 어려운 예측을 개선하는 방법으로 넘어갑니다. 템플릿을 의도적으로 조절하고, 커스텀 MSA를 넣고, seed를 바꿔 반복 실행하는 방법입니다. 로컬 AlphaFold 2를 설치한 이유가 바로 거기에 있습니다. 한 번의 예쁜 그림을 얻기 위해서가 아니라, 같은 질문을 여러 각도에서 찔러 보고 믿을 만한 구조 가설만 남기기 위해서입니다.

참고

1Google DeepMind AlphaFold GitHub 저장소

2AlphaFold genetic databases 안내

3SBGrid AlphaFold2 문서의 GPU memory 설명

4NVIDIA NIM for AlphaFold2 prerequisites

5AlphaFold 2.3.2 설치 및 버전 변경 설명

6Intro to Bioinformatics Software: AlphaFold2 HPC notes

책 목록

AlphaFold 실전 사용법: 서열 준비부터 구조 해석, AlphaFold 3와 재현 가능한 보고까지

전체 목차 보기

이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.

틸노트는 사용자가 AI를 활용해 노트를 쉽게 작성하거나 편집할 수 있는 서비스입니다.

회원 가입

AI 스퀘어 단톡방에 함께해요

AI 활용과 틸노트 사용 팁을 나누는 오픈채팅방입니다. 입장 비밀번호는 tilnote입니다.

참여하기
이용약관·개인정보처리방침