Ollama 아키텍처 분석 보고서 / 실사용 시나리오 Q&A

╔══════════════════════════════════════════════════════════════════╗
║                        Ollama System                             ║
║                                                                  ║
║  ┌──────────────────────────────────────────────────────────┐   ║
║  │                    CLI Layer (Cobra)                      │   ║
║  │  ollama run / pull / push / create / list / show / serve  │   ║
║  └──────────────────────┬───────────────────────────────────┘   ║
║                         │                                         ║
║  ┌──────────────────────▼───────────────────────────────────┐   ║
║  │              HTTP Server (Gin + CORS)                     │   ║
║  │         127.0.0.1:11434  (OLLAMA_HOST 설정 가능)          │   ║
║  │                                                           │   ║
║  │   OpenAI Compatibility   Anthropic Compatibility          │   ║
║  │   Middleware             Middleware                       │   ║
║  └──────────────────────┬───────────────────────────────────┘   ║
║                         │                                         ║
║  ┌──────────────────────▼───────────────────────────────────┐   ║
║  │                   Route Handlers                          │   ║
║  │  ChatHandler / GenerateHandler / EmbedHandler             │   ║
║  │  PullHandler / PushHandler / CreateHandler                │   ║
║  └──────────────────────┬───────────────────────────────────┘   ║
║                         │ scheduleRunner()                        ║
║  ┌──────────────────────▼───────────────────────────────────┐   ║
║  │                   Scheduler                               │   ║
║  │  - 모델 로딩/언로딩 관리                                   │   ║
║  │  - VRAM 기반 Eviction                                     │   ║
║  │  - Reference Counting                                     │   ║
║  │  - Keep-Alive 타이머                                      │   ║
║  └──────────────────────┬───────────────────────────────────┘   ║
║                         │ spawn process                           ║
║  ┌──────────────────────▼───────────────────────────────────┐   ║
║  │               Runner Process (별도 프로세스)               │   ║
║  │                                                           │   ║
║  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │   ║
║  │  │LlamaRunner  │  │OllamaRunner │  │ImageGen Runner  │  │   ║
║  │  │(llama.cpp)  │  │(Go native)  │  │(diffusion)      │  │   ║
║  │  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘  │   ║
║  │         └────────────────┴──────────────────┘           │   ║
║  │                          │                                │   ║
║  │               GGML Backend (GPU/CPU)                      │   ║
║  │           CUDA  /  ROCm  /  Metal  /  CPU                │   ║
║  └──────────────────────────────────────────────────────────┘   ║
║                                                                  ║
║  ┌──────────────────────────────────────────────────────────┐   ║
║  │              Model Storage (Content-Addressable)          │   ║
║  │   ~/.ollama/models/manifests/ + blobs/sha256-[digest]    │   ║
║  └──────────────────────────────────────────────────────────┘   ║
╚══════════════════════════════════════════════════════════════════╝

type Server struct {
    addr          net.Addr    // 리스닝 주소
    sched         *Scheduler  // 모델 스케줄러
    defaultNumCtx int         // 기본 컨텍스트 길이
}

type LlamaServer interface {
    Load(ctx context.Context, opts api.Options) error
    Ping(ctx context.Context) error
    Completion(ctx context.Context, req CompletionRequest, fn func(CompletionResponse)) error
    Embedding(ctx context.Context, input string) ([]float64, error)
    Tokenize(ctx context.Context, content string) ([]int, error)
    Detokenize(ctx context.Context, tokens []int) (string, error)
    MemorySize(ctx context.Context) (uint64, error)
    Close() error
}

Manifest (JSON)
  └── Layers []Layer
        ├── Digest: "sha256-abc123..."
        ├── MediaType: "application/vnd.ollama.image.model"
        └── Size: 4_000_000_000

클라이언트
    │
    │ POST /api/chat
    ▼
ChatHandler()
    │ JSON 파싱 + 유효성 검사
    │
    ▼
scheduleRunner(modelName, options)
    │
    ▼
Scheduler.GetRunner()
    ├─ [이미 로드됨] → Runner 참조 반환
    └─ [미로드] → LlmRequest 큐에 추가
                        │
                        ▼
             processPending() goroutine
                        │
                        ├─ GPU 디바이스 감지
                        ├─ VRAM 여유 계산
                        ├─ 필요 시 기존 모델 Eviction
                        └─ Runner 프로세스 spawn
                                 │
                                 ▼
                      Runner 프로세스 (별도 포트)
                                 │
                        HTTP RPC 통신
                                 │
                                 ▼
Runner.Completion()
    │
    ├─ 메시지 → 토크나이즈
    ├─ KV 캐시 초기화/재사용
    ├─ Forward pass 실행 (GPU)
    ├─ 다음 토큰 샘플링
    └─ 반복 (EOS 또는 max_tokens까지)
    │
    ▼
ChatResponse 청크 스트리밍 (NDJSON)
    │
    ▼
클라이언트 (done: true + 메트릭)

"llama3.2:3b"
    │
    ▼
GetModel(name)
    │
    ├─ 로컬 manifest 존재 확인
    ├─ 없으면 registry에서 Pull
    ▼
manifest.json 파싱
    │
    ▼
GGUF 헤더 파싱 → 모델 메타데이터 추출
    │ (파라미터 수, 컨텍스트 길이, 양자화 방식 등)
    ▼
채팅 템플릿 자동 감지 or 명시적 로드
    │
    ▼
Model struct 반환

// 큐에 들어가는 요청 단위
type LlmRequest struct {
    ctx             context.Context
    model           *Model
    opts            api.Options
    sessionDuration *api.Duration
    successCh       chan *runnerRef   // 로드 완료 시 Runner 전달
    errCh           chan error
}

// 실행 중인 Runner 참조 (Reference Counted)
type runnerRef struct {
    refMu    sync.Mutex
    refCount uint          // 현재 처리 중인 요청 수
    llama    llm.LlamaServer
    model    *Model
    pid      int           // Runner 프로세스 PID
    gpus     []ml.DeviceID // 사용 중인 GPU
    expireTimer *time.Timer
}

요청 A → llama3.2 로드 → refCount: 1
요청 B → llama3.2 이미 로드됨 → refCount: 2
요청 A 완료 → refCount: 1
요청 B 완료 → refCount: 0 → Keep-Alive 타이머 시작
5분 후 → 모델 언로드 (다음 요청 시 재로드)

~/.ollama/models/
├── manifests/
│   └── registry.ollama.com/
│       └── library/
│           ├── llama3.2/
│           │   ├── latest
│           │   └── 3b
│           └── mistral/
│               └── latest
└── blobs/
    ├── sha256-abc123...  (모델 가중치 GGUF 파일)
    ├── sha256-def456...  (템플릿)
    └── sha256-ghi789...  (파라미터)

1. 모델명 파싱 (registry/namespace/name:tag)
2. 레지스트리 API에서 Manifest 조회
3. 필요한 레이어 블랍 병렬 다운로드 (16파트 청크)
4. 부분 다운로드 재개 지원 (Range 헤더)
5. SHA256 다이제스트 검증
6. Manifest + 블랍 로컬 저장

FROM llama3.2

SYSTEM """
You are a helpful Korean assistant.
항상 한국어로 답변해주세요.
"""

PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192

TEMPLATE """
{{- if .System }}<|system|>
{{ .System }}<|end|>
{{- end }}
{{- range .Messages }}<|{{ .Role }}|>
{{ .Content }}<|end|>
{{- end }}<|assistant|>
"""

[Ollama Server Process]
        │
        │ exec.Command() 로 Runner 스폰
        │ 환경변수로 포트/설정 전달
        ▼
[Runner Process (llama.cpp / ollama-engine)]
        │
        │ localhost:랜덤포트 HTTP 서버
        │ JSON RPC 통신
        ▼
[GGML Backend]
        │
        ├── CUDA (libcuda.so)
        ├── ROCm (librocblas.so)
        ├── Metal (Apple Framework)
        └── CPU (AVX2/AVX512)

// CGO 바인딩 예시 (개념적)
/*
#include "llama.h"
*/
import "C"

func loadModel(modelPath string) *C.llama_model {
    params := C.llama_model_default_params()
    return C.llama_load_model_from_file(C.CString(modelPath), params)
}

{
  "model": "llama3.2",
  "messages": [...],
  "options": {
    "temperature": 0.8,
    "top_k": 40,
    "top_p": 0.9,
    "min_p": 0.05,
    "repeat_penalty": 1.1,
    "num_ctx": 4096,
    "num_predict": 512,
    "seed": 42,
    "stop": ["\n\n", "<|end|>"],
    "num_gpu": 35
  },
  "keep_alive": "10m"
}

POST /v1/chat/completions     → ChatHandler (OpenAI 형식)
POST /v1/completions          → GenerateHandler (OpenAI 형식)
POST /v1/embeddings           → EmbedHandler (OpenAI 형식)
GET  /v1/models               → ListHandler (OpenAI 형식)

{"model":"llama3.2","message":{"role":"assistant","content":"안"},"done":false}
{"model":"llama3.2","message":{"role":"assistant","content":"녕"},"done":false}
{"model":"llama3.2","message":{"role":"assistant","content":"하세요"},"done":false}
{"model":"llama3.2","message":{"role":"assistant","content":"!"},"done":false}
{
  "model":"llama3.2",
  "done":true,
  "total_duration": 2340000000,
  "load_duration": 100000000,
  "prompt_eval_count": 12,
  "prompt_eval_duration": 340000000,
  "eval_count": 48,
  "eval_duration": 1900000000
}

type ChatRequest struct {
    Model     string          `json:"model"`
    Messages  []Message       `json:"messages"`
    Stream    *bool           `json:"stream"`
    Tools     []Tool          `json:"tools"`         // 함수 호출
    Think     *ThinkValue     `json:"think"`         // 추론 모드 (DeepSeek 등)
    KeepAlive *Duration       `json:"keep_alive"`
    Options   map[string]any  `json:"options"`
}

type Message struct {
    Role      string      `json:"role"`    // system/user/assistant/tool
    Content   string      `json:"content"`
    Images    []ImageData `json:"images"`  // Base64 이미지 (멀티모달)
    ToolCalls []ToolCall  `json:"tool_calls"`
}

type Options struct {
    // 샘플링 파라미터 (요청마다 변경 가능)
    Temperature    float32   // 창의성 (0.0 ~ 2.0)
    TopK           int       // Top-K 샘플링
    TopP           float32   // Top-P (nucleus) 샘플링
    MinP           float32   // Min-P 샘플링
    RepeatPenalty  float32   // 반복 패널티
    Seed           int       // 재현성을 위한 시드

    // 로드 타임 파라미터 (모델 재로드 시 적용)
    NumCtx         int       // 컨텍스트 윈도우 크기
    NumBatch       int       // 배치 크기
    NumGPU         int       // GPU 오프로드 레이어 수 (-1 = 전체)
    NumThread      int       // CPU 스레드 수
    UseMMap        *bool     // 메모리 매핑
    UseMLock       bool      // 메모리 잠금 (스왑 방지)
}

type Model struct {
    Name           string
    Config         model.ConfigV2
    ModelPath      string
    AdapterPaths   []string     // LoRA 어댑터
    ProjectorPaths []string     // Vision 프로젝터
    System         string       // 시스템 프롬프트
    Template       *template.Template
    Digest         string
    Options        map[string]any
    Messages       []api.Message // Few-shot 예시
}

ollama/
├── api/              # Go 클라이언트 라이브러리 + 타입 정의
├── auth/             # Ed25519 기반 인증
├── cmd/              # CLI 커맨드 (cobra)
│   └── cmd.go        # run, pull, push, list, show, create...
├── convert/          # 모델 포맷 변환 (HuggingFace → GGUF 등)
├── discover/         # GPU 감지 (CUDA, ROCm, Metal)
├── envconfig/        # 환경변수 설정 파싱
├── format/           # 파일 크기, 시간 등 포맷팅 유틸
├── integration/      # 통합 테스트
├── llama/            # llama.cpp CGO 바인딩 + C/C++ 소스
├── llm/              # LlamaServer 인터페이스 + 구현체
├── middleware/       # OpenAI/Anthropic 호환 미들웨어
├── ml/               # ML 백엔드 추상화 레이어
├── model/            # Go 네이티브 모델 아키텍처 구현
│   ├── llama/
│   ├── mistral/
│   ├── qwen/
│   └── ...
├── manifest/         # 모델 매니페스트 + 블랍 관리
├── runner/           # 모델 실행 엔진
│   ├── llamarunner/  # llama.cpp 기반
│   ├── ollamarunner/ # Go 네이티브
│   └── x/
│       ├── imagegen/ # 이미지 생성
│       └── mlxrunner/# Apple MLX
├── server/           # HTTP 서버 + 핸들러 + 스케줄러
│   ├── routes.go     # 라우트 정의
│   ├── sched.go      # 스케줄러
│   └── ...
├── template/         # 채팅 템플릿 시스템
└── tokenizer/        # 토크나이저 유틸리티

# GPU 상태 확인
ollama ps

# VRAM에 올라간 레이어 수 확인 (디버그 로그)
OLLAMA_DEBUG=1 ollama run llama3.2

# VRAM이 부족하면 더 작은 양자화 모델 사용
ollama pull llama3.2:3b-instruct-q4_K_M  # 4비트 양자화, ~2GB

# 또는 CPU 스레드 수 늘리기
OLLAMA_NUM_THREAD=8 ollama serve

# 요청 시 num_ctx 늘리기
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "긴 문서..."}],
  "options": {
    "num_ctx": 8192
  }
}'

FROM llama3.2
PARAMETER num_ctx 8192

ollama create my-llama --file ./Modelfile

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "2+2=?"}],
  "options": {
    "temperature": 0,
    "seed": 42
  }
}'

# 모든 인터페이스에서 리스닝
OLLAMA_HOST=0.0.0.0 ollama serve

# 또는 특정 IP
OLLAMA_HOST=192.168.1.100:11434 ollama serve

OLLAMA_ORIGINS="http://localhost:3000,https://myapp.com" ollama serve

# 동시 로딩 허용 수 설정 (기본: 1)
OLLAMA_NUM_PARALLEL=2 ollama serve

# 모델을 keep_alive=-1로 호출하여 영구 유지
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "keep_alive": -1,
  "prompt": ""
}'

# Unified Memory 활용 (CPU+GPU 공유 메모리)
# MacBook Pro M3 Pro (18GB): llama3.2:8b Q8 모델까지 풀 GPU 실행 가능

# 메모리 매핑 비활성화 시 초기 로딩은 느리지만 추론 속도 향상
OLLAMA_USE_MMAP=0 ollama serve

# MLX Runner 사용 (실험적 - 더 빠른 Metal 추론)
OLLAMA_LLM_LIBRARY=mlx ollama serve

import ollama

# 스트리밍 채팅
for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': '한국의 수도는?'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

# 임베딩
response = ollama.embed(model='nomic-embed-text', input='텍스트')
print(response['embeddings'])

import ollama from 'ollama'

const response = await ollama.chat({
  model: 'llama3.2',
  messages: [{ role: 'user', content: '안녕하세요!' }],
  stream: true,
})

for await (const part of response) {
  process.stdout.write(part.message.content)
}

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # 아무 값이나 OK
)

response = client.chat.completions.create(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Hello!'}],
)

# LangChain
from langchain_ollama import ChatOllama

llm = ChatOllama(model="llama3.2", temperature=0)
response = llm.invoke("파이썬으로 피보나치 수열을 구현해줘")

# LlamaIndex
from llama_index.llms.ollama import Ollama

llm = Ollama(model="llama3.2", request_timeout=120.0)
response = llm.complete("안녕하세요!")

# 방법 1: 로컬 GGUF 파일
cat > Modelfile << 'EOF'
FROM /path/to/my-model.gguf

PARAMETER temperature 0.7
SYSTEM "You are a helpful assistant."
EOF

ollama create my-custom-model --file Modelfile
ollama run my-custom-model

# 방법 2: HuggingFace 레포에서 직접
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M

# LLaVA 모델 사용
ollama pull llava

# API로 이미지 전송 (Base64 인코딩)
import base64, ollama

with open('image.jpg', 'rb') as f:
    image_data = base64.b64encode(f.read()).decode()

response = ollama.chat(
    model='llava',
    messages=[{
        'role': 'user',
        'content': '이 이미지에 무엇이 보이나요?',
        'images': [image_data]
    }]
)

# NVIDIA GPU
docker run -d \
  --gpus=all \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

# GPU 없이 CPU만
docker run -d \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

# 모델 실행
docker exec -it ollama ollama run llama3.2

import ollama

tools = [{
    'type': 'function',
    'function': {
        'name': 'get_weather',
        'description': '특정 도시의 날씨를 조회합니다',
        'parameters': {
            'type': 'object',
            'properties': {
                'city': {'type': 'string', 'description': '도시 이름'},
            },
            'required': ['city'],
        },
    },
}]

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': '서울 날씨 알려줘'}],
    tools=tools,
)

# tool_calls가 있으면 함수 실행
if response.message.tool_calls:
    for tool_call in response.message.tool_calls:
        print(f"호출: {tool_call.function.name}({tool_call.function.arguments})")