본문으로 건너뛰기
PromptQuorum인간을 위해 설계. AI를 위해 구조화.
홈/고급 로컬 LLM
Overview & Reference

Docker Model Runner 리뷰: Docker CLI로 실행하는 로컬 LLM

·11분 읽기Hans Kuepper 저 · PromptQuorum 창립자 · 오픈 웨이트·오픈소스 AI 디스커버리 엔진

Docker Model Runner는 Docker Desktop과 Docker Engine의 기능이며, 별도로 다운로드하는 애플리케이션이 아닙니다. docker model CLI 명령어로 대규모 언어 모델을 가져오고 실행할 수 있습니다. 로컬 추론은 llama.cpp(CPU 및 Apple Silicon용) 또는 vLLM(NVIDIA GPU용, 더 높은 처리량이 필요한 서빙에 적합)을 통해 실행됩니다. 대부분의 리뷰가 놓치는 세부 사항은, 이 추론 엔진이 네이티브 호스트 프로세스로 동작한다는 점입니다. 즉 컨테이너 내부에서 실행되지 않으며, 이를 통해 컨테이너 격리를 거치지 않고 GPU 하드웨어에 직접 접근할 수 있습니다. Docker Model Runner는 OpenAI 호환 API를 제공하며 Docker Desktop의 일부로 무료로 제공됩니다. 다만 Docker Desktop 자체가 무료인지는 조직의 규모에 따라 달라집니다(아래 요금제 참조).

핵심 요점

  • Docker Desktop(macOS, Windows)과 Docker Engine(Linux)에 내장되어 있어 별도 다운로드가 필요 없음
  • 로컬 추론 엔진은 CPU/Apple Silicon용 llama.cpp 또는 NVIDIA GPU 기반 서빙용 vLLM
  • 컨테이너 런타임 외부에서 네이티브 호스트 프로세스로 동작하여 GPU에 직접 접근
  • CLI: docker model pull <모델>, docker model run <모델>, docker model list
  • 호스트에서는 http://localhost:12434/engines/v1, 다른 컨테이너에서는 http://model-runner.docker.internal/engines/v1로 OpenAI 호환 API 제공
  • 모델은 Docker Hub의 AI 모델 카탈로그, 다른 OCI 호환 레지스트리, 또는 Hugging Face에서 가져옴
  • 추가 비용 없음 — 이 기능은 Docker Desktop에 포함되어 있으며, Docker Desktop 자체의 유료 구독 필요 여부는 기업 규모에 따라 결정됨

📍 한 문장으로

Docker Model Runner는 Docker Desktop과 Docker Engine에 내장된 기능으로, docker model CLI 명령어를 통해 LLM을 로컬에서 실행하며, 네이티브 호스트 프로세스로 동작하는 llama.cpp 또는 vLLM을 추론 엔진으로 사용하고 OpenAI 호환 API를 제공합니다.

💬 쉽게 말하면

이미 Docker로 컨테이너를 실행하고 있다면, Docker Model Runner를 사용해 같은 방식으로 — docker model pull과 docker model run으로 — AI 모델을 가져오고 실행할 수 있습니다. 별도의 채팅 애플리케이션을 설치할 필요가 없으며, 모델 자체는 실제로 컨테이너 안에서 실행되지 않습니다.

언어 선택:
🇺🇸en🇩🇪de🇫🇷fr🇯🇵ja🇨🇳zh🇪🇸es🇧🇷pt🇸🇦ar🇰🇷ko

Docker Model Runner는 Docker Desktop과 Docker Engine에 내장된 기능으로, docker model CLI 명령어를 사용해 대규모 언어 모델을 로컬에서 실행합니다. 추론 엔진으로는 llama.cpp 또는 vLLM을 사용하며, OpenAI 호환 API를 통해 노출됩니다. 이는 독립적인 애플리케이션이 아니라 Docker Desktop에 추가된 기능이므로, 대부분의 개발자가 이미 설치해 둔 Docker Desktop에 무료로 포함되어 제공됩니다. 이 리뷰에서는 Docker Model Runner가 실제로 무엇을 하는지, 추론을 컨테이너 안에서 실행하지 않는 방식, 설치 및 사용 방법, 그리고 Ollama나 llama.cpp 같은 다른 로컬 런타임 도구들과의 관계를 다룹니다.

Docker Model Runner 리뷰: Docker CLI로 실행하는 로컬 LLM

Docker Model Runner란?

Docker Model Runner는 개발자가 컨테이너용으로 이미 사용 중인 동일한 docker CLI를 통해 대규모 언어 모델을 로컬에서 가져오고 실행할 수 있게 해 주는 Docker Desktop 및 Docker Engine의 기능입니다. Docker 공식 제품 페이지에 따르면, OpenAI 호환 API를 갖춘 로컬 우선 추론을 제공하며 Docker Hub, 다른 OCI 호환 레지스트리, 또는 Hugging Face에서 모델을 가져옵니다. 이는 그래픽 창을 가진 채팅 애플리케이션이 아니라, CLI 기능에 로컬 추론 서버가 결합된 형태로, 터미널이나 Docker Compose, 또는 API를 호출하는 코드에서 사용하도록 설계되었습니다.

  • Docker Desktop(macOS, Windows)에 포함되어 있으며, Linux에서는 Docker Engine용 docker-model-plugin 패키지로 제공 — 별도의 설치 프로그램이 없음
  • 로컬 추론 엔진: Docker 문서에 따르면 CPU 및 Apple Silicon용 llama.cpp, NVIDIA GPU 기반 서빙용 vLLM
  • 모델 출처: Docker Hub의 선별된 AI 모델 카탈로그, 모든 OCI 호환 레지스트리, 또는 Hugging Face
  • 개발자가 Docker 주변에서 이미 사용 중인 도구와 통합: Docker Compose, Testcontainers, 그리고 OpenAI 호환 API를 통한 LangChain, Spring AI, Open WebUI 같은 프레임워크
  • 개발사: Docker, Inc.

설치 및 시작하기

Docker Model Runner는 Docker Desktop과 Docker Engine에 내장된 CLI 기능이며, 독립적으로 다운로드하는 애플리케이션이 아닙니다. 따라서 별도의 설치 프로그램이나 다운로드 버튼이 존재하지 않으며, Docker Desktop(또는 Linux에서는 Docker Engine과 model-runner 플러그인)을 설치하면 docker model 명령어를 사용할 수 있게 됩니다.

  1. 1
    macOS 또는 Windows에서는 Docker Desktop을 설치하고, Linux에서는 Docker Engine과 model-runner 플러그인을 설치합니다(Debian/Ubuntu에서는 sudo apt-get install docker-model-plugin, Fedora/RHEL에서는 sudo dnf install docker-model-plugin).
  2. 2
    Model Runner가 아직 활성화되어 있지 않다면 활성화합니다: docker desktop enable model-runner(Docker Desktop), 또는 Docker Engine에서 플러그인이 활성화되어 있는지 확인합니다.
  3. 3
    Docker Hub의 AI 카탈로그에서 모델을 가져옵니다: docker model pull ai/smollm2:360M-Q4_K_M.
  4. 4
    명령줄에서 직접 실행합니다: docker model run ai/smollm2:360M-Q4_K_M "Give me a fact about whales."
  5. 5
    언제든지 docker model list로 로컬에 이미 가져온 모델 목록을 확인할 수 있습니다.
  6. 6
    CLI 대신 HTTP로 모델에 접근하려면 OpenAI 호환 API를 사용하세요 — 정확한 엔드포인트는 아래 OpenAI 호환 API를 참고하세요.

컨테이너가 아닌 호스트 프로세스로 동작하는 이유

docker라는 명령어 접두사에도 불구하고, Docker Model Runner는 모델 추론을 컨테이너 안에서 실행하지 않습니다. 이 기능을 소개하는 Docker 공식 블로그 게시물은 이 점을 명확히 밝히고 있습니다. docker model run을 실행해도 "어떤 종류의 컨테이너도 실행되지 않는다"는 것입니다. 대신 이 명령어는 Docker Desktop을 통해 Model Runner가 호스팅하는 추론 서버 API를 호출하며, 이 추론 서버는 자신의 추론 엔진(llama.cpp 또는 vLLM)을 네이티브 호스트 프로세스로 실행합니다 — 이는 다른 로컬 설치 프로그램과 마찬가지로 운영체제 위에서 직접 실행되는 일반적인 프로세스입니다.

  • 제시된 이유는 GPU 접근입니다. 네이티브 호스트 프로세스는 컨테이너에서 호스트로의 GPU 패스스루라는 추가적인 간접 단계를 거치지 않고, 머신의 GPU(Apple Silicon 내장 GPU 또는 NVIDIA GPU)를 직접 사용할 수 있습니다
  • 이는 성능을 위한 의도적인 아키텍처 선택이며, Docker의 컨테이너 런타임의 한계가 아닙니다 — Docker Model Runner는 워크플로의 다른 부분에서는 컨테이너를 사용합니다(예를 들어 일부 모델 패키징은 OCI 기반입니다)만, 추론 프로세스 자체에는 사용하지 않습니다
  • 실제로 이는 실행 중인 모델이 docker ps로 확인할 수 있는 컨테이너보다는 머신의 백그라운드 서비스처럼 동작한다는 것을 의미합니다
  • 모델은 다른 모델이 요청되거나 일정 기간 비활성 상태가 지속될 때까지 메모리에 계속 로드된 상태를 유지하므로, 시작 후 첫 요청은 이후 요청보다 느립니다

llama.cpp vs. vLLM: 어떤 엔진이 모델을 실행하는가

Docker Model Runner는 자체 추론 엔진을 구현하지 않습니다 — Docker 문서에 따르면, 기존에 존재하는 두 개의 오픈소스 엔진을 감싸고 하드웨어와 모델 형식에 따라 둘 중 하나를 선택합니다.

llama.cpp

용도:
로컬 개발, 리소스 효율적인 추론
모델 형식:
GGUF(양자화)
지원 플랫폼:
CPU와 Apple Silicon, 일부 Windows/Linux GPU 백엔드도 지원
llama.cpp 관련 문서 (10개)

표시되지 않은 172개 더보기

vLLM

용도:
프로덕션 지향의 더 높은 처리량 서빙
모델 형식:
Safetensors
지원 플랫폼:
NVIDIA GPU를 갖춘 Linux 및 Windows(WSL2)
vLLM 관련 문서 (10개)

표시되지 않은 89개 더보기

이는 본 사이트의 llama.cpp 해설에서 자세히 다룬 것과 동일한 llama.cpp 엔진이며, vLLM 해설에서 다룬 것과 동일한 vLLM 엔진입니다 — Docker Model Runner는 이 엔진들 위에 구축된 패키징 및 CLI 계층일 뿐, 둘 중 어느 것도 처음부터 새로 만든 대안이 아닙니다. Docker는 또한 NVIDIA GPU를 갖춘 Linux에서 이미지 생성 모델(Stable Diffusion)을 위한 실험적인 Diffusers 지원도 문서화하고 있는데, 이는 LLM에 초점을 맞춘 본 리뷰의 범위를 벗어납니다.

OpenAI 호환 API

Docker의 해당 기능 소개 블로그 게시물에 따르면, Docker Model Runner는 기존 OpenAI 클라이언트 코드가 클라우드 엔드포인트 대신 로컬 모델을 가리킬 수 있도록 OpenAI 호환 HTTP API를 제공합니다.

  • 호스트 머신에서: http://localhost:12434/engines/v1(TCP 접근은 docker desktop enable model-runner --tcp 12434로 한 번 활성화해야 함)
  • 같은 Docker 네트워크 내 다른 컨테이너에서: http://model-runner.docker.internal/engines/v1
  • Docker 자체의 통합 예제에 따르면, LangChain, Spring AI, Open WebUI 등 이미 OpenAI API 형식으로 구축된 도구 및 프레임워크와 호환
  • 모델은 요청이 도착하면 필요에 따라 로드되며, 다른 모델이 요청되거나 비활성 시간 초과가 지날 때까지 메모리에 상주

지원 플랫폼

Docker 문서에 따르면, Docker Model Runner의 하드웨어 지원은 운영체제와 사용 중인 추론 엔진에 따라 다릅니다.

macOS

세부 사항:
Apple Silicon, llama.cpp를 통한 네이티브 GPU 가속

Windows

세부 사항:
NVIDIA GPU를 탑재한 AMD64(드라이버 576.57 이상)는 llama.cpp 또는 vLLM(WSL2), Qualcomm Adreno 6xx 시리즈 GPU를 탑재한 ARM64는 llama.cpp

Linux

세부 사항:
llama.cpp를 통한 CPU 전용, NVIDIA CUDA, AMD ROCm, Vulkan 백엔드; vLLM을 통한 NVIDIA GPU(드라이버 575.57.08 이상)

정확한 최소 드라이버 버전과 지원 GPU 계열은 Docker가 이 기능을 업데이트함에 따라 변경됩니다 — 특정 GPU를 전제로 배포를 계획하기 전에 docs.docker.com/ai/model-runner에서 현재 요구 사항을 확인하세요.

Docker Model Runner 요금제

Docker Model Runner 자체는 별도의 비용을 발생시키지 않습니다 — 이는 Docker Desktop과 Docker Engine에 포함된 기능입니다. 비용이 발생하는지 여부는 전적으로 Docker Desktop 사용이 Docker 자체의 구독 서비스 계약에 따라 무료 자격을 갖추는지에 달려 있습니다.

Personal(무료)

대상:
개인, 교육 기관, 비영리 오픈소스 프로젝트, 그리고 직원 250명 미만이면서 연 매출 1,000만 달러 미만인 기업
Docker Model Runner 포함 여부:
포함

Pro / Team / Business(유료)

대상:
더 큰 규모의 기업, 또는 무료 등급의 범위를 넘어서는 팀 기능이 필요한 조직
Docker Model Runner 포함 여부:
포함

Docker Hub의 선별된 AI 모델은 구독 등급과 관계없이 무료로 가져올 수 있습니다. Docker의 유료 요금제(Pro, Team, Business)는 팀 좌석이나 중앙 관리처럼 Model Runner 자체와 무관한 기능을 추가합니다 — 최신 가격은 docker.com/pricing에서 확인하세요. 이 가격은 Model Runner 기능과 별개로 변동됩니다.

Docker Model Runner는 누구에게 적합한가

Docker Model Runner는 특정한 워크플로에 적합합니다. 이미 Docker를 중심으로 개발하고 있으며, 스택에 두 번째 도구를 추가하지 않고 로컬 LLM 추론을 더하고 싶은 개발자입니다.

다음의 경우 Docker Model Runner를 사용하세요

  • 이미 Docker Desktop 또는 Docker Engine을 매일 사용 중이며, 별도의 애플리케이션을 설치하지 않고 동일한 CLI에 로컬 LLM 추론을 추가하고 싶은 경우
  • 애플리케이션이나 서비스가 이미 Docker Compose나 컨테이너를 중심으로 구축되어 있으며, model-runner.docker.internal을 통해 다른 컨테이너에서 모델 엔드포인트에 접근할 수 있도록 하고 싶은 경우
  • 도구를 바꾸지 않고 CPU/Apple Silicon 개발(llama.cpp)에서 NVIDIA GPU 프로덕션 서빙(vLLM)으로 전환할 수 있는 선택지를 원하는 경우
  • 그래픽 채팅 창보다는 터미널과 HTTP API로 작업하는 것이 편한 경우

다음의 경우 좀 더 지켜보거나 다른 대안을 검토하세요

  • 모델과 대화하는 주된 방식으로 그래픽 기반의 클릭식 채팅 인터페이스를 원하는 경우 — Docker Model Runner에는 내장 채팅 창이 없으므로, 필요하다면 Open WebUI 같은 프런트엔드와 함께 사용하세요
  • 아직 Docker를 사용하지 않고 있으며, 단지 로컬 모델을 실행하기 위해 Docker Desktop을 설치하고 싶지 않은 경우 — 이런 경우에는 Jan이나 GPT4All 같은 전용 애플리케이션이 설치 부담이 더 적습니다
  • 격리를 위해 추론 프로세스가 엄격하게 컨테이너 안에서 실행되어야 하는 경우 — Docker Model Runner는 GPU 성능을 위해 의도적으로 엔진을 컨테이너가 아닌 호스트 프로세스로 실행합니다(자세한 내용은 위의 호스트 프로세스로 동작하는 이유 참조)
  • 조직이 직원 250명 / 매출 1,000만 달러라는 무료 사용 기준을 초과했는데 아직 유료 Docker 구독에 대한 예산을 확보하지 못한 경우 — 먼저 Docker 라이선스 상태를 확인하세요

경쟁 서비스 및 대안

Docker Model Runner는 동일한 기반 엔진을 감싼 CLI 우선 엔진 및 데스크톱 애플리케이션과 함께 로컬 추론 런타임 영역에 속합니다. 전체 카탈로그는 로컬 LLM 소프트웨어 디렉터리를 참고하세요.

  • llama.cpp — Docker Model Runner 자체가 CPU/Apple Silicon용으로 사용하는 추론 엔진입니다. 이를 직접 사용하면 Docker의 래퍼가 노출하지 않는 빌드 플래그와 양자화에 대한 제어권을 얻을 수 있습니다.
  • vLLM — Docker Model Runner가 프로덕션 워크로드에 사용하는 것과 동일한 GPU 서빙 엔진입니다. Docker의 단순화된 CLI가 아니라 vLLM의 전체 설정 범위가 필요하다면 직접 사용하는 편이 더 적합합니다.
  • Ollama — 가장 가까운 "한 줄 명령" 비교 대상입니다. Docker Model Runner와 마찬가지로 Ollama도 간단한 pull-and-run CLI와 OpenAI 호환 API 뒤에서 llama.cpp를 감싸고 있지만, Docker Desktop의 기능이 아니라 독립 도구로 제공됩니다 — 아직 Docker를 사용하지 않는다면 더 적합한 선택입니다.
  • Jan — 동일한 llama.cpp 엔진을 기반으로 한 무료 오픈소스 데스크톱 애플리케이션으로, 그래픽 채팅 창을 제공합니다. CLI와 API 기반 워크플로 대신 클릭 방식의 인터페이스를 원하는 개발자에게 적합합니다.
  • GPT4All — llama.cpp 기반의 또 다른 오픈소스 로컬 채팅 애플리케이션으로, Jan과 마찬가지로 "터미널이 아니라 창을 원한다"는 사용 사례에 해당합니다.

디렉터리에서 비교

흔한 오해

Docker Model Runner에 관한 혼란은 대부분 이것이 일반적인 Docker 컨테이너 워크로드처럼 동작한다고 가정하거나, 별도로 설치하는 제품이 아니라 Docker Desktop의 기능이라는 점을 간과하는 데서 비롯됩니다.

오해 1: 모델이 컨테이너 안에서 실행된다고 가정하는 것

명령어가 docker model run이기 때문에, docker ps로 확인할 수 있는 컨테이너 안에서 추론이 일어난다고 가정하기 쉽습니다. 하지만 그렇지 않습니다 — Docker 공식 문서는 추론 엔진이 GPU에 직접 접근하기 위해 네이티브 호스트 프로세스로 동작하며, 컨테이너 안에서 실행되지 않는다는 점을 확인해 줍니다.

오해 2: 별도의 설치 프로그램이나 다운로드 페이지를 찾는 것

Docker Model Runner에는 독립적인 설치 프로그램이 없습니다. 이는 Docker Desktop(macOS, Windows)과 Docker Engine에 model-runner 플러그인을 더한(Linux) 기능이며, 별도의 제품인 "Docker Model Runner"가 아니라 Docker 자체를 설치하는 것입니다.

오해 3: Docker Model Runner가 자체적인 별도 요금을 부과한다고 가정하는 것

Model Runner 자체에는 추가 요금이 없습니다. 유일한 비용 관련 질문은, 기존의 Docker Desktop 사용이 무료 Personal 요금제(Docker 구독 서비스 계약에 따라 직원 250명 미만, 연 매출 1,000만 달러 미만) 범위에 해당하는지, 아니면 유료 Pro/Team/Business 요금제가 필요한지 여부입니다 — 이는 이 기능 자체가 아니라 Docker Desktop 전반에 관한 라이선스 문제입니다.

오해 4: 하나의 엔진이 모든 플랫폼과 GPU를 커버할 것이라고 기대하는 것

llama.cpp와 vLLM은 서로 다른 하드웨어를 지원합니다. llama.cpp는 CPU와 Apple Silicon(일부 Windows/Linux GPU 백엔드 포함)을 처리하는 반면, vLLM은 Linux와 Windows WSL2의 NVIDIA GPU로 제한됩니다. 특정 모델/엔진 조합이 사용자의 머신에서 작동할 것이라고 가정하기 전에, 위의 지원 플랫폼 표를 확인하세요.

자주 묻는 질문

Docker Model Runner란 무엇입니까?

Docker Model Runner는 Docker Desktop과 Docker Engine에 내장된 기능으로, docker model CLI 명령어를 통해 대규모 언어 모델을 로컬에서 실행하며, llama.cpp 또는 vLLM을 추론 엔진으로 사용하고 OpenAI 호환 API를 제공합니다.

Docker Model Runner는 무료입니까?

이 기능 자체는 별도의 비용을 발생시키지 않습니다 — Docker Desktop과 Docker Engine의 일부입니다. 유료 Docker 구독이 필요한지 여부는 조직의 규모에 따라 달라집니다. Docker의 구독 서비스 계약에 따르면, Docker Desktop은 개인, 비영리 오픈소스 프로젝트, 그리고 직원 250명 미만이면서 연 매출 1,000만 달러 미만인 기업에는 무료입니다.

Docker Model Runner는 모델을 컨테이너 안에서 실행합니까?

아니요. docker model이라는 명령어 접두사에도 불구하고, 이 기능을 소개하는 Docker 공식 블로그 게시물에 따르면 추론 엔진(llama.cpp 또는 vLLM)은 컨테이너 런타임 외부에서 네이티브 호스트 프로세스로 동작합니다 — 이를 통해 컨테이너 격리를 거치지 않고 GPU 하드웨어에 직접 접근할 수 있습니다.

Docker Model Runner는 어떤 CLI 명령어를 사용합니까?

핵심 명령어는 모델을 다운로드하는 docker model pull <모델>, 명령줄에서 추론을 실행하는 docker model run <모델>, 그리고 로컬에 이미 가져온 모델을 확인하는 docker model list입니다.

Docker Model Runner의 API 엔드포인트는 무엇입니까?

OpenAI 호환 API는 호스트 머신에서는 http://localhost:12434/engines/v1(TCP 접근 활성화 후), 같은 Docker 네트워크의 다른 컨테이너에서는 http://model-runner.docker.internal/engines/v1로 제공됩니다.

Docker Model Runner는 llama.cpp를 사용합니까, vLLM을 사용합니까?

상황에 따라 둘 다 사용합니다. llama.cpp는 로컬 개발을 위한 CPU 및 Apple Silicon 추론을 담당하며, vLLM은 더 높은 처리량의 프로덕션 사용을 목표로 Linux 및 Windows WSL2에서 NVIDIA GPU 기반 서빙을 담당합니다.

Docker Model Runner는 어떤 플랫폼을 지원합니까?

Apple Silicon을 탑재한 macOS, NVIDIA GPU를 탑재한 AMD64 또는 Qualcomm Adreno 6xx 시리즈 GPU를 탑재한 ARM64의 Windows, 그리고 CPU 전용, NVIDIA CUDA, AMD ROCm, Vulkan 백엔드를 갖춘 Linux를 지원합니다. 자세한 내용은 위의 지원 플랫폼 섹션을 참고하세요.

Docker Model Runner는 Ollama와 어떻게 다릅니까?

둘 다 간단한 pull-and-run CLI와 OpenAI 호환 API 뒤에서 llama.cpp를 감싸고 있습니다. 주된 차이는 패키징 방식입니다. Ollama는 단독으로 설치하는 독립 도구인 반면, Docker Model Runner는 Docker Desktop/Engine의 기능입니다 — 이미 Docker를 매일 사용 중이라면, 워크플로에 두 번째 도구를 추가하지 않아도 되므로 더 적합합니다.

Docker Model Runner의 모델은 어디에서 옵니까?

Docker의 제품 페이지에 따르면, 모델은 Docker Hub의 선별된 AI 모델 카탈로그, 다른 OCI 호환 레지스트리, 또는 Hugging Face에서 가져올 수 있습니다.

출처

← 고급 로컬 LLM으로 돌아가기

MCP