올라마(Ollama)와 llama.cpp, 로컬 모델을 실행하는 도구

🤔 모델 파일을 받았는데 어떻게 실행하는지 모를 때

허깅페이스에서 가중치 파일을 내려받는 데까지는 갔는데, 그 파일을 더블클릭해서 열 수는 없습니다. 모델 파일은 숫자 묶음일 뿐이라, 모델 파일을 메모리에 올리고 질문을 받아 답을 내는 실행 프로그램이 따로 있어야 합니다. 로컬 AI 이야기에 llama.cpp와 올라마와 LM Studio라는 이름이 늘 함께 나오는 이유입니다.

세 이름이 각각 무엇을 하는지, 서로 어떤 관계인지, 처음 시작할 때 어느 것을 고르고 명령을 어떻게 입력하는지를 정리했습니다.

🔑 llama.cpp와 올라마의 정의

llama.cpp는 모델을 계산해 답을 만드는 실행 도구이고, Ollama는 모델 관리와 대화 및 API 연결을 제공하는 프로그램입니다. API는 다른 프로그램이 모델에 요청을 보내는 연결 방식입니다.

엔진과 완성차의 관계로 생각하면 역할을 나누기 쉽습니다. 다만 Ollama가 모든 모델을 언제나 같은 llama.cpp 엔진으로 실행한다는 뜻은 아닙니다. 지원되는 실행 방식은 모델과 도구 버전에 따라 달라집니다.

llama.cpp는 GGUF 형식의 지원 모델과 CPU 및 GPU 혼합 실행을 제공합니다. GGUF 파일이라고 모든 모델 구조가 바로 실행되는 것은 아닙니다.

LM Studio는 모델을 검색하고 대화할 수 있는 화면을 제공하며 llama.cpp 기반 GGUF와 애플 실리콘의 MLX 경로 등을 지원합니다. Ollama에도 앱 화면이 있으므로 “터미널이면 Ollama, 화면이면 LM Studio”로만 나누지 않고 쓸 모델과 기능 및 기기 지원을 비교합니다.

💻 올라마로 시작하는 명령

이미 설치했다면 먼저 ollama --version으로 버전을 확인합니다. 설치하지 않았다면 공식 다운로드에서 운영체제에 맞는 설치 파일을 사용합니다. 맥은 앱을 Applications로 옮겨 실행하는 방법을 제공합니다. 다른 설치 방식이 이미 있다면 중복 설치하지 않습니다. command not found는 명령을 찾지 못했다는 뜻이므로 설치와 명령 경로를 확인한 뒤 터미널을 다시 엽니다.

터미널에서 설치된 모델과 실행 상태를 확인합니다.

앱이나 서비스가 서버를 실행 중이면 ollama serve를 따로 실행하지 않습니다. 서버 연결 오류가 나면 앱이 켜져 있는지 확인합니다. 명령줄 도구인 CLI만 설치했고 서버가 없는 경우에는 한 터미널에서 ollama serve를 실행해 두고 다른 창에서 조회합니다. 주소를 이미 사용 중이라는 오류는 기존 서버부터 확인합니다.

아래의 설치된모델:태그는 그대로 입력하는 모델 이름이 아닙니다. ollama list에서 확인한 작은 로컬 모델의 정확한 이름으로 바꿉니다.

목록이 비어 있으면 모델 크기 선택과 라이선스 및 저장 공간을 확인한 뒤 공식 라이브러리에서 지원되는 작은 모델을 고릅니다. ollama pull 모델이름:태그로 받으며 run도 없는 모델이면 다운로드할 수 있으므로 이름을 먼저 확인합니다.

대화 화면에서 /bye를 입력하면 대화를 종료합니다. 종료 직후 모델이 메모리에 남아 있을 수 있으며 파일 삭제와 메모리 해제 및 서버 종료는 서로 다릅니다. 직접 ollama serve를 실행한 터미널에서는 Ctrl+C로 그 서버를 종료합니다. Ollama 앱으로 켠 서버는 Ollama 앱을 종료해 끄고, 운영체제 서비스로 켠 서버는 그 서비스 관리 도구에서 끕니다.

ollama ps의 PROCESSOR가 CPU라고 해서 그 자체로 실패나 메모리 부족은 아닙니다. 지원 장치와 실행 설정 및 로그를 함께 확인합니다. 24GB 맥 사례도 당시 환경의 결과로 읽습니다.

🔌 다른 프로그램에 연결하는 API

기본 설정의 Ollama 서버는 내 컴퓨터를 뜻하는 localhost의 11434번 포트에서 요청을 받습니다. 다른 프로그램은 이 주소로 요청해 모델의 답을 받을 수 있습니다. 처음에는 외부 접속을 열지 않고 같은 컴퓨터에서 확인합니다.

다음은 macOS나 리눅스 셸용 예제입니다. model 값을 위에서 확인한 설치된 로컬 모델 이름으로 바꾼 뒤 실행합니다.

stream: false는 답을 여러 조각 대신 이름과 값을 묶어 표현하는 JSON 형식의 응답 하나로 받게 합니다. 결과의 message.content에서 2회의실이 나오는지 확인합니다. 연결 오류는 서버와 주소를, 모델을 찾지 못했다는 오류는 설치된 이름을 확인합니다. 요청 도중 중단하려면 Ctrl+C를 누릅니다.

Ollama와 llama.cpp에는 OpenAI API와 호환되는 기능이 있지만 모든 기능과 상태 관리 방식이 같지는 않습니다. 주소를 바꾸기 전에 대상 프로그램과 모델의 기능 지원을 확인합니다. 클로드 코드와 코덱스 같은 코딩 에이전트의 연결 조건은 아래 클로드 코드와 코덱스를 로컬 모델에 연결하기에서 다룹니다.

Ollama에는 클라우드 모델도 있습니다. 설치 목록에 이름이 보인다는 사실만으로 로컬 실행을 확정하지 않습니다. 모델 설명과 실제 실행 대상 및 도구의 외부 연결을 확인합니다. 클라우드 기능을 끄는 설정은 바로 아래 절에서 설명합니다.

⚙️ 올라마 API 종류, 서버 주소, 동시 요청 설정

앞의 curl 예제가 동작했다면 Ollama 서버가 다른 프로그램의 요청을 받고 있다는 뜻입니다. 스크립트나 웹 화면, 코딩 에이전트에서 이 서버를 계속 쓰려면 서버가 어디에 열려 있는지, 어떤 형식의 요청을 받는지, 요청이 몰리면 메모리가 어떻게 달라지는지 알아야 합니다.

한 포트에서 받는 API 세 종류

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

Ollama API의 주요 경로는 /api/chat(대화), /api/generate(단일 생성), /api/embed(임베딩), /api/tags(설치된 모델 목록), /api/ps(지금 메모리에 올라간 모델)입니다. 서버가 응답하는지와 설치된 모델 이름은 터미널에서 아래 한 줄로 확인합니다.

결과의 models 목록에 설치된 모델 이름이 나옵니다. 호환 API는 원래 서비스의 기능을 일부만 지원하므로, OpenAI나 Anthropic 형식의 앱이 특정 기능에서 오류를 내면 Ollama 문서의 지원 범위부터 확인합니다.

서버 주소와 외부 접근

Ollama 서버는 기본으로 127.0.0.1:11434에 열립니다. 127.0.0.1은 명령을 실행한 그 컴퓨터 자신을 가리키는 주소라서, 같은 컴퓨터의 프로그램만 이 서버에 요청할 수 있습니다. OLLAMA_HOST 환경 변수를 0.0.0.0으로 바꾸면 와이파이나 유선 랜처럼 이 컴퓨터에 연결된 모든 네트워크에서 요청을 받게 됩니다. Ollama 로컬 API는 API 키를 검사하지 않으므로, 이렇게 연 서버는 같은 네트워크의 다른 기기도 인증 없이 쓸 수 있습니다. 다른 기기에서 써야 한다면 기본 주소를 유지한 채 원격 접속의 SSH 터널을 씁니다.

llama.cpp의 llama-server도 기본으로 127.0.0.1에서만 요청을 받습니다. 2026년 10월 24일 공식 저장소 문서 기준 기본 포트는 9931이며, 설치한 버전의 기본값은 llama-server --help로 확인합니다. llama-server는 --api-key 옵션으로 서버 자체에 키 인증을 걸 수 있다는 점이 Ollama와 다릅니다.

동시 요청, 상주 시간, 컨텍스트 길이

여러 프로그램이 한꺼번에 요청하면 Ollama는 메모리가 허락하는 만큼 여러 모델을 올리고, 한 모델 안에서도 요청 여러 개를 함께 처리합니다. 새 모델을 올릴 메모리가 없으면 요청을 대기열에 넣습니다. 이 동작은 서버를 켤 때 환경 변수로 정합니다.

Ollama 문서는 필요한 메모리가 병렬 수 곱하기 컨텍스트 길이에 비례해 늘어난다고 설명합니다. 늘어나는 것은 가중치가 아니라 요청마다 대화 내용을 담아 두는 KV 캐시입니다. 메모리가 빠듯한 기기에서 병렬 수를 올리면 모델 일부가 CPU로 밀려나 오히려 느려질 수 있으므로, 바꾼 뒤 ollama ps의 PROCESSOR 열을 다시 봅니다.

모델은 마지막 요청 뒤 기본 5분 동안 메모리에 남았다가 내려갑니다. 서버 전체의 상주 시간은 OLLAMA_KEEP_ALIVE로, 요청 하나의 상주 시간은 요청에 keep_alive 값을 넣어 정합니다. 컨텍스트 길이는 서버 전체에 OLLAMA_CONTEXT_LENGTH로, 요청마다 "options": {"num_ctx": 8192}처럼 정합니다. 실제로 잡힌 길이는 ollama ps의 CONTEXT 열에 나옵니다. 이미 실행 중인 서버에는 새 터미널에서 바꾼 환경 변수가 적용되지 않으므로 서버를 다시 시작한 뒤 확인합니다.

이름에 cloud가 붙은 Ollama 클라우드 모델은 요청이 Ollama의 서버로 나갑니다. 자료를 내 컴퓨터 밖으로 보내지 않아야 한다면 서버 환경에 OLLAMA_NO_CLOUD=1을 설정하고 서버를 다시 시작합니다. 이 설정은 Ollama의 클라우드 모델 실행과 Ollama 웹 검색을 끄며, 함께 쓰는 다른 앱의 외부 API 호출까지 막지는 않습니다.

🤖 클로드 코드와 코덱스를 로컬 모델에 연결하기

코딩 에이전트를 로컬 모델에 연결한다는 것은 에이전트가 요청을 보내는 주소를 내 컴퓨터의 Ollama 서버로 바꿔, 어떤 파일을 열고 어떤 명령을 실행할지 판단하는 일을 로컬 모델에 맡기는 것입니다. 파일을 읽고 고치는 동작은 클로드 코드나 코덱스 CLI가 그대로 하고, 다음 행동을 정하는 모델만 바뀝니다. 그래서 연결은 되더라도 결과는 로컬 모델의 성능과 컨텍스트 길이에 크게 좌우됩니다.

도구별 연결 방법

ollama launch는 Ollama가 제공하는 연결 명령으로, 실행할 때 모델을 고르게 하거나 ollama launch claude --model 모델이름처럼 바로 지정할 수 있습니다. 목록에는 클라우드 모델도 섞여 있으므로 고른 모델이 로컬 모델인지 확인합니다.

클로드 코드를 직접 연결할 때는 macOS나 리눅스 터미널에서 아래 형식을 씁니다. 모델 이름은 ollama list에 있는 도구 호출 지원 모델로 바꿉니다. 이 한 줄은 이번에 실행한 클로드 코드에만 환경 변수를 넘기며 설정 파일은 바꾸지 않습니다.

주소가 /v1로 끝나지 않는다는 점이 중요합니다. 클로드 코드는 Anthropic 메시지 형식으로 요청하므로, OpenAI 호환 주소인 http://localhost:11434/v1을 넣으면 연결되지 않습니다. 연결한 뒤에는 클로드 코드 안에서 /status를 입력합니다. 표시되는 Status 탭의 Anthropic base URL 줄에 http://localhost:11434가 표시되면 요청이 내 컴퓨터의 Ollama 서버로 가고 있다는 뜻입니다. Auth token(또는 API key) 줄에 ANTHROPIC_AUTH_TOKEN 같은 환경 변수 이름이 보이면 위 명령으로 넣은 값이 쓰이는 것이고, claude.ai 계정이 적힌 Login method 줄이 보이면 환경 변수가 전달되지 않은 것입니다.

코덱스 CLI는 --oss 옵션으로 Ollama 같은 로컬 제공자를 씁니다. 한 번만 쓸 때는 codex --oss --local-provider ollama -m "설치된_로컬_모델_이름"처럼 실행하고, 늘 쓰려면 코덱스 설정 파일 config.toml에 oss_provider = "ollama"를 적습니다.

연결이 제대로 동작하려면 필요한 조건

1. 도구 호출을 지원하는 모델: 에이전트는 모델이 "이 파일을 읽어라", "이 명령을 실행하라"는 도구 호출을 정해진 형식으로 내놓아야 움직입니다. 설치한 모델은 ollama show 모델이름 결과의 Capabilities에 tools가 있는지 봅니다. 없는 모델은 대화만 하고 파일을 고치지 못합니다.
2. 충분한 컨텍스트 길이: 에이전트는 파일 내용과 명령 결과를 계속 쌓습니다. Ollama 문서는 웹 검색, 에이전트, 코딩 도구처럼 긴 컨텍스트가 필요한 작업에 64,000토큰 이상을 권합니다. 그만큼 늘리면 KV 캐시 메모리도 늘어나므로, 늘린 뒤 ollama ps의 CONTEXT와 PROCESSOR 열을 함께 확인합니다.

공식 문서가 밝힌 한계

• 앤트로픽의 지원 범위: 게이트웨이는 요청을 받아 다른 모델 서버로 넘겨 주는 중계 서버입니다. 클로드 코드 공식 문서는 게이트웨이를 거쳐 Claude가 아닌 모델에 연결하는 방식을 지원하지 않는다고 밝힙니다. Ollama 연결은 Ollama가 제공하는 기능이므로, 문제가 생기면 Ollama 문서와 지원 범위를 기준으로 확인합니다. 코덱스의 --oss는 코덱스 CLI가 공식으로 제공하는 옵션이라는 점이 다릅니다.
• 빠지는 기능: Ollama의 호환 API는 특정 도구 사용을 강제하는 tool_choice와, 반복되는 앞부분 입력을 저장해 다시 쓰는 프롬프트 캐싱 같은 일부 기능을 지원하지 않습니다.
• 오프라인 여부: 모델은 로컬이어도 에이전트의 웹 검색이나, 에이전트에 외부 도구를 연결하는 MCP 서버 호출은 인터넷으로 나갈 수 있습니다.

처음에는 날짜와 장소를 적은 연습용 텍스트 파일을 하나 만들어 에이전트에게 읽게 합니다. 에이전트 화면에 표시되는 파일 읽기 도구 호출이 실제로 있었는지, 답의 날짜와 장소가 파일 내용과 같은지 확인하고, 수정이나 긴 작업은 그다음에 맡깁니다.

🛠️ llama.cpp를 직접 쓰는 경우

llama.cpp를 직접 검토할 상황은 다음과 같습니다.

• 실행 옵션을 세밀하게 조정할 때: GPU에 올릴 층 수, 컨텍스트 길이, 여러 GPU에 나누는 비율 같은 옵션을 직접 지정합니다. 그래픽카드 두 장에 가중치를 나눠 올리는 것도 llama.cpp의 옵션으로 합니다.
• 필요한 모델을 직접 실행하려 할 때: 필요한 모델이 현재 버전에서 지원되는지 먼저 확인합니다. 모든 새 모델을 다른 도구보다 먼저 지원하는 것은 아닙니다.
• 여러 대에 나눠 올릴 때: 컴퓨터 사이에서 연산을 요청하는 RPC 백엔드로 지원되는 분산 실행을 구성할 수 있습니다. DGX 스파크 두 대를 묶는 커뮤니티 기록에 이 방식이 쓰였습니다.

소스 코드를 실행 프로그램으로 만드는 빌드는 저장소 안내를 따르며, 맥에서는 Metal이 기본으로 켜집니다. 엔비디아 카드에서는 CUDA 옵션을 켜서 빌드합니다. 처음 시작하는 단계라면 올라마로 모델이 돌아가는 것을 먼저 확인하고, 옵션이 필요해질 때 넘어와도 늦지 않습니다.

🐢 느릴 때 확인하는 순서

답이 비정상적으로 느리면 순서대로 봅니다.

1. ollama ps로 실행 장치를 봅니다. CPU 배치라면 GPU 지원과 설정 및 메모리를 함께 확인합니다.
2. 생각 모드와 출력 길이를 봅니다. 추론 출력을 조절하는 기능은 모델별 지원이 다르며 줄인 뒤에도 답의 정확성을 확인합니다.
3. 입력 길이와 동시 작업을 봅니다. 캐시와 작업 공간 및 다른 앱의 사용량을 함께 확인합니다.
4. 같은 조건의 시간을 비교합니다. 첫 모델 로드와 입력 처리 및 생성 시간을 구분하고 대역폭 하나로 원인을 확정하지 않습니다.

본문의 진단 순서입니다. 한 항목만으로 원인을 단정하지 않고 현재 실행 상태와 설정을 함께 확인합니다.

⚠️ 자주 하는 실수

• 서버가 있는데 하나 더 실행합니다: 앱과 서비스 및 현재 포트 사용부터 확인합니다.
• 표시 크기가 다르면 다른 파일이라고 봅니다: 태그, 버전 식별자와 단위를 함께 확인하며 모든 차이를 단위 문제로 단정하지 않습니다.
• API를 인증 없이 외부에 엽니다: 인터넷 공개 없이 시작하고 외부 접속이 필요하면 원격 접속의 권한 설정을 확인합니다.
• 클라우드 모델을 로컬로 착각합니다: 실제 요청 목적지를 확인합니다.

❓ 자주 묻는 질문

Ollama와 LM Studio는 답이 같나요?

같은 모델이라도 양자화, 입력 템플릿과 생성 설정 및 실행 버전이 다르면 답과 성능이 달라질 수 있습니다. 화면 편의뿐 아니라 모델 지원과 필요한 API를 비교합니다.

허깅페이스에서 받은 GGUF 파일을 Ollama에서 쓸 수 있나요?

지원되는 모델 구조와 GGUF라면 가져오는 방법이 있습니다. 파일 확장자만으로 호환성을 보장하지 않으며 공식 가져오기 문서를 확인합니다.

윈도우에서도 같은 명령인가요?

ollama 명령은 사용할 수 있지만 설치 조건과 셸의 인용 방식은 다릅니다. 위 여러 줄 curl 예제는 macOS와 리눅스용이므로 PowerShell에 그대로 붙이지 않습니다. GPU 가속도 카드와 드라이버 지원을 확인합니다.

로컬 모델로 바꾸면 클로드 코드 사용량 한도를 쓰지 않나요?

모델의 추론이 실제로 내 컴퓨터의 Ollama 서버에서 처리되면 그 추론은 Anthropic의 모델 사용량을 쓰지 않습니다. 로컬 서버를 쓰고 있는지는 클로드 코드 안에서 /status를 입력해, Anthropic base URL 줄이 http://localhost:11434로 표시되는지 보면 알 수 있습니다. 웹 검색이나 다른 연결 도구의 사용량과 비용은 별도입니다.

vLLM은 무엇이 다른가요?

모델을 여러 요청에 제공하는 서버용 실행 도구입니다. 동시 처리, 모델 지원과 하드웨어 조건을 비교해 선택하며 혼자 쓴다는 이유만으로 특정 도구만 가능한 것은 아닙니다.

첫 답을 확인하고 한 가지 바꿔 보기

설치된 작은 로컬 모델로 대화를 시작해 “교육은 11월 12일 2회의실에서 열립니다. 시간은 미정입니다. 날짜, 장소와 시간을 정리하세요”라고 입력합니다. 세 항목을 원문과 대조하고, 모델이 없는 시간을 만들어 냈다면 시간 항목을 오류로 표시합니다.

/bye로 대화를 마치고 ollama ps에서 로드 상태를 확인합니다. 같은 모델로 새 대화를 시작한 뒤 장소만 3회의실로 바꿔 반복합니다. 새 답의 장소는 3회의실이고 날짜와 시간 미정은 유지되어야 합니다.

응답이 느리면 모델을 다시 내려받기 전에 실행 장치와 입력 길이 및 오류 기록을 확인합니다. API 예제도 실행했다면 message.content의 장소를 대조합니다. 추론을 끝낸 뒤 실습 모델의 메모리를 비우려면 ollama stop 설치된모델:태그에서 이름을 바꿔 실행합니다. 파일을 계속 사용할 계획이라면 삭제할 필요는 없습니다.

📋 3줄 요약

1. llama.cpp와 Ollama 및 LM Studio는 역할과 지원 방식이 다르므로 사용할 모델과 기기의 호환성을 확인합니다.

2. 설치된 작은 로컬 모델로 대화와 API 응답을 확인하고 대화 종료와 메모리 해제 및 파일 삭제를 구분합니다.

3. 느릴 때는 실행 장치와 설정 및 기록을 함께 보고 CPU 표시나 대역폭 하나로 원인을 확정하지 않습니다.

참고 자료

• llama.cpp 공식 저장소
• Ollama 명령 안내
• Ollama 채팅 API
• Ollama FAQ
• Ollama macOS 설치 조건
• LM Studio 시작 안내
• Ollama OpenAI 호환 범위
• Ollama Anthropic 호환 범위
• Ollama 컨텍스트 길이
• Ollama 로컬 API 인증
• llama.cpp 서버 옵션
• Ollama의 Claude Code 연결
• Ollama의 Codex 연결
• Claude Code 게이트웨이 지원 범위