Ollama 딥다이브
— 내 컴퓨터에서 LLM을 한 줄로 돌리는 로컬 런타임

1프로젝트 한줄 요약

Ollama는 거대 언어 모델(LLM)을 내 컴퓨터에서 한 줄 명령으로 다운로드·실행·관리하는 오픈소스 로컬 런타임이다. ollama run gemma3이라고 입력하면 모델이 자동으로 받아지고, 그래픽카드가 감지되고, 채팅이 바로 시작된다.

2왜 주목받는가

왜 별 약 17만 개를 받았나

2023년 출시 이후 로컬 LLM 붐의 사실상 표준 진입점이 됐다. README 상단의 모델 목록(Gemma, Qwen, DeepSeek, gpt-oss 등)이 모델 출시 속도에 맞춰 끊임없이 갱신되는 것 자체가 생태계의 중심임을 보여준다. 프라이버시(데이터가 외부로 안 나감)·오프라인 동작·API 사용료 0원이라는 가치가 명령어 한 줄의 편의성과 만나 폭발적으로 퍼졌다.

경쟁 도구 비교

3기술 스택 전체 지도

언어 구성 (GitHub 기준, 근사치)

※ 비율은 GitHub Linguist 집계 기준이며 커밋에 따라 변동한다.

핵심 런타임 / 백엔드

가속 백엔드 (실행 시점 선택)

인프라 / 배포

4아키텍처 심화 분석

시스템 구조도

핵심 설계 패턴 ①: 클라이언트-서버 분리

핵심 설계 패턴 ②: 추론 런너 프로세스 격리

실제 모델 계산은 서버가 아니라 자식 프로세스 runner가 맡는다. runner 안에 C++ 추론 엔진(llama.cpp)이 들어 있다. 별도 프로세스로 띄우는 이유 — GPU 메모리 부족으로 runner가 죽어도 메인 서버는 살아남아 다음 요청을 받을 수 있게 하기 위함이다(장애 격리).

핵심 설계 패턴 ③: 모델을 레이어로 저장 (Docker 매니페스트 이식)

모델 파일을 통째로 저장하지 않고 여러 조각(layer)으로 쪼갠다. 가중치·템플릿·시스템 프롬프트·파라미터·라이선스가 각각 별도 레이어이고, 매니페스트가 "이 모델 = 이 조각들의 조합"을 기록한다. 조각은 SHA256 해시로 식별된다.

핵심 설계 패턴 ④: 하드웨어 추상화 (백엔드 다중 빌드)

같은 ollama run이 RTX 4090에서도, M3 맥에서도, AMD 라데온에서도 돈다. 비결은 "여러 백엔드를 모두 빌드해 두고 실행 시점에 골라 쓰기"다. 각 백엔드(CUDA/Metal/ROCm/Vulkan/CPU)는 같은 추론 인터페이스를 구현한 별개 라이브러리다.

핵심 설계 패턴 ⑤: OpenAI 호환 어댑터

자체 API(/api/chat)와 별개로 OpenAI와 똑같은 URL 구조(/v1/chat/completions)도 제공한다. 기존 ChatGPT 코드에서 base_url과 api_key 두 줄만 바꾸면 로컬 모델로 갈아끼울 수 있다. "더 좋은 새 API"를 정의하는 대신 기존 표준과 호환되게 만들어 채택 마찰을 없앤 전략이다.

5디렉토리 구조 해부

읽기 순서 추천: cmd/(명령이 어떻게 시작되나) → server/routes.go(요청이 어디로 가나) → runner/(실제 추론) → llm/·llama/(C++ 엔진 연결). 이 흐름만 따라가도 "한 줄 명령어 뒤에서 벌어지는 일"이 코드로 보인다.

6학습 포인트 (기술별)

A. Go 서버 아키텍처 — 추상화 잘하는 코드의 표본

배울 것: Gin 기반 REST 서버를 어떻게 모듈로 쪼개는가. server/routes.go의 라우팅, 스케줄러의 모델 로드/언로드 결정 로직, NDJSON 스트리밍 응답 구현. 패키지 경계가 명확한 Go 프로젝트의 좋은 예시다.

B. CGO — Go와 C++을 잇는 다리

배울 것: Go의 깔끔한 서버 코드 + C++의 빠른 수치 연산을 한 프로그램에 합치는 법. llama/ 패키지가 어떻게 llama.cpp 함수를 CGO로 호출하는지. 두 언어를 섞을 때의 메모리·빌드 관리 패턴.

C. 프로세스 격리 설계

배울 것: 왜 추론을 별도 runner 프로세스로 분리했는가. 장애 격리 — 자식이 죽어도 부모(서버)는 생존하는 패턴은 안정적인 시스템 설계의 핵심 기법이다.

D. 콘텐츠 주소화 저장 (Content-Addressable Storage)

배울 것: 모델을 SHA256 해시로 식별되는 레이어로 쪼개 저장하는 방식. 같은 내용은 한 번만 저장하고 여러 매니페스트가 참조하는 구조는 Docker·Git이 쓰는 바로 그 아이디어다.

E. 하드웨어 추상화 계층

배울 것: 같은 인터페이스를 여러 백엔드(CUDA/Metal/ROCm/CPU)로 구현하고 런타임에 고르는 패턴. discover/의 자동 감지 + llm/의 추상화가 어떻게 "한 명령어, 모든 하드웨어"를 만드는지.

F. 호환 어댑터 전략

배울 것: openai/ 패키지가 OpenAI 엔드포인트를 흉내내는 방식. 새 도구를 만들 때 기존 표준과 호환되게 만들어 마찰을 없애는 것이 종종 "더 좋은 새 API"보다 강력하다는 교훈.

7하드웨어 / 시스템 요구사항

대략 모델 크기 × 0.6 GB ≒ 필요 메모리(기본 4비트 양자화 기준). 핵심 공식은 모델 크기 ≤ 메모리 크기 — 모델이 메모리에 통째로 안 들어가면 스왑이 끼어 끔찍하게 느려진다.

8직접 해볼 수 있는 실습 과제

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

# 가장 작은 모델 실행
ollama run gemma3:1b

> 안녕? 자기소개 해줘   # 첫 응답을 받아보면 끝

# Modelfile
FROM gemma3:1b
SYSTEM "너는 항상 사투리로 답하는 친절한 비서다."
PARAMETER temperature 0.8

# Python
from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 아무 값이나 OK
)
r = client.chat.completions.create(
    model="gemma3", messages=[{"role":"user","content":"안녕"}])
print(r.choices[0].message.content)

# 레포 클론 후
git clone https://github.com/ollama/ollama
# routes.go에서 /api/chat 핸들러를 찾아
# 스케줄러 → runner spawn 경로를 추적
# 빌드: go generate ./... && go build .

9관련 기술 심화 학습 로드맵

1주차: 로컬 LLM 기초 체험

2주차: 내부 동작 이해

3주차: 소스 코드 & 빌드

4주차: 응용 & 통합

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — ollama/ollama
• 공식 문서 — docs.ollama.com
• 모델 카탈로그 — ollama.com/library
• 개발 가이드 (소스 빌드)
• REST API 레퍼런스
• Modelfile 가이드
• server/routes.go (라우팅 핵심)
• llama.cpp — 내부 추론 엔진
• GPU 지원 문서
• OpenAI 호환 어댑터 코드