본문으로 건너뛰기

프론트엔드 개발자의 로컬 LLM — Ollama로 시작하는 로컬 모델 실행 가이드

Ollama는 오픈소스 모델을 로컬에서 내려받아 실행하고 API로 노출해 주는 도구입니다. 설치와 Modelfile, GGUF 양자화 감각, OpenAI 호환 API로 웹앱 프로토타이핑까지 정리한 로컬 LLM 입문 가이드.

· 7분 읽기
share

프론트엔드 개발자의 로컬 LLM — Ollama로 시작하는 로컬 모델 실행 가이드

개요

LLM 기반 기능을 웹앱에 넣어 보려면 API 키 발급, 과금 설정, 네트워크 왕복부터 마주하게 됩니다. 아이디어 단계의 프로토타입에는 무겁습니다. 반대로 모델이 내 컴퓨터에서 돌면 키도 없고, 데이터가 밖으로 나가지 않으며, 요금 걱정 없이 마음껏 시도할 수 있습니다.

Ollama는 이 “로컬 LLM”을 최대한 쉽게 만들어 주는 도구입니다. 오픈소스 모델을 내려받아 실행하고, CLI와 로컬 API 서버로 노출해 줍니다. 이 글은 프론트엔드 개발자 관점에서 Ollama를 설치하고, 모델 파일의 구조를 이해하고, OpenAI 호환 API로 기존 웹앱 프로토타입에 붙이는 것까지를 다룹니다. 끝에는 “어디까지가 로컬로 감당되는 범위인지” 감각을 정리했습니다.

Ollama가 하는 일

Ollama가 해 주는 일을 정리하면 세 가지입니다.

  • 모델 관리: 모델 레지스트리에서 모델 파일을 받아오고(ollama pull), 목록을 보여 줍니다(ollama list).
  • 실행: 모델을 메모리에 올려 대화형 CLI(ollama run)를 제공합니다.
  • API 서버: 백그라운드에서 로컬 서버를 띄워 애플리케이션에서 호출할 수 있게 합니다. 기본으로 localhost:11434에 바인딩됩니다.

내부적으로는 llama.cpp 기반의 추론 엔진과 GGUF 모델 포맷 생태계 위에 얹혀 있습니다. 그래서 Ollama를 잘 쓰려면 GGUF와 양자화에 대한 최소한의 감각이 필요한데, 뒤에서 다룹니다.

설치와 첫 실행

macOS는 공식 다운로드 페이지의 앱으로 설치하고, Linux는 공식 문서가 권장하는 설치 스크립트를 씁니다.

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

# 설치 후 가장 작은 실습용 모델 실행
ollama run llama3.2

프롬프트가 뜨면 한국어로 몇 마디 주고받아 볼 수 있습니다. llama3.2는 Meta의 소형 모델로 1B/3B 버전이 있어서, M1/M2급 맥이나 보급형 GPU에서도 돌아가는 첫 실습용으로 적당합니다. 자주 쓰게 될 명령은 다음과 같습니다.

ollama pull llama3.2   # 모델만 내려받기
ollama list            # 내려받은 모델 목록
ollama ps              # 지금 메모리에 올라와 있는 모델과 프로세서(GPU/CPU) 확인
ollama stop llama3.2   # 메모리에서 내리기

ollama ps의 PROCESSOR 열을 보면 모델이 전부 GPU에 올라갔는지, 일부가 CPU로 넘쳤는지 확인할 수 있습니다. 기본적으로 모델은 마지막 사용 후 5분간 메모리에 유지되다가 언로드되며, 이 유지 시간은 keep_alive 설정으로 바꿀 수 있습니다(공식 FAQ 기준).

Modelfile로 모델 커스터마이즈

Docker 이미지를 만들 듯, 기반 모델 위에 나만의 설정을 얹은 커스텀 모델을 만들 수 있습니다. Modelfile에 기반 모델, 시스템 프롬프트, 추론 옵션을 적습니다. 문법은 공식 Modelfile 참조 문서에 정리되어 있습니다.

FROM llama3.2

SYSTEM """
당신은 프론트엔드 코드 리뷰 도우미입니다.
- 한국어로 답합니다.
- React와 TypeScript 위주로 예시를 듭니다.
- 가능하면 문제의 원인을 먼저 한 줄로 요약합니다.
"""

PARAMETER temperature 0.3
PARAMETER num_ctx 8192
ollama create fe-reviewer -f ./Modelfile
ollama run fe-reviewer

자주 쓰는 명령은 이렇습니다.

  • FROM: 기반이 될 모델(레지스트리 이름이나 로컬 GGUF 파일 경로)
  • SYSTEM: 시스템 프롬프트. 응답 톤과 형식을 고정하는 용도
  • PARAMETER: 추론 옵션. temperature는 무작위성, num_ctx는 컨텍스트 길이(토큰 수)

num_ctx는 뒤에서 메모리 계산의 핵심 등장인물입니다.

GGUF와 양자화: 모델 이름 읽는 법

모델 레지스트리를 둘러보면 llama3.2:3b-instruct-q4_K_M 같은 태그를 만나게 됩니다. 뒤의 q4_K_M가 양자화 방식입니다. 감각을 정리하면 다음과 같습니다.

원래 모델의 가중치는 보통 16비트 부동소수점(fp16)입니다. 양자화는 이 값을 4비트나 8비트 정수 등으로 줄여 파일 크기와 메모리 사용량을 낮추는 기술이고, GGUF는 이런 가중치와 메타데이터를 담는 llama.cpp 생태계의 컨테이너 포맷입니다. 포맷의 세부 사항은 Hugging Face의 GGUF 문서에 표로 정리되어 있습니다.

라벨 읽는 법은 이렇습니다.

  • Q4, Q8 같은 숫자는 대략적인 비트 수입니다. 숫자가 작을수록 작고 빠르지만 품질 손실 위험이 커집니다.
  • _K가 붙으면 K-quant 계열로, 블록별 스케일을 활용해 같은 비트 수에서 더 나은 품질을 내는 방식입니다.
  • _S, _M, _L 접미사는 텐서별로 양자화 강도를 섞은 조합의 크기입니다.

llama.cpp의 quantize 문서는 “대부분의 경우 Q4_K_M을 권장하고, 품질이 더 중요하면 Q5나 Q8_0으로 올라가라”는 실용적 기준을 제시합니다. 제 경험 기준으로도 기본 선택은 q4_K_M, 답변 품질이 미세하게 흔들리는 게 신경 쓰이면 q8_0을 내려받아 비교하는 흐름이면 충분했습니다.

VRAM과 컨텍스트 길이 감각

“내 컴퓨터에서 어느 모델까지 돌릴 수 있는가”는 대략의 산수로 판단할 수 있습니다.

가중치 크기는 대략 파라미터 수 × 비트 수 ÷ 8입니다. 8B 모델을 4비트 양자화(q4)하면 8 × 4 ÷ 8 = 약 4GB, 8비트(q8)면 약 8GB입니다. 70B 모델은 q4여도 35GB를 넘게 되어 일반적인 데스크톱 GPU 단장으로는 부담입니다. Apple Silicon은 CPU와 GPU가 메모리를 공유하는 통합 메모리 구조라 “VRAM”이 아니라 시스템 메모리 전체가 예산이 되지만, 다른 앱과 나눠 써야 하므로 여유를 두는 게 안전합니다.

컨텍스트 길이도 메모리를 먹습니다. Ollama는 기본적으로 컨텍스트 창을 4096 토큰으로 실행합니다(작성 시점 기준 공식 FAQ 기준). 대화가 길어지거나 긴 문서를 넣으려면 num_ctx를 늘려야 하는데, 컨텍스트에 비례하는 KV 캐시 메모리가 함께 늘어납니다. 즉 “8B q4 모델 = 4GB니까 8GB 메모리면 넉넉하겠다”고 계산하다가 num_ctx를 32k로 올리는 순간 예산이 깨질 수 있습니다. 전역 기본값은 OLLAMA_CONTEXT_LENGTH 환경 변수로, 실행 시점에는 /set parameter num_ctx 8192처럼 바꿀 수 있습니다.

이 두 가지(가중치 + KV 캐시)가 “돌아가는가”의 기준이고, ollama ps로 실제 상주 크기와 CPU/GPU 분배를 확인하면서 조정하면 됩니다.

OpenAI 호환 API로 웹앱 프로토타입에 붙이기

Ollama가 프론트엔드 개발자에게 특히 좋은 이유는 2024년 2월 8일부터 OpenAI의 Chat Completions API와 호환성을 내장했다는 점입니다. 기존에 OpenAI SDK로 짜 둔 코드에서 baseURL만 로컬로 바꾸면 그대로 동작합니다.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama', // 필요하지만 값은 무시됩니다
});

export async function askReviewer(code: string) {
  const stream = await client.chat.completions.create({
    model: 'fe-reviewer', // Modelfile로 만든 커스텀 모델
    messages: [
      {
        role: 'system',
        content: '프론트엔드 코드 리뷰 도우미로서 한국어로 답합니다.',
      },
      { role: 'user', content: `이 코드를 리뷰해 줘:\n\n${code}` },
    ],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
  }
}

프로토타입에서 프로덕션 원격 API로 갈아타는 것도 baseURL과 키를 환경 변수로 분리하는 수준의 변경입니다. curl로 바로 확인할 수도 있습니다.

curl http://localhost:11434/v1/chat/completions \
  -d '{
    "model": "llama3.2",
    "messages": [{ "role": "user", "content": "useEffect 클린업 함수를 설명해 줘" }]
  }'

브라우저에서 로컬 서버를 직접 호출하는 구성은 피하는 게 좋습니다. API 키가 없는 대신 출처 정책 문제가 있고, 서버 주소가 클라이언트 코드에 드러납니다. Next.js 같은 서버 레이어의 라우트에서 호출하고 브라우저는 그 라우트를 향하게 하는 구성이 깔끔합니다. 필요하면 OLLAMA_ORIGINS 환경 변수로 허용 출처를 지정할 수 있습니다.

어디까지 로컬로 감당되는가

로컬 LLM의 한계를 알고 쓰는 것이 중요합니다. 체감상 경계선은 이렇습니다.

  • 잘 되는 영역: 요약, 분류, 형식 변환, 간단한 코드 힌트처럼 짧은 입력·짧은 출력의 보조 작업. 그리고 오프라인 동작과 데이터가 나가면 안 되는 환경.
  • 아슬아슬한 영역: 긴 대화(컨텍스트가 늘어 메모리와 속도가 함께 나빠짐), 코딩 어시스턴트처럼 정확도가 중요한 작업의 소형 모델 처리.
  • 로컬이 무리인 영역: 최상위 대형 모델급 품질, 높은 동시성(여러 사용자의 동시 요청), 낮은 지연이 핵심 가치인 서비스.

현실적인 하이브리드도 있습니다. 개발과 테스트는 로컬로 돌리고 배포 환경에서만 원격 API를 쓰거나, 프롬프트 설계·파인프라인 실험을 로컬에서 충분히 돌린 뒤 상위 모델로 최종 검증하는 식입니다. 어느 쪽이든 “OpenAI 호환 인터페이스 하나로 갈아 끼울 수 있다”는 점이 이 생태계의 가장 편리한 특성입니다.

정리

  • Ollama는 설치 즉시 ollama run으로 로컬 LLM을 쓸 수 있게 해 주는 진입 도구입니다.
  • Modelfile로 시스템 프롬프트와 옵션을 고정한 커스텀 모델을 만들 수 있고, num_ctx 같은 옵션이 메모리 예산과 직결됩니다.
  • 모델 태그의 q4_K_M 같은 라벨은 양자화 방식이며, 기본 선택은 llama.cpp 문서 권장대로 Q4_K_M, 품질 필요 시 Q8_0입니다.
  • 메모리 감각은 “파라미터 × 비트 ÷ 8의 가중치 + 컨텍스트에 비례하는 KV 캐시”라는 산수로 충분합니다.
  • /v1 호환 API 덕분에 기존 웹앱 프로토타입에 baseURL 하나로 붙일 수 있습니다.

LLM 기능의 기획 단계를 API 키 없이 내 책상에서 돌려볼 수 있게 된 것만으로도 Ollama를 한 번쯤 깔아 볼 가치가 충분합니다.

레퍼런스

Related