로컬 모델 서빙 기초 (올라마 서버, OpenAI 호환 API, 동시 요청)

Q: 올라마 클라우드 모델도 이 서버로 부르나요?

`:cloud` 태그가 붙은 모델은 같은 방식으로 부르지만 요청이 올라마의 클라우드 서버로 나갑니다. 데이터를 내 컴퓨터 밖으로 보내지 않으려면 클라우드 기능을 끄는 `OLLAMA_NO_CLOUD=1`을 설정합니다.

로컬 모델 서빙은 내 컴퓨터에서 돌리는 모델을 API 서버로 열어 다른 프로그램이 주소와 요청 형식만으로 쓰게 하는 일입니다. 올라마는 11434 포트에서 자체 API와 OpenAI 호환 API, Anthropic 호환 API를 함께 제공하고, 동시 요청 수와 컨텍스트 길이가 메모리 사용량을 정합니다.

같은 말:올라마 서버ollama serve올라마 OpenAI 호환OLLAMA_NUM_PARALLEL로컬 LLM API

홍승협(준이아빠)게시 2026.10.03코스 1 / 8번째 개념

새로 올라온 개념이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요

#AI #API #자동화

🤔 터미널 대화는 되는데 다른 프로그램에서 모델을 부르고 싶을 때
🔑 로컬 모델 서빙의 정의
🌐 서버가 열리는 주소와 바꾸는 법
🔌 한 주소로 받는 API 세 종류
⚖️ 동시 요청과 메모리
⏳ 모델 상주 시간과 컨텍스트 길이
🧰 llama-server, LM Studio와 비교
⚠️ 자주 하는 실수
❓ 자주 묻는 질문
📋 3줄 요약

🤔 터미널 대화는 되는데 다른 프로그램에서 모델을 부르고 싶을 때

올라마(Ollama)를 설치하고 ollama run으로 대화해 보면 로컬 모델이 잘 답합니다. 그다음 떠오르는 질문은 이 모델을 내가 만든 스크립트나 웹 화면, 코딩 에이전트에서 어떻게 부르는지입니다. 매번 터미널에 들어가 대화할 수는 없으니, 모델을 프로그램이 부를 수 있는 서버로 열어 두어야 합니다.

지금부터 올라마 서버가 어디에 열리는지, 어떤 형식의 요청을 받는지, 여러 요청이 동시에 오면 메모리가 어떻게 달라지는지 정리합니다. 설치와 기본 명령은 1차 코스에서 다뤘으므로 여기서는 서버 운영에 필요한 설정만 봅니다. 버전과 기본값은 2026년 9월 28일 공식 문서 기준이고, 올라마 최신 버전은 v0.34.4입니다.

🔑 로컬 모델 서빙의 정의

로컬 모델 서빙은 내 컴퓨터에서 돌리는 모델을 API 서버로 열어 다른 프로그램이 주소와 요청 형식만으로 쓰게 하는 일입니다.

API는 프로그램끼리 요청과 응답을 주고받는 약속입니다. 서빙을 하면 모델을 부르는 쪽은 모델이 어떤 기기에서 어떻게 돌아가는지 몰라도 되고, 주소 하나와 요청 형식만 맞추면 됩니다. 올라마는 앱을 켜 두거나 ollama serve를 실행하면 이 서버가 떠 있는 상태가 되고, 지금 켤 수 있는 설정 목록은 ollama serve --help로 봅니다.

🌐 서버가 열리는 주소와 바꾸는 법

올라마 서버는 기본으로 127.0.0.1의 11434 포트에 열립니다. 127.0.0.1은 이 컴퓨터 자신을 가리키는 주소라서, 같은 컴퓨터의 프로그램만 부를 수 있고 다른 기기에서는 닿지 않습니다. 다른 기기에서 부르려면 OLLAMA_HOST 환경 변수로 여는 주소를 바꿉니다. 설정 위치는 운영체제마다 다릅니다.

환경	설정 방법
맥 앱	`launchctl setenv OLLAMA_HOST "0.0.0.0:11434"` 후 앱 재시작
리눅스 systemd	`systemctl edit ollama.service`에 `Environment="OLLAMA_HOST=0.0.0.0:11434"` 추가 후 재시작
윈도우	사용자 환경 변수에 추가한 뒤 앱 재시작

여기서 주의할 점이 있습니다. 올라마 로컬 서버는 API 키를 검사하지 않습니다. OpenAI 호환 클라이언트가 키 값을 요구해도 올라마는 그 값을 무시합니다. 그래서 0.0.0.0으로 열면 그 컴퓨터에 닿는 누구나 모델을 쓸 수 있으므로, 테일스케일처럼 내 기기끼리만 묶인 망 안에서만 여는 편이 안전합니다. 원격 접속 구성은 원격 접속으로 집 컴퓨터의 로컬 AI 쓰기에, 잠그는 방법은 로컬 AI 보안과 백업에 정리했습니다.

🔌 한 주소로 받는 API 세 종류

올라마 서버는 같은 11434 포트에서 요청 형식이 다른 API 세 가지를 함께 받습니다.

종류	기본 주소	주로 쓰는 곳
올라마 API	`http://localhost:11434/api`	올라마 전용 기능(모델 목록, 모델 받기)
OpenAI 호환	`http://localhost:11434/v1`	OpenAI 형식을 쓰는 앱과 라이브러리
Anthropic 호환	`http://localhost:11434` (클라이언트가 `/v1/messages`를 붙임)	클로드 코드처럼 Anthropic 형식을 쓰는 도구

올라마 API의 주요 경로는 /api/chat(대화), /api/generate(단일 생성), /api/embed(임베딩), /api/tags(설치된 모델), /api/ps(지금 올라가 있는 모델)입니다. OpenAI 형식으로 짠 코드가 있다면 주소만 바꿔 그대로 붙습니다.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")  # 키는 형식상 필요하지만 무시됨
reply = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "로컬 서빙을 한 문장으로 설명해 줘"}],
)
print(reply.choices[0].message.content)

다만 호환 API는 원래 서비스의 일부만 지원합니다. 공식 문서 기준으로 OpenAI 호환은 /v1/chat/completions, /v1/completions, /v1/models, /v1/embeddings, /v1/responses를 받고, 스트리밍, JSON 모드, 이미지 입력, 도구 호출은 되지만 tool_choice와 확률값(logprobs)은 지원하지 않습니다. Anthropic 호환 쪽에서는 프롬프트 캐싱, 토큰 계산 경로, PDF 입력이 빠져 있습니다. 호환 API를 쓰는 앱이 특정 기능에서 오류를 낸다면 이 지원 범위부터 확인합니다.

⚖️ 동시 요청과 메모리

여러 프로그램이 한꺼번에 요청을 보낼 때 올라마의 동시 처리는 두 단계로 나뉩니다. 메모리가 충분하면 여러 모델을 동시에 올리고, 한 모델 안에서도 요청 여러 개를 병렬로 처리합니다. 새 모델을 올릴 메모리가 없으면 요청을 대기열에 넣고 놀고 있는 모델을 내립니다.

환경 변수	뜻	기본값
`OLLAMA_NUM_PARALLEL`	모델 하나가 동시에 처리하는 요청 수	1
`OLLAMA_MAX_LOADED_MODELS`	동시에 올려 둘 모델 수	GPU 수의 3배, CPU 추론이면 3
`OLLAMA_MAX_QUEUE`	바쁠 때 대기열에 넣는 요청 수	512 (넘치면 503 응답)

가장 중요한 것은 병렬 수와 메모리의 관계입니다. 공식 문서는 필요한 메모리가 병렬 수 곱하기 컨텍스트 길이에 비례해 늘어난다고 적습니다. 컨텍스트 2K에 병렬 4면 8K 컨텍스트만큼의 메모리를 추가로 잡는 식입니다. 여기서 늘어나는 것은 모델 가중치가 아니라 요청마다 대화 내용을 담아 두는 KV 캐시입니다. 메모리가 빠듯한 기기에서 병렬 수를 올리면 모델 일부가 CPU로 밀려나 오히려 느려질 수 있습니다. 모델 크기와 메모리 어림셈은 로컬 모델 크기 고르기에서 다뤘습니다.

⏳ 모델 상주 시간과 컨텍스트 길이

모델은 마지막 요청 뒤 5분 동안 메모리에 남았다가 내려갑니다. 다음 요청이 그 뒤에 오면 모델을 다시 올리는 시간이 걸립니다.

상주 시간 바꾸기: 서버 전체는 OLLAMA_KEEP_ALIVE, 요청마다는 keep_alive 값으로 정합니다. "24h"처럼 기간을 주거나, 음수면 계속 유지, 0이면 응답 직후 내립니다
미리 올려 두기: 빈 요청 curl http://localhost:11434/api/generate -d '{"model": "llama3.2"}'를 한 번 보내 둡니다
즉시 내리기: ollama stop 모델이름

컨텍스트 길이는 공식 컨텍스트 문서 기준으로 GPU 메모리가 24GiB 미만이면 4k, 24~48GiB면 32k, 48GiB 이상이면 256k가 기본입니다. 긴 문서나 에이전트 작업에는 최소 64,000토큰을 권합니다. 서버 전체는 OLLAMA_CONTEXT_LENGTH=64000 ollama serve처럼, 요청마다는 "options": {"num_ctx": 64000}으로 정합니다. OpenAI 호환 API에는 컨텍스트 크기를 넘길 방법이 없어서, 그 경로로 쓰려면 서버 설정이나 Modelfile의 PARAMETER num_ctx로 미리 늘려 둡니다. 실제로 잡힌 컨텍스트는 ollama ps의 CONTEXT 열에서 확인합니다.

🧰 llama-server, LM Studio와 비교

올라마 말고도 로컬 모델을 서버로 여는 도구가 있습니다.

llama.cpp의 llama-server: 기본 주소는 127.0.0.1:8080이고 OpenAI 호환과 Anthropic 호환 경로를 모두 제공합니다. -c로 컨텍스트, -np(--parallel)로 동시 처리 슬롯 수를 정하고, --api-key로 키 인증을 걸 수 있습니다. 도구 호출에는 --jinja 플래그가 필요합니다
LM Studio: 앱의 개발자 탭에서 서버를 켜거나 lms server start를 쓰고, 문서 예시 포트는 1234입니다

키 인증을 서버 자체에서 걸고 싶거나 슬롯을 세밀하게 나누고 싶다면 llama-server, 모델 관리와 여러 도구 연동을 편하게 하려면 올라마가 맞습니다. 여러 사람이 동시에 쓰는 규모라면 요청을 묶어 처리하는 vLLM 같은 전용 엔진을 검토하는 사례도 있습니다.

⚠️ 자주 하는 실수

다른 기기에서 부르는데 OLLAMA_HOST를 바꾸지 않습니다: 기본값은 127.0.0.1이라 다른 기기에서는 닿지 않습니다
0.0.0.0으로 연 서버를 인터넷에 노출합니다: 올라마는 키를 검사하지 않으므로 누구나 쓸 수 있습니다
병렬 수만 올리고 메모리를 확인하지 않습니다: ollama ps의 PROCESSOR 열이 CPU로 바뀌었다면 메모리가 부족한 것입니다
OpenAI 호환 요청에 긴 문서를 넣고 잘렸다고 봅니다: 기본 컨텍스트가 짧을 수 있으므로 서버 쪽에서 늘립니다

❓ 자주 묻는 질문

올라마 서버를 켜 두면 계속 메모리를 쓰나요?

서버 프로그램 자체는 가볍고, 메모리를 크게 쓰는 것은 올라간 모델입니다. 기본 5분이 지나면 모델이 내려가므로 요청이 없을 때는 메모리가 비워집니다. 상주 시간을 길게 잡으면 응답은 빨라지는 대신 그만큼 메모리를 계속 씁니다.

올라마 클라우드 모델도 이 서버로 부르나요?

:cloud 태그가 붙은 모델은 같은 방식으로 부르지만 요청이 올라마의 클라우드 서버로 나갑니다. 데이터를 내 컴퓨터 밖으로 보내지 않으려면 클라우드 기능을 끄는 OLLAMA_NO_CLOUD=1을 설정합니다.

요청이 몰리면 서버가 멈추나요?

대기열이 512개까지 쌓이고, 그보다 많으면 과부하를 뜻하는 503 응답을 돌려줍니다. 요청이 꾸준히 몰린다면 병렬 수를 메모리 안에서 조금 올리거나 기기를 나누는 쪽을 봅니다.

📋 3줄 요약

올라마 서버는 기본으로 127.0.0.1의 11434 포트에서만 열리고, 같은 주소로 자체 API(/api)와 OpenAI 호환(/v1), Anthropic 호환(/v1/messages) 요청을 함께 받습니다.
모델 하나가 동시에 처리하는 요청 수 OLLAMA_NUM_PARALLEL의 기본값은 1이고, 이 값과 컨텍스트 길이를 곱한 만큼 메모리가 늘어납니다.
OpenAI 호환 API는 컨텍스트 크기를 요청으로 정할 수 없어서, 긴 문맥이 필요하면 서버 쪽 OLLAMA_CONTEXT_LENGTH나 Modelfile의 num_ctx로 미리 늘립니다.

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

올라마 서버에서 OLLAMA_NUM_PARALLEL을 1에서 4로 올렸습니다. 공식 문서 기준으로 메모리 사용량은 어떻게 달라질까요?

2개념 / 클래스코딩 에이전트와 로컬 모델 연결하기 (클로드 코드, 코덱스, 올라마)