Ollama 완벽 가이드: 기본 사용법, 파라미터 튜닝 및 Modelfile 활용법

📌 Executive Summary

• 초간편 로컬 LLM 환경: Ollama는 Llama 3, Gemma, Mistral, Qwen 등 오픈소스 대형 언어 모델을 단일 명령어로 다운로드하고 CPU/GPU에서 즉시 실행할 수 있는 경량 프레임워크입니다.
• 세밀한 커스터마이징: Modelfile을 통해 시스템 프롬프트 부여, LoRA 어댑터 결합, 그리고 temperature, top_p, num_ctx 등 추론 파라미터를 맞춤 튜닝한 커스텀 모델을 생성할 수 있습니다.
• 손쉬운 애플리케이션 연동: 표준 REST API(http://localhost:11434) 및 OpenAI 호환 엔드포인트를 제공하여 기존 파이프라인이나 서비스 백엔드에 즉시 통합 가능합니다.

📊 리포트 개요

🔍 핵심 분석

1. Ollama 개요 및 서버 실행

Ollama는 복잡한 인공지능 모델 빌드나 드라이버 세팅 없이도 로컬 환경에서 오픈소스 LLM을 손쉽게 구동할 수 있도록 패키징된 도구입니다.

• GPU 가속 및 CPU 폴백: NVIDIA CUDA, Apple Silicon(Metal), AMD ROCm을 자동 감지하며, 전용 GPU가 없는 환경에서는 CPU로 자동 실행됩니다.
• 백그라운드 서비스 시작: 설치 후 터미널에서 다음 명령으로 서버를 구동합니다.

# 기본 백그라운드 서버 구동 (포트: 11434)
ollama serve

# 디버그 상세 로그 모드로 서버 구동
OLLAMA_DEBUG=1 ollama serve

2. 기본 CLI 명령어 완벽 가이드

Ollama는 Docker 스타일의 친숙하고 직관적인 CLI 명령어를 제공합니다.

💡 실행 방식별 예제

# 1. 모델 다운로드
ollama pull llama3.2
ollama pull qwen2.5-coder:7b

# 2. 대화형 인터랙티브 셸 실행
ollama run llama3.2

# 3. 일회성 프롬프트 즉시 실행 (인라인 전달)
ollama run llama3.2 "Python으로 빠른 정렬(Quick Sort) 알고리즘을 작성해줘."

# 4. 파이프라인 및 파일 리다이렉션 활용
cat document.txt | ollama run llama3.2 "이 텍스트의 핵심 내용을 3줄로 요약해줘."
ollama run llama3.2 "AI 기술 트렌드 5가지" > trend_report.txt

3. Modelfile 작성 및 모델 커스터마이징

Modelfile은 Dockerfile과 유사한 문법으로 베이스 모델에 시스템 프롬프트, 템플릿, 추론 파라미터, LoRA 어댑터를 패키징하여 새로운 커스텀 모델을 정의하는 설정 파일입니다.

주요 지시문 (Directives)

커스텀 한국어 비서 모델 작성 예시 (Modelfile-korean)

# 1. 베이스 모델 지정
FROM llama3.2

# 2. 시스템 프롬프트 (페르소나 및 응답 규칙)
SYSTEM """
당신은 한국어 비즈니스 문서 및 개발 관련 질의응답을 지원하는 전문 AI 어시스턴트입니다.
항상 정중하고 친절한 어조로 답변하며, 기술적 질문에는 명확한 코드 예시를 함께 제공하세요.
"""

# 3. 추론 파라미터 최적화
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER top_k 40
PARAMETER num_ctx 4096
PARAMETER repeat_penalty 1.1

커스텀 모델 빌드 및 실행

# Modelfile을 기반으로 커스텀 모델 'korean-assistant' 생성
ollama create korean-assistant -f ./Modelfile-korean

# 생성된 커스텀 모델 실행
ollama run korean-assistant "서울 3대 궁궐의 역사와 특징에 대해 알려줘."

4. 핵심 추론 파라미터 (Parameters) 상세 가이드

생성 품질과 답변 성향을 결정하는 주요 파라미터 목록입니다.

💡 용도별 파라미터 추천 프리셋

• 코드 생성 & 사실 질의 (정확도 우선): temperature: 0.2, top_p: 0.5, repeat_penalty: 1.15
• 일반 대화 & 요약 (균형 잡힌 모드): temperature: 0.7, top_p: 0.9, repeat_penalty: 1.1
• 창작 & 브레인스토밍 (다양성 우선): temperature: 0.95, top_p: 0.95, repeat_penalty: 1.05

5. REST API 연동 가이드

Ollama는 기본적으로 http://localhost:11434 포트에서 REST API를 제공하여 백엔드, 프론트엔드, 스크립트 등에서 쉽게 호출할 수 있습니다.

엔드포인트 개요

• POST /api/generate: 단일 프롬프트 텍스트 생성
• POST /api/chat: 멀티턴 대화형 메시지 생성 (Chat completions)
• GET /api/tags: 로컬 설치 모델 목록 조회

cURL 호출 예제

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "왜 하늘은 파란색인가요?",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "num_ctx": 4096
  }
}'

Python (requests 및 OpenAI SDK 호환)

# OpenAI 호환 라이브러리를 활용한 연동
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": "system", "content": "친절한 개발 도우미입니다."},
        {"role": "user", "content": "REST API와 GraphQL의 차이점을 설명해줘."}
    ],
    temperature=0.7
)

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

6. 주요 모델 라인업 및 권장 활용 사례

🎯 결론 및 실무 권장사항

1. 손쉬운 시작: ollama pull <모델명>과 ollama run <모델명> 두 가지만으로도 로컬 AI 환경 구축이 즉시 완료됩니다.
2. 커스텀 모델 패키징: 실무 환경에서는 단순 프롬프트 입력 대신 Modelfile을 작성하여 팀 전용 시스템 프롬프트와 파라미터(num_ctx, temperature)를 고정 생성하는 방식을 권장합니다.
3. API 연동성: OpenAI 호환 엔드포인트(/v1)를 지원하므로, 기존 LangChain, LlamaIndex, Dify 등 다양한 LLM 프레임워크와 무수정 연동이 가능합니다.

⚠️ 한계 및 주의사항

• 하드웨어 메모리(VRAM) 관리: num_ctx(컨텍스트 창)를 과도하게 크게 잡으면(예: 32K 이상) 메모리 부족(OOM) 오류가 발생하거나 추론 속도가 급격히 저하될 수 있습니다.
• 모델별 권장 파라미터 상이: 모델 아키텍처(Llama 계열 vs Qwen 계열 vs Phi 계열)에 따라 기본 최적 temperature 및 템플릿 형식이 다르므로 사전 테스트가 필요합니다.
• 최신 릴리즈 확인: Ollama는 잦은 버전 업데이트를 통해 새로운 아키텍처(Gemma 2, Llama 3.2 Vision 등)와 기능이 추가되므로, 주기적으로 ollama --version을 확인하고 업데이트하는 것이 좋습니다.

📚 수집 소스 및 참고 자료

• Ollama 공식 웹사이트 및 모델 라이브러리
• Ollama 사용법 - AI Vibe Coding 가이드 /with MINZKN
• Ollama 명령어 완벽 정리 — 설치부터 커스텀 모델, API 연동까지
• Ollama란? Ollama 사용법 : 내 PC에서 무료로 LLM 실행하기
• vLLM & Ollama 완벽 가이드 : LLM 서빙 엔진의 구동, 파라미터 비교
• Ollama 로컬 LLM 실행 완벽 가이드 — 설치부터 API 연동까지 | TechFeed