Ollama GGUF 모델 가져오기 및 Modelfile 설정 방법

GGUF 모델을 Ollama로 가져오는 두 가지 방법

GGUF 모델을 Ollama로 가져오는 방법은 두 가지가 있으며, 적절한 방법은 현재 파일의 위치에 따라 결정됩니다. 모델이 Hugging Face 저장소에 있다면 ollama run 명령 하나로 Modelfile 없이 바로 내려받아 실행할 수 있습니다. 만약 .gguf 파일이 이미 서버 디스크에 있다면, 두 줄짜리 Modelfile을 작성한 뒤 ollama create 명령을 실행합니다.

두 방법 모두 결과는 같습니다. 로컬 Ollama 라이브러리에 모델이 등록되어 ollama run 및 Ollama API를 통해 서비스를 제공할 수 있게 됩니다. 다른 사람이 게시한 파일을 사용할 때는 첫 번째 방법을, 직접 모델을 양자화했거나 scp 또는 rsync을 통해 파일을 전달받았을 때, 혹은 서버가 Hugging Face에 접근할 수 없을 때는 두 번째 방법을 사용하십시오.

GGUF 파일은 가중치, 토크나이저, 모델 메타데이터를 하나로 담고 있는 바이너리입니다. 이는 llama.cpp가 읽는 형식이며, Ollama는 llama.cpp를 기반으로 구축되었기 때문에 거의 모든 오픈 모델이 커뮤니티를 통해 GGUF로 변환되어 제공됩니다. Ollama는 .safetensors 가중치 폴더를 직접 불러올 수 없으므로 변환 단계가 반드시 필요합니다.

아래 내용은 Ollama가 이미 설치되어 있고 서비스가 실행 중임을 전제로 합니다. 그렇지 않다면 VPS에 Ollama 설치하기를 먼저 수행한 뒤 돌아오십시오. 가장 먼저 ollama list을 실행하십시오. 연결 오류 대신 표가 출력된다면(비어 있더라도) 서버가 정상 작동 중이며 이 가이드의 나머지 과정을 진행할 수 있습니다.

방법 1: Modelfile 없이 Hugging Face에서 GGUF 실행하기

Ollama는 Hugging Face 저장소에서 GGUF 파일을 직접 가져올 수 있습니다. 명령어는 hf.co/ 접두사를 붙인 저장소 경로입니다.

ollama run hf.co/{username}/{repository}

hf.co와 huggingface.co 모두 도메인 이름으로 사용할 수 있습니다. Hugging Face 문서에 나온 실제 예시는 다음과 같습니다.

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

첫 실행 시 파일을 다운로드하므로 다운로드가 완료될 때까지 채팅 프롬프트가 나타나지 않습니다. 이후 모델은 로컬 라이브러리에 저장되어 빠르게 시작됩니다. 두 번째 셸을 열고 ollama list을 실행하면 저장된 이름을 확인할 수 있습니다. 해당 이름은 태그를 포함한 전체 hf.co/... 문자열이며, 매번 입력하기에는 너무 깁니다. 짧은 별칭을 지정하십시오.

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

이 방법은 GGUF 파일이 실제로 포함된 저장소에서만 작동합니다. .safetensors 가중치만 게시하는 저장소는 Ollama가 가져올 파일이 없으므로, 아래에 설명된 변환 단계를 거쳐야 합니다.

Ollama는 어떤 양자화 방식을 선택합니까?

2026년 8월 25일에 확인한 Hugging Face의 Ollama 문서는 기본값에 대해 다음과 같이 명시합니다. "기본적으로 모델 저장소 내에 Q4_K_M 양자화 방식이 존재하면 이를 사용합니다. 존재하지 않는 경우, 저장소에 있는 적절한 양자화 유형 중 하나를 기본값으로 선택합니다." 따라서 10개의 양자화 파일을 게시하는 저장소는 Q4_K_M을 제공하며, Q4_K_M이 없는 저장소는 Ollama가 대신 선택한 양자화 방식을 사용하게 됩니다. 기본값은 변경될 수 있으므로 의존하기 전에 해당 페이지를 다시 확인하십시오.

태그를 추가하여 특정 양자화 방식을 요청할 수 있습니다.

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

양자화 이름은 대소문자를 구분하지 않으므로 :iq3_m과 :IQ3_M는 동일한 의미입니다. 저장소 내의 짧은 이름이 모호할 경우 안전하게 정확한 파일 이름을 태그로 전달할 수도 있습니다. 태그는 저장소에 존재하는 파일 이름이어야 하므로, 입력하기 전에 Files and versions 탭을 열어 실제 파일 이름을 확인하십시오. 어떤 양자화 방식을 선택할지는 메모리와 품질 사이의 문제이며, Q4, Q8, FP16의 차이점에서 해당 절충안을 적절히 다루고 있습니다.

경로 2: 로컬 디스크에서 .gguf 파일 가져오기

파일이 이미 서버에 있다면 Modelfile이 필요합니다. 한 줄로도 충분합니다. 디렉터리를 만들고 그 안에 Modelfile을 넣은 뒤, FROM으로 해당 파일을 지정하십시오.

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

이 내용을 Modelfile로 저장한 다음 모델을 빌드합니다.

ollama create my-model

ollama create는 기본적으로 현재 디렉터리에 있는 Modelfile이라는 파일을 읽습니다. 파일 이름이 다르거나 다른 위치에 있다면 ollama create my-model -f /home/you/models/my-model/Modelfile과 같이 -f을 사용하십시오. ollama create --help를 실행하면 해당 플래그와 기본값을 확인할 수 있습니다. FROM의 경로는 절대 경로여도 좋고 Modelfile 기준의 상대 경로여도 좋습니다. 따라서 둘 다 같은 디렉터리에 있다면 FROM ./my-model-Q4_K_M.gguf도 작동합니다. 절대 경로를 사용하면 모호함이 완전히 사라집니다.

결과를 신뢰하기 전에 확인하십시오.

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list 목록에 이제 my-model이 포함되어야 합니다. ollama show my-model는 Ollama가 파일 자체 메타데이터에서 읽어 들인 아키텍처, 파라미터 수, 컨텍스트 길이, 양자화 정보를 출력합니다. 파일 이름은 누군가 직접 입력한 문자열일 뿐이므로, 파일 이름을 신뢰하기보다 이 값들을 직접 확인하십시오. 모델이 테스트 프롬프트에 정상적인 언어로 답변하고 멈춘다면 가져오기가 성공한 것입니다. 그렇지 않다면 아래의 템플릿 섹션을 확인하십시오. 거의 항상 그 부분이 원인입니다.

디스크 공간과 관련하여 알아둘 점이 있습니다. ollama create는 GGUF 파일을 원래 위치에서 참조하는 대신 Ollama의 자체 모델 저장소로 복사합니다. 원본 파일을 삭제하기 전까지는 가중치가 디스크에 두 번 저장됩니다. ollama run my-model이 정상적으로 작동하면 원본 파일을 삭제하거나, 중복 비용이 발생하지 않는 곳으로 옮기십시오. Ollama의 모델 디스크 저장 위치에서 구조와 이동 방법을 확인할 수 있습니다.

--quantize가 적용되는 경우와 그렇지 않은 경우

ollama create에는 --quantize 플래그가 있으며, 이는 단 한 가지 경우, 즉 FP16이나 FP32 형식의 전체 정밀도 가중치를 가진 소스 모델을 위해 존재합니다. Ollama의 가져오기 문서에는 q8_0와 k-means 변형인 q4_K_S 및 q4_K_M이 대상 형식으로 나열되어 있습니다.

ollama create --quantize q4_K_M my-model

이미 양자화된 파일에는 이 플래그를 전달하지 마십시오. 이름에 Q4_K_M이나 Q5_K_S가 포함된 .gguf는 이미 이 단계를 거친 상태이므로 플래그가 수행할 작업이 없습니다. 양자화는 높은 정밀도에서 낮은 정밀도로 변환하는 단방향 과정이므로, Q4에서 Q8로 다시 올라갈 수는 없습니다. 소스 파일이 .safetensors 형식의 Hugging Face 저장소라면, Ollama 문서에서 권장하는 도구인 llama.cpp 저장소의 convert_hf_to_gguf.py을 사용하여 먼저 변환한 뒤, 해당 스크립트가 생성한 GGUF 파일을 가져오십시오. Ollama와 llama.cpp의 관계에서 변환 스크립트가 왜 다른 프로젝트에 속하는지 설명합니다.

가져온 GGUF 모델이 깨진 글자를 출력하거나 멈추지 않는 이유는 무엇입니까?

이는 대부분의 가져오기 튜토리얼에서 다루지 않지만, 반드시 마주하게 되는 실패 사례입니다. 증상은 모델이 고장 난 것처럼 보입니다. <|im_start|>assistant 또는 <|end|>과 같은 문자열이 응답에 제어 토큰으로 나타납니다. 모델은 답변을 마친 뒤 스스로 새로운 사용자 질문을 작성하고 그에 대한 답변까지 이어갑니다. Ctrl+C를 누를 때까지 생성 작업이 멈추지 않습니다.

모델 자체는 정상입니다. 채팅 템플릿이 잘못된 것입니다. 채팅 템플릿은 사용자의 메시지를 모델이 학습한 정확한 토큰 시퀀스로 변환하는 래퍼(wrapper)이며, 시스템 프롬프트가 끝나고 사용자 차례가 시작되는 지점을 알리는 고유 마커를 포함합니다. Ollama는 사용자를 위해 템플릿을 하나 선택합니다. 문서에 따르면 GGUF 파일 내부에 저장된 내장 tokenizer.chat_template 메타데이터를 기반으로 "자주 사용되는 템플릿 목록에서 자동으로 선택"됩니다. 해당 메타데이터가 없거나 목록과 일치하는 항목이 없으면 일반적인 래퍼가 적용됩니다. 그러면 모델은 학습 과정에서 본 적 없는 형태의 프롬프트를 보게 되고, 학습된 턴 종료 마커를 찾지 못해 생성을 멈추지 못합니다.

Ollama가 실제로 선택한 템플릿을 확인하십시오:

ollama show --template my-model
ollama show --modelfile my-model

템플릿이 비어 있거나 지나치게 일반적이라면 문제가 확인된 것입니다. Modelfile에 템플릿을 직접 작성하십시오:

FROM /home/you/models/my-model-Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""

PARAMETER stop "<|end|>"

ollama create my-model 명령으로 다시 빌드하고 동일한 테스트 프롬프트를 다시 보냅니다. stop 매개변수는 안전장치 역할을 합니다. 이 매개변수는 특정 문자열이 나타날 때 Ollama가 생성을 강제로 중단하도록 지시하므로, 래퍼를 조정하는 동안에도 생성이 멈추지 않는 증상을 방지합니다. 지정한 마커가 나타나지 않아 응답이 계속된다면, a num_predict ceiling을 사용하여 템플릿 출력과 관계없이 고정된 토큰 수에서 생성을 차단하십시오.

템플릿은 Jinja 템플릿이 아닌 Go 템플릿이어야 합니다. Hugging Face 문서에도 명시되어 있듯이, 원본 모델 저장소의 tokenizer.chat_template 필드에는 Jinja 형식이 포함되어 있어 이를 그대로 복사하면 작동하지 않습니다. Ollama의 구문은 시스템 프롬프트를 위한 {{ .System }}, 사용자 메시지를 위한 {{ .Prompt }}, 모델의 응답을 위한 {{ .Response }}라는 세 가지 변수를 사용합니다. 모델 카드나 tokenizer_config.json에서 실제 턴 마커를 확인한 뒤, 이를 직접 Go 구문으로 다시 작성하십시오.

대부분의 작업을 줄여주는 지름길이 있습니다. 많은 모델이 공통 프롬프트 형식을 공유하므로, 라이브러리에 있는 다른 모델이 동일한 형식을 사용한다면 ollama show --template 명령을 실행하여 출력된 내용을 복사하십시오.

Hugging Face 저장소의 템플릿, 시스템 및 매개변수 파일

Hugging Face 경로는 Modelfile 내의 지침 대신 저장소에 있는 파일을 통해 동일한 제어 기능을 제공합니다. 저장소 소유자이거나 직접 양자화(quant)한 모델을 게시하는 경우, 해당 파일들을 추가하면 모든 ollama run hf.co/...이 이를 자동으로 인식합니다.

• template라는 이름의 파일은 Go 템플릿을 포함합니다. 규칙은 동일하며, Jinja가 아닌 Go를 사용해야 합니다.
• system이라는 이름의 파일은 시스템 프롬프트를 포함합니다.
• params이라는 이름의 파일은 샘플링 매개변수를 포함하며, 반드시 JSON 형식이어야 합니다.

최소한의 params 파일 예시:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

저장소 소유자가 아닌 경우에는 해당 파일을 추가할 수 없습니다. 모델을 한 번 가져온(pull) 후, ollama show --modelfile hf.co/...을 실행하여 제공받은 내용을 덤프하고 그 출력을 Modelfile로 저장하십시오. 이 파일의 FROM 줄은 Ollama가 이미 다운로드한 blob을 가리키므로, TEMPLATE 및 PARAMETER 줄을 편집한 뒤 ollama create을 실행하여 아무것도 다시 다운로드하지 않고 고정된 로컬 복사본을 빌드할 수 있습니다. 이것이 타인의 잘못된 양자화 모델을 수정하는 표준적인 방법입니다.

비공개 GGUF 저장소를 가져오는 방법

비공개 저장소에 접근하려면 Hugging Face 계정에 Ollama의 SSH 키를 등록해야 합니다. 이 방식은 API 토큰 대신 SSH 키를 사용하는 것이 공식적인 방법이므로, 이미 보유한 토큰으로는 저장소를 열 수 없습니다.

공개 키를 출력합니다. 공식 스크립트로 Ollama를 설치한 Linux 서버에서는 서비스가 ollama 사용자로 실행되므로, 키는 해당 사용자의 홈 디렉터리에 위치합니다.

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

만약 ollama serve를 본인 계정으로 직접 실행한다면 경로는 ~/.ollama/id_ed25519.pub이 됩니다. 전체 줄을 복사한 뒤, https://huggingface.co/settings/keys에서 Hugging Face 계정 설정으로 이동하여 새로운 SSH 키로 추가합니다. 이제 일반 명령어로 비공개 저장소를 가져올 수 있습니다.

ollama run hf.co/{username}/{repository}

키를 추가했는데도 가져오기가 실패한다면, 잘못된 파일을 출력했을 가능성이 큽니다. 서버가 다운로드를 수행하며 자신의 키를 제시하는데, systemd로 시작된 서버는 사용자의 ~/.ollama을 읽지 않기 때문에 홈 디렉터리에 있는 키는 Hugging Face가 인식하는 키가 아닙니다.

모델이 VPS에서 실행될 수 있습니까?

이를 결정하는 수치는 디스크상의 파일 크기와 컨텍스트 윈도우에 필요한 메모리의 합입니다. 가중치는 파일에서 차지하는 크기와 거의 동일하게 메모리에 로드되며, 컨텍스트 할당은 그 위에 추가되어 허용하는 토큰 수에 따라 증가합니다. ollama list를 실행하여 Ollama가 기록한 모델 크기를 확인하고, 서버의 free -h과 비교하십시오. 이때 운영체제와 서버에서 실행 중인 다른 프로세스를 위한 여유 공간을 확보해야 합니다. 실제 모델에 적용된 계산 사례를 확인하려면 VPS에서 Nemotron 3.5 Lightning 실행하기를 참조하십시오. 여기에는 가져올 정확한 태그, 필요한 RAM 용량, CPU 전용 서버의 성능 수준이 명시되어 있습니다.

사용자가 간과하기 쉬운 부분은 컨텍스트입니다. 기본 윈도우 크기로 로드되는 모델이라도 num_ctx를 높이면 실패할 수 있는데, 이는 할당량이 요청한 윈도우 크기에 비례하여 확장되기 때문입니다. num_ctx 설정과 메모리 비용에서 크기 산정 방법을 확인할 수 있습니다. 총합이 너무 크다면 일반적으로 동일 모델의 더 작은 양자화 버전을 사용하는 것이 해결책이며, 이에 대한 비교는 Q4와 Q8 비교에서 다룹니다.

실패는 명확하게 나타납니다. CPU 전용 VPS에서는 커널의 out of memory killer가 프로세스를 중단시키며, journalctl -u ollama -n 50와 dmesg을 함께 확인하면 종료 기록을 볼 수 있습니다. GPU가 있는 서버에서는 ollama ps을 실행하면 PROCESSOR 열이 출력됩니다. 이를 통해 로드된 모델이 GPU 메모리에 있는지, 시스템 메모리에 있는지, 혹은 양쪽에 나뉘어 있는지 알 수 있습니다. 시스템 메모리로 넘어간 모델도 응답은 하지만 속도가 느립니다. 초당 토큰 수 측정을 통해 "느리다"는 표현을 양자화 버전 간에 비교 가능한 수치로 변환할 수 있습니다.

가져온 모델 확인하기

가져오기 작업을 마친 후에는 다음 네 가지 명령어를 순서대로 실행하십시오.

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list은 모델이 존재하는지 확인하고 Ollama가 기록한 모델 크기를 보여줍니다. ollama show는 Ollama가 GGUF 파일에서 필요한 메타데이터를 정상적으로 읽어 들였는지 확인합니다. ollama show --modelfile은 모델이 실제로 사용할 템플릿과 매개변수를 보여줍니다. 이는 사용자가 문제를 겪기 전에 잘못된 출력 결과를 유발하는 설정을 미리 찾아내는 중요한 단계입니다. 테스트 프롬프트는 전체 체인을 검증합니다. 템플릿이 손상된 모델은 아주 짧은 요청에도 실패하기 때문입니다. 프롬프트 결과가 정상적으로 돌아오면, 해당 모델 이름을 Ollama API와 통신하는 다른 모든 도구에서 사용할 수 있습니다. 여기에는 자체 서버를 가리키는 코딩 에이전트도 포함됩니다. 잘못 가져온 모델은 ollama rm my-model 명령어로 삭제하고 다시 빌드하십시오. 이 명령어는 Ollama가 생성한 복사본만 삭제하며, 원본 .gguf 파일은 그대로 유지합니다.

FAQ

Modelfile을 작성하지 않고도 GGUF를 Ollama로 가져올 수 있습니까?

네, 파일이 Hugging Face 저장소에 있는 경우 가능합니다. ollama run hf.co/{username}/{repository}은 해당 파일을 직접 가져와 실행하며, ollama run hf.co/{username}/{repository}:{quantization}는 특정 양자화 버전을 선택합니다. Modelfile은 로컬 디스크에 이미 존재하는 .gguf를 사용할 때만 필요하며, 이 경우 FROM /path/to/file.gguf 뒤에 ollama create my-model을 붙인 한 줄만 작성하면 됩니다.

양자화 방식을 지정하지 않으면 Ollama는 어떤 버전을 다운로드합니까?

2026년 8월 25일 기준 Hugging Face 문서에 따르면, 저장소에 해당 양자화 버전이 존재할 경우 Q4_K_M이 사용되며, 그렇지 않으면 저장소에 있는 적절한 양자화 유형 중 하나를 선택합니다. 이를 제어하려면 :Q8_0와 같은 태그를 추가하십시오. 실제로 어떤 파일이 다운로드되었는지 확인하려면 파일 이름이 아닌 파일 메타데이터에서 양자화 정보를 출력하는 ollama show <model>을 사용하십시오.

가져온 모델이 반복되거나 생성을 멈추지 않는 이유는 무엇입니까?

채팅 템플릿이 모델과 일치하지 않기 때문입니다. Ollama는 GGUF 내부의 tokenizer.chat_template 메타데이터에서 템플릿을 자동으로 선택하는데, 이 메타데이터가 없거나 인식할 수 없는 경우 일반적인 래퍼가 적용되어 모델이 학습 시 사용된 턴 종료 마커를 인식하지 못하게 됩니다. 현재 템플릿을 확인하려면 ollama show --template <model>를 실행하고, Modelfile에 TEMPLATE 블록과 PARAMETER stop 라인을 추가한 뒤 ollama create를 다시 실행하십시오. 이때 Go 템플릿 형식으로 작성해야 합니다. 원본 저장소의 Jinja 템플릿은 작동하지 않습니다.

다운로드한 GGUF 파일에 --quantize를 사용해야 합니까?

아니요. --quantize은 ollama create 과정에서 FP16 또는 FP32 소스를 변환하는 데 사용되며, 이미 Q4_K_M과 같이 파일 이름에 양자화 정보가 포함된 파일은 이미 변환이 완료된 상태입니다. 다시 양자화한다고 해서 정밀도가 복구되지 않으며, 이전 상태로 되돌릴 방법도 없습니다. 이 플래그는 직접 safetensors를 전체 정밀도 GGUF로 변환한 후 더 작은 크기의 모델이 필요할 때만 사용하십시오.

비공개 GGUF 저장소를 어떻게 가져옵니까?

Ollama의 SSH 공개 키를 Hugging Face 계정에 추가하십시오. 표준 Linux 설치 환경에서는 sudo cat /usr/share/ollama/.ollama/id_ed25519.pub로 키를 출력할 수 있으며, 서버를 사용자 계정으로 직접 실행하는 경우에는 ~/.ollama/id_ed25519.pub에서 확인할 수 있습니다. 이 키를 계정의 SSH 키 설정 페이지에 추가하십시오. 설정이 완료되면 ollama run hf.co/{username}/{repository}을 통해 본인의 비공개 저장소나 소속된 조직의 저장소에 접근할 수 있습니다.