흔한 오류와 문제 해결 체크리스트

AlphaFold를 처음 실행할 때 가장 당황스러운 순간은 모델이 틀린 구조를 내놓을 때가 아니다. 그보다 훨씬 앞에서 일이 멈춘다. Colab 런타임이 끊기고, HPC 작업이 대기열에서 사라지고, Docker 안에서는 GPU가 보이지 않고, 데이터베이스 파일 하나가 없다는 이유로 몇 시간짜리 작업이 실패한다.

이 장의 핵심은 단순하다. AlphaFold 작업의 절반은 모델 실행이 아니라 환경과 데이터 문제를 안정화하는 일이다. 좋은 예측은 좋은 입력에서 시작하지만, 안정적인 예측은 좋은 실행 환경에서 시작한다. 오류 메시지는 짜증나는 빨간 글씨가 아니라, 파이프라인의 어느 지점에서 일이 끊겼는지 알려 주는 표지판이다. 표지판을 읽는 순서만 익히면 문제 해결은 훨씬 덜 무섭다.

오류를 보기 전에 파이프라인을 먼저 나누기

AlphaFold 오류를 해결할 때 가장 나쁜 습관은 로그의 마지막 줄만 보고 바로 검색창에 붙여 넣는 것이다. 마지막 줄은 대개 "실패했다"는 선언일 뿐, 실패의 원인이 아닐 수 있다. 먼저 전체 과정을 네 구간으로 나누어 보자.

첫째는 입력 검증이다. FASTA나 JSON이 올바른지, 체인 구분이 맞는지, 서열에 이상한 문자가 섞이지 않았는지 확인하는 단계다. AlphaFold 2 계열은 주로 FASTA를, AlphaFold 3 계열은 JSON을 사용한다. 여기서 틀리면 모델은 시작도 하지 못한다.

둘째는 데이터 파이프라인이다. MSA 검색, 템플릿 검색, mmCIF 구조 파일 접근이 이 구간에 들어간다. 실제 현장에서는 이 단계에서 매우 많은 오류가 난다. 데이터베이스 경로가 틀렸거나, 파일 권한이 없거나, 압축이 덜 풀렸거나, 공유 파일 시스템이 너무 느릴 수 있다.

셋째는 모델 추론이다. GPU가 본격적으로 일하는 구간이다. CUDA, JAX/XLA, Docker 또는 Singularity, GPU 메모리 부족 문제가 여기서 드러난다. "unknown backend: gpu", "CUDA version mismatch", "RESOURCE_EXHAUSTED" 같은 메시지를 자주 만난다.

넷째는 후처리와 결과 해석이다. 구조 파일은 나왔지만 pLDDT가 낮거나, ipTM이 낮거나, 잔기끼리 심하게 겹치거나, ranking score가 비정상적으로 떨어질 수 있다. 이 경우에는 실행 실패와 생물학적 불확실성을 구분해야 한다.

이 네 구간을 나누어 놓으면 문제 해결은 "뭔가 안 된다"에서 "MSA 검색 전 단계에서 실패한다", "GPU 추론이 시작된 뒤 메모리가 터진다", "구조는 나오지만 결과 품질이 이상하다"처럼 훨씬 구체적인 작업이 된다.

첫 번째 원칙: 작은 smoke test로 환경부터 검증하기

큰 복합체를 바로 돌리는 것은 새로 산 자동차로 눈길 산악 코스를 먼저 달리는 것과 비슷하다. 문제가 생겼을 때 엔진 문제인지, 타이어 문제인지, 운전자의 경로 선택 문제인지 알기 어렵다. AlphaFold도 마찬가지다. 처음에는 반드시 작은 smoke test, 즉 "연기가 나는지 확인하는 짧은 시험 실행"을 해야 한다.

짧은 단백질 하나, 적은 샘플 수, 낮은 recycle 또는 diffusion step으로 시작한다. ColabFold라면 50~150개 잔기 정도의 단일 체인 예제를 쓰고, MSA와 template 옵션은 기본값에 가깝게 둔다. AlphaFold 3라면 샘플 수를 1로 줄이고, 탐색 실행에서는 diffusion step을 줄인 작은 JSON으로 먼저 확인한다. macOS용 AlphaFold 3 가이드도 설치 확인용 실행에서 --num_samples 1, --diffusion_steps 20처럼 작은 설정을 권장한다.¹

Smoke test가 성공하면 적어도 다음 사실은 확인된다.

• 입력 파일을 읽을 수 있다.

• 모델 가중치 또는 파라미터 경로가 맞다.

• 데이터베이스를 쓰는 설정이라면 기본 접근이 가능하다.

• GPU 또는 실행 백엔드가 최소한의 추론을 수행할 수 있다.

• 출력 디렉터리에 파일을 쓸 권한이 있다.

반대로 smoke test도 실패한다면 긴 서열, 복잡한 multimer, 거대한 MSA를 의심할 필요가 없다. 이때는 환경 자체가 아직 준비되지 않은 것이다. 큰 작업을 반복 제출하지 말고, 작은 테스트가 통과할 때까지 입력·경로·GPU·컨테이너를 점검해야 한다.

실전에서는 다음과 같은 순서가 좋다.

# 1. GPU가 호스트에서 보이는지 확인
nvidia-smi

# 2. 컨테이너 안에서도 GPU가 보이는지 확인
# Docker 예시
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

# 3. AlphaFold의 아주 작은 예제 실행
# 실제 명령은 사용하는 도구와 설치 방식에 맞게 조정한다.

공식 AlphaFold 3 설치 문서도 NVIDIA 드라이버 설치 후 nvidia-smi를 확인하고, Docker 컨테이너 내부에서 GPU가 보이는지 별도로 확인하는 절차를 제시한다.² 이 두 검사를 통과하지 못하면 AlphaFold 명령을 고쳐도 문제가 해결되지 않는다. 모델 이전에 도로가 끊겨 있는 셈이다.

Colab에서 멈출 때: 런타임, GPU, 시간 제한부터 의심하기

ColabFold나 Colab 기반 노트북은 시작이 쉽지만, 그만큼 실행 환경이 내 손안에 완전히 있지는 않다. 오늘은 GPU가 잡히지만 내일은 CPU만 배정될 수 있고, 무료 런타임은 예고 없이 끊길 수 있다. 브라우저 창을 오래 닫아 두면 세션이 사라지기도 한다.

Colab에서 가장 먼저 확인할 것은 "정말 GPU를 쓰고 있는가"이다. 노트북 메뉴에서 런타임 유형이 GPU로 설정되어 있는지 확인하고, 셀에서 다음을 실행해 본다.

!nvidia-smi

여기서 GPU 정보가 나오지 않으면 모델 옵션을 줄여도 소용이 없다. GPU가 없는 상태에서 긴 단백질이나 multimer를 돌리면 매우 오래 걸리거나 중간에 중단된다.

Colab에서 작업이 자꾸 끊긴다면 입력 크기를 줄여 원인을 분리한다. 같은 노트북에서 짧은 단일 체인은 성공하는데 긴 multimer만 실패한다면, 노트북 자체가 아니라 입력 규모가 문제일 가능성이 높다. 이때는 체인을 나누어 단일 도메인부터 예측하고, 필요한 부분만 multimer로 다시 묶는 전략을 쓴다. 특히 1,000개 잔기를 훌쩍 넘는 단백질이나 여러 개의 긴 사슬을 넣은 복합체는 Colab 환경에서 무리일 수 있다.

Colab에서 자주 효과가 있는 조치는 다음과 같다.

• 긴 단백질을 도메인 단위로 나누어 먼저 예측한다.

• multimer 입력에서 불필요한 태그, 긴 linker, 낮은 복잡도 영역을 제거한 테스트를 만든다.

• recycle 수, seed 수, sample 수를 줄여 탐색 실행을 먼저 한다.

• MSA 생성이 오래 걸리면 동일 입력을 반복 실행하지 말고 결과 파일을 저장해 둔다.

• 중요한 작업은 Colab이 아니라 로컬 GPU, HPC, 클라우드 환경으로 옮긴다.

Colab은 "빠른 실험실 노트"에 가깝다. 논문에 들어갈 최종 구조, 대규모 variant screening, 긴 복합체 반복 예측은 Colab만 믿기보다 재현 가능한 환경에서 다시 실행하는 것이 안전하다.

HPC에서 실패할 때: 제출 오류와 실행 오류를 구분하기

HPC에서는 오류가 두 번 나타날 수 있다. 하나는 작업을 제출하는 순간이고, 다른 하나는 작업이 실제 노드에서 실행된 뒤다. 이 둘을 구분하지 않으면 엉뚱한 곳을 고치게 된다.

제출 순간의 오류는 보통 스케줄러 설정 문제다. 예를 들어 Slurm의 #SBATCH, PBS의 #PBS 지시어에 잘못된 키를 쓰거나, 존재하지 않는 파티션을 요청하거나, 한 노드에 없는 GPU 개수를 요청하면 작업이 시작되기 전에 거절된다. VIB의 HPC AlphaFold 문제 해결 자료도 잘못된 자원 요청, 잘못된 클러스터 모듈, FASTA 파일 이름 오류, 메모리 부족, GPU 메모리 부족, 저장 공간 부족, 시간 제한 초과를 대표적인 HPC 오류로 정리한다.³

실행 후 오류는 로그 파일에 남는다. HPC에서는 표준 출력과 표준 오류가 별도 파일로 저장되는 경우가 많다. 많은 경우 진짜 단서는 로그의 맨 아래쪽에 있다. 하지만 맨 마지막 줄만 보지 말고, 그보다 위에서 처음 등장하는 Error, Traceback, RuntimeError, No such file, CUDA, Out of memory를 찾아야 한다.

HPC에서 작업이 시간 제한으로 죽는다면 세 가지를 확인한다. 첫째, GPU를 실제로 요청했는지 확인한다. GPU 없이 CPU 노드에서 추론을 돌리면 예상보다 훨씬 오래 걸린다. 둘째, MSA와 template 검색이 공유 파일 시스템에서 병목을 일으키는지 확인한다. 셋째, 입력 자체가 너무 큰지 확인한다. 긴 multimer 입력과 거대한 MSA는 계산 시간이 갑자기 늘어난다.

긴 작업은 가능하면 두 단계로 나누는 것이 좋다. 먼저 CPU 중심의 데이터 파이프라인, 즉 MSA와 template 검색을 수행하고, 그 결과를 저장한 뒤 GPU 추론을 별도 작업으로 실행한다. 이렇게 하면 MSA 검색에서 실패했을 때 비싼 GPU 시간을 낭비하지 않고, GPU 추론이 실패했을 때도 전처리 결과를 재사용할 수 있다.

HPC 운영에서는 다음 습관이 큰 차이를 만든다.

• 작업 이름에 입력 이름, 날짜, 주요 옵션을 넣는다.

• 표준 출력과 표준 오류 파일을 따로 저장한다.

• 실행 명령 전체를 로그 첫머리에 남긴다.

• 사용한 모듈, 컨테이너 이미지, GPU 종류를 기록한다.

• 실패한 작업은 입력을 줄인 smoke test로 같은 노드 유형에서 재현한다.

HPC의 오류는 대개 "AlphaFold가 이상하다"가 아니라 "요청한 자원, 실제 배정된 자원, 입력 크기, 파일 시스템 속도 중 하나가 맞지 않는다"에 가깝다.

GPU가 없다고 나올 때: unknown backend: gpu의 해부

Unknown backend: 'gpu' requested, but no platforms that are instances of gpu are present.라는 오류는 무섭게 보이지만 의미는 단순하다. 프로그램이 GPU로 실행하라고 요청받았는데, 실행 환경 안에서 GPU를 찾지 못했다는 뜻이다. UChicago RCC의 AlphaFold 문서도 이 오류의 해결 방향을 GPU 노드에서 실행 중인지, CUDA_VISIBLE_DEVICES가 올바른지 확인하는 것으로 안내한다.⁴

이 오류는 다음 중 하나에서 자주 생긴다.

• GPU 노드가 아닌 CPU 노드에서 작업을 실행했다.

• 스케줄러에서 GPU를 요청하지 않았다.

• CUDA_VISIBLE_DEVICES가 비어 있거나 잘못 설정되었다.

• Docker 컨테이너 실행 시 --gpus all을 빠뜨렸다.

• Singularity 또는 Apptainer 실행 시 --nv를 빠뜨렸다.

• NVIDIA Container Toolkit이 설치 또는 설정되지 않았다.

• JAX/XLA가 GPU 지원 버전이 아니라 CPU 버전으로 설치되었다.

진단은 바깥에서 안쪽으로 들어간다. 먼저 호스트에서 nvidia-smi가 되는지 본다. 그다음 컨테이너 안에서 nvidia-smi가 되는지 본다. 마지막으로 Python 안에서 JAX가 GPU를 인식하는지 확인한다.

# 호스트 확인
nvidia-smi

# Docker 컨테이너 확인
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

# Singularity/Apptainer 예시
singularity exec --nv alphafold3.sif nvidia-smi

호스트에서는 GPU가 보이는데 컨테이너 안에서는 보이지 않는다면 AlphaFold 명령이 아니라 컨테이너 GPU 연결 문제다. Docker에서는 NVIDIA Container Toolkit 설정을 확인하고, Singularity/Apptainer에서는 --nv 옵션과 bind mount 경로를 확인한다. 컨테이너 내부에서 GPU가 보인 뒤에야 AlphaFold의 CUDA, JAX, XLA 문제를 논할 수 있다.

CUDA version mismatch와 JAX/XLA 문제

CUDA 관련 오류는 이름이 비슷하지만 원인이 여러 층으로 나뉜다. NVIDIA 드라이버, CUDA 런타임, cuDNN, JAX, XLA, 컨테이너 이미지가 서로 맞물려야 한다. 한 층만 맞지 않아도 GPU가 보이지 않거나, 보이더라도 추론 중에 실패한다.

AlphaFold 3 공식 설치 문서는 Linux 환경, NVIDIA GPU, Docker 기반 실행을 전제로 하며, 전체 설치에는 유전 데이터베이스 저장 공간이 크게 필요하고, 특히 긴 입력의 genetic search에는 많은 RAM이 필요하다고 설명한다. 또한 공식 문서 기준으로 AlphaFold 3는 Compute Capability 8.0 이상의 NVIDIA GPU를 요구하며, A100 80GB 또는 H100 80GB에서 최대 5,120 tokens 입력을 검증했다고 밝힌다.⁵ 이 말은 "어떤 NVIDIA GPU든 된다"가 아니라는 뜻이다.

CUDA mismatch가 의심될 때는 먼저 nvidia-smi의 출력에서 드라이버 버전과 표시되는 CUDA 버전을 확인한다. 그다음 현재 컨테이너나 Python 환경이 요구하는 CUDA 버전과 비교한다. UChicago RCC 문서는 AlphaFold 3 환경에서 CUDA version mismatch가 날 경우 NVIDIA 드라이버와 CUDA 버전의 호환성을 확인하라고 안내한다.⁴

JAX/XLA 문제는 더 까다롭다. JAX는 Python에서 GPU 계산을 실행하게 해 주는 핵심 라이브러리이고, XLA는 계산 그래프를 GPU에 맞게 최적화하는 컴파일러 계층이라고 이해하면 된다. 이 둘이 설치된 CUDA 버전과 맞지 않으면 GPU를 못 찾거나 실행 중에 컴파일 오류가 난다. 로컬에 직접 설치했다면 JAX 공식 설치 지침과 AlphaFold 버전의 요구 사항을 대조해야 한다. 컨테이너를 쓴다면 되도록 공식 또는 기관에서 검증한 이미지를 쓰는 편이 안전하다.

AlphaFold 3에는 GPU 세대와 관련된 알려진 이슈도 있다. 공식 known issues 문서는 CUDA Capability 7.x GPU, 예를 들어 V100에서 특정 설정 없이 실행하면 잔기 충돌이 많은 비정상 출력과 매우 낮은 ranking score가 나올 수 있으며, XLA_FLAGS에 --xla_disable_hlo_passes=custom-kernel-fusion-rewriter를 포함하는 우회 방법을 제시한다.⁶ V100은 여전히 많은 HPC에 남아 있는 GPU라서 이 문제는 실무적으로 중요하다. "구조가 나왔으니 성공"이 아니라, GPU 세대에 따른 알려진 수치 문제가 있는지 확인해야 한다.

Docker와 Singularity에서 GPU가 안 보일 때

Docker와 Singularity는 AlphaFold 환경을 안정화하는 강력한 도구지만, GPU 연결과 파일 경로 연결이라는 두 가지 문을 통과해야 한다. 문 하나가 닫히면 컨테이너 안의 프로그램은 바깥세상을 볼 수 없다.

Docker에서는 대개 다음 조건이 필요하다. 호스트에 NVIDIA 드라이버가 설치되어 있어야 하고, NVIDIA Container Toolkit이 설정되어 있어야 하며, 컨테이너 실행 시 --gpus all 또는 적절한 GPU 지정 옵션을 넣어야 한다. 공식 AlphaFold 3 설치 문서는 Docker에서 GPU를 확인하기 위해 CUDA base image로 nvidia-smi를 실행하는 검사를 제시한다.²

Singularity 또는 Apptainer에서는 --nv 옵션이 핵심이다. HPC에서는 보안과 권한 문제 때문에 Docker 대신 Singularity를 많이 쓴다. 이때 --nv를 빠뜨리면 컨테이너 안에서 GPU 라이브러리를 찾지 못한다. 또한 데이터베이스, 모델 가중치, 입력, 출력 경로를 -B 또는 --bind로 컨테이너 내부에 연결해야 한다.

예를 들어 호스트의 /scratch/user/af3_db를 컨테이너 안의 /root/public_databases로 연결했다면, AlphaFold 명령의 --db_dir도 컨테이너 내부 경로인 /root/public_databases를 가리켜야 한다. 호스트 경로를 그대로 쓰면 컨테이너 안에서는 "없는 경로"가 된다.

FlashAttention 오류도 자주 나온다. AlphaFold 3 실행에서 implementation='triton' for FlashAttention is unsupported on this GPU generation 같은 메시지가 나오면, 해당 GPU 세대가 Triton 구현을 지원하지 않는다는 뜻일 수 있다. RCC 문서는 이런 경우 --flash_attention_implementation=xla로 전환하는 해결책을 제시한다.⁴

컨테이너 오류를 볼 때는 다음 질문을 차례로 던지면 된다.

• 컨테이너 안에서 nvidia-smi가 실행되는가?

• 입력 파일 경로가 컨테이너 내부에서 실제로 보이는가?

• 모델 가중치 경로가 컨테이너 내부에서 읽히는가?

• 데이터베이스 경로가 컨테이너 내부에서 읽히는가?

• 출력 디렉터리에 컨테이너 사용자가 쓸 권한이 있는가?

이 다섯 질문에 모두 "예"라고 답할 수 있으면 컨테이너 문제의 절반은 해결된 것이다.

데이터베이스 경로 오류: 파일은 있는데 AlphaFold가 못 찾는 이유

데이터베이스 오류는 실무에서 가장 흔하고, 가장 허무하다. 파일은 분명히 어딘가에 있는데 AlphaFold는 "없다"고 말한다. 이때는 대부분 경로, 권한, 압축 해제, bind mount 중 하나가 문제다.

AlphaFold 3의 full database는 다운로드 크기와 압축 해제 후 크기가 모두 크다. 공식 설치 문서는 데이터베이스 다운로드가 약 252GB, 압축 해제 후 약 630GB에 달할 수 있으며, 전체 설치에는 최대 1TB 수준의 디스크 공간이 필요할 수 있다고 안내한다.⁵ 공간이 부족하면 다운로드가 중간에 끝난 것처럼 보여도 실제로는 파일이 깨져 있거나 일부만 존재할 수 있다.

데이터베이스 경로를 점검할 때는 "상위 폴더가 존재한다"에서 멈추면 안 된다. 필요한 파일이 정확한 이름으로 존재하는지 확인해야 한다. AlphaFold 3에서는 UniRef90, MGnify, BFD small, UniProt, PDB seqres, mmCIF, RNA 관련 데이터베이스 등이 필요할 수 있다. 실행 옵션에 따라 모든 데이터베이스가 필요하지 않을 수도 있지만, full data pipeline을 켰다면 누락 파일이 바로 오류로 이어진다.

권한 문제도 조용히 숨어 있다. 공식 문서는 데이터베이스 디렉터리와 파일에 읽기·쓰기 권한이 충분하지 않으면 MSA 도구에서 불투명한 외부 오류가 날 수 있으며, 예를 들어 chmod 755 --recursive <DB_DIR> 같은 방식으로 권한을 점검하라고 안내한다.⁵

실무 점검은 다음 순서로 한다.

# 경로가 실제로 존재하는지
ls -lh /path/to/databases

# 주요 파일이 있는지
find /path/to/databases -maxdepth 2 -type f | head

# 권한 확인
ls -ld /path/to/databases
ls -lh /path/to/databases | head

# 컨테이너 내부에서 같은 경로가 보이는지
singularity exec --nv -B /path/to/databases:/db alphafold3.sif ls -lh /db

Failed to get mmCIF for <PDB_ID> 같은 오류는 template 또는 구조 데이터베이스 접근 문제일 수 있다. RCC 문서도 이 오류에서 데이터베이스 디렉터리가 접근 가능하고 필요한 파일을 포함하는지, 권한이 적절한지 확인하라고 안내한다.⁴ 이 메시지를 모델 추론 오류로 착각하면 안 된다. 대개는 추론 이전의 template 검색 또는 구조 파일 접근 문제다.

모델 가중치와 파라미터를 못 읽을 때

AlphaFold는 코드만으로 실행되지 않는다. 모델 가중치, 즉 학습된 신경망의 숫자 파일이 필요하다. AlphaFold 3는 공식 모델 파라미터 접근 절차와 사용 조건이 따로 있으며, 설치는 되었더라도 가중치 파일이 없거나 경로가 틀리면 추론이 실패한다.⁵

가중치 오류는 보통 다음처럼 나타난다.

• model parameters를 찾을 수 없다는 메시지가 나온다.

• model_dir 또는 params 경로가 없다고 나온다.

• 파일 권한 때문에 읽기 실패가 난다.

• 컨테이너 안에서는 경로가 다르게 보여 실패한다.

• 압축 파일 또는 분할 파일을 예상 형식과 다르게 배치했다.

해결의 핵심은 "내가 보는 경로"와 "AlphaFold 프로세스가 보는 경로"를 구분하는 것이다. 로컬 터미널에서는 /home/me/params가 보이더라도, Docker 컨테이너 안에서는 /root/models로 mount했을 수 있다. 그러면 명령에는 /root/models를 넣어야 한다.

모델 가중치 문제를 확인할 때는 다음을 기록한다.

# 호스트에서 확인
ls -lh /host/path/to/models

# Docker 내부에서 확인하는 예시
docker run --rm \
  --volume /host/path/to/models:/root/models \
  alphafold3 \
  ls -lh /root/models

가중치 파일은 민감한 라이선스 조건을 따를 수 있으므로, 로그를 공유하거나 이슈를 올릴 때 파일 자체를 첨부하면 안 된다. 대신 파일 이름, 크기, 경로 구조, 권한, 다운로드 출처가 공식 절차였는지를 기록한다.

입력 파일 오류: FASTA와 JSON은 생각보다 엄격하다

입력 오류는 초보자만의 문제가 아니다. 숙련자도 복합체 FASTA에서 체인 순서를 바꾸거나, JSON의 entity ID를 잘못 연결하거나, ligand 이름을 잘못 넣는다. AlphaFold는 생물학적 의도를 추측해 주지 않는다. 입력이 틀리면 틀린 세계를 매우 성실하게 예측한다.

FASTA에서 흔한 문제는 다음과 같다.

• 서열에 공백, 숫자, 특수문자, 알 수 없는 문자가 섞였다.

• chain header가 중복되거나 비어 있다.

• multimer에서 같은 사슬 복제 수를 잘못 표현했다.

• signal peptide, tag, linker, 절단 전 pro-peptide를 포함할지 결정하지 않았다.

• 너무 긴 무질서 꼬리까지 넣어 복합체 interface를 흐리게 만들었다.

JSON에서는 문법 오류와 생물학적 정의 오류가 함께 나온다. 쉼표 하나가 빠져도 JSON은 깨지고, entity ID가 맞지 않아도 검증에서 실패한다. AlphaFold 3 계열에서는 단백질, DNA, RNA, ligand, ion, modified residue를 각각 올바른 형식으로 넣어야 한다. 앞 장에서 본 것처럼 JSON은 단순한 입력 파일이 아니라 "예측할 분자 세계의 설계도"다.

입력 검증에서 중요한 습관은 최소 재현 입력을 만드는 것이다. 복잡한 JSON이 실패하면 ligand, ion, templates, custom MSA를 모두 뺀 단백질 단독 입력으로 먼저 실행한다. 단백질 단독은 성공하는데 ligand를 넣으면 실패한다면 ligand 정의가 문제일 가능성이 커진다. 단백질과 ligand는 성공하는데 금속 ion을 넣으면 실패한다면 ion 또는 결합 정의를 봐야 한다.

공식 AlphaFold 3 known issues에는 SMILES로 정의한 ligand에서 Cl, Br처럼 두 글자 원자를 잘못 처리한 특정 기간의 버그가 기록되어 있다.⁶ 이런 사례는 입력이 문법적으로 맞아도 버전별 알려진 문제가 결과에 영향을 줄 수 있음을 보여 준다. 따라서 ligand가 포함된 예측에서 이상한 pose나 충돌이 반복된다면 입력 형식뿐 아니라 사용한 AlphaFold 3 commit, 릴리스 노트, known issues도 확인해야 한다.

MSA와 template 검색이 느리거나 실패할 때

AlphaFold의 계산 시간은 GPU 추론만으로 결정되지 않는다. 많은 경우 가장 오래 걸리는 구간은 MSA 검색이다. 데이터베이스가 크고, 파일 I/O가 많고, 공유 스토리지가 느리면 작은 단백질도 예상보다 오래 걸린다.

MSA 검색 실패는 다음 원인에서 자주 생긴다.

• 데이터베이스 경로가 틀렸다.

• HMMER, HH-suite, jackhmmer 같은 외부 도구가 PATH에 없다.

• 데이터베이스 파일 권한이 없다.

• /tmp 또는 작업 디렉터리 공간이 부족하다.

• 공유 파일 시스템 I/O가 느리거나 순간적으로 끊긴다.

• 너무 많은 작업이 동시에 같은 데이터베이스를 읽는다.

이때 로그에서 jackhmmer, hhblits, hmmsearch, nhmmer, No space left on device, Permission denied 같은 단어를 찾는다. No space left on device는 꼭 전체 디스크가 꽉 찼다는 뜻만은 아니다. 임시 디렉터리 /tmp가 작아서 실패할 수도 있다. HPC에서는 $TMPDIR, $SCRATCH, 로컬 SSD를 명시적으로 쓰는 것이 좋다.

MSA 검색을 안정화하려면 같은 입력으로 매번 처음부터 다시 검색하지 않도록 캐시 또는 중간 결과를 보존한다. 대규모 작업에서는 MSA/template 검색을 CPU 작업으로 먼저 수행하고, GPU 추론 작업은 그 결과를 받아 실행하도록 나누는 것이 비용과 실패율을 줄인다. AlphaFold 3 공식 known issues 문서는 AlphaFold Server와 로컬 AlphaFold 3 사이에서 genetic search 방식 차이로 MSA 깊이가 달라질 수 있으며, 특정 입력에서는 더 깊은 MSA가 pTM과 ipTM을 높일 수 있다고 설명한다.⁶ 즉, MSA는 단순한 부속품이 아니라 결과 품질을 좌우하는 입력 정보다.

MSA가 너무 얕으면 모델은 진화적 단서를 충분히 얻지 못한다. 반대로 MSA가 지나치게 크면 메모리와 시간이 폭발한다. 어려운 단백질에서는 MSA를 더 풍부하게 만드는 전략이 필요하지만, 실행 안정성 문제가 먼저라면 MSA depth를 제한해 작은 테스트부터 통과시키는 것이 순서다.

GPU out-of-memory와 resource exhaustion

out of memory, RESOURCE_EXHAUSTED, CUDA_ERROR_OUT_OF_MEMORY는 AlphaFold 사용자라면 언젠가 만나는 문구다. 이것은 모델이 "모른다"고 말하는 것이 아니라, 주어진 입력과 설정을 현재 GPU 메모리에 올릴 수 없다는 뜻이다.

메모리를 키우는 주범은 대체로 정해져 있다. 서열이 길수록, MSA가 깊을수록, multimer 체인 수가 많을수록, sample·seed·recycle 수가 많을수록 메모리 사용량이 커진다. 특히 복합체는 단순히 각 사슬 길이를 더한 것보다 더 부담스러울 수 있다. 사슬 사이 관계를 계산해야 하기 때문이다.

해결은 작은 것부터 시도한다. 처음부터 "더 큰 GPU를 빌리자"로 가면 비용이 커진다. 먼저 입력과 옵션을 줄여 원인을 확인한다.

1. 불필요한 체인을 제거한다. 실제 interface에 필요 없는 항체 tag, 정제 tag, 긴 linker, 낮은 복잡도 tail을 뺀 테스트를 만든다.

2. 도메인 단위로 나눈다. 전체 단백질 대신 기능 도메인, 결합 도메인, 절단 후 성숙형 서열을 따로 예측한다.

3. MSA depth를 제한한다. 탐색 단계에서는 너무 깊은 MSA를 피하고, 성공한 뒤 필요하면 다시 늘린다.

4. seed와 sample 수를 줄인다. 다양한 샘플링은 최종 비교에 중요하지만, 환경 검증 단계에서는 1개로 충분하다.

5. recycle 또는 diffusion step을 줄인다. 탐색 실행에서는 낮게 두고, 최종 후보에서만 높인다.

6. 더 큰 GPU나 unified memory 환경을 쓴다. 입력 자체가 큰 경우에는 A100/H100 80GB급 GPU나 충분한 unified memory가 필요할 수 있다.

7. 작업을 분할한다. 여러 입력을 한 번에 돌리지 말고 개별 작업으로 나누어 실패 범위를 좁힌다.

AlphaFold 3 공식 문서가 A100 80GB와 H100 80GB에서 최대 5,120 tokens 입력을 검증했다고 설명하는 것은 중요한 기준점이다.⁵ 내가 가진 GPU가 16GB 또는 24GB라면 같은 규모를 기대하면 안 된다. Colab의 T4나 L4, 로컬 RTX 3090/4090, HPC의 V100/A100/H100은 모두 메모리와 지원 기능이 다르다.

메모리 오류를 줄이는 가장 현실적인 기술은 "탐색 실행"과 "최종 실행"을 분리하는 것이다. 탐색 실행에서는 작은 설정으로 모델이 돌아가는지, 결과가 대략 말이 되는지 본다. 최종 실행에서만 seed 반복, sample 증가, recycle 증가, 더 풍부한 MSA를 적용한다.

작업 시간 초과: 느린 것과 멈춘 것은 다르다

HPC 로그를 보면 몇 시간 동안 아무 메시지도 없는 경우가 있다. 이때 작업이 멈춘 것인지, 조용히 계산 중인지 구분해야 한다. MSA 검색이나 모델 컴파일 단계는 긴 시간 동안 출력이 거의 없을 수 있다. 반대로 파일 시스템 오류로 외부 도구가 멈춰 있는 경우도 있다.

시간 초과가 반복되면 먼저 작은 입력으로 같은 설정을 실행한다. 작은 입력은 빠르게 끝나는데 큰 입력만 시간 초과된다면 자원 부족 또는 입력 규모 문제다. 작은 입력도 같은 지점에서 멈춘다면 환경 또는 데이터베이스 문제다.

긴 multimer 작업에서는 다음 전략이 유용하다.

• MSA/template 검색을 선행 작업으로 분리한다.

• GPU 추론은 MSA 결과가 준비된 뒤 별도 작업으로 실행한다.

• walltime을 넉넉히 잡되, 무작정 최대로 잡기보다 단계별 로그를 남긴다.

• 같은 입력으로 seed 20개를 한 작업에 넣지 말고 seed별 작업 배열로 나눈다.

• 중간 결과와 출력 디렉터리를 덮어쓰지 않게 job ID를 붙인다.

HPC 스케줄러에서는 긴 작업 하나보다 적절히 나눈 작업 여러 개가 관리하기 쉽다. 실패했을 때도 전체가 아니라 실패한 조각만 다시 실행하면 된다.

결과는 나왔지만 pLDDT가 낮을 때

구조 파일이 생성되었다고 항상 성공은 아니다. 전체 pLDDT가 낮거나, 도메인 배치가 흔들리거나, 복합체 ipTM이 낮으면 해석에 조심해야 한다. 하지만 낮은 점수를 곧바로 "실패"라고 부르면 안 된다. AlphaFold가 낮은 신뢰도를 보이는 데에는 생물학적 이유도 많다.

무질서 영역은 실제로 고정된 구조가 없을 수 있다. 유연한 linker는 한 가지 자세로 고정되지 않는다. 복합체는 특정 ligand, DNA, RNA, 금속 ion, 막 환경, 인산화 같은 변형이 있어야 안정해질 수 있다. 이런 요소가 입력에서 빠지면 모델은 당연히 불안정한 구조를 낼 수 있다.

그래도 먼저 입력 실수를 확인해야 한다. 낮은 pLDDT나 낮은 ipTM이 보이면 다음을 점검한다.

• FASTA 서열이 정확한 isoform인지 확인한다.

• signal peptide, transmembrane region, tag, linker 포함 여부를 확인한다.

• multimer에서 체인 구분과 복제 수가 맞는지 확인한다.

• 필요한 ligand, ion, nucleic acid, modified residue가 빠지지 않았는지 확인한다.

• template이나 custom MSA가 오히려 잘못된 정보를 주지 않았는지 확인한다.

• 여러 seed에서 같은 접힘 또는 interface가 반복되는지 확인한다.

특히 복합체에서는 높은 pLDDT만 보고 믿으면 안 된다. 각 체인은 예쁘게 접혔지만 서로의 배치는 엉터리일 수 있다. 이때는 ipTM, 사슬 간 PAE, interface 잔기의 생물학적 타당성, seed 반복성을 함께 본다. 앞 장들에서 강조했듯이 pLDDT는 국소 구조의 신뢰도이고, 복합체 배치의 신뢰도는 별개의 문제다.

잔기 충돌과 ranking score 급락

결과 구조에서 원자나 잔기가 비정상적으로 겹치는 residue clash가 많다면 두 가지 가능성을 생각해야 한다. 하나는 입력 또는 생물학적 조건이 잘못되어 모델이 무리한 구조를 만들었다는 것이다. 다른 하나는 버전 또는 하드웨어 관련 알려진 문제다.

AlphaFold 3 공식 known issues에 기록된 CUDA Capability 7.x GPU 문제는 바로 이런 경우와 연결된다. V100 같은 7.x GPU에서 특정 XLA_FLAGS 설정 없이 실행하면 충돌이 많은 명백히 나쁜 출력과 -99 이하의 ranking score가 나올 수 있다고 알려져 있다.⁶ 따라서 V100에서 AlphaFold 3 결과가 이상하게 나쁘다면 "내 단백질이 이상한가?"라고 고민하기 전에 공식 known issues와 실행 환경을 먼저 확인해야 한다.

잔기 충돌이 있을 때는 다음 순서로 본다. 먼저 같은 입력을 권장 GPU 또는 다른 환경에서 작은 설정으로 다시 실행한다. 그다음 seed를 바꾸어 반복한다. 모든 seed에서 같은 부위가 충돌한다면 입력의 ligand, ion, modified residue, template 문제가 있을 수 있다. 특정 GPU나 특정 버전에서만 충돌한다면 환경 또는 known issue 가능성이 커진다.

구조 후처리 도구로 clash를 완화할 수는 있지만, 그것이 예측의 근본 문제를 해결하지는 않는다. 심한 clash가 있는 모델을 에너지 최소화로 살짝 다듬어 논문 그림에 쓰는 것은 위험하다. 먼저 왜 그런 구조가 나왔는지 확인해야 한다.

AlphaFold Server와 로컬 결과가 다를 때

같은 입력을 AlphaFold Server와 로컬 AlphaFold 3에서 돌렸는데 결과가 다를 수 있다. 이때 "둘 중 하나가 틀렸다"고 단정하기보다 MSA와 실행 설정 차이를 봐야 한다.

공식 known issues 문서는 AlphaFold Server와 공개된 로컬 AlphaFold 3가 같은 모델 가중치와 동등한 모델 코드를 사용하지만, genetic search 방식이 다르며 일부 경우 서버에서 더 깊은 MSA가 만들어질 수 있다고 설명한다. 특정 입력에서는 이 차이 때문에 서버 결과의 pTM과 ipTM이 더 높아질 수 있다.⁶

따라서 서버와 로컬 결과가 다르면 다음을 맞춰 본다.

• 입력 서열과 ligand 정의가 완전히 같은가?

• template 사용 여부와 날짜 제한이 같은가?

• MSA가 같은 깊이와 구성으로 만들어졌는가?

• seed와 sample 수가 같은가?

• 로컬 버전, commit, known issues가 무엇인가?

• GPU 세대와 XLA 설정이 권장 조건에 맞는가?

서버 결과를 "정답"으로, 로컬 결과를 "오답"으로 단순히 나누면 안 된다. 두 결과가 왜 달라졌는지 추적하는 과정에서 오히려 단백질의 유연성, MSA 의존성, interface의 불확실성을 더 잘 이해할 수 있다.

오류 메시지별 빠른 진단표

아래 표는 자주 만나는 증상과 첫 진단 방향을 정리한 것이다. 표만 보고 기계적으로 해결하기보다는, 앞에서 설명한 파이프라인 구간과 함께 읽어야 한다.

이 표에서 가장 중요한 행은 사실 첫 번째와 두 번째다. GPU와 CUDA 문제가 해결되지 않은 상태에서는 나머지 모든 조치가 흔들린다. 반대로 GPU가 정상이고 작은 예제가 성공한다면, 이후 문제는 입력 크기나 데이터 접근 문제로 좁혀진다.

재실행 전략: 실패를 자산으로 남기기

문제 해결의 목표는 "이번 한 번 성공"이 아니다. 다음 실패를 더 빨리 해결할 수 있는 기록을 남기는 것이다. AlphaFold 실행은 입력, 데이터베이스, 코드 버전, 모델 파라미터, GPU, seed, 옵션이 모두 결과에 영향을 준다. 하나라도 빠지면 나중에 같은 결과를 재현하기 어렵다.

실행할 때마다 최소한 다음 정보를 저장하자.

• 실행 날짜와 작업 ID

• 전체 실행 명령

• 입력 FASTA 또는 JSON의 사본

• AlphaFold 버전, commit, 컨테이너 이미지 태그

• 모델 가중치 또는 파라미터 버전과 경로

• 데이터베이스 버전과 경로

• GPU 모델, 드라이버, CUDA 버전

• seed, sample 수, recycle 또는 diffusion step

• 표준 출력과 표준 오류 로그

• 최종 구조 파일과 confidence JSON, ranking 파일

이 정보는 문제 해결뿐 아니라 논문, 보고서, 내부 재현성에도 중요하다. 대규모 워크플로에서는 입력과 출력이 파일 시스템 여기저기에 흩어지기 쉽다. 실패한 작업도 지우지 말고, 최소한 로그와 입력은 남겨 두는 편이 좋다. 같은 오류가 반복될 때 과거 로그는 검색 가능한 실험 노트가 된다.

재실행은 무작정 같은 명령을 다시 누르는 일이 아니다. 다음 순서로 진행한다.

1. 입력 검증: FASTA/JSON, 체인, ligand, ion, modified residue를 확인한다.

2. 데이터베이스와 가중치 접근 확인: db_dir, model_dir, bind mount, 권한을 확인한다.

3. GPU와 컨테이너 환경 확인: 호스트와 컨테이너 안에서 nvidia-smi를 확인한다.

4. 작은 smoke test 실행: 짧은 단일 체인, 적은 sample, 낮은 step으로 검증한다.

5. 원래 작업을 축소 실행: 긴 입력을 도메인 또는 일부 체인으로 줄여 실행한다.

6. 전체 작업 재실행: 원인이 해결된 뒤 최종 설정으로 실행한다.

이 순서를 따르면 실패한 작업도 점점 작아진다. 처음에는 "AlphaFold가 안 된다"였던 문제가 "컨테이너 안에서 /root/public_databases/mmcif_files가 보이지 않는다"처럼 손에 잡히는 문제로 바뀐다.

최종 체크리스트: 전체 작업을 다시 돌리기 전

큰 작업을 다시 제출하기 전에 아래 체크리스트를 한 번만 훑어도 많은 시간을 아낄 수 있다.

입력은 올바른가? FASTA라면 서열 문자와 체인 header를 확인한다. JSON이라면 문법, entity ID, ligand, ion, modified residue 정의를 확인한다. 같은 단백질이라도 isoform, 절단형, 성숙형, tag 포함 여부가 결과를 바꾼다.

데이터베이스는 완전한가? 필요한 파일이 정확한 이름으로 있고, 압축이 풀렸거나 실행 방식이 기대하는 형식으로 준비되었는지 확인한다. 컨테이너를 쓴다면 호스트 경로가 아니라 컨테이너 내부 경로에서 ls로 확인한다.

모델 가중치는 읽히는가? model_dir가 맞는지, 파일 권한이 있는지, 컨테이너 안에서도 보이는지 확인한다. AlphaFold 3 파라미터는 공식 접근 절차와 사용 조건을 따른다.

GPU 환경은 정상인가? 호스트와 컨테이너 안에서 nvidia-smi를 실행한다. CUDA, JAX/XLA, 드라이버 호환성을 확인한다. V100 등 CUDA Capability 7.x GPU에서는 AlphaFold 3 known issue와 권장 XLA_FLAGS를 확인한다.⁶

자원 설정은 입력 크기에 맞는가? 긴 서열, 큰 multimer, 많은 seed와 sample, 깊은 MSA는 GPU 메모리와 시간을 크게 늘린다. 탐색 실행과 최종 실행을 분리한다.

로그는 남는가? 실패했을 때 같은 상황을 재현할 수 있도록 실행 명령, 버전, GPU 정보, 입력 파일, 오류 메시지를 함께 저장한다. 로그 없는 실패는 기억에만 남고, 기억은 다음 주가 되면 거의 쓸모없어진다.

AlphaFold 문제 해결은 탐정 일과 비슷하다. 범인은 대개 마지막 줄에 있지 않다. 입력 파일의 작은 오타, 컨테이너 바깥에만 존재하는 데이터베이스, GPU를 받지 못한 HPC 작업, 너무 큰 MSA, 알려진 CUDA 이슈가 서로 비슷한 얼굴로 나타난다. 그래서 순서가 중요하다. 입력을 확인하고, 데이터와 가중치를 확인하고, GPU와 컨테이너를 확인하고, 작은 테스트를 통과시킨 뒤, 전체 작업으로 돌아간다.

이 원칙을 익히면 AlphaFold는 더 이상 "한 번 돌려 보고 운에 맡기는 도구"가 아니다. 실패해도 원인을 좁힐 수 있고, 성공하면 그 성공을 다시 재현할 수 있는 연구 도구가 된다. 마지막 장에서는 바로 이 지점에서 한 걸음 더 나아가, 책임 있는 사용과 재현 가능한 보고서 작성법을 정리한다.

참고

¹Troubleshooting - AlphaFold 3 for Mac

²AlphaFold 3 Installation and Running Your First Prediction

³Troubleshooting – E-Learning@VIB

⁴Alphafold - RCC User Guide

⁵AlphaFold 3 Installation Guide

⁶AlphaFold 3 Known Issues