로컬 대규모 언어 모델 (LLM)을 실행하는 과정은 종종 설렘으로 시작하여 의존성 충돌로 끝납니다.

Python을 설치합니다.

그다음 PyTorch를 설치합니다.

그다음 CUDA를 설치합니다.

그다음 모델 서빙 프레임워크 (model-serving framework)를 설치합니다.

그다음 올바른 토크나이저 (tokenizer)를 설치합니다.

그다음 양자화된 모델 형식 (quantized model format)을 설치합니다.

그러다 보면 한 라이브러리가 다른 라이브러리의 다른 버전을 요구한다는 사실을 발견하게 됩니다.

Docker는 소프트웨어를 패키징, 배포 및 실행하는 일관된 방법을 제공함으로써 개발자들이 전통적인 애플리케이션에서 유사한 문제를 해결하도록 도왔습니다.

Docker Model Runner는 그 경험을 AI 모델로 가져옵니다.

추론 서버 (inference server)를 수동으로 구성하고, 모델 파일을 다운로드하고, API를 노출하며, 런타임 의존성 (runtime dependencies)을 관리하는 대신, 다음과 같은 익숙한 명령어를 사용할 수 있습니다:

docker model pull ai/smollm2
docker model run ai/smollm2

Docker Model Runner는 모델 아티팩트 (model artifact)를 관리하고, 추론 엔진 (inference engine)을 선택하며, 모델을 로드하고, 애플리케이션이 호출할 수 있는 API를 노출합니다.

이 글에서는 다음 내용을 살펴봅:

• Docker Model Runner란 무엇인가
• 일반 컨테이너를 실행하는 것과 어떻게 다른가
• 설치 및 활성화 방법
• 로컬 모델을 가져오고(pull) 실행하는 방법
• API를 통해 모델을 호출하는 방법
• Python 및 Docker Compose와 함께 사용하는 방법
• 모델 패키징 및 OCI 아티팩트 (OCI artifacts)의 작동 방식
• 어떤 추론 엔진을 선택해야 하는가
• 보안, 성능 및 운영 고려 사항

Docker Model Runner란 무엇인가?

종종 DMR로 약칭되는 Docker Model Runner는 AI 모델을 관리, 실행, 서빙 및 배포하기 위한 Docker 기능입니다.

이를 통해 개발자는 다음과 같은 작업을 수행할 수 있습니다:

• Docker Hub에서 모델 가져오기 (Pull)
• Hugging Face에서 지원되는 모델 가져오기
• Docker CLI에서 모델 실행하기
• Docker Desktop을 통해 모델과 상호작용하기
• 호환 가능한 REST API를 통해 모델 노출하기
• 컨테이너화된 애플리케이션에서 모델 사용하기
• 모델 파일을 OCI 아티팩트로 패키징하기
• 커스텀 모델을 OCI 호환 레지스트리에 푸시(Push)하기
• 컨텍스트 크기 (context size) 및 런타임 파라미터 구성하기
• 서로 다른 워크로드에 대해 서로 다른 추론 엔진 실행하기

Docker Model Runner는 현재 OpenAI, Anthropic, 그리고 Ollama 호환 인터페이스를 지원합니다. 또한 추론 엔진 (inference engines)으로서 llama.cpp, vLLM, 그리고 Diffusers를 지원합니다.

Docker는 2025년 4월에 Model Runner를 베타 버전으로 도입했으며, 2025년 9월에 일반 가용성 (general availability)을 발표했습니다.

Docker Model Runner가 해결하는 문제

로컬 LLM을 실행하는 데 통상적으로 무엇이 필요한지 생각해 보십시오.

다음 작업들이 필요할 수 있습니다:

1. 호환 가능한 모델 찾기.
2. 수 기가바이트(GB)의 모델 가중치 (model weights) 다운로드하기.
3. 모델이 GGUF, Safetensors 또는 다른 형식을 사용하는지 확인하기.
4. 추론 엔진 (inference engine) 선택하기.
5. CPU, GPU, CUDA, Metal 또는 ROCm 지원 구성하기.
6. 추론 서버 (inference server) 시작하기.
7. API 엔드포인트 (endpoint) 구성하기.
8. 애플리케이션을 해당 엔드포인트에 연결하기.
9. 모델 버전 및 로컬 스토리지 관리하기.
10. 다른 머신에서 동일한 환경 재현하기.

각 작업은 개별적으로 관리할 수 있습니다.

어려움은 이 모든 것을 한꺼번에 관리하는 데서 발생합니다.

Docker Model Runner는 이러한 문제들을 중심으로 일관된 개발자 워크플로 (developer workflow)를 생성합니다:

Application
    |
    | OpenAI, Anthropic, 또는 Ollama 호환 API
...

애플리케이션은 토크나이저 (tokenizer), 모델 프로세스 (model process), 추론 서버 (inference server), 또는 모델 파일 위치를 직접 관리할 필요가 없습니다.

애플리케이션은 API를 호출합니다.

Docker Model Runner가 그 뒤에서 런타임 (runtime)을 처리합니다.

AI 모델이 정말 컨테이너로서 실행되는 것인가?

정확히 그렇지는 않습니다.

이 구분은 중요합니다.

모델은 기본적으로 가중치 (weights), 설정 파일 (configuration files), 토크나이저 정보 (tokenizer information), 그리고 메타데이터 (metadata)의 집합입니다. 모델 그 자체로는 애플리케이션 프로세스가 아닙니다.

Docker Model Runner는 두 가지 관심사를 분리합니다:

모델 아티팩트 (The model artifact)

아티팩트에는 모델 가중치와 관련 메타데이터가 포함됩니다.

모델은 OCI 아티팩트 형식 (OCI artifact format)을 사용하여 패키징할 수 있으며, 익숙한 리포지토리 이름과 태그를 사용하여 레지스트리 (registries)에 저장할 수 있습니다.

추론 엔진 (The inference engine)

추론 엔진은 모델을 메모리에 로드하고 실제 연산을 수행합니다.

설정에 따라 Docker Model Runner는 다음을 사용할 수 있습니다:

• llama.cpp
• vLLM
• Diffusers

Linux에서는 Model Runner와 그 추론 엔진(inference engines)이 컨테이너 내부에서 실행됩니다. macOS 및 Windows에서는 Docker가 추론 엔진을 일반적인 애플리케이션 컨테이너로 취급하는 대신, 플랫폼별 샌드박싱(sandboxing)을 사용합니다.

사용자 경험은 컨테이너를 실행하는 것과 유사하지만, Docker는 내부적으로 특화된 모델 서빙 라이프사이클(model-serving lifecycle)을 관리합니다.

Docker Model Runner의 작동 방식

애플리케이션이 모델을 요청하면, Docker Model Runner는 여러 작업을 수행합니다.

1. 모델 해석 (Resolve the model)

Docker는 요청된 모델을 Docker Hub, 다른 OCI 호환 레지스트리(registry), Hugging Face 또는 로컬 모델 캐시(local model cache)에서 찾습니다.

2. 아티팩트 다운로드 (Download the artifact)

모델을 로컬에서 사용할 수 없는 경우, Docker가 이를 다운로드합니다.

모델은 수십억 개의 파라미터(parameters)를 포함할 수 있기 때문에, 첫 다운로드에는 시간이 걸릴 수 있습니다.

3. 모델 로컬 캐싱 (Cache the model locally)

다운로드된 모델은 캐시된 상태로 유지되어, 향후 요청 시 동일한 아티팩트를 다시 다운로드할 필요가 없습니다.

4. 추론 엔진 선택 (Select an inference engine)

Docker Model Runner는 어떤 엔진이 모델을 서빙해야 하는지 결정합니다.

예를 들어:

• 양자화된(quantized) GGUF 모델은 일반적으로 llama.cpp를 사용합니다.
• 높은 처리량(high-throughput) 서빙을 목적으로 하는 Safetensors 모델은 vLLM을 사용할 수 있습니다.
• Stable Diffusion 모델은 Diffusers를 사용할 수 있습니다.

5. 모델을 메모리에 로드 (Load the model into memory)

모델은 메모리를 영구적으로 점유하는 대신, 요청될 때 로드됩니다.

6. API를 통한 모델 서빙 (Serve the model through an API)

애플리케이션은 호환 가능한 HTTP 엔드포인트(endpoint)를 통해 모델과 상호작용합니다.

모델은 온디맨드(on demand) 방식으로 로드되며, 리소스 사용량을 줄이기 위해 비활성 상태 이후에는 언로드(unload)될 수 있습니다.

요구 사항 (Prerequisites)

Docker Model Runner는 Docker Desktop 및 Docker Engine을 통해 사용할 수 있습니다.

이 글을 작성하는 시점을 기준으로, 문서화된 Docker Desktop의 최소 버전은 다음과 같습니다:

• 지원되는 macOS 시스템의 Docker Desktop 4.40 이상
• 지원되는 Windows 시스템의 Docker Desktop 4.41 이상
• Linux에서 Docker Model Runner 플러그인이 포함된 Docker Engine

하드웨어 지원은 운영 체제(Operating System) 및 추론 엔진(Inference Engine)에 따라 다릅니다. Docker의 현재 문서에는 Apple Silicon, Windows에서 지원되는 NVIDIA 및 Qualcomm 구성, 그리고 Docker Engine을 통한 CPU, CUDA, ROCm 및 Vulkan 옵션이 포함되어 있습니다.

또한 모델은 사용 가능한 RAM 또는 GPU 메모리 내에 적합해야 합니다.

작은 양자화된(Quantized) 모델은 개발용 노트북에서 원활하게 실행될 수 있습니다. 더 큰 모델은 훨씬 더 많은 메모리나 전용 GPU를 필요로 할 수 있습니다.

1단계: Docker Model Runner 활성화하기

Docker Desktop

Docker Desktop을 열고 다음 경로로 이동합니다:

Settings → AI

다음 항목을 활성화합니다:

Docker Model Runner

호스트에서 실행되는 애플리케이션에서 모델을 직접 호출하려면 다음 항목도 활성화하십시오:

Host-side TCP support

기본 호스트 포트는 일반적으로 다음과 같습니다:

12434

Docker Desktop은 또한 모델을 탐색, 다운로드, 실행 및 검사할 수 있는 Models 섹션을 제공합니다.

명령줄(Command Line)에서도 TCP 액세스를 활성화할 수 있습니다:

docker desktop enable model-runner --tcp 12434

Ubuntu 또는 Debian의 Docker Engine

sudo apt-get update
sudo apt-get install docker-model-plugin

RPM 기반 Linux 배포판의 Docker Engine

sudo dnf update
sudo dnf install docker-model-plugin

설치를 확인합니다:

docker model version

Docker Engine은 기본적으로 12434 포트에서 TCP 액세스를 활성화합니다.

2단계: 모델 검색하기

Docker Hub의 AI 네임스페이스(Namespace)를 검색할 수 있습니다:

docker model search

특정 모델 제품군을 검색합니다:

docker model search llama

Docker Hub와 Hugging Face를 모두 검색합니다:

docker model search --source=all

Docker Model Runner는 Docker Hub와 Hugging Face를 통해 사용할 수 있는 모델을 검색할 수 있습니다.

3단계: 모델 가져오기 (Pull)

가벼운 첫 실험을 위해 SmolLM2를 가져옵니다:

docker model pull ai/smollm2

특정 모델 변형(Variant)을 선택할 수도 있습니다:

docker model pull ai/smollm2:360M-Q4_K_M

태그(Tag)는 모델에 대해 더 많은 정보를 알려줍니다:

360M       약 3억 6천만 개의 파라미터 (parameters)
Q4_K_M     4비트 양자화 (quantized)된 GGUF 변형

양자화 (Quantization)는 가중치 (weights)를 더 적은 비트 (bits)로 표현함으로써 모델 실행에 필요한 메모리 (memory)를 줄여줍니다.

Q4_K_M 모델은 일부 품질 손실이 발생할 수 있지만, 일반적으로 F16 모델보다 메모리를 적게 사용합니다.

Docker의 추론 엔진 (inference-engine) 문서에서는 많은 로컬 llama.cpp 워크로드에 대해 모델 품질과 메모리 사용량 사이의 실용적인 균형점으로 Q4_K_M을 권장합니다.

Hugging Face에서 가져오기 (Pulling)

Docker Model Runner는 지원되는 GGUF 모델을 Hugging Face에서 직접 가져올 수도 있습니다:

docker model pull \
  hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF

태그 (tag)를 사용하여 특정 양자화 버전을 요청할 수 있습니다:

docker model pull \
  hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF:Q4_K_S

양자화 태그가 제공되지 않으면, Docker는 모델 가져오기 (model-pull) 동작에 따라 사용 가능한 GGUF 변형을 선택하려고 시도합니다.

단계 4: 모델 실행하기 (Run the Model)

대화형 세션 (interactive session)을 시작합니다:

docker model run ai/smollm2

이제 터미널 (terminal)에서 직접 프롬프트 (prompts)를 입력할 수 있습니다.

단일 프롬프트의 경우:

docker model run ai/smollm2 \
  "Explain retrieval-augmented generation in simple terms."

대화형 대화창을 열지 않고 모델을 미리 로드 (preload)할 수도 있습니다:

docker model run --detach ai/smollm2

모델이 이미 메모리에 로드되어 있으므로, 프리로딩 (Preloading)을 통해 첫 번째 애플리케이션 요청의 지연 시간 (latency)을 줄일 수 있습니다.

유용한 Docker Model 명령어

다운로드된 모델 목록 보기:

docker model list

현재 메모리에 로드된 모델 목록 보기:

docker model ps

모델 조사 (Inspect):

docker model inspect ai/smollm2

Model Runner 상태 확인:

docker model status

디스크 사용량 확인:

docker model df

Model Runner 로그 보기:

docker model logs

캡처된 요청 (requests) 및 응답 (responses) 보기:

docker model requests

실행 중인 모델 언로드 (Unload):

docker model unload ai/smollm2

다운로드된 모델 제거:

docker model rm ai/smollm2

docker model CLI에는 벤치마킹 (benchmarking), 패키징 (packaging), 푸시 (pushing), 태깅 (tagging), 검사 (inspecting), 그리고 Model Runner 컨텍스트 (contexts)를 관리하기 위한 명령어도 포함되어 있습니다.

OpenAI 호환 API를 통한 모델 호출

터미널에서 모델을 실행하는 것은 실험 용도로 유용합니다.

일반적으로 애플리케이션은 API를 통해 모델과 통신합니다.

호스트에서 직접 실행되는 소프트웨어의 경우, Docker Model Runner는 다음과 같은 위치에 OpenAI 호환 엔드포인트 (endpoint)를 노출합니다:

http://localhost:12434/v1

curl로 요청을 보냅니다:

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
...

응답은 OpenAI 호환 chat-completions 구조를 따릅니다.

Docker Model Runner는 다음과 같은 일반적인 파라미터 (parameters)를 지원합니다:

• model
• messages
• prompt
• max_tokens
• temperature
• top_p
• stream
• stop
• presence_penalty
• frequency_penalty

API 요청 시에는 전체 모델 식별자 (identifier)를 사용하세요:

{
  "model": "ai/smollm2"
}

Docker Hub 모델은 일반적으로 다음과 같은 식별자를 사용합니다:

ai/smollm2
ai/llama3.2
ai/qwen2.5-coder

커스텀 모델은 다음과 같은 식별자를 사용할 수 있습니다:

myorganization/my-model

Docker는 호환 가능한 모델에 대한 chat completions, text completions, embeddings, 모델 목록 (model listing), JSON 모드 (JSON mode), 멀티모달 입력 (multimodal input), 그리고 호환 가능한 llama.cpp 모델을 위한 함수 호출 (function calling)을 문서화하고 있습니다.

Python에서 Docker Model Runner 사용하기

엔드포인트가 OpenAI와 호환되기 때문에, OpenAI Python SDK를 사용하는 기존 애플리케이션은 베이스 URL (base URL)을 변경함으로써 Docker Model Runner로 리다이렉션 (redirected)할 수 있는 경우가 많습니다.

SDK를 설치합니다:

pip install openai

app.py를 생성합니다:

from openai import OpenAI

def main() -> None:
...

실행합니다:

python app.py

API 키 (API key) 값은 플레이스홀더 (placeholder)입니다. Docker Model Runner는 로컬 OpenAI 호환 엔드포인트에 대해 API 키를 요구하지 않습니다.

스트리밍 응답 (Streaming Responses)

채팅 인터페이스의 경우, 사용자들은 일반적으로 토큰 (tokens)이 생성되는 대로 나타나기를 기대합니다.

stream을 true로 설정:

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
...

스트리밍 (Streaming)은 애플리케이션이 출력을 보여주기 전에 전체 응답을 기다릴 필요가 없기 때문에 체감 지연 시간 (perceived latency)을 줄여줍니다. Docker Model Runner는 호환 가능한 API 인터페이스를 통해 스트리밍 (streaming)을 지원합니다.

Anthropic 호환 API

Anthropic 스타일의 API를 위해 설계된 애플리케이션은 다음을 호출할 수 있습니다:

예시:

curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
...