본문으로 건너뛰기

사전 요구사항

KeyNet을 사용하기 전에 필요한 시스템 요구사항과 소프트웨어를 안내합니다.

권장 환경
  • OS: Ubuntu 22.04 LTS
  • Python: 3.12
  • Docker: 20.10.0 이상

Python​

Python 3.12를 권장합니다 (3.9 이상 지원):

# Python 버전 확인
python --version
# Python 3.12.x

Git​

# Git 버전 확인
git --version

Docker 설치​

Docker는 application을 container로 패키징하여 실행하는 도구입니다. Container는 코드와 모든 의존성을 포함하는 격리된 실행 환경입니다.

# Docker 공식 GPG key 추가
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Repository 추가
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker 설치 (Docker Compose plugin 포함)
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Docker 권한 설정 (Linux)​

Linux에서 매번 sudo를 입력하지 않으려면 현재 사용자를 docker 그룹에 추가합니다:

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 로그아웃 후 재로그인하여 적용
# 또는 다음 명령어로 즉시 적용
newgrp docker

# 확인 (sudo 없이 실행)
docker ps

Docker Compose​

Docker Compose는 여러 container를 함께 실행하고 관리하는 도구입니다.

Ubuntu에서 Docker를 위 방법으로 설치했다면 Docker Compose plugin이 이미 포함되어 있습니다.

설치 확인:

docker compose version
# Docker Compose version v2.x.x
팁

docker-compose (V1, 하이픈)이 아닌 docker compose (V2, 공백) 명령어를 사용합니다.

GPU 지원 설정​

Docker container에서 GPU를 사용하려면 NVIDIA Container Toolkit이 필요합니다.

PyTorch 버전 제약

keynet-train 은 PyTorch 2.8.0 이하만 지원합니다.

  • 의존하는 onnxruntime 버전이 ONNX IR version 9까지만 지원
  • GPU 학습 시 PyTorch 버전 선택 제한
  • Docker로 첫 학습 실행 참고
NVIDIA Container Toolkit
  • nvidia-docker, nvidia-docker2는 deprecated되었습니다 (Docker 19.03 이후)
  • NVIDIA Container Toolkit이 현재 권장되는 방법입니다
  • Docker와 별도로 설치해야 합니다 (Docker를 대체하는 것이 아님)

NVIDIA GPU Driver 확인​

NVIDIA GPU driver가 설치되어 있어야 합니다:

# Driver 설치 확인
nvidia-smi

정상적으로 GPU 정보가 출력되면 driver가 설치된 것입니다.

NVIDIA Container Toolkit 설치​

1. Repository 설정:

# GPG key 및 repository 추가
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Package 목록 업데이트
sudo apt-get update

2. NVIDIA Container Toolkit 설치:

# Toolkit 설치
sudo apt-get install -y nvidia-container-toolkit

3. Docker 설정:

# Docker runtime 설정
sudo nvidia-ctk runtime configure --runtime=docker

# Docker 재시작
sudo systemctl restart docker

설치 확인​

GPU 접근이 정상적으로 작동하는지 테스트합니다:

# GPU 접근 테스트
sudo docker run --rm --gpus all ubuntu nvidia-smi

정상적으로 GPU 정보가 출력되면 설정이 완료된 것입니다.

Docker에서 GPU 사용​

Container 내부에서 GPU를 사용하려면 --gpus 플래그를 사용합니다:

# 모든 GPU 사용
docker run --gpus all <이미지>

# 특정 GPU 사용
docker run --gpus '"device=0,1"' <이미지>
Docker Compose에서 GPU 사용

Docker Compose에서 GPU를 사용하려면 deploy 섹션에 GPU 설정을 추가합니다:

services:
  your-service:
    image: your-image
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

다음 단계​

모든 준비가 완료되었다면:

  1. uv 설치 (권장) - 빠른 Python package manager
  2. 로컬 실험 환경 - MLflow 개발환경 설정