Ollama란 무엇인가 — Docker 컨테이너로 로컬 LLM 설치하고 API까지 사용하기

ChatGPT나 Claude처럼 외부 AI 서비스를 호출하는 대신, 자신의 PC나 서버에서 직접 대규모 언어 모델을 실행하고 싶을 때 가장 먼저 접하는 도구 중 하나가 Ollama입니다. 복잡한 추론 엔진 설정과 모델 파일 관리를 감추고 ollama run이라는 단순한 명령과 HTTP API를 제공하기 때문입니다.

 

Ollama를 운영체제에 직접 설치할 수도 있지만 Docker 컨테이너로 실행하면 설치 파일과 실행 환경을 분리하고, 버전 교체와 삭제·복구를 일관된 방식으로 관리할 수 있습니다. 반면 GPU 연결과 모델 데이터 영속화, 네트워크 노출은 컨테이너 환경에서 따로 이해해야 합니다.

 

이 글에서는 Ollama의 역할과 내부 구조를 먼저 살펴본 다음 CPU, NVIDIA GPU, AMD GPU 환경에서 컨테이너로 설치하는 방법을 단계별로 설명합니다. 모델 다운로드, REST API, OpenAI 호환 API, Docker Compose 구성과 운영 보안까지 한 번에 정리합니다.

Ollama란 무엇인가

Ollama는 로컬 또는 자체 서버에서 생성형 AI 모델을 내려받고 실행할 수 있게 해주는 모델 실행·관리 도구입니다. 사용자는 추론 엔진의 세부 옵션을 매번 조합하는 대신 모델 이름을 지정해 실행하고, CLI나 HTTP API로 대화할 수 있습니다.

 

Ollama가 담당하는 주요 기능은 다음과 같습니다.

• 모델 Registry에서 모델 Manifest와 Layer 다운로드
• 로컬 모델 파일과 버전 관리
• 하드웨어에 맞는 CPU·GPU 추론 Backend 선택
• 모델 Load·Unload와 메모리 유지 시간 관리
• Text Generation, Chat, Embedding, Vision과 Tool Calling API 제공
• Modelfile을 이용한 System Prompt와 Parameter 기반 사용자 모델 구성
• OpenAI API 일부와 호환되는 Endpoint 제공

Ollama 자체가 ChatGPT 같은 완성형 웹 채팅 서비스는 아닙니다. 모델을 실행하고 API를 제공하는 Model Runtime과 Model Server에 가깝습니다. 브라우저 UI가 필요하면 별도의 Web UI를 연결하고, RAG나 Agent가 필요하면 애플리케이션 계층을 추가해야 합니다.

그림: Ollama의 기본 구성과 요청 처리 흐름 · Ollama API, Docker 설치 문서를 바탕으로 재구성

Ollama와 vLLM은 같은 도구인가

둘 다 모델을 실행하지만 지향점이 다릅니다. Ollama는 개인 개발 환경과 소규모 자체 호스팅에서 모델을 쉽게 받고 실행하는 경험에 강점이 있습니다. vLLM은 다수 사용자의 요청을 높은 처리량으로 제공하는 Model Serving과 GPU 활용 최적화에 더 초점을 둡니다.

구분	Ollama	vLLM
주 사용 목적	로컬 개발, 개인·팀 단위 모델 실행	고처리량 GPU Model Serving
시작 난이도	모델 이름만으로 쉽게 실행	모델·GPU·Serving 옵션 설계 필요
모델 관리	Pull·List·Run 통합	Hugging Face 등 외부 모델 경로 중심
API	Ollama Native API + OpenAI 일부 호환	OpenAI 호환 Serving 중심
확장 관점	단일 호스트와 간단한 서비스에 적합	병렬 처리와 서버급 운영에 적합

따라서 “개발자가 로컬 모델을 빠르게 사용한다”면 Ollama가 편하고, “많은 사용자가 동시에 쓰는 GPU 추론 API를 운영한다”면 vLLM이나 전용 Serving Platform을 함께 비교해야 합니다.

컨테이너로 설치하면 무엇이 달라지는가

컨테이너는 Ollama 실행 파일과 라이브러리를 Image 안에 넣고 Host와 분리해 실행합니다. 하지만 모델 파일까지 컨테이너의 임시 Filesystem에 저장하면 컨테이너를 교체할 때 수 GB에서 수십 GB의 모델을 잃을 수 있습니다.

 

그래서 Ollama 컨테이너는 세 가지 연결이 핵심입니다.

Host의 11434 Port
→ Ollama Container의 11434 Port

Named Volume ollama_data
→ Container의 /root/.ollama

Host GPU Device 또는 GPU Runtime
→ Container의 추론 Backend

그림: Ollama 컨테이너 설치에서 반드시 연결해야 하는 구성 요소 · Ollama Docker 공식 문서를 바탕으로 재구성

컨테이너를 삭제해도 Named Volume이 남아 있으면 새 컨테이너가 기존 모델을 그대로 사용할 수 있습니다. 반대로 -v ollama:/root/.ollama를 빼면 모델은 컨테이너 수명에 종속됩니다.

설치 전 준비 사항

먼저 Docker Engine 또는 Docker Desktop이 설치되어 있어야 합니다.

docker version

GPU를 사용할 계획이라면 운영체제와 GPU 종류를 먼저 확인합니다.

# NVIDIA GPU
nvidia-smi

# AMD ROCm 환경
rocminfo

모델의 Parameter 수와 Quantization에 따라 메모리 요구량이 크게 달라집니다. 모델 파일이 4GB라고 해서 VRAM도 정확히 4GB만 필요한 것은 아닙니다. Model Weight 외에도 KV Cache와 Runtime Buffer가 필요하고 Context Length를 늘릴수록 추가 메모리가 사용됩니다.

 

처음에는 자신의 RAM 또는 VRAM보다 충분히 작은 모델로 설치 흐름을 검증하는 편이 좋습니다. 구체적인 모델 크기와 Tag는 Ollama Model Library에서 확인할 수 있습니다.

1단계: CPU 전용 컨테이너 실행

GPU 없이 기능부터 확인하려면 다음 명령으로 시작할 수 있습니다.

docker run -d \
  --name ollama \
  --restart unless-stopped \
  -p 127.0.0.1:11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama:latest

공식 문서는 -p 11434:11434를 사용하지만, 이 형식은 Docker 설정에 따라 Host의 모든 Network Interface에 Port를 공개할 수 있습니다. 이 글에서는 로컬 사용을 기본으로 하므로 127.0.0.1에만 Bind했습니다.

 

각 옵션의 의미는 다음과 같습니다.

옵션	의미
-d	Background에서 컨테이너 실행
--name ollama	컨테이너 이름을 ollama로 지정
--restart unless-stopped	사용자가 중지하지 않았다면 Docker 재시작 후 자동 실행
-p 127.0.0.1:11434:11434	Host의 Localhost Port를 컨테이너 API Port에 연결
-v ollama_data:/root/.ollama	모델과 설정을 Named Volume에 영구 저장
ollama/ollama:latest	공식 Ollama Image 사용

운영 환경에서는 latest 대신 검증한 Version Tag나 Image Digest를 고정하는 것이 안전합니다. latest는 다시 배포하는 시점에 다른 Version을 가져올 수 있기 때문입니다.

 

컨테이너 상태와 Log를 확인합니다.

docker ps --filter name=ollama
docker logs --tail 100 ollama

API가 응답하는지 확인합니다.

curl http://localhost:11434/api/version

2단계: 모델 다운로드와 첫 실행

공식 Docker 문서는 다음과 같이 컨테이너 안에서 CLI를 실행하는 방법을 안내합니다.

docker exec -it ollama ollama run llama3.2

모델이 없으면 먼저 내려받고, 다운로드가 끝나면 바로 대화 Prompt가 열립니다. 대화를 종료한 뒤 모델 목록을 확인할 수 있습니다.

docker exec ollama ollama list

모델 다운로드와 실행을 분리하고 싶다면 다음처럼 사용합니다.

docker exec ollama ollama pull llama3.2
docker exec -it ollama ollama run llama3.2

API로도 모델을 받을 수 있습니다.

curl http://localhost:11434/api/pull \
  -H 'Content-Type: application/json' \
  -d '{"model":"llama3.2","stream":false}'

Model Pull은 큰 Network Traffic과 Disk 사용량을 발생시킵니다. 여러 컨테이너가 같은 Model Volume을 동시에 수정하도록 구성하기보다 하나의 Ollama Instance가 Volume을 관리하도록 하는 편이 단순합니다.

3단계: Ollama Native API 호출

Ollama의 기본 API Base URL은 http://localhost:11434/api입니다. Chat Endpoint에 stream:false를 주면 한 번의 JSON Response를 받을 수 있습니다.

curl http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "llama3.2",
    "messages": [
      {"role": "user", "content": "컨테이너의 장점을 세 문장으로 설명해줘"}
    ],
    "stream": false
  }'

stream의 기본값은 true입니다. 이 경우 완성된 JSON 하나가 아니라 생성 과정이 여러 JSON Object로 순차 전달됩니다. CLI에서는 자연스럽지만 일반적인 JSON Parser에 바로 넣으면 오류로 보일 수 있으므로 애플리케이션 방식에 맞게 설정해야 합니다.

 

Response에는 답변뿐 아니라 Model Load 시간, Prompt Token 수, 생성 Token 수와 추론 시간도 포함됩니다. 이를 이용하면 다음과 같은 대략적인 생성 속도를 계산할 수 있습니다.

초당 생성 Token
= eval_count / (eval_duration / 1,000,000,000)

4단계: OpenAI SDK와 연결

Ollama는 OpenAI API의 일부와 호환되는 /v1 Endpoint도 제공합니다. 기존 OpenAI Client의 base_url을 바꾸면 Ollama Model을 호출할 수 있습니다.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",
)

response = client.chat.completions.create(
    model="llama3.2",
    messages=[
        {"role": "user", "content": "Ollama를 한 문장으로 설명해줘"}
    ],
)

print(response.choices[0].message.content)

공식 문서 예제의 api_key="ollama"는 OpenAI SDK가 값을 요구하기 때문에 넣는 Placeholder이고, Local Ollama API가 이 값을 인증하는 것은 아닙니다. Ollama 공식 문서에 따르면 localhost:11434의 Local API에는 인증이 필요하지 않습니다.

 

“OpenAI 호환”도 모든 기능이 완전히 같다는 뜻은 아닙니다. 사용하는 Endpoint, Tool Calling, Vision, Structured Output와 Streaming이 대상 Model에서 실제로 동작하는지 확인해야 합니다.

NVIDIA GPU로 실행하기

Linux 또는 Windows WSL2에서 NVIDIA GPU를 컨테이너에 연결하려면 Host에 NVIDIA Driver와 NVIDIA Container Toolkit이 필요합니다. 설치 방법은 운영체제마다 다르므로 NVIDIA Container Toolkit 공식 설치 문서를 따라야 합니다.

 

Toolkit 설치 후 Docker Runtime을 구성하고 Docker를 재시작합니다.

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

GPU가 컨테이너에서 보이는지 먼저 확인합니다.

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

그다음 Ollama를 GPU Option과 함께 실행합니다.

docker run -d \
  --name ollama \
  --restart unless-stopped \
  --gpus all \
  -p 127.0.0.1:11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama:latest

여러 GPU 중 일부만 사용하려면 Host의 GPU UUID를 확인하고 CUDA_VISIBLE_DEVICES를 제한할 수 있습니다. Ollama 공식 하드웨어 문서는 숫자 Index보다 UUID가 더 안정적이라고 안내합니다.

nvidia-smi -L

GPU Offload 여부는 모델을 한 번 실행한 뒤 확인합니다.

docker exec ollama ollama ps

PROCESSOR가 100% GPU인지, 일부 CPU Offload가 발생했는지 확인합니다. Model과 Context가 VRAM보다 크면 일부 연산이 CPU로 넘어가 속도가 크게 느려질 수 있습니다.

AMD GPU로 실행하기

AMD ROCm을 사용할 때는 공식 rocm Tag와 GPU Device를 전달합니다.

docker run -d \
  --name ollama \
  --restart unless-stopped \
  --device /dev/kfd \
  --device /dev/dri \
  -p 127.0.0.1:11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama:rocm

지원 GPU와 필요한 ROCm Driver Version은 Ollama의 Hardware Support 문서에서 확인해야 합니다. 일부 Linux 배포판은 SELinux가 Container의 GPU Device 접근을 차단할 수 있으므로 Permission 오류가 나면 Audit Log와 Container Device 정책도 확인합니다.

 

최근 공식 Image에는 접근 가능한 Device가 있을 때 사용할 수 있는 Vulkan Backend도 포함됩니다. Vulkan과 ROCm 중 어느 쪽이 더 안정적인지는 GPU와 Driver 조합에 따라 다르므로 동일한 Model과 Prompt로 실제 성능과 오류를 비교해야 합니다.

그림: 컨테이너 환경별 Ollama 가속 경로 · Ollama Docker, Hardware Support 문서를 바탕으로 재구성

macOS Docker에서는 GPU를 사용할 수 있을까

중요한 제한이 있습니다. Ollama 공식 FAQ는 macOS의 Docker Desktop에서는 GPU Passthrough와 Emulation 제약 때문에 Ollama GPU 가속을 사용할 수 없다고 안내합니다.

 

Apple Silicon의 Metal GPU를 활용하려면 Ollama macOS App 또는 Native 설치를 사용하는 편이 적합합니다. 컨테이너 격리가 꼭 필요하면 Docker에서는 CPU로 실행되며, Native Ollama Server를 Host에서 실행하고 다른 Container가 host.docker.internal:11434로 접근하도록 구성하는 방법을 검토할 수 있습니다.

 

이때 Native Server를 외부에 Bind하면 인증 없는 API가 Network에 노출될 수 있습니다. Host Firewall과 Reverse Proxy 인증을 함께 설계해야 합니다.

Docker Compose로 관리하기

반복 실행과 설정 관리를 위해 다음과 같은 compose.yaml을 사용할 수 있습니다.

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "127.0.0.1:11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      OLLAMA_KEEP_ALIVE: "5m"
    healthcheck:
      test: ["CMD", "ollama", "list"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  ollama_data:

실행과 상태 확인은 다음과 같습니다.

docker compose up -d
docker compose ps
docker compose logs -f ollama

NVIDIA GPU를 Compose에서 예약하려면 ollama Service에 다음 설정을 추가할 수 있습니다. Docker Compose Version이 GPU Device Reservation을 지원하는지 먼저 확인해야 합니다.

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

같은 Compose Network의 다른 Service가 Ollama를 호출한다면 Host에 Port를 공개할 필요가 없습니다.

Web UI Container
→ http://ollama:11434
→ Ollama Container

이 경우 ports를 제거하고 내부 Network에서 Service 이름 ollama를 사용하면 공격 표면을 줄일 수 있습니다.

모델과 메모리 운영 이해하기

Ollama는 기본적으로 사용이 끝난 Model을 일정 시간 메모리에 유지해 다음 요청의 Load 시간을 줄입니다. 공식 FAQ의 기본값은 5분이며 OLLAMA_KEEP_ALIVE 또는 API의 keep_alive로 조정할 수 있습니다.

environment:
  OLLAMA_KEEP_ALIVE: "10m"

항상 메모리에 유지하면 첫 Token 지연은 줄지만 다른 Model이 들어갈 VRAM이 부족해질 수 있습니다. 여러 Model을 번갈아 쓰는 작은 GPU에서는 짧게 유지하고, 하나의 Model에 요청이 집중되면 길게 유지하는 방식으로 조정합니다.

 

Context Length도 메모리에 큰 영향을 줍니다. Ollama는 VRAM에 따라 기본 Context를 다르게 정하고, 긴 Context를 설정할수록 KV Cache가 커집니다. Agent나 Coding 작업 때문에 Context를 늘릴 때는 단순히 Model이 Load되는지만 보지 말고 실제 긴 Prompt에서 VRAM과 Token 속도를 측정해야 합니다.

docker exec ollama ollama ps
docker stats ollama

Update와 Backup

Named Volume을 사용했다면 Container Image를 교체해도 Model 데이터는 유지됩니다. Compose에서는 다음 순서로 Update할 수 있습니다.

docker compose pull
docker compose up -d

운영 환경에서는 먼저 새 Version을 별도 환경에서 검증하고 Version Tag 또는 Digest를 변경해야 합니다. API가 대체로 하위 호환을 지향하더라도 Ollama 공식 문서는 API가 엄격하게 Versioning되는 것은 아니라고 설명합니다.

 

Volume 자체는 Backup 정책에 포함해야 합니다. 다만 공개 Registry에서 언제든 다시 받을 수 있는 Model Layer와 직접 만든 Modelfile·Private Model의 중요도는 다릅니다. 복구 시간을 줄여야 한다면 전체 Volume을 Backup하고, 저장 비용을 줄여야 한다면 사용자 정의 자산과 구성 정보를 우선 보존합니다.

외부 공개 전에 반드시 알아야 할 보안 사항

Local Ollama API에는 기본 인증이 없습니다. 따라서 다음과 같은 구성은 피해야 합니다.

Internet
→ 0.0.0.0:11434
→ 인증 없는 Ollama API

공격자가 API에 접근하면 Model을 반복 호출해 CPU·GPU와 Memory를 소모하고, Model Pull로 Disk와 Network를 사용하거나 운영자가 의도하지 않은 Model에 접근할 수 있습니다.

 

외부나 사내 Network에 제공해야 한다면 Ollama 앞에 Reverse Proxy 또는 API Gateway를 두고 다음 통제를 적용합니다.

• TLS와 사용자·Service 인증
• IP·Network Allowlist
• 사용자별 Rate Limit과 동시 요청 수 제한
• 허용 Model 목록과 Endpoint 제한
• Request Body 크기와 Timeout 제한
• Prompt·Response Log의 개인정보 Masking
• Model Pull·Create·Delete 같은 관리 API 분리
• Container CPU·Memory와 GPU 사용량 Monitoring

단순히 OLLAMA_HOST=0.0.0.0:11434를 설정하는 것은 접근 허용 범위를 넓힐 뿐 인증을 추가하지 않습니다.

자주 발생하는 문제

API는 열렸는데 응답이 너무 느리다

CPU로 실행 중이거나 일부 Layer가 CPU로 Offload되었을 수 있습니다.

docker exec ollama ollama ps
docker stats ollama

Model을 줄이거나 Context Length를 낮추고, GPU Runtime과 Driver가 Container에 정상적으로 전달되는지 확인합니다.

컨테이너를 다시 만들었더니 모델이 사라졌다

/root/.ollama에 Volume을 Mount하지 않았거나 다른 Volume 이름을 사용했을 가능성이 큽니다.

docker volume ls
docker inspect ollama

삭제 전에 현재 Mount와 Volume 이름을 확인해야 합니다.

다른 컨테이너에서 localhost:11434가 연결되지 않는다

Container 안의 localhost는 그 Container 자신입니다. 같은 Docker Network에서는 Ollama Service 이름을 사용합니다.

http://ollama:11434

Host에서 실행하는 Ollama에 Docker Desktop Container가 접근한다면 host.docker.internal을 사용할 수 있습니다.

브라우저에서 CORS 오류가 발생한다

Ollama는 허용 Origin을 OLLAMA_ORIGINS로 추가할 수 있습니다. 모든 Origin을 무조건 허용하기보다 실제 Web UI의 Origin만 지정해야 합니다. CORS는 브라우저 정책이며 API 인증을 대신하지 않습니다.

Ollama 컨테이너가 적합한 경우와 아닌 경우

Ollama Container는 다음 상황에 잘 맞습니다.

• 개발자 PC나 팀 서버에서 여러 Model을 빠르게 시험할 때
• 외부 API로 보내기 어려운 문서를 Local Model로 처리할 때
• RAG·Agent·AI Gateway 개발을 위한 내부 Model Endpoint가 필요할 때
• 동일한 설정을 여러 Linux Server에서 재현할 때

반대로 다음 요구사항이 핵심이면 다른 Serving Stack도 비교해야 합니다.

• 수많은 동시 사용자의 높은 Throughput
• 여러 GPU와 여러 Node를 이용한 분산 Serving
• 자동 확장, Rolling Update와 정교한 Request Scheduling
• 엄격한 Multi-tenancy와 Model별 SLA
• Kubernetes 기반 대규모 GPU Pool 운영

Ollama 앞에 API Gateway를 두면 인증과 Rate Limit은 보완할 수 있지만, Runtime 자체가 대규모 분산 Serving Platform으로 바뀌는 것은 아닙니다.

마무리

Ollama는 모델 다운로드, 실행, 메모리 관리와 API 제공을 하나의 사용 경험으로 묶어 로컬 LLM의 진입 장벽을 낮춘 도구입니다. Docker로 실행할 때 핵심은 복잡하지 않습니다.

공식 Image 실행
→ 11434 Port 연결
→ /root/.ollama Volume 영속화
→ 필요하면 NVIDIA·AMD GPU 연결
→ Model Pull
→ Native 또는 OpenAI 호환 API 호출

가장 간단한 CPU 설치는 한 줄로 끝나지만 실제 운영에서는 세 가지를 놓치면 안 됩니다. Model Volume을 영속화하고, GPU가 실제로 사용되는지 확인하며, 인증 없는 11434 Port를 외부에 직접 공개하지 않는 것입니다.

 

macOS에서 Docker를 사용할 때는 GPU 가속이 되지 않는다는 점도 중요합니다. Apple GPU를 활용하려면 Native Ollama를 사용하고, Linux·WSL2의 NVIDIA 환경에서는 NVIDIA Container Toolkit을 구성해야 합니다.

 

처음에는 작은 Model과 Localhost Binding으로 기능을 검증하고, 이후 Model 크기·Context·동시 요청·보안 요구사항을 측정하면서 자신의 환경에 맞는 구성으로 확장하는 것이 가장 안전합니다.

참고 자료

• Ollama Docker 공식 문서
• Ollama API 소개
• Ollama Chat API
• Ollama Model Pull API
• Ollama OpenAI 호환 API
• Ollama 인증 안내
• Ollama Hardware Support
• Ollama Context Length
• Ollama Model Library