#Ollama

오픈 모델을 내 컴퓨터에서 한 줄로 내려받아 실행하고, 로컬 HTTP API 로 제공하는 런타임입니다. 내부적으로 llama.cpp 계열 엔진 위에서 GGUF 모델을 돌리며, localhost:11434 에 자체 API·OpenAI 호환 API 를 동시에 띄워 줍니다. 데이터가 밖으로 나가면 안 되는 실험, 비용 없는 반복 테스트, 임베딩 배치 작업에 특히 유용합니다.

#설치

macOS·Windows 는 ollama.com/download 의 데스크톱 앱으로도 설치할 수 있습니다. 설치하면 서버가 백그라운드로 뜨고, 기본적으로 127.0.0.1:11434 에 바인딩됩니다.

ollama --version        # 설치 확인
ollama run gemma4       # 모델을 받고 곧바로 대화 세션 시작

⚠️ 함정: 기본 바인딩은 127.0.0.1 입니다. 다른 기기(도커 컨테이너 포함)에서 접근하려면 OLLAMA_HOST=0.0.0.0:11434 로 바꿔야 하는데, Ollama API 에는 인증이 없습니다. 외부에 열 때는 반드시 리버스 프록시나 방화벽 뒤에 두세요.

#주요 명령어

ollama run 에서 자주 쓰는 플래그입니다.

모델 이름은 이름:태그 형식입니다. 태그를 생략하면 latest 이고, 태그로 크기·양자화를 고릅니다. 사용 가능한 태그는 ollama.com/search 의 모델 페이지에서 확인합니다.

#Modelfile — 커스텀 모델 만들기

Dockerfile 과 비슷한 형식으로 베이스 모델 + 파라미터 + 시스템 프롬프트를 묶어 새 모델 이름으로 저장합니다. 가중치를 복사하지 않으므로 거의 공간을 차지하지 않습니다.

FROM gemma4
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
SYSTEM """
너는 사내 코드 리뷰어다. 지적은 파일:라인 형식으로 하고, 확신이 없으면 추측하지 말고 질문한다.
"""

ollama create reviewer -f ./Modelfile
ollama run reviewer
ollama show --modelfile reviewer   # 최종 적용된 Modelfile 확인

⚠️ 함정: 컨텍스트 길이 기본값은 모델이 지원하는 최대치보다 훨씬 작게 잡혀 있습니다(FAQ 기준 4096 토큰). 긴 문서를 넣으면 에러 없이 앞부분이 조용히 잘립니다. RAG 나 긴 대화에서 답이 이상하면 먼저 num_ctx 를 의심하세요. 서버 전체 기본값은 OLLAMA_CONTEXT_LENGTH 환경 변수로 바꿀 수 있고, 늘릴수록 메모리 사용량도 함께 늘어납니다.

#GGUF 모델 가져오기

Hugging Face 에 올라온 GGUF 는 Modelfile 없이 바로 실행할 수 있습니다.

# 기본: 저장소에 Q4_K_M 이 있으면 그것을 사용
ollama run hf.co/{username}/{repository}

# 양자화 지정
ollama run hf.co/{username}/{repository}:Q8_0

# 예: 한국어 튜닝된 BGE-M3 임베딩 모델
ollama pull hf.co/Neuwhufbox/BGE-m3-ko-gguf

로컬 GGUF 파일은 FROM /path/to/model.gguf 한 줄짜리 Modelfile 로 ollama create 하면 됩니다. Ollama 는 GGUF 를 가져올 때 양자화를 해주지 않으므로, 필요하면 llama.cpp 로 미리 양자화해 두세요. 직접 파인튜닝한 모델을 GGUF 로 변환해 등록하는 전체 과정은 파인튜닝 예제에 있습니다.

#REST API

#/api/chat

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    { "role": "system", "content": "한국어로 세 문장 이내로 답한다." },
    { "role": "user", "content": "벡터 DB 가 왜 필요한가?" }
  ],
  "stream": false,
  "options": { "temperature": 0.2, "num_ctx": 8192 },
  "keep_alive": "10m"
}'

응답의 message.content 가 답변이고, prompt_eval_count·eval_count(토큰 수), eval_duration(나노초)으로 속도를 계산할 수 있습니다. 한 번 묻고 끝나는 단순 생성은 /api/generate(prompt 필드)를 씁니다.

구조화 출력 예시입니다.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [{ "role": "user", "content": "서울은 대한민국의 수도이고 인구는 약 930만이다. 정보를 추출해." }],
  "stream": false,
  "format": {
    "type": "object",
    "properties": { "city": { "type": "string" }, "population": { "type": "integer" } },
    "required": ["city", "population"]
  }
}'

#OpenAI 호환 엔드포인트

http://localhost:11434/v1/ 은 OpenAI API 형식을 따릅니다. 기존 OpenAI SDK 코드에서 baseURL 만 바꾸면 로컬 모델로 돌릴 수 있어, 비용 없는 개발·테스트 환경으로 쓰기 좋습니다.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:11434/v1/",
  apiKey: "ollama", // 필수 값이지만 검사하지 않음
});

const res = await client.chat.completions.create({
  model: "gemma4",
  messages: [{ role: "user", content: "RAG 를 한 문장으로 설명해줘" }],
});
console.log(res.choices[0].message.content);

지원 엔드포인트: /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/models, /v1/responses(상태 없는 요청만). logprobs 처럼 지원하지 않는 필드도 있으니 옮길 때 확인하세요.

또한 Anthropic 호환 API 도 제공하므로, ollama launch claude 로 Claude Code 를 로컬/Ollama 클라우드 모델에 붙일 수 있습니다. → Claude Code

#임베딩 모델 사용

RAG 의 인덱싱 단계는 호출량이 많아 로컬 임베딩의 이득이 가장 큰 곳입니다. → 임베딩 개념, RAG

ollama pull embeddinggemma

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": ["첫 번째 문서", "두 번째 문서"]
}'
# → { "embeddings": [[...], [...]], ... }

• input 에 문자열 하나 또는 배열을 넣습니다. 배열로 묶어 보내면 요청 수가 줄어 훨씬 빠릅니다.
• /api/embed 가 돌려주는 벡터는 L2 정규화되어 있어, 코사인 유사도와 내적이 같은 값이 됩니다.
• 공식 문서가 권하는 모델: embeddinggemma, qwen3-embedding, all-minilm. 한국어 비중이 크면 다국어 모델(BGE-M3 계열 등)을 후보에 넣고 자기 데이터로 검색 품질을 비교해서 고르세요.

LangChain 에서는 @langchain/ollama 패키지로 붙입니다.

import { ChatOllama, OllamaEmbeddings } from "@langchain/ollama";

const llm = new ChatOllama({ model: "gemma4", temperature: 0 });
const embeddings = new OllamaEmbeddings({ model: "embeddinggemma" });

const vector = await embeddings.embedQuery("로컬 임베딩 테스트");

⚠️ 함정: 인덱싱할 때와 검색할 때 같은 임베딩 모델(같은 태그·양자화) 을 써야 합니다. 모델을 바꾸면 벡터 공간이 달라져 기존 인덱스를 전부 다시 만들어야 합니다. 태그를 생략한 latest 는 나중에 가리키는 대상이 바뀔 수 있으니 운영에서는 태그를 고정하세요.

#로컬 모델 선택 팁

⚠️ 함정: 로컬 소형 모델은 도구 호출 형식을 자주 틀리거나 아예 도구를 부르지 않습니다. 클라우드 모델로 만든 에이전트를 그대로 로컬 모델로 바꾸면 에러 없이 품질만 떨어집니다. 모델을 바꿀 때마다 평가셋을 다시 돌리세요.

#참고 자료

• Ollama 공식 문서
• Ollama — CLI Reference
• Ollama — Modelfile Reference
• Ollama — Chat API
• Ollama — OpenAI compatibility
• Ollama — Embeddings
• Ollama — FAQ
• Hugging Face — Use Ollama with any GGUF Model
• GitHub — ollama/ollama