AI 모델 Docker run 명령어와 옵션

AI 모델을 Docker run으로 실행하는 기본 명령어 구조는 무엇인가요?

Docker run 명령어는 AI 모델 이미지를 자동으로 내려받은 뒤 컨테이너를 바로 실행하는 구조로 설계되어 있습니다. 기본 형식은 docker run [옵션] 이미지:태그 [실행 명령]이며, AI 모델처럼 GPU와 포트 매핑이 필요한 경우 옵션을 조합해 한 줄로 작성합니다.

기본 실행 흐름

• 이미지가 로컬에 없으면 자동으로 pull이 진행됩니다.
• -p 옵션으로 호스트 포트와 컨테이너 포트를 연결하고, --gpus 옵션으로 GPU 자원을 지정합니다.
• -v 옵션으로 모델 파일이나 설정을 호스트와 공유하면 컨테이너 재시작 시에도 데이터가 유지됩니다.

Model Runner와 결합하는 방식

Docker Model Runner는 위 구조를 기반으로 모델을 내려받고 추론 엔진을 실행한 뒤 API를 열어 줍니다.

운영체제와 GPU, 모델 형식, 메모리 조건이 충족되면 로컬에서 바로 API 호출이 가능해집니다.

이때 docker run 한 번으로 모델 다운로드부터 API 제공까지 이어지므로 별도의 설치 스크립트가 필요 없습니다.

docker run에 주로 사용하는 -p, -it, —name 옵션은 어떻게 적용하나요?

AI 모델을 Docker로 실행할 때는 -p 옵션으로 외부 포트를 컨테이너 내부 포트에 연결하고, -it 옵션으로 대화형 터미널을 활성화하며, —name 옵션으로 컨테이너를 쉽게 식별합니다.

포트 매핑이 필요한 경우

-p 옵션은 AI 모델이 제공하는 API나 웹 인터페이스를 외부에서 접근하게 만듭니다. 예를 들어 모델이 8000번 포트에서 실행된다면 -p 8000:8000 형태로 작성하면 호스트의 8000번 포트로 요청을 전달할 수 있습니다. 포트 번호는 모델 문서에 따라 정확히 맞춰야 합니다.

대화형 실행이 필요한 경우

-it 옵션은 컨테이너 내부에서 bash나 python 셸을 바로 열어 로그를 확인하거나 디버깅할 때 사용합니다. AI 모델처럼 초기화 시간이 긴 경우 -it를 붙이면 실행 상태를 실시간으로 확인하기 편합니다.

-p, -it, —name 세 옵션을 함께 쓰면 AI 모델 컨테이너를 안정적으로 실행하고 관리하기 가장 좋습니다.

이름으로 관리하는 경우

—name 옵션은 여러 컨테이너를 동시에 운영할 때 필수입니다. docker run --name my-ai-model ...처럼 이름을 지정해 두면 docker ps나 docker stop 명령에서 바로 찾아 제어할 수 있습니다.

Docker Model Runner로 AI 모델을 로컬에서 실행하고 API를 여는 방법은?

Docker Model Runner를 사용하면 모델을 내려받고 추론 엔진을 실행해 애플리케이션이 호출할 수 있는 API를 바로 열 수 있습니다. Docker Model Runner는 플러그인과 지원 엔진을 준비한 뒤 목록 명령으로 다운로드된 모델을 확인하는 방식으로 동작합니다. 준비가 끝나면 추론 API가 열리며, 별도 인증 없이 호출할 수 있습니다.

실행 가능 여부를 결정하는 요소

• 운영체제 호환성
• GPU 지원 여부
• 모델 형식과 메모리 용량

추론 API는 인증이 없으므로 접근 가능한 네트워크를 미리 확인해야 합니다.

API 활용 방향

UI가 필요할 때는 Open WebUI를 연결하고, 애플리케이션에서는 호환 API를 직접 호출하면 됩니다. 로컬 환경에서 모델을 서비스하는 가장 간단한 경로 중 하나입니다.

실행 중인 AI 모델 컨테이너에 접속하거나 종료하려면 어떤 명령어를 사용하나요?

AI 모델이 실행 중인 컨테이너에 접속할 때는 docker exec를, 빠져나올 때는 Ctrl+P+Q를 순서대로 누르면 됩니다. attach는 정적 컨테이너에서 주로 쓰이고, exec는 데몬 방식으로 동작하는 AI 모델 컨테이너에 적합합니다.

정적 컨테이너와 데몬 컨테이너의 접속 차이

정적 컨테이너는 내부에 계속 실행되는 프로그램이 없기 때문에 attach 방식으로 연결합니다. 이 경우 -dit 옵션을 함께 사용하면 bash 셸이 유지되면서 접속이 가능해집니다.

데몬 프로세스 형태로 실행되는 AI 모델 컨테이너는 exec 명령어로 외부에서 진입합니다. nginx나 데이터베이스처럼 백그라운드에서 지속적으로 동작하는 경우에 exec가 안정적입니다.

컨테이너에서 빠져나오는 방법

Bash 셸에서 exit나 Ctrl+D를 입력하면 컨테이너 자체가 정지됩니다. 반대로 Ctrl+P 다음에 Ctrl+Q를 누르면 컨테이너를 멈추지 않고 세션만 빠져나올 수 있습니다.

Ctrl+P+Q 조합을 기억하면 AI 모델 컨테이너를 유지하면서도 안전하게 작업을 마칠 수 있습니다.

이 방식을 활용하면 모델 추론이 계속 진행되는 동안에도 필요한 순간에만 컨테이너 내부로 들어갔다 나올 수 있습니다.

Docker로 AI 모델을 실행하는 방법을 직접 따라 해보면 로컬 환경에서의 테스트가 훨씬 수월해질 거예요. 다음 포스팅에서는 Docker Compose를 활용해 여러 모델을 한 번에 관리하는 사례를 정리해 볼게요. 오늘 배운 내용이 실제 프로젝트에 도움이 되셨으면 좋겠습니다.

자주 묻는 질문

Docker run 명령어는 자동으로 이미지를 pull하나요?

네, docker run 명령어는 지정한 이미지가 로컬에 없으면 자동으로 pull을 진행합니다. 별도로 docker pull을 먼저 실행하지 않아도 컨테이너를 바로 시작할 수 있어 편리하죠. 다만 네트워크 상태에 따라 pull 시간이 달라질 수 있으니, 처음 실행할 때는 조금 기다려 보는 게 좋습니다.

Docker Model Runner 실행 가능 여부는 어떤 요소에 따라 달라지나요?

Docker Model Runner 실행 가능 여부는 운영체제, GPU 지원 여부, 모델 형식, 그리고 메모리 용량에 따라 달라집니다. GPU가 있으면 더 빠르게 추론할 수 있고, 모델 크기가 메모리를 초과하면 실행이 어렵습니다. 따라서 실행 전에 시스템 사양을 미리 확인하는 게 안전합니다.

컨테이너에서 빠져나올 때 Ctrl+P, Ctrl+Q를 쓰는 이유는 무엇인가요?

Ctrl+P, Ctrl+Q를 순서대로 누르면 컨테이너를 정지시키지 않고 빠져나올 수 있기 때문입니다. exit나 Ctrl+D를 쓰면 컨테이너가 바로 멈춰버리는데, 이 단축키는 attach 상태에서만 detach를 수행합니다. AI 모델처럼 장시간 실행해야 하는 경우에 특히 유용합니다.

정적 컨테이너와 데몬 프로세스 컨테이너 실행 시 옵션 차이는 무엇인가요?

정적 컨테이너는 -it 또는 -dit 옵션으로 bash 같은 인터랙티브 셸을 유지하며 실행하고, 데몬 프로세스 컨테이너는 exec 명령으로 외부에서 접속합니다. 정적 컨테이너는 내부에 계속 실행되는 프로그램이 없기 때문에 -dit가 필요하고, nginx나 mysql처럼 항상 돌아가는 프로그램은 exec로 관리하는 게 일반적입니다.

사용하지 않는 컨테이너와 이미지는 어떻게 정리하나요?

사용하지 않는 컨테이너와 이미지를 정리하려면 먼저 컨테이너를 중지하거나 삭제해야 이미지도 삭제할 수 있습니다. 컨테이너가 남아 있으면 이미지 삭제가 제한되기 때문에 순서를 지키는 게 중요합니다. 정리하지 않으면 디스크 용량이 부족해지는 오류가 발생할 수 있으니 주기적으로 확인하세요.

참고 자료

• Docker 명령과 로컬 API로 모델을 서비스하는 런타임aisparkup.com
• ✅ Docker 명령어 정리velog.io
• Docker Run 명령어의 기본 구조reddit.com