Day 06 — Ollama: 가장 간단한 로컬 LLM 실행

Phase 2: 로컬 LLM | 예상 학습 시간: 40분

🎯 학습 목표

• Ollama로 로컬에서 LLM을 설치, 실행, 커스터마이징할 수 있다
• Ollama의 REST API를 사용해 애플리케이션에서 로컬 모델을 호출할 수 있다
• Ollama와 vLLM 중 상황에 맞는 도구를 선택하는 기준을 이해한다

1. Ollama란

Ollama는 로컬 환경(개인 PC, 서버)에서 오픈소스 LLM을 손쉽게 다운로드하고 실행할 수 있게 해주는 도구입니다. 내부적으로 llama.cpp를 엔진으로 사용하며, 모델 다운로드·양자화 버전 관리·REST API 서버·CLI를 하나로 통합해 “가장 진입장벽이 낮은 로컬 LLM 실행 도구"로 자리잡았습니다.

Docker와 비슷한 사용 경험을 목표로 설계되었습니다 — docker pull처럼 ollama pull, docker run처럼 ollama run을 사용합니다.

# macOS / Linux 설치
curl -fsSL https://ollama.com/install.sh | sh

# 설치 확인
ollama --version

2. 기본 명령어 — pull, run, serve

# 모델 다운로드 (기본 태그는 보통 4-bit 양자화 버전)
ollama pull llama3.1:8b

# 모델 다운로드 + 대화형 실행 (없으면 자동으로 pull)
ollama run llama3.1:8b

# 백그라운드에서 API 서버로 실행 (기본 포트 11434)
ollama serve

# 로컬에 다운로드된 모델 목록 확인
ollama list

# 현재 메모리에 로드되어 실행 중인 모델 확인
ollama ps

# 모델 삭제
ollama rm llama3.1:8b

ollama run 안에서는 대화형으로 프롬프트를 주고받을 수 있고, /bye로 종료합니다. 대부분의 배포판(macOS 앱, systemd 서비스)은 설치 시 ollama serve가 자동으로 백그라운드 데몬으로 등록되어 별도 실행 없이도 API가 열려 있습니다.

💡 실무 팁: ollama pull llama3.1:8b처럼 태그를 명시하지 않으면 기본적으로 :latest가 아니라 모델별로 지정된 기본 양자화 버전(대개 Q4_0 계열)이 받아집니다. 태그 뒤에 -q8_0, -fp16 등을 붙여 정밀도를 직접 지정할 수 있습니다 (예: ollama pull llama3.1:8b-instruct-q8_0).

3. Modelfile — 모델 커스터마이징

Ollama는 Dockerfile과 유사한 개념인 Modelfile로 시스템 프롬프트, 파라미터, 베이스 모델을 정의해 나만의 커스텀 모델을 만들 수 있습니다.

# Modelfile
FROM llama3.1:8b

# 생성 파라미터 조정
PARAMETER temperature 0.3
PARAMETER num_ctx 8192
PARAMETER top_p 0.9

# 시스템 프롬프트 고정
SYSTEM """
당신은 한국어로만 답하는 친절한 AI 엔지니어링 튜터입니다.
코드 예제는 항상 주석과 함께 제공하세요.
"""

# Modelfile로부터 커스텀 모델 생성
ollama create my-tutor -f ./Modelfile

# 생성한 모델 실행
ollama run my-tutor

주요 PARAMETER 옵션:

4. REST API — 애플리케이션에서 호출하기

Ollama는 설치 즉시 http://localhost:11434에서 REST API를 제공하므로, 별도 서버 코드 없이 바로 애플리케이션에 통합할 수 있습니다.

# 기본 생성 API (스트리밍 기본 활성화)
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1:8b",
  "prompt": "Transformer의 attention을 한 문장으로 설명해줘",
  "stream": false
}'

# 대화형(chat) API — 메시지 히스토리 형식 지원
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.1:8b",
  "messages": [
    {"role": "system", "content": "당신은 친절한 AI 튜터입니다."},
    {"role": "user", "content": "KV 캐시가 왜 필요한가요?"}
  ],
  "stream": false
}'

Python에서는 공식 클라이언트 라이브러리로 더 간단히 호출할 수 있습니다.

import ollama

response = ollama.chat(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "vLLM과 Ollama의 차이를 요약해줘"}],
)
print(response["message"]["content"])

또한 Ollama는 OpenAI SDK와 호환되는 엔드포인트(/v1/chat/completions)도 제공해, 기존에 OpenAI API용으로 작성된 코드를 baseURL만 바꿔서 그대로 재사용할 수 있습니다.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)

5. 양자화 레벨 — Ollama가 제공하는 선택지

Ollama의 모델 라이브러리는 대부분 GGUF 포맷의 다양한 양자화 버전을 태그로 제공합니다.

# 특정 양자화 버전을 명시해서 다운로드
ollama pull llama3.1:8b-instruct-q4_K_M
ollama pull llama3.1:8b-instruct-q8_0

💡 실무 팁: VRAM이 넉넉하지 않은 개인 GPU(8~16GB)에서는 q4_K_M이 품질/용량 균형의 사실상 기본 선택지입니다. 정확도가 중요한 작업(코드 생성, 수치 추론)에서는 q8_0 이상을 고려하되, VRAM 여유를 반드시 계산해야 합니다 (Day 03의 VRAM 어림 공식 참고).

6. Ollama vs vLLM — 언제 무엇을 쓸까

Ollama와 vLLM은 둘 다 로컬/자체 인프라에서 LLM을 서빙하지만, 설계 목표가 다릅니다.

💡 실무 팁: “로컬에서 빠르게 아이디어를 검증하고 싶다"면 Ollama, “실제 트래픽을 받는 API 서버를 GPU 클러스터에 배포해야 한다"면 vLLM으로 넘어가는 것이 자연스러운 흐름입니다. 다음 시간(Day 07)에 vLLM을 자세히 다룹니다.

📝 핵심 요약

1. Ollama는 llama.cpp를 엔진으로 한 원커맨드 로컬 LLM 실행 도구로, Docker와 유사한 CLI 경험을 제공한다
2. Modelfile로 시스템 프롬프트, temperature, context 크기 등을 정의해 커스텀 모델을 만들 수 있다
3. localhost:11434의 REST API와 OpenAI 호환 엔드포인트로 기존 코드에 쉽게 통합 가능하다
4. GGUF 양자화 태그(q4_K_M, q8_0 등)로 품질/VRAM 트레이드오프를 직접 선택할 수 있다
5. Ollama는 개인/개발 환경, vLLM은 고처리량 프로덕션 서빙에 적합하다

🔗 참고 자료

• Ollama 공식 문서
• Ollama GitHub 저장소
• Ollama API Reference

⬅️ 이전: Day 05 — Token / Embedding / Context Window / KV Cache | 다음: Day 07 — vLLM 고성능 추론 서버 구축 ➡️