Ollama 사용법: Mac·Windows 설치부터 첫 모델 실행과 로컬 API 연결까지

Ollama는 로컬 LLM을 터미널 명령과 HTTP API로 실행하는 도구다. 처음이라면 설치 후 ollama run 모델명으로 대화를 시작하고, ollama list로 내려받은 모델을 확인한 뒤, 프로그램에서는 http://localhost:11434의 API를 호출하면 된다. 아래 순서대로 하면 설치 확인부터 모델 삭제까지 한 번에 끝난다.

Mac과 Windows에 Ollama 설치하기

가장 덜 헷갈리는 방법은 공식 다운로드 페이지에서 설치 파일을 받는 것이다. Ollama 공식 문서는 macOS, Windows, Linux를 지원 대상으로 안내한다.

• macOS: Ollama 다운로드에서 앱을 받아 Applications에 설치한다. 공식 저장소가 안내하는 셸 설치 명령 curl -fsSL https://ollama.com/install.sh | sh도 있지만, 명령의 내용을 확인하지 않고 원격 스크립트를 실행하는 것이 불편하다면 DMG가 낫다.
• Windows: 공식 설치 프로그램을 쓰거나 PowerShell에서 irm https://ollama.com/install.ps1 | iex를 실행한다. 회사 PC라면 PowerShell 실행 정책과 관리자 권한 때문에 스크립트 방식이 막힐 수 있으므로 설치 프로그램을 먼저 권한다.

설치가 끝나면 새 터미널을 열고 확인한다.

ollama --version

명령을 찾지 못하면 기존 터미널이 설치 전 PATH를 들고 있을 수 있다. 터미널을 완전히 닫아 다시 열고, 그래도 안 되면 앱이 실제로 설치됐는지 확인한다. Windows에서는 PowerShell과 명령 프롬프트를 새로 열어 각각 시험해 보는 편이 빠르다.

첫 모델 실행하기

모델은 Ollama 모델 라이브러리에서 고른다. 모델 페이지에는 태그별 크기가 표시되므로 다운로드 전에 디스크 여유와 메모리를 확인하자. 아래 gemma4는 공식 Quickstart가 현재 예제로 사용하는 이름이다.

ollama run gemma4

처음 실행하면 모델을 먼저 내려받고 대화 입력창이 열린다. 질문을 입력하고, 대화를 끝낼 때는 /bye를 입력한다. 모델을 미리 받기만 하려면 다음처럼 분리할 수 있다.

ollama pull gemma4
ollama run gemma4

모델 이름 뒤 태그는 서로 다른 파일을 가리킨다. 예를 들어 모델 페이지에 :latest, 크기, 양자화가 다른 태그가 있다면 정확한 태그까지 복사하는 편이 재현성이 좋다. 이름을 추측하지 말고 라이브러리 페이지의 실행 명령을 그대로 쓰자.

내려받은 모델 확인·삭제하기

로컬 모델은 용량을 많이 차지할 수 있다. 다음 네 명령만 알아도 일상적인 관리는 충분하다.

ollama list
ollama show gemma4
ollama ps
ollama rm gemma4

ollama list는 저장된 모델, ollama show는 모델 정보, ollama ps는 현재 메모리에 올라간 모델을 보여준다. ollama rm은 해당 모델 파일을 삭제하므로 이름과 태그를 확인한 뒤 실행한다. 모델을 바꾸었는데 메모리가 바로 줄지 않는다면 ollama ps로 아직 적재된 모델이 있는지 먼저 본다.

다운로드가 중단되면 같은 ollama pull을 다시 실행해 본다. 디스크 부족이라면 모델을 무작정 재시도하지 말고 ollama list로 불필요한 모델부터 정리한다.

로컬 API 연결하기

Ollama가 실행 중이면 기본 API는 http://localhost:11434/api에서 제공된다. 별도 API 키 없이 같은 컴퓨터에서 호출할 수 있다. 공식 API 문서의 생성 예제를 한국어 질문으로 바꾸면 다음과 같다.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "양자화를 한 문단으로 설명해 줘",
  "stream": false
}'

대화 이력을 역할별 메시지로 보내려면 /api/chat을 쓴다.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {"role": "user", "content": "이 문장을 세 줄로 요약해 줘"}
  ],
  "stream": false
}'

응답이 여러 JSON 줄로 이어지는 것이 오류는 아니다. Ollama의 생성 API는 기본적으로 스트리밍한다. 한 번에 완성된 JSON이 필요하면 예제처럼 "stream": false를 넣는다.

Python이나 JavaScript 앱에서도 같은 주소를 호출하면 된다. 다만 localhost는 ‘Ollama가 실행되는 컴퓨터 자신’을 뜻한다. Docker 컨테이너나 다른 PC에서 localhost:11434를 호출하면 그 컨테이너나 다른 PC를 찾게 된다. 이 경우 네트워크 노출 설정과 방화벽을 별도로 다뤄야 하며, 인증 없이 인터넷에 포트를 공개해서는 안 된다.

자주 막히는 지점

connection refused: 모델 문제가 아니라 Ollama 서비스가 안 떠 있는 경우가 많다. Ollama 앱을 실행한 뒤 ollama list가 동작하는지 먼저 확인한다.

model not found: 라이브러리에 표시된 모델명과 태그를 다시 복사한다. 로컬 보유 여부는 ollama list로 확인한다.

응답이 지나치게 느림: 더 작은 모델 또는 더 강하게 양자화된 태그로 비교한다. 긴 입력은 KV cache 등 실행 메모리와 처리 시간을 늘리므로 짧은 질문으로 먼저 정상 동작을 확인한다.

API는 되는데 앱 연결은 실패함: 앱의 Base URL이 http://localhost:11434인지, Ollama 고유 API를 기대하는지 OpenAI 호환 API를 기대하는지 구분한다. 엔드포인트 형식이 다르면 주소만 맞아도 요청은 실패한다.

처음 설치한 뒤 확인할 순서

1. ollama --version이 실행되는지 본다.
2. 공식 라이브러리에서 모델 태그와 파일 크기를 확인한다.
3. ollama run <정확한 모델명>으로 짧은 질문을 보낸다.
4. ollama list와 ollama ps의 차이를 확인한다.
5. curl http://localhost:11434/api/generate ...로 앱 밖에서도 API가 응답하는지 시험한다.

여기까지 되면 설치, 모델 실행, 파일 관리, 로컬 API의 네 단계가 모두 검증된 것이다. 그 다음에야 문서 요약 앱이나 코드 에디터 같은 외부 도구를 연결하는 편이 문제 원인을 찾기 쉽다.

출처: Ollama Quickstart, Ollama API Introduction, Ollama CLI Reference, Ollama 공식 저장소, Ollama 모델 라이브러리