Huggingface 모델을 Ollama에 등록하기

huggingface to ollama

1. 소개

Ollama는 로컬 환경에서 LLM(Large Language Model)을 쉽게 다룰 수 있도록 도와주는 툴입니다. 주로 Llama 기반 모델들을 사용하지만, 그 외 다양한 모델도 활용할 수 있습니다. 오늘은 Hugging Face에서 제공하는 모델을 Ollama에 등록하여 사용할 수 있는 방법을 단계별로 알아보겠습니다.

2. 준비물 확인하기

1. Hugging Face 계정: 모델을 다운받기 위해 필요합니다.
2. Ollama 설치: Ollama가 제대로 설치되어 있어야 합니다. (Mac 또는 Linux 환경에서 동작)
3. 터미널/CLI 사용법: 기본적인 터미널 명령어 사용 방법.

3. Hugging Face에서 모델 찾기

우선 Hugging Face에서 원하는 모델을 찾습니다. Ollama와 함께 사용하기 위해서는 gguf 형태의 양자화(Quantized) 모델을 받는 것이 좋습니다. 모델 크기가 상대적으로 작아, 로컬 환경에서 돌리기에 훨씬 수월하기 때문입니다.

1. Hugging Face에 접속합니다.
2. 탐색창에서 “gguf” 키워드로 검색하거나, 원하는 모델을 찾아서 gguf 버전이 있는지 확인합니다.
3. 해당 모델 리포지토리에서 .gguf 파일을 다운로드합니다.
   • 예: llama-3.2-Korean-Bllossom-3B-gguf-Q4_K_M.gguf (가상의 예시)

팁: 모델이 클 경우 RAM 점유율이 많아질 수 있으니, 먼저 작은 용량의 모델을 테스트 삼아 사용해보는 것을 추천합니다.

4. Modelfile 작성하기

Ollama는 Docker와 비슷한 이미지 생성 방식을 사용합니다. Ollama가 원하는 형태대로 작성된 “Modelfile”이 필요합니다.
아래는 예시 Modelfile입니다. 파일 이름은 Modelfile(확장자 없이)로 저장해주세요.

#Modelfile  
FROM ./llama-3.2-Korean-Bllossom-3B-gguf-Q4\_K\_M.gguf

TEMPLATE """{{- if .Messages }}  
{{- range $index, $\_ := .Messages }}  
{{- if eq .Role "user" }}  
{{- if and (eq (len (slice $.Messages $index)) 1) $.Tools }}\[AVAILABLE\_TOOLS\] {{ $.Tools }}\[/AVAILABLE\_TOOLS\]  
{{- end }}\[INST\] {{ if and $.System (eq (len (slice $.Messages $index)) 1) }}{{ $.System }}

{{ end }}{{ .Content }}\[/INST\]  
{{- else if eq .Role "assistant" }}  
{{- if .Content }} {{ .Content }}  
{{- else if .ToolCalls }}\[TOOL\_CALLS\] \[  
{{- range .ToolCalls }}{"name": "{{ .Function.Name }}", "arguments": {{ .Function.Arguments }}}  
{{- end }}\]  
{{- end }}  
{{- else if eq .Role "tool" }}\[TOOL\_RESULTS\] {"content": {{ .Content }}} \[/TOOL\_RESULTS\]  
{{- end }}  
{{- end }}  
{{- else }}\[INST\] {{ if .System }}{{ .System }}

{{ end }}{{ .Prompt }}\[/INST\]  
{{- end }} {{ .Response }}  
{{- if .Response }}  
{{- end }}"""  
PARAMETER stop \[INST\]  
PARAMETER stop \[/INST\]

SYSTEM """You are a helpful AI assistant. Please answer the user's questions kindly. 당신은 유능한 AI 어시스턴트 입니다. 사용자의 질문에 대해 친절하게 답변해주세요."""

• FROM: Ollama가 불러올 모델의 경로(또는 파일명)를 지정합니다.
• TEMPLATE: 메시지 작성 규칙, 시스템 프롬프트 등을 정의합니다. 이 템플릿을 통해 사용자 입력과 어시스턴트 출력을 구조적으로 관리할 수 있습니다.
• PARAMETER stop: 특정 패턴을 만나면 답변을 중단하도록 하는 파라미터를 설정합니다.
• SYSTEM: AI 시스템의 기본 프롬프트(= 시나리오, 역할)입니다. Ollama가 답변을 생성할 때 기준으로 삼게 됩니다.

5. Ollama에 모델 등록하기

이제 준비가 모두 끝났습니다. 다음 명령어를 통해 새로운 Ollama 모델 이미지를 빌드(생성)해보겠습니다:

ollama create llama3.2-kor -f Modelfile

• llama3.2-kor: Ollama 내부에서 사용할 모델 이미지를 가리키는 이름입니다. 원하는 이름을 자유롭게 지정 가능합니다.
• -f Modelfile: 빌드 시 사용할 파일을 명시합니다.

명령어를 실행하면 대략 아래와 같은 출력이 나타납니다:

transferring model data 100%  
using existing layer sha256:389f380bbfbe77d9171937b3d166a26ccc3e04201f3d9fb0ca1b5e01b6787621  
using existing layer sha256:491dfa501e59ed17239711477601bdc7f559de5407fbd4a2a79078b271045621  
creating new layer sha256:a25a6d48d6611ea12c25544d43104f7a4bcc68da33459f80e9bd0b5835ce05a4  
using existing layer sha256:ed11eda7790d05b49395598a42b155812b17e263214292f7b87d15e14003d337  
creating new layer sha256:fd9d4efaf9d0b1ddaf61355ebb82636402b47d87ad56a32c4ad09f8b2e3114a0  
writing manif  
...

참고: 이미지(모델)가 생성되는 데 시간이 조금 걸릴 수 있습니다. 용량이 큰 모델일수록 오래 걸립니다.

6. 모델 테스트하기

빌드가 끝났다면 이제 Ollama에 “llama3.2-kor”라는 이름으로 모델이 등록되었습니다. 다음 명령어로 간단히 테스트해볼 수 있습니다:

ollama run llama3.2-kor

그럼 대화형으로 모델과 인터랙션이 가능합니다.
(예: “안녕, 오늘 날씨가 어때 보여?” 라고 물어보면, 모델이 지정된 시스템 프롬프트에 따라 답변을 생성합니다.)

7. 마무리 & 주의 사항

• 모델 성능: gguf 형태의 모델은 용량을 줄였기 때문에 성능이 떨어질 수 있습니다. 적절한 균형점을 찾는 것이 중요합니다.
• 저작권: 모델마다 저작권·라이선스가 다를 수 있으니, 사용하기 전에 라이선스를 꼭 확인하세요.
• 하드웨어 스펙: 로컬에서 큰 모델을 돌릴 경우, GPU나 CPU 자원 소모가 크니 PC 사양을 고려해야 합니다.

결론

이렇게 Hugging Face에서 받은 .gguf 모델을 Modelfile을 통해 Ollama에 등록하는 과정을 간단히 살펴봤습니다. 앞으로 원하는 모델들을 손쉽게 Ollama에서 바로 빌드해볼 수 있으니, 자유롭게 시도해보세요!

궁금한 점이나 더 자세한 내용은 아래 댓글로 남겨주시거나, Ollama와 Hugging Face 공식 문서를 참고해주시기 바랍니다. 감사합니다!