Use Ollama with any GGUF Model on Hugging Face Hub

🆕 이제 Hugging Face Hub에서 비공개(private) GGUF 모델도 실행할 수 있다!

개요

대부분 Ollama에서 지원하는 model들을 ollama pull을 이용해서 사용해 보거나 혹은 GGUF들을 받아서 Modelfile을 만든 뒤에는 사용해 봤어도 Hugging Face에서 커뮤니티(bartowski, MaziyarPanahi 등)가 만든 모든 GGUF 양자화 모델을 새로운 Modelfile을 생성하지 않고도 사용해보지는 않았을 것이다.

현재 Hugging Face Hub에 있는 약 45,000개의 공개 GGUF 체크포인트들을 단일 ollama run 명령어로 실행할 수 있다
또한 양자화 타입 선택, 시스템 프롬프트 설정 등의 커스터마이징도 가능하다.

Quick Start

1. 자신이 사용하고자하는 모델 repo를 들어간다.
2. 우측의 Use this model을 누른뒤 설정아이콘을 눌러서 Local Apps 설정을 들어간다.
3. Local Apps 설정에서 ollama를 활성화합니다.
4. 모델 페이지에서 Use this model 드롭다운에서 ollama를 선택합니다. 예: bartowski/Llama-3.2-1B-Instruct-GGUF

ollama run hf.co/{username}/{repository}
# EX)ollama run hf.co/google/gemma-3-27b-it-qat-q4_0-gguf

hf.co와 huggingface.co 도메인 이름 모두 사용할 수 있다.

Custom Quantization

기본적으로 Q4_K_M 양자화가 모델 저장소에 있으면 Default값으로 사용된다.
없는 경우 저장소 내에 있는 합리적인 양자화 타입 중 하나가 선택된다.

다른 타입을 선택하려면

1. 모델 페이지의 Files and versions 탭에서 특정 GGUF 파일에 대한 GGUF 뷰어를 연다.
2. Use this model 드롭다운에서 ollama를 선택한다.
3. 아래와 같은 형식의 명령어가 나오면, 복사하여 실행한다. 

ollama run hf.co/{username}/{repository}:{quantization}
# EX) ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:IQ3_M

 

Custom Chat Template and Parameters

기본적으로 템플릿은 GGUF 파일 내에 저장된 기본 제공 tokenizer.chat_template 메타데이터를 기반으로 일반적으로 사용되는 템플릿 목록에서 자동으로 선택된다.

그런데 GGUF 파일에 기본 제공 템플릿이 없거나 채팅 템플릿을 사용자 정의하려면 저장소에 template이라는 새 파일을 만어서 사용하면 된다. 단, 템플릿은 Jinja 템플릿이 아닌 Go 템플릿이어야 한다.

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

 

Go 템플릿 형식에 대한 자세한 내용은 이 문서를 참조하면 된다.

선택적으로 저장소에 system이라는 새 파일을 만들어 시스템 프롬프트를 구성할 수 있습니다.

샘플링 매개변수를 변경하려면 저장소에 JSON형식의 params라는 파일을 만들어주면 된다.
사용 가능한 모든 매개변수 목록은 이 문서를 참고하면 된다. (이전에 작성했던 글에서의 num_ctx 설정법 참고)

Run Private GGUFs from the Hugging Face Hub

일반적인 모델 Repo들은 위에서 설명한 대로 바로 run으로 다운로드할 수 있는데,
Google이나 Meta처럼 private repo 같은 곳에서는 기본적으로 모델 저장소에서 동의를 진행해 준 뒤 ssh키를 등록해줘야 한다.

1. cat ~/. ollama/id_ed25519.pub를 쳐서 나오는 SSH 키를 복사한다.
2. 허깅페이스의 계정 설정에서 Add new SSH key를 클릭하여 해당 키를 추가한다
3. 위에서 설명했던 것과 같이 run을 실행한다: ollama run hf.co/{username}/{repository}

참고 자료

• Ollama 공식 문서
• Hugging Face Hub GGUF 문서