Docker 모델 러너

Docker Model Runner(DMR)를 사용하면 Docker로 AI 모델을 쉽게 관리하고, 실행하고, 배포할 수 있어요. 개발자를 위해 설계된 이 도구는 Docker Hub나 OCI 호환 레지스트리, 또는 Hugging Face에서 대규모 언어 모델(LLM)과 기타 AI 모델을 가져오고 실행하고 서빙하는 과정을 간소화해 줘요.

출처: 문서

본문

요구 사항: Docker Engine 또는 Docker Desktop(Windows) 4.41+ 또는 Docker Desktop(MacOS) 4.40+

대상: 아래 요구 사항 섹션 참고

Docker Desktop과 Docker Engine에 원활하게 통합되어, OpenAI와 Ollama 호환 API로 모델을 서빙하고, GGUF 파일을 OCI Artifact로 패키징하고, 명령줄과 그래픽 인터페이스 모두에서 모델과 상호작용할 수 있어요.

생성형 AI 애플리케이션을 만들든, 머신러닝 워크플로를 실험하든, AI를 소프트웨어 개발 수명 주기에 통합하든, Docker Model Runner는 로컬에서 AI 모델을 사용하는 일관되고 안전하며 효율적인 방법을 제공해요.

주요 기능

Docker Hub 또는 OCI 호환 레지스트리에서 모델 풀(pull) 및 푸시(push)
Hugging Face에서 모델 풀
기존 앱과 쉬운 통합을 위해 OpenAI 및 Ollama 호환 API로 모델 서빙
llama.cpp, vLLM, Diffusers 추론 엔진 지원(NVIDIA GPU를 사용하는 Linux에서 vLLM과 Diffusers)
Diffusers 백엔드로 Stable Diffusion 모델을 사용해 텍스트 프롬프트에서 이미지 생성
GGUF와 Safetensors 파일을 OCI Artifact로 패키징해 모든 컨테이너 레지스트리에 게시
명령줄이나 Docker Desktop GUI에서 직접 AI 모델 실행 및 상호작용
Cline, Continue, Cursor, Aider 같은 AI 코딩 도구 연결
컨텍스트 크기와 모델 파라미터를 구성해 성능 조정
ChatGPT 같은 웹 인터페이스를 위한 Open WebUI 설정
로컬 모델 관리와 로그 표시
프롬프트와 응답 세부 정보 표시
다중 턴 상호작용을 위한 대화 컨텍스트 지원

요구 사항

Docker Model Runner는 다음 플랫폼을 지원해요: Windows, MacOS, Linux

Windows(amd64):

NVIDIA GPU
NVIDIA 드라이버 576.57+

Windows(arm64):

Adreno용 OpenCL
Qualcomm Adreno GPU(6xx 시리즈 이상)

참고: 일부 llama.cpp 기능은 6xx 시리즈에서 완전히 지원되지 않을 수 있어요.

Apple Silicon

Docker Engine 전용:

CPU, NVIDIA(CUDA), AMD(ROCm), Vulkan 백엔드 지원
NVIDIA GPU 사용 시 NVIDIA 드라이버 575.57.08+ 필요

Docker Model Runner의 동작 방식

모델은 처음 사용할 때 Docker Hub, OCI 호환 레지스트리, 또는 Hugging Face에서 풀되어 로컬에 저장돼요. 요청이 있을 때만 런타임에 메모리로 로드되고, 사용하지 않을 때는 리소스를 최적화하기 위해 언로드돼요. 모델이 클 수 있으므로 초기 풀이 시간이 걸릴 수 있어요. 이후에는 로컬에 캐시되어 더 빠르게 접근할 수 있어요. OpenAI와 Ollama 호환 API로 모델과 상호작용할 수 있어요.

추론 엔진

Docker Model Runner는 세 가지 추론 엔진을 지원해요:

엔진	용도에 가장 적합	모델 형식
llama.cpp	로컬 개발, 리소스 효율	GGUF(양자화)
vLLM	프로덕션, 높은 처리량	Safetensors
Diffusers	이미지 생성(Stable Diffusion)	Safetensors

llama.cpp는 기본 엔진이며 모든 플랫폼에서 동작해요. vLLM은 NVIDIA GPU가 필요하며 Linux x86_64와 WSL2를 사용하는 Windows에서 지원돼요. Diffusers는 이미지 생성을 지원하며 Linux(x86_64 또는 ARM64)의 NVIDIA GPU가 필요해요. 자세한 비교와 설정은 추론 엔진 문서를 참고해 주세요.

컨텍스트 크기

모델은 처리할 수 있는 토큰 수를 결정하는 구성 가능한 컨텍스트 크기(context length)를 가져요. 기본값은 모델마다 다르지만 일반적으로 2,048~8,192 토큰이에요. 모델별로 조정할 수 있어요:

$ docker model configure --context-size 8192 ai/qwen2.5-coder

컨텍스트 크기와 기타 파라미터에 대한 자세한 내용은 구성 옵션 문서를 참고해 주세요.

팁: Testcontainers나 Docker Compose를 사용하나요? Java와 Go용 Testcontainers, 그리고 Docker Compose는 Docker Model Runner를 지원해요.

보안과 격리

실행 환경

Docker Model Runner는 추론 엔진을 호스트에서 격리해요:

Linux에서 Docker Model Runner와 Diffusers 같은 추론 엔진은 격리 경계를 제공하는 컨테이너 안에서 실행돼요.
macOS와 Windows에서 엔진은 컨테이너 안에서 실행되지 않으므로, Docker Model Runner는 샌드박스 환경(각각 seatbelt/sandbox-exec와 Job Objects)에서 실행해요.

네트워킹

Model Runner API는 인증되지 않아요. 같은 Docker 네트워크의 다른 컨테이너를 포함해 여기에 도달할 수 있는 모든 클라이언트가 모델을 풀하고, 로드하고, 실행하고, 추론 요청을 보낼 수 있어요.

알려진 문제

`docker model`이 인식되지 않음

Docker Model Runner 명령을 실행했는데 다음이 보인다면:

docker: 'model' is not a docker command

Docker가 예상 CLI 플러그인 디렉터리에 없어서 플러그인을 찾지 못한다는 뜻이에요. 이 문제를 해결하려면 Docker가 감지할 수 있도록 심볼릭 링크를 만들어 주세요:

$ ln -s /Applications/Docker.app/Contents/Resources/cli-plugins/docker-model ~/.docker/cli-plugins/docker-model

링크한 뒤 명령을 다시 실행해 주세요.

프라이버시와 데이터 수집

Docker Model Runner는 Docker Desktop의 프라이버시 설정을 존중해요. 데이터 수집은 Send usage statistics 설정으로 제어돼요:

비활성화(Disabled): 사용 데이터가 수집되지 않아요.
활성화(Enabled): 최소한의 비개인 데이터만 수집돼요:
- 모델 이름(Docker Hub로 HEAD 요청)
- 사용자 에이전트 정보
- 요청이 호스트에서 왔는지 컨테이너에서 왔는지

Docker Engine과 함께 Docker Model Runner를 사용할 때는 설정과 관계없이 모델 이름을 추적하기 위해 Docker Hub로 HEAD 요청이 만들어져요.

프롬프트 내용, 응답, 개인 식별 정보는 절대 수집되지 않아요.

피드백 공유

Docker Model Runner를 사용해 주셔서 감사해요. 버그를 신고하거나 기능을 요청하려면 GitHub에 이슈를 열어 주세요. Enable Docker Model Runner 설정 옆의 Give feedback 링크로도 피드백을 줄 수 있어요.

다음 단계

DMR 시작하기 — DMR 활성화하고 첫 모델 실행
API 레퍼런스 — OpenAI 및 Ollama 호환 API 문서
구성 옵션 — 컨텍스트 크기와 런타임 파라미터
추론 엔진 — llama.cpp, vLLM, Diffusers 세부 사항
IDE 통합 — Cline, Continue, Cursor 등 연결
Open WebUI 통합 — 웹 채팅 인터페이스 설정

Docker 모델 러너