6장. RAG 의 원리와 로컬 모델로 옮기기

Ollama 로 로컬 모델 띄우기

캡슐 커피 머신은 캡슐을 사 와서 넣고 버튼만 누르면 커피가 나옵니다. 다른 맛이 마시고 싶으면 캡슐만 바꿉니다. Ollama 가 LLM 의 캡슐 커피 머신입니다.

Ollama 설치, 모델 내려받기, 서버 켜기, 파이썬에서 부르기의 네 걸음 흐름도

1번 Ollama 를 한 번 설치하고, 2번 ollama pull 로 모델(캡슐)을 내려받습니다. 3번 Ollama 가 내 PC 의 11434번 포트에서 서버로 떠 있고, 4번 파이썬은 그 주소로 요청을 보냅니다. 여기서 머신이 Ollama, 캡슐이 모델 파일, 버튼이 API 요청입니다.

Ollama 는 어떤 프로그램인가

Ollama(올라마)는 공개된 LLM 을 내 PC 에 내려받아, 명령 한 줄로 띄우고 API 로 쓰게 해 주는 프로그램입니다. Windows, macOS, Linux 에서 돌고, 누구나 코드를 보고 고칠 수 있는 오픈 소스(MIT 라이선스)입니다.

견줄 것	내용
하는 일	모델 내려받기(`pull`), 띄우기(`run`), 서버로 요청 받기(11434번 포트)를 한 프로그램이 한다
모델 파일	대개 4비트 안팎으로 줄인(양자화한) GGUF 파일이라, 같은 모델의 Hugging Face 원본보다 작고 4GB GPU 에도 들어간다
속에서 돌아가는 엔진	llama.cpp. C 와 C++ 로 짠 LLM 실행 엔진으로, GPU 가 없거나 작아도 돌게 만든 공개 프로젝트다
요청 받는 법	자체 API(`/api/…`)와 OpenAI 와 같은 꼴의 API(`/v1/…`) 둘 다 받는다. 그래서 이 장은 `openai` 라이브러리로 부른다
이 교안에서	6장부터 21장까지 로컬 LLM 은 거의 Ollama 로 띄운다. 교안을 만든 PC 는 0.40.1 로 시작해 앱이 스스로 0.40.12, 0.40.13 으로 업데이트했다

어디서 나왔나

Ollama 는 2023년에 공개되었습니다. 그해 Meta 가 Llama 2 를 누구나 받아 쓸 수 있게 내놓으면서, 공개 모델을 내 PC 에서 돌려 보려는 사람이 크게 늘었습니다. 그런데 모델 파일을 구하고, 줄이고, 실행 엔진을 설치해 맞추는 일이 초보자에게는 어려웠습니다. Ollama 는 이 과정을 ollama run 모델이름 한 줄로 줄이는 것을 목표로 나왔습니다. 만든 사람들(Jeffrey Morgan, Michael Chiang)은 그전에 Docker 와 관련된 도구를 만들었습니다. 그래서인지 pull, run, ps, rm 같은 명령과, 모델을 설정 파일(Modelfile)로 꾸미는 방식이 Docker 와 닮았습니다. 14장에서 Docker 를 만나면 비슷한 명령을 다시 보게 됩니다.

이름은 영어 낱말이 아니고, 머리글자도 아닙니다. 이름이 어디서 왔는지는 공식 문서에 밝혀져 있지 않아 이 교안에서는 짐작하지 않습니다. 읽을 때는 "올라마"라고 읽습니다.

더 읽을 곳	주소
공식 누리집과 모델 목록	ollama.com
소스 코드와 문서	github.com/ollama/ollama
OpenAI 와 같은 꼴의 API 설명	docs.ollama.com/api/openai-compatibility

자주 쓰는 명령

설치는 setup.md 의 "Ollama 설치"를 따릅니다. 설치한 뒤 PowerShell 에서 이렇게 씁니다.

PowerShell

ollama pull qwen2.5:0.5b
ollama list
ollama run qwen2.5:0.5b "안녕하세요"
ollama ps
ollama stop qwen2.5:0.5b

명령	하는 일
`ollama pull 이름`	모델을 내려받는다. 한 번 받으면 다시 받지 않는다
`ollama list`	내려받은 모델과 크기를 본다
`ollama run 이름 "질문"`	터미널에서 바로 물어본다
`ollama ps`	지금 메모리에 올라 있는 모델과 GPU 사용량을 본다
`ollama stop 이름`	메모리에서 내린다. 가만히 두어도 몇 분 뒤 내려간다

교안을 만든 PC 에서 ollama list 를 실행한 결과입니다. 내려받은 시각 열과 이 장에서 쓰지 않는 모델은 뺐습니다.

출력

NAME                       ID              SIZE
qwen2.5:3b                 357c53fb659c    1.9 GB
qwen2.5:1.5b               65ec06548149    986 MB
qwen2.5:0.5b               a8b0c5157701    397 MB

과정을 따라가면 늘어나는 목록

6장에서는 위의 셋이면 됩니다. 뒤의 장까지 따라 하면 모델이 늘어납니다. 아래는 수강생의 PC(가상환경 .venv 를 켠 PowerShell)에서 ollama list 를 실행한 결과입니다. 내 목록이 이것과 달라도 괜찮습니다. 그 장에 필요한 모델만 있으면 됩니다.

출력

(.venv) PS C:\llm-course> ollama list
NAME                              ID              SIZE      MODIFIED
qwen2.5:0.5b-instruct-fp16        c82efd44bfdc    994 MB    6 days ago
qwen2.5:0.5b-instruct-q8_0        84d044692a2c    531 MB    6 days ago
qwen2.5vl:3b                      fb90415cde1e    3.2 GB    6 days ago
llama3.2:1b                       baf6a787fdff    1.3 GB    6 days ago
gemma3:1b                         97558784bdc9    806 MB    6 days ago
qwen2.5:3b                        357c53fb659c    1.9 GB    7 days ago
qwen2.5:1.5b                      65ec06548149    986 MB    7 days ago
qwen2.5:0.5b                      a8b0c5157701    397 MB    7 days ago
nomic-embed-text:latest           0a109f422b47    274 MB    3 weeks ago

열	뜻
`NAME`	모델 이름. 콜론(`:`) 앞이 모델, 뒤가 태그(tag, 꼬리표)다. 태그는 크기(`0.5b` = 파라미터 5억 개, b 는 billion)나 저장 방식(`q8_0` = 8비트, `fp16` = 16비트)을 적는다. 코드의 `model=` 에는 이 이름을 그대로 적는다
`ID`	모델 파일을 가리키는 고유 번호의 앞 12글자. 같은 ID 면 같은 파일이다. 사람이 쓸 일은 거의 없다
`SIZE`	디스크에서 차지하는 크기. 대개 4비트로 줄인 파일이라 같은 모델의 Hugging Face 파일보다 작다
`MODIFIED`	내려받거나 고친 지 얼마나 됐는지. 받은 때에 따라 다르다

모델	쓰는 곳
`qwen2.5:0.5b`, `qwen2.5:1.5b`, `qwen2.5:3b`	6장 실습 5, 6. 그 뒤로는 `qwen2.5:3b` 를 가장 많이 쓴다
`llama3.2:1b`, `gemma3:1b`	7장 프로젝트에서 다른 회사의 작은 모델과 견준다
`qwen2.5vl:3b`	12장. 그림을 보고 답하는 비전 언어 모델(vl = vision-language)
`qwen2.5:0.5b-instruct-q8_0`, `qwen2.5:0.5b-instruct-fp16`	15장. 같은 모델을 저장 방식만 바꿔 양자화를 견준다
`nomic-embed-text:latest`	이 교안에서는 쓰지 않는다. 글을 임베딩으로 바꾸는 모델로, 다른 자료를 따라 하며 받아 둔 것이다. `latest` 는 태그를 적지 않고 받았을 때 붙는 기본 태그다

필요 없는 모델은 ollama rm 이름(rm = remove, 지우다)으로 지워 디스크를 비웁니다. 지운 모델은 그 장을 다시 할 때 ollama pull 로 다시 받으면 됩니다.

서버가 떠 있는지 보기

Ollama 는 설치하면 백그라운드에서 서버를 켜 둡니다. 파이썬에서 주소 하나로 확인합니다.

Python

import json
import urllib.request

try:
    # Ollama 서버의 버전을 묻는다. 서버가 꺼져 있으면 연결 오류가 난다
    with urllib.request.urlopen("http://localhost:11434/api/version", timeout=3) as r:
        print("Ollama 서버:", json.load(r))
except OSError as e:
    print("서버에 연결하지 못했습니다:", e)

교안을 만든 PC 에서는 {'version': '0.40.1'} 이 나왔습니다. 연결하지 못하면 시작 메뉴에서 Ollama 를 켜거나 PowerShell 에서 ollama serve 를 실행합니다.

코드에 나오는 함수

코드	쉬운 뜻
`urllib.request.urlopen(주소, timeout=3)`	주소로 요청을 보내고 응답을 연다. urllib 은 URL 을 다루는 표준 라이브러리다. 3초 안에 답이 없으면 포기한다
`with ... as r:`	응답을 다 읽으면 연결을 저절로 닫는다
`json.load(r)`	JSON(JavaScript Object Notation, 자바스크립트 객체 표기법) 꼴의 응답을 파이썬 사전으로 바꾼다
`http://localhost:11434/api/version`	localhost 는 "이 PC 자신", 11434 는 Ollama 가 기다리는 포트(문 번호), `/api/version` 은 버전을 알려 주는 창구다
`except OSError as e:`	연결이 안 되거나 시간이 지나면 나는 오류를 받아, 프로그램을 멈추지 않고 안내 문구를 찍는다

이 코드가 뜻하는 것

가게에 전화를 걸어 "문 열었나요?" 하고 묻는 일과 같습니다. 받으면 영업 중이고, 3초 동안 안 받으면 문을 닫은 것으로 봅니다.

줄	하는 일	쉽게 말하면
`try:`	아래 줄에서 오류가 나도 멈추지 않게 감싼다	안 받아도 당황하지 않게 준비한다
`urlopen(".../api/version", timeout=3)`	내 PC 의 Ollama 서버에 버전을 묻는다	가게에 전화를 건다
`print("Ollama 서버:", json.load(r))`	받은 답을 사전으로 바꿔 찍는다	"네, 영업 중입니다"를 듣는다
`except OSError as e:`	연결하지 못하면 오류 내용을 찍는다	안 받으면 "닫혀 있네" 하고 적어 둔다

{'version': '0.40.1'} 처럼 사전이 나오면 서버가 떠 있다는 뜻이고, 그 안의 값이 Ollama 의 버전입니다. "서버에 연결하지 못했습니다"가 나오면 Ollama 가 꺼져 있다는 뜻입니다.

브라우저로 확인하기

코드 없이 브라우저의 주소 창에 넣어 봐도 됩니다. 아래는 교안을 만든 PC 에서 연 결과입니다.

주소	나오는 것
`http://localhost:11434`	`Ollama is running` 한 줄
`http://localhost:11434/v1/models`	받아 둔 모델 목록(JSON). `{"object":"list","data":[{"id":"qwen2.5:0.5b-instruct-fp16", …` 처럼 시작한다
`http://localhost:11434/api/version`	Ollama 버전. `{"version":"0.40.13"}` 처럼 나온다

http://localhost:11434/v1/ 처럼 /v1/ 까지만 넣으면 404 page not found 가 나옵니다. 수강생이 실제로 이 화면을 보고 물어 온 적이 있습니다. 오류가 아니라 정상입니다. /v1/ 은 주소의 앞부분일 뿐이라 그 자리에 보여 줄 쪽이 없어서 "그런 쪽은 없다(404)"고 답한 것입니다. 파이썬 코드는 그 뒤의 /v1/chat/completions, /v1/models 로 요청을 보냅니다. 오히려 404 가 왔다는 것은 서버가 떠서 대답했다는 뜻입니다. 서버가 꺼져 있으면 404 가 아니라 "사이트에 연결할 수 없음" 화면이 나옵니다.

브라우저에 보이는 것	뜻
`Ollama is running`, JSON 글	서버가 떠 있고 그 주소에 창구가 있다
`404 page not found`	서버는 떠 있지만 그 주소에는 창구가 없다. 주소 끝을 확인한다
"사이트에 연결할 수 없음"	서버가 꺼져 있다. Ollama 를 켜거나 `ollama serve` 를 실행한다

Ollama 는 기본으로 내 PC 안(localhost)에서 오는 요청만 받습니다. 같은 와이파이의 다른 기기에서는 이 주소로 들어올 수 없습니다.

주의할 점

여러 모델을 잇달아 부르면 앞의 모델이 몇 분 동안 GPU 에 남아 있어, 나중 모델이 GPU 에 다 들어가지 못하고 CPU 로 일부가 넘어갑니다. 이 PC 의 실습 6에서는 3B 모델이 68% 를 CPU 에서 돌아 세 배쯤 느렸습니다. ollama ps 의 PROCESSOR 열로 확인하고, 쓰지 않는 모델은 ollama stop 으로 내립니다.
모델을 메모리에 처음 올릴 때는 오래 걸립니다. 이 PC 에서 처음 부른 질문은 답이 나오기까지 2분 넘게 걸렸고, 그다음부터는 1초 안팎이었습니다. 속도를 잴 때는 한 번 불러 둔 뒤에 잽니다.
모델 이름의 :0.5b 같은 꼬리(태그)가 크기와 판을 정합니다. 태그 없이 qwen2.5 라고 쓰면 기본 크기(7B)를 내려받아 4GB GPU 에는 다 들어가지 않습니다.