Ollama API 사용법, 로컬 LLM을 내 서비스에 연동하기
Ollama를 설치해서 로컬 LLM을 돌리는 일은 이제 꽤 익숙해졌습니다. 터미널에서 모델 하나 내려받고 짧게 대화해 보는 건 클릭 몇 번으로 끝나거든요. 그런데 이걸 내 파이썬 스크립트나 웹 서비스 백엔드에 붙여 쓰려고 하면 이야기가 조금 달라집니다. 포트 설정이 꼬이거나 CORS 보안 정책에 막혀서 통신 에러가 나기 쉽더라구요.
기본적으로 Ollama는 로컬 호스트의 11434 포트를 열어 내부 요청을 받도록 되어 있구요. 이 기본 장벽을 풀지 않으면 로컬 웹 브라우저에서 실행되는 자바스크립트 코드조차 API에 닿지 못합니다. 다행히 최신 버전의 Ollama는 OpenAI 규격과 비슷한 엔드포인트를 함께 제공해서 연동 작업 자체는 훨씬 단순해졌습니다. 기존 클라우드 API 호출 코드를 크게 바꾸지 않고도 로컬 엔진으로 옮겨 탈 수 있습니다.
Ollama API를 서비스에 붙이는 순서
Step 1: 로컬에서 API 서버 통신 상태 체크
가장 먼저 할 일은 백그라운드에서 돌아가는 Ollama 서버가 요청에 제대로 답하는지 확인하는 것입니다. 기본 포트인 11434로 curl 요청을 보내서 정상 동작 여부를 먼저 봐야 하구요. 응답 스트리밍을 끄는 옵션을 넣어 한 번에 텍스트가 떨어지는지 확인하는 편이 좋습니다. 터미널을 열고 아래 명령어를 넣어 보세요.
응답 JSON 안에 response 필드가 들어 있고, 텍스트가 정상적으로 돌아온다면 일단 엔진 자체는 제대로 작동하는 상태입니다.
Step 2: 외부 접속 허용을 위한 CORS 환경 변수 수정
로컬에서 잘 뜨는 걸 확인한 뒤, 프론트엔드 웹 앱이나 다른 컨테이너에서 API를 호출하려고 하면 CORS 에러가 날 수 있습니다. 보안을 위해 Ollama가 기본적으로 외부 요청을 꽤 단단하게 막아두기 때문이거든요. 이 제한을 풀려면 운영체제 시스템 환경 변수에 값을 직접 넣어야 합니다. 윈도우 환경에서는 시스템 트레이에 있는 Ollama 앱을 완전히 종료한 다음, 아래 환경 변수 두 개를 등록하고 다시 실행해야 반영됩니다.
OLLAMA_ORIGINS = *
맥이나 리눅스 환경이라면 터미널에서 launchctl을 사용하거나 systemd 서비스 설정 파일을 열어 같은 환경 변수를 넣어주면 됩니다.
Step 3: OpenAI SDK 호환 코드로 연동 구현
서버를 다시 띄웠다면 이제 애플리케이션 코드에 붙일 차례입니다. Ollama 전용 클라이언트도 있지만, 기존 OpenAI 패키지를 재활용하는 방식이 가장 무난합니다. 프로젝트에서 쓰던 코드 구조를 거의 건드리지 않고 로컬 LLM을 끼워 넣을 수 있으니까요. Node.js 환경을 예로 들면 다음처럼 클라이언트를 만들 수 있습니다.
const client = new OpenAI({
baseURL: 'http://localhost:11434/v1',
apiKey: 'any-string-here'
});
apiKey 매개변수에는 아무 문자나 넣어도 에러 없이 통과하므로, 별도 인증값이 없어도 기본 연동은 바로 시작할 수 있습니다.
Step 4: JSON 모드 설정으로 데이터 포맷 고정
웹 서비스 개발에서는 자유로운 줄글 답변보다 일정한 구조의 JSON 형식이 더 자주 필요합니다. 그럴 때 API 요청 파라미터에 response_format 설정을 추가하면 구조가 정돈된 결과물을 받을 수 있구요. 이 옵션을 쓸 때는 프롬프트 안에도 원하는 JSON 구조를 구체적으로 적어 두는 편이 좋습니다. 그래야 엉뚱한 문자열이 튀어나오지 않습니다. 아래처럼 호출 객체에 포맷 인자를 넣어 요청하면 됩니다.
model: 'llama3',
messages: [{ role: 'user', content: 'JSON 형식으로 회원 프로필 데이터를 한 명분 만들어줘' }],
response_format: { type: 'json_object' }
});
다만 모델 체급이 너무 작은 8B 이하의 로컬 모델들은 가끔 괄호 개수를 못 맞춰서 출력이 깨질 수 있습니다. 이런 경우에는 가벼운 검증 로직을 코드 쪽에 넣어 두는 편이 유용합니다.
로컬 LLM 연동이 주는 감각
직접 로컬 서버 API에 프로젝트 연동 테스트를 해보면, 요금 청구서 걱정이 없다는 점이 가장 먼저 체감됩니다. 매번 Claude나 GPT API를 호출할 때마다 토큰을 아끼려고 프롬프트를 깎던 번거로움이 줄어들거든요. 다만 회사 내부망이 아닌 클라우드 운영 환경에 배포할 때는 계산이 다시 복잡해집니다. GPU 인스턴스를 계속 유지하는 서버 비용이 오히려 API 사용료보다 더 커질 수도 있기 때문입니다.
앞으로는 로컬 LLM과 상용 API를 함께 쓰는 하이브리드 아키텍처가 점점 자연스러운 선택지가 될 가능성이 큽니다. 간단한 맞춤법 검사나 텍스트 데이터 파싱 같은 반복 작업은 로컬 Ollama API에 맡기고, 무거운 논리 추론만 Claude에 넘겨 비용을 줄이는 방식이죠. 특히 프라이버시가 민감한 개인 데이터 가공 영역에서는 로컬 구동 API가 꽤 강한 선택지가 될 수 있습니다.
처음에 CORS 에러로 주저앉지 않고 통신만 한 번 제대로 뚫어 두면, 개발용 AI 비서처럼 꽤 넓게 활용할 수 있습니다. 다음번에는 로컬 API에 커스텀 시스템 프롬프트를 미리 넣어서 고유 모델로 뽑아내는 Modelfile 빌드법을 이어서 다뤄보겠습니다.
이런 글도 있어요
관련 검색어
- 🔍 Ollama 사용법
- 🔍 Ollama 비교
- 🔍 로컬 LLM 사용법
- 🔍 로컬 LLM 비교
- 🔍 API 연동 사용법
- 🔍 API 연동 비교
