DiffDock Batch 사용법

내려받기 — DiffDock Batch (Windows·macOS·Linux)

DiffDock으로 도킹을 돌려 보신 적 있으신가요?
NVIDIA의 build.nvidia.com에서 무료로 써 볼 수 있지만, 웹 화면에서는 단백질 하나에 리간드 하나씩입니다.
후보 리간드가 수십 개, 단백질이 몇 개만 되어도 파일을 올리고 결과를 받아 저장하는 일을 수백 번 되풀이해야 하죠.

API를 직접 부르면 되지만, 그러려면 스크립트를 짜야 합니다.
분당 요청 한도에 걸리면 기다렸다 다시 보내야 하고, 결과 JSON에서 포즈와 confidence를 꺼내 정리하는 일도 남습니다.

DiffDock Batch는 그 일을 대신합니다.
파일을 한꺼번에 골라 넣고 [실행] 을 누르면, 단백질 × 리간드 조합을 차례로 API에 보내고 결과를 폴더에 쌓습니다.
한도에 맞춰 속도를 조절하고, 끝난 뒤에는 모든 결과를 CSV 하나로 묶어 줍니다.

내려받기와 실행

내려받기 페이지에서 zip을 받아 압축을 풀고, 운영체제에 맞는 파일을 실행하세요.

• Python 3.9 이상이 있어야 합니다. 없으면 Python 설치 페이지를 열어 줍니다.
  Windows에서 설치할 때는 “Add python.exe to PATH"를 꼭 체크하세요.
• 처음 한 번만 실행 환경(가상환경과 requests, keyring 패키지)을 준비합니다. 1~2분 걸릴 수 있어요.
• NVIDIA API 키가 필요합니다. build.nvidia.com에 가입하면 무료 체험 키를 받을 수 있습니다.

macOS에서는 처음에 “확인되지 않은 개발자” 경고가 뜰 수 있습니다.
파일을 Control+클릭 → 열기 → 열기 를 누르면 됩니다.
그래도 안 되면 터미널에서 chmod +x DiffDock_Mac.command 를 실행하세요.

실행하면 검은 창(실행 창)과 브라우저가 함께 열립니다.
화면은 브라우저에 뜨지만, 프로그램 자체는 이 컴퓨터에서 돌아갑니다.
끝낼 때는 실행 창을 닫으세요. 작업 중에 닫으면 작업도 멈춥니다.

사용법

기본 순서

1. API 키 입력 — 한 번 저장해 두면 다음부터는 건너뜁니다.
2. 파일 추가 — [파일 선택…] 으로 .pdb / .sdf / .mol2 파일을 여러 개 고르거나, 점선 영역에 끌어다 놓습니다.
3. 결과 저장 폴더 — 비워 두면 문서/DiffDock_results에 저장합니다.
4. 옵션 확인 — 기본값 그대로 써도 됩니다.
5. [파일 확인] — 실제 작업 수, 예상 저장 용량, 최소 소요 시간을 먼저 봅니다.
6. [실행] — 시작합니다. 멈추려면 [중지] 를 누릅니다.

5번을 따로 둔 데는 이유가 있습니다.
단백질 10개에 리간드 100개면 작업이 1,000건이고, 무료 API로는 하루가 넘게 걸릴 수 있거든요.
돌리기 전에 규모부터 확인하도록 나눠 두었습니다.

파일 넣기

확장자로 단백질과 리간드를 알아서 나눕니다. .pdb는 단백질, .sdf와 .mol2는 리간드입니다.

• 같은 이름의 파일을 다시 넣으면 새 파일로 바뀝니다.
• 여러 분자가 든 SDF/MOL2는 분자마다 리간드 하나로 나눕니다.
  이름은 원본파일명_분자이름이고, 분자 이름이 없거나 겹치면 번호를 붙입니다.
  화합물 라이브러리를 SDF 한 파일로 받는 일이 흔해서 넣은 기능입니다.
• 파일 하나는 50MB까지, 파일 하나에 든 분자는 10만 개까지입니다.
• 고른 파일은 프로그램을 끄면 목록에서 사라집니다. 원본 파일은 그대로 있어요.

조합 방식

단백질마다 정해진 리간드가 따로 있다면 앞부분 일치를 쓰세요.
리간드 파일 이름을 단백질이름_리간드이름으로 맞춰 두기만 하면 됩니다.
대소문자는 가리지 않습니다.

DiffDock 옵션

DiffDock 쪽 기본값을 그대로 두었습니다. 특별한 이유가 없으면 바꾸지 않아도 됩니다.
steps가 time_divisions보다 크면 실행하지 않고 오류를 냅니다.

그 밖의 체크 항목입니다.

• trajectory 저장 (기본 꺼짐) — 포즈가 만들어지는 과정을 trajectory_rank01.pdb 처럼 따로 저장합니다. 용량이 커서 꺼 두었습니다.
• 단백질 ATOM 줄만 사용 (기본 켜짐) — PDB에서 ATOM으로 시작하는 줄만 보냅니다. 물 분자나 기존 리간드(HETATM)가 섞여 들어가 결과를 흐리지 않게 하려는 것입니다.
• 결과 있으면 건너뛰기 (기본 켜짐) — 같은 옵션의 결과가 이미 있으면 다시 보내지 않습니다. 중간에 멈췄다가 이어 할 때 꼭 필요합니다.
• 큰 파일은 에셋 업로드 (기본 꺼짐) — 파일을 먼저 NVIDIA 저장소에 올리고 참조만 보냅니다. 꺼 두어도 서버가 “파일이 너무 크다”(413)고 답하면 자동으로 이 방식으로 다시 보냅니다.
• JSON에는 position_confidence만 저장 (기본 켜짐) — 끄면 API 응답 전체를 JSON에 저장합니다. 포즈 구조는 SDF로 따로 저장되니 대개 켜 두는 편이 낫습니다.

포즈 구조 저장

조합 하나에 포즈 10개면 파일이 13개 생깁니다. 1만 건이면 13만 개죠.
대량 작업이라면 합친 파일만이나 저장 안 함으로 바꾸세요. 파일 수와 용량이 크게 줄어듭니다.
confidence 값은 어느 쪽이든 통합 CSV에 남습니다.

진행 상황과 중지

실행하면 아래쪽에 로그와 결과 표가 흐르고, 상태 줄에 남은 예상 시간이 뜹니다.
최근 50건의 평균 처리 시간으로 계산합니다.

[중지] 를 누르면 그 자리에서 멈춥니다. 이미 받은 결과는 그대로 남아요.
그때 계산을 기다리던 1건은 결과 없이 끝나고, 다음 실행에서 다시 보냅니다.
다시 [실행] 을 누르면 끝난 것은 건너뛰고 남은 것부터 이어서 합니다.

작업 중에는 컴퓨터가 절전 모드로 들어가지 않게 막습니다 (Windows·macOS).
밤새 돌려 두었는데 잠들어 멈춰 있으면 곤란하니까요.

알아두기

2D 리간드는 결과가 나오지 않습니다

DiffDock은 리간드의 3D 좌표가 필요합니다.
ChemDraw에서 저장한 파일이나 PubChem의 2D SDF처럼 z 좌표가 모두 0인 파일은 API가 응답은 해도 결과가 비어 있습니다.

그래서 파일을 넣을 때 좌표를 검사해, 2D 구조면 목록에 [2D] 로 표시합니다.
실행할 때는 API를 부르지 않고 건너뛰며, summary.csv에 skipped_2d로 남깁니다.
어차피 빈 결과가 올 요청으로 한도를 깎아 먹을 이유가 없거든요.

3D로 바꾸는 방법은 이렇습니다. 하나 골라 쓰세요.

• PubChem — 화합물 페이지 → Download → 3D Conformer → SDF
• RCSB 리간드 — ..._ideal.sdf (이상 좌표, 3D)
• Open Babel — obabel 입력.sdf -O 출력_3d.sdf --gen3d
• RDKit — AllChem.EmbedMolecule(Chem.AddHs(mol)) 후 저장

3D 파일인데도 결과가 비면 로그에 “결과가 비어 있습니다"로 나옵니다.
금속 착물이나 아주 큰 분자처럼 DiffDock이 처리하지 못하는 분자일 수 있습니다.

API 호출 한도

NVIDIA 무료 체험은 크레딧이 아니라 분당 요청 수로 제한됩니다.
흔히 분당 40회로 알려져 있지만 모델과 시간대에 따라 다를 수 있으니, build.nvidia.com 계정 화면에서 본인 한도를 확인하세요.

분당 최대 API 요청의 기본값을 30으로 둔 것은 40보다 여유를 두려는 것입니다.
이 숫자에는 도킹 요청뿐 아니라 계산이 끝났는지 묻는 상태 확인 요청과 에셋 업로드까지 들어갑니다.
그래서 상태 확인은 10초 간격으로만 합니다.

그래도 한도 초과(429)가 나면 서버가 알려 준 시간만큼 기다렸다가 다시 보냅니다.
서버가 시간을 알려 주지 않으면 30초, 60초, 90초… 로 늘려 가며 기다립니다. 최대 5분입니다.

멈추는 경우

아래 상황에서는 더 돌려 봐야 소용없으므로 그 자리에서 멈춥니다.

• 인증 오류(401·403) — API 키가 틀렸거나 만료되었습니다.
• 연속 10건 실패 — 인터넷이나 NVIDIA 서비스에 문제가 있는 경우입니다.
  2D 리간드나 빈 결과처럼 파일 쪽 문제는 이 숫자에 세지 않습니다.
• 저장 공간 부족 — 시작할 때 남은 공간이 2GB보다 적으면 미리 경고합니다.

어느 경우든 원인을 고친 뒤 다시 [실행] 하면 남은 것부터 이어서 합니다.
네트워크 오류는 바로 실패로 치지 않고, 30초부터 두 배씩 늘려 가며 다섯 번까지 다시 시도합니다.

결과 폴더 구조

결과 저장 폴더/
├── summary.csv                 전체 작업 요약 (엑셀에서 바로 열림)
├── run_log.txt                 전체 실행 기록
├── confidence_summary.csv      통합 결과
├── results_index.jsonl         통합 CSV를 만드는 기록 (지우지 마세요)
└── 8G43/                       단백질별 폴더
    └── 8G43-ZU6_ideal-poses10_td20_st18/
        ├── 8G43-ZU6_ideal-poses10_td20_st18.json
        ├── rank01.sdf …
        ├── all_poses.sdf
        └── confidence.csv

폴더 이름 끝의 poses10_td20_st18은 옵션 표기입니다. trajectory를 저장하면 _traj가 붙습니다.
옵션을 바꿔 다시 돌리면 다른 이름으로 저장되므로, 이전 결과를 덮어쓰지 않습니다.
같은 조합을 옵션만 바꿔 비교해 보는 일이 잦아서 이렇게 했습니다.

confidence_summary.csv는 한 행이 도킹 1건입니다.
단백질, 리간드, 옵션 다음에 confidence_rank01부터 포즈 수만큼 값이 이어집니다.
엑셀에서 열어 정렬하면 어느 조합이 잘 붙는지 한눈에 볼 수 있습니다.

대량 실행

수천 개 파일, 수십만 건 작업도 다루도록 만들었습니다.

• 고른 파일은 메모리가 아니라 임시 폴더(~/.diffdock_batch/staging)에 두고, 끄면 지웁니다.
• 화면의 결과 표는 최근 300건만 보여 줍니다. 전체는 CSV와 run_log.txt에 있습니다.

하지만 걸리는 시간은 NVIDIA 무료 API가 정합니다. 한 건씩 차례로 보내므로
총 시간 ≈ 작업 수 × 한 건당 시간입니다. 30초/건이면 1만 건에 약 3.5일이죠.

단백질 3,000개 × 리간드 500개 = 150만 건은 무료 API로는 현실적이지 않습니다.
30초/건이면 약 1.4년, 분당 40회를 꽉 채워도 최소 26일입니다.
이 규모라면 DiffDock을 연구실 GPU에 직접 설치해 돌리는 것을 권합니다.

API 키 보안

• 키는 이 컴퓨터의 프로그램 안에만 있고, 브라우저 화면에는 끝 4자리만 보입니다.
• 이 PC에 안전하게 저장을 켜면 Windows 자격 증명 관리자나 macOS 키체인에 저장합니다.
  키체인을 쓸 수 없는 환경에서만 ~/.diffdock_batch/api_key 파일에 본인만 읽을 수 있는 권한으로 저장합니다.
• 저장을 끄고 새 키를 넣으면 예전에 저장된 키는 지웁니다. [저장된 키 삭제] 로 언제든 지울 수 있어요.
• 키는 NVIDIA API(HTTPS)로만 보내고, 로그와 summary.csv에는 가려서 남깁니다.
• 프로그램 화면은 이 컴퓨터(127.0.0.1)에서만 열 수 있고, 실행할 때마다 접속 주소가 새로 만들어집니다.

키가 노출되었다면 build.nvidia.com에서 즉시 폐기하세요.

설정은 어디에 남나

~/.diffdock_batch/ 폴더입니다. Windows라면 C:\Users\사용자\.diffdock_batch\ 입니다.
마지막에 쓴 옵션과 저장 폴더, 실행 환경(가상환경)이 여기 있습니다.

이 폴더를 지우면 설정과 실행 환경이 처음 상태로 돌아갑니다.
키체인에 저장한 키는 이 폴더에 없으니 [저장된 키 삭제] 로 지우세요.

함께 쓰면 좋은 것

• 실험 사진과 동영상이 쌓인 폴더를 날짜별로 정리하려면 File Organizer를 보세요.

내려받기 — DiffDock Batch (Windows·macOS·Linux)