(폐쇄망 LLM 7-2) Docker 환경 구축

이전 글: 하드웨어/소프트웨어 설계

이 글은 망분리 환경 AI 배포 시리즈의 여덟 번째 글입니다.

다음 글: vLLM 서버 구축

왜 Docker인가?

모든 프로덕션 환경 관리는 고통스럽지만 망분리 환경에서 LLM 모델을 서비스 해야 하는 저희는 더더욱 곤란한 입장에 처해 있습니다. 방대할 뿐만 아니라 수많은 패키지 의존성에 묶여있는 라이브러리 하나를 꾸준히 그리고 아주 빈번하게 업데이트를 해야 합니다. 바로

vLLM

입니다.

왜 이런 시련이 발생하는 걸까요…?

2025-12-20에 있었던 vllm pull request를 보실까요:

GLM-4.7 을 지원하기 위한 tool call parser 추가

위 내용은 GLM-4.7 모델 출시 전 vLLM이 GLM-4.7을 지원하기 위해 tool call parser를 추가한 내용입니다. Tool call parser가 없으면 모델을 vLLM으로 돌려도 agentic coding 시 파일 찾기, 문자열 찾기 등이 불가능합니다. Pull request 30876을 올린 zRzRzRzRzRzRzRzR은 GLM 모델을 만드는 Z.ai 직원입니다. 보통은 그렇지 않습니다만, Z.ai 직원이 올린 저 pull request는 굉장히 빠르게 vLLM에 merge(적용)되었고, 며칠 뒤 HuggingFace에 GLM-4.7 모델이 출시되었습니다.

위 흐름에서 볼 수 있듯이 vLLM은 단순히 모델 서빙뿐 아니라 tool call parser, chat template 등 다양한 기능을 제공합니다. 새로운 모델이 출시되면 대부분 해당 모델을 출시한 곳에서 vLLM에 지원을 추가합니다. 그리고

우리도 그 버전을 업데이트 해야 그 최신 모델을 사용할 수 있습니다

그런데 문제는 vLLM에 tool call parser만 있는 게 아닙니다. 하드웨어별 지원도 있고, CUDA 버전에 따라 지원도 달라집니다. 그래서 vLLM 버전에 따라 CUDA toolkit 버전도 다릅니다. 깔다 보면 다른 패키지 버전도 바꿔줘야 하고, NCCL이라고 또 있습니다… 버전 잘못 깔면 GPU 간 통신도 안 되고 여러모로 골치가 아픕니다.

이걸 수동으로 관리하면 정신 건강에 해롭습니다. 인터넷망에서 다운받아 옮겼다가 안 되는 거 확인하고, 클로드에 물어봐서 확인하고, 다시 받아서 또 옮기고… 한번 잘 돌아가는 환경을 만들어도 vLLM 업데이트하면 CUDA 버전이 안 맞고, CUDA 올리면 드라이버가 안 맞고… 끝이 없습니다. Docker를 쓰면 이런 문제가 사라집니다. vLLM 공식 이미지에는 호환되는 CUDA, NCCL, cuDNN이 전부 들어있거든요. 그냥 이미지만 받으면 됩니다.

참고로 Docker로 길을 정하면 Open-WebUI 설치도 편해집니다. 이것도 이미지로 제공되거든요.

---

망분리 환경에서 Docker 설치

Docker 설치가 끝나있다고 가정하고 이후 글들을 진행할 겁니다. 근데 망분리 환경에서 Docker를 어떻게 설치할까요?

방법 1: 수동 설치 (비추천)

패키지들을 외부망에서 다운받아 USB나 별도 경로로 옮기는 방법입니다.

필요한 패키지:

• Docker Engine (.deb 또는 .rpm)
• containerd
• docker-compose
• NVIDIA Driver
• NVIDIA Container Toolkit

각각의 의존성까지 챙기다 보면 패키지가 수십 개가 됩니다. 버전 맞추는 것도 일이고요. 이 방법은 자세히 다루지 않겠습니다.

방법 2: 서버 도입 시 업체 요청 (추천)

서버를 새로 도입할 때 업체에 미리 요청하세요:

설치 요청 사항:
- Docker Engine
- NVIDIA Driver (최신 안정 버전)
- NVIDIA Container Toolkit

서버 납품 시점에는 대부분 인터넷 연결이 가능한 상태입니다. 업체가 세팅해주면 깔끔하게 끝나요.

업체한테 다음 명령어가 잘 수행되는 상태로 넘겨달라고 하면 깔끔합니다.

docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

(버전 12.8.0은 예시입니다)

출력 예시:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 570.86.11              Driver Version: 570.86.11      CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA RTX Pro 6000 ...        On  |   00000000:41:00.0 Off |                  Off |
| 30%   32C    P8             26W /  400W |       1MiB /  98304MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

이 출력이 나오면 Docker 컨테이너 안에서 GPU를 정상적으로 인식한다는 뜻입니다. vLLM이든 Open-WebUI든 올릴 준비가 된 거예요.

방법 3: 초기 세팅 기간 활용

회사에 따라 서버 도입 초기에는 인터넷망, 이후에는 업무망으로 영구 분리하는 정책을 허용해주는 곳도 있습니다.

이 기간에 필요한 걸 전부 설치하면 됩니다:

• Docker + NVIDIA Container Toolkit
• 필요한 Docker 이미지들 (docker pull)
• 기타 의존성

IT 부서와 협의가 필요하지만, 가능하다면 이것 또한 편한 방법입니다.

설치 스크립트

Ubuntu 기준 설치 스크립트를 준비했습니다:

스크립트	다운로드
Docker Engine	install-docker.sh
NVIDIA Container Toolkit	install-cuda-container.sh

다운로드 후 순서대로 실행하면 됩니다:

# 1. Docker 설치
sudo ./install-docker.sh

# 2. 로그아웃 후 재로그인 (docker 그룹 적용)

# 3. NVIDIA Container Toolkit 설치
sudo ./install-cuda-container.sh

NVIDIA 드라이버는 미리 설치되어 있어야 합니다. nvidia-smi 명령이 동작하는지 먼저 확인하세요.

---

다음 글

Docker 환경이 준비됐으니 다음 글에서는 vLLM을 설치하고 모델을 올려보겠습니다.

---

시리즈 목차

전체 목차는 AI 활용에서 확인하실 수 있습니다.