콘텐츠로 이동

Ollama API

개요

ollama run으로 터미널에서 대화할 수도 있지만, 실제 애플리케이션이 모델을 쓰려면 HTTP API가 필요해요. Ollama는 로컬 포트에 REST API를 띄워서, 텍스트 생성·채팅·모델 관리·임베딩을 프로그램적으로 호출하게 합니다. 이 페이지는 그 API의 핵심 엔드포인트와 옵션을 공식 문서 기준으로 설명해요. 도커나 별도 제품에서 로컬 모델을 끌어다 쓸 때 우리가 쓰는 경로예요.

핵심 개념

기본 주소와 서버 확인

Ollama 서버는 기본적으로 로컬에서 동작하고, 상태/버전 확인은 GET /api/version으로 해요.

텍스트 생성 — /api/generate

/api/generate는 프롬프트 하나로 답을 생성하는 단일 완성 엔드포인트예요. 이전 대화 히스토리가 필요 없는 작업에 적합합니다. stream: false로 두면 응답 전체를 한 번에 받아요.

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?",
  "stream": false
}'

채팅 — /api/chat

/api/chat은 대화 흐름을 다루는 엔드포인트예요. messages 배열에 system·user·assistant·tool 역할의 메시지를 넣고, 매 요청마다 전체 히스토리를 보내요. 도구 호출(tool calling)도 여기서 tools로 지원돼요. 애플리케이션 코드에선 단순 생성이라도 /api/chat을 기본으로 쓰는 편이 자연스러워요.

스트리밍과 옵션

두 엔드포인트 모두 스트리밍을 기본(stream 기본 true)으로, 줄 단위 JSON 조각으로 토큰을 흘려보내요. 스크립트에선 stream: false로 단일 객체를 받는 게 다루기 쉬워요. 응답엔 생성 토큰 수(eval_count), 입력 토큰 수(prompt_eval_count), 나노초 단위 시간 등 토큰/초 계산이 바로 되는 메타데이터가 담겨요.

options 객체로 모델 실행 파라미터를 조절해요. temperature(창의성), num_ctx(컨텍스트 창), num_predict(생성 토큰 한도), seed(재현용) 등이 대표적이에요. keep_alive로 모델을 메모리에 얼마나 유지할지 정합니다.

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "Name three container runtimes."}],
  "stream": false,
  "options": {"temperature": 0.2, "num_ctx": 8192, "num_predict": 200, "seed": 42}
}'

모델 관리·기타 엔드포인트

모델을 프로그램적으로 관리하는 엔드포인트도 있어요. POST /api/pull(모델 내려받기·진행률 스트리밍), DELETE /api/delete(삭제), POST /api/show(모델 메타데이터), POST /api/copy(복사), GET /api/tags(설치 모델 목록), GET /api/ps(현재 메모리에 로드된 모델)가 있어요. 텍스트를 벡터로 바꾸는 임베딩 엔드포인트와, 일부 OpenAI 엔드포인트를 호환해주는 레이어도 제공합니다.

실제 적용 (데이터스케쳐스)

  • 앱에서 로컬 모델 호출 — 분류·파싱 같은 소형 작업을 /api/generate나 /api/chat으로 프로그램에서 호출해요. 외부 API 비용 없이 민감 데이터를 로컬에서 처리할 수 있어요.
  • 스트리밍 UI — 채팅형 UI는 stream을 켜서 첫 토큰을 빨리 보여주고, 배치 작업은 stream: false로 한 번에 받아요.
  • 모델 수명 관리 — keep_alive와 /api/ps로 모델이 메모리에 머무는 시간을 관리해, 잦은 로딩 비용을 줄여요.

일부 OpenAI 호환 엔드포인트는 완전한 OpenAI 기능을 모두 구현하진 않아요. 표준이 필요한 곳은 각 문서의 호환 목록을 확인해요.

더 알아보기