Jak zaimportować model GGUF do Ollama krok po kroku

Dwie metody importu modelu GGUF do Ollama

Istnieją dwie metody importu modelu GGUF do Ollama, a wybór właściwej zależy od aktualnej lokalizacji pliku. Jeśli model znajduje się w repozytorium Hugging Face, jedno polecenie ollama run pobiera go i uruchamia bez konieczności tworzenia pliku Modelfile. Jeśli plik .gguf znajduje się już na dysku serwera, należy utworzyć dwuliniowy plik Modelfile i wykonać ollama create.

Obie ścieżki prowadzą do tego samego rezultatu: nazwanego modelu w lokalnej bibliotece Ollama, który ollama run oraz API Ollama mogą udostępniać. Pierwszą metodę należy stosować, gdy plik został opublikowany przez inną osobę. Drugą metodę należy wybrać w przypadku samodzielnej kwantyzacji modelu, gdy plik został dostarczony przez scp lub rsync, albo gdy maszyna nie ma dostępu do Hugging Face.

Plik GGUF to pojedynczy plik binarny zawierający wagi, tokenizator oraz metadane modelu. Jest to format odczytywany przez llama.cpp, a ponieważ Ollama bazuje na llama.cpp, niemal każdy otwarty model posiada społecznościową konwersję do formatu GGUF. Ollama nie wczytuje bezpośrednio folderu wag .safetensors, dlatego krok konwersji jest niezbędny.

Poniższe instrukcje zakładają, że Ollama jest już zainstalowana, a jej usługa działa. Jeśli tak nie jest, należy rozpocząć od instalacji Ollama na VPS i powrócić do tego miejsca. W pierwszej kolejności należy wykonać ollama list. Jeśli polecenie zwróci tabelę (nawet pustą) zamiast błędu połączenia, serwer działa poprawnie i dalsza część przewodnika będzie skuteczna.

Metoda pierwsza: uruchomienie GGUF z Hugging Face bez pliku Modelfile

Ollama potrafi pobrać plik GGUF bezpośrednio z repozytorium Hugging Face. Polecenie wymaga podania ścieżki do repozytorium z prefiksem hf.co/:

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

Zarówno hf.co, jak i huggingface.co działają jako nazwa domeny. Rzeczywisty przykład z dokumentacji Hugging Face:

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

Pierwsze uruchomienie powoduje pobranie pliku, więc monit czatu nie pojawi się, dopóki pobieranie nie zostanie zakończone. Po tym procesie model znajduje się w lokalnej bibliotece i uruchamia się szybko. Otwórz drugą powłokę i wykonaj ollama list, aby sprawdzić nazwę, pod którą model został zapisany. Nazwa ta jest pełnym ciągiem hf.co/... wraz z tagiem, co jest uciążliwe przy każdorazowym wpisywaniu. Nadaj mu krótki alias:

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

Ta metoda działa tylko w przypadku repozytoriów, które faktycznie zawierają pliki GGUF. Repozytorium publikujące wagi .safetensors i nic poza tym nie dostarcza Ollama danych do pobrania; w takim przypadku wymagany jest krok konwersji opisany w dalszej części.

Którą kwantyzację wybiera Ollama?

Dokumentacja Ollama w serwisie Hugging Face, sprawdzona 25 sierpnia 2026 roku, jasno określa zachowanie domyślne: „Domyślnie używany jest schemat kwantyzacji Q4_K_M, jeśli jest obecny w repozytorium modelu. W przeciwnym razie wybieramy jeden z rozsądnych typów kwantyzacji dostępnych w repozytorium”. Repozytorium publikujące dziesięć wariantów kwantyzacji dostarczy zatem Q4_K_M, a repozytorium bez Q4_K_M spowoduje wybór dokonany przez Ollama w imieniu użytkownika. Przed poleganiem na tym mechanizmie należy ponownie zapoznać się z tą stroną, ponieważ wartości domyślne ulegają zmianie.

Wybierz konkretną kwantyzację, dodając ją jako tag:

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

Nazwa kwantyzacji nie jest wrażliwa na wielkość liter, więc :iq3_m oraz :IQ3_M oznaczają to samo. Można również przekazać dokładną nazwę pliku jako tag, co jest bezpieczną metodą, gdy krótkie nazwy w repozytorium są niejednoznaczne. Tag musi wskazywać na plik istniejący w danym repozytorium, dlatego przed wpisaniem nazwy należy otworzyć kartę Files and versions i sprawdzić rzeczywiste nazwy plików. Wybór kwantyzacji jest kwestią balansu między pamięcią a jakością, a różnice między Q4, Q8 oraz FP16 szczegółowo omawiają to zagadnienie.

Druga metoda: import pliku .gguf z własnego dysku

Gdy plik znajduje się już na serwerze, wymagany jest plik Modelfile. Może on składać się z jednej linii. Utwórz katalog, umieść w nim Modelfile i wskaż FROM plik:

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

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

Zapisz to jako Modelfile, a następnie zbuduj model:

ollama create my-model

ollama create domyślnie odczytuje plik o nazwie Modelfile w bieżącym katalogu. Użyj -f, gdy plik ma inną nazwę lub znajduje się w innej lokalizacji, tak jak w ollama create my-model -f /home/you/models/my-model/Modelfile. Uruchom ollama create --help, aby wyświetlić flagę i jej wartość domyślną dla procesu budowania. Ścieżka w FROM może być bezwzględna lub relatywna względem pliku Modelfile, więc FROM ./my-model-Q4_K_M.gguf zadziała, gdy oba elementy znajdują się w tym samym katalogu. Ścieżka bezwzględna eliminuje wszelkie wątpliwości.

Sprawdź wynik przed rozpoczęciem użytkowania:

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

ollama list powinien teraz zawierać my-model. ollama show my-model wyświetla architekturę, liczbę parametrów, długość kontekstu oraz kwantyzację, które Ollama odczytała z metadanych pliku. Należy polegać na tych wartościach, a nie na nazwie pliku, ponieważ nazwa jest ciągiem znaków wpisanym ręcznie. Jeśli model odpowiada na testowy prompt w naturalnym języku i kończy generowanie, import przebiegł pomyślnie. Jeśli nie, przejdź do sekcji dotyczącej szablonów poniżej, ponieważ to niemal zawsze jest przyczyną problemu.

Ważna uwaga dotycząca miejsca na dysku: ollama create kopiuje plik GGUF do wewnętrznego magazynu modeli Ollama, zamiast odwoływać się do pliku w jego pierwotnej lokalizacji. Wagi zajmują miejsce na dysku dwukrotnie, dopóki nie usuniesz oryginału. Usuń plik źródłowy, gdy ollama run my-model zadziała, lub przenieś go w miejsce, gdzie nie generuje dodatkowych kosztów. gdzie Ollama przechowuje modele na dysku zawiera informacje o strukturze katalogów i sposobie jej zmiany.

Kiedy --quantize ma zastosowanie, a kiedy nie

ollama create posiada flagę --quantize, która istnieje tylko dla jednego przypadku: modelu źródłowego w formacie FP16 lub FP32, co oznacza wagi o pełnej precyzji. Dokumentacja importu Ollama wymienia q8_0 oraz warianty k-means q4_K_S i q4_K_M jako cele konwersji.

ollama create --quantize q4_K_M my-model

Nie należy używać tej flagi w odniesieniu do pliku, który jest już skwantyzowany. Plik .gguf, którego nazwa zawiera Q4_K_M lub Q5_K_S, przeszedł już ten etap i flaga nie wykona żadnej pracy. Kwantyzacja jest konwersją jednostronną z wyższej precyzji na niższą, więc nie ma możliwości przejścia z Q4 do Q8. Jeśli źródłem jest repozytorium Hugging Face z plikami .safetensors, należy najpierw dokonać konwersji za pomocą convert_hf_to_gguf.py z repozytorium llama.cpp, które jest narzędziem wskazywanym przez dokumentację Ollama, a następnie zaimportować plik GGUF wygenerowany przez ten skrypt. Zależności między Ollama a llama.cpp wyjaśnia, dlaczego skrypt konwertujący należy do innego projektu.

Dlaczego zaimportowany plik GGUF generuje niezrozumiałe znaki lub nie kończy odpowiedzi?

To najczęściej pomijany błąd podczas importu, na który z pewnością trafisz. Objawy sugerują uszkodzenie modelu. Tokeny sterujące pojawiają się w odpowiedzi jako widoczny tekst, na przykład ciągi znaków takie jak <|im_start|>assistant lub <|end|>. Model odpowiada, a następnie sam tworzy kolejne pytanie użytkownika i udziela na nie odpowiedzi. Generowanie trwa do momentu przerwania procesu za pomocą Ctrl+C.

Model jest sprawny. Problem leży w niepoprawnym szablonie czatu (chat template). Szablon czatu to struktura, która przekształca wiadomość w sekwencję tokenów zgodną z tą, na której trenowano model, uwzględniając znaczniki końca promptu systemowego oraz początku wypowiedzi użytkownika. Ollama wybiera szablon automatycznie: dokumentacja wskazuje, że szablon jest dobierany z listy powszechnie używanych wzorców na podstawie wbudowanych metadanych tokenizer.chat_template zapisanych w pliku GGUF. Gdy metadane są nieobecne lub nie pasują do żadnego wzorca z listy, stosowany jest szablon ogólny. Model otrzymuje wtedy prompt o strukturze niezgodnej z procesem treningowym, przez co nie rozpoznaje znacznika końca tury, na którym powinien zakończyć generowanie.

Wyświetl szablon wybrany przez Ollama:

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

Pusty lub ewidentnie ogólny szablon potwierdza przyczynę problemu. Zdefiniuj szablon samodzielnie w pliku 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|>"

Przebuduj model za pomocą ollama create my-model i wyślij ponownie ten sam testowy prompt. Parametr stop stanowi zabezpieczenie: instruuje Ollama, aby przerwać generowanie w momencie wystąpienia wskazanego ciągu znaków. Eliminuje to problem nieskończonego generowania nawet w trakcie dopracowywania samego szablonu. Jeśli odpowiedź nadal trwa, ponieważ żaden ze wskazanych znaczników nie wystąpił, limit num_predict przerwie proces po osiągnięciu określonej liczby tokenów, niezależnie od tego, co generuje szablon.

Szablon musi być zgodny ze składnią Go, a nie Jinja. Dokumentacja Hugging Face wyraźnie o tym informuje, co jest istotne, ponieważ pole tokenizer.chat_template w oryginalnym repozytorium modelu zawiera składnię Jinja. Wklejenie jej bez zmian nie zadziała. Składnia Ollama wykorzystuje trzy zmienne: {{ .System }} dla promptu systemowego, {{ .Prompt }} dla wiadomości użytkownika oraz {{ .Response }} dla odpowiedzi modelu. Znajdź rzeczywiste znaczniki tur modelu w jego karcie (model card) lub pliku tokenizer_config.json, a następnie ręcznie przepisz je na składnię Go.

Jeden skrót pozwala zaoszczędzić większość tej pracy. Wiele modeli współdzieli ten sam format promptu. Jeśli inny model w Twojej bibliotece korzysta z tego samego formatu, uruchom ollama show --template dla tego modelu i skopiuj wyświetloną treść.

Pliki szablonu, systemu i parametrów w repozytorium Hugging Face

Ścieżka Hugging Face oferuje te same możliwości kontroli co pliki w repozytorium, zamiast instrukcji w pliku Modelfile. Jeśli jesteś właścicielem repozytorium lub publikujesz własną kwantyzację, dodaj je tam, a każde ollama run hf.co/... je uwzględni.

• Plik o nazwie template zawiera szablon Go. Obowiązuje ta sama zasada: Go, nie Jinja.
• Plik o nazwie system zawiera prompt systemowy.
• Plik o nazwie params zawiera parametry próbkowania i musi być w formacie JSON.

Minimalny plik params:

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

Jeśli nie jesteś właścicielem repozytorium, nie możesz dodać tych plików. Pobierz model jednokrotnie, uruchom ollama show --modelfile hf.co/..., aby zrzucić otrzymaną konfigurację i zapisz to wyjście jako Modelfile. Linia FROM wskazuje na blob, który Ollama już pobrała, więc edytuj linie TEMPLATE oraz PARAMETER i uruchom ollama create, aby zbudować poprawioną lokalną kopię bez ponownego pobierania danych. Jest to standardowy sposób naprawy błędnej kwantyzacji stworzonej przez kogoś innego.

Importowanie prywatnego repozytorium GGUF

Prywatne repozytorium wymaga dodania klucza SSH serwera Ollama do konta w serwisie Hugging Face. Udokumentowana metoda dla tej ścieżki wykorzystuje klucz SSH zamiast tokena API, zatem posiadany już token nie zapewni dostępu do repozytorium.

Wyświetl klucz publiczny. Na serwerze Linux, gdzie Ollama została zainstalowana za pomocą oficjalnego skryptu, usługa działa jako użytkownik ollama, więc klucz znajduje się w katalogu domowym tego użytkownika:

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

Jeśli uruchamiasz ollama serve samodzielnie jako własny użytkownik, ścieżka to ~/.ollama/id_ed25519.pub. Skopiuj cały wiersz, otwórz ustawienia konta Hugging Face pod adresem https://huggingface.co/settings/keys i dodaj go jako nowy klucz SSH. Standardowe polecenie zadziała wtedy dla prywatnych repozytoriów:

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

Jeśli pobieranie nadal kończy się niepowodzeniem po dodaniu klucza, prawdopodobnie wyświetlono niewłaściwy plik. Serwer wykonuje pobieranie i przedstawia własny klucz, a serwer uruchomiony przez systemd nigdy nie odczytuje pliku ~/.ollama użytkownika, więc klucz w katalogu domowym użytkownika nie jest tym, który widzi Hugging Face.

Czy model zmieści się na Twoim VPS?

Wartością decydującą jest rozmiar pliku na dysku oraz pamięć wymagana przez okno kontekstowe. Wagi ładowane są do pamięci w rozmiarze zbliżonym do zajmowanego na dysku, a alokacja kontekstu jest doliczana do tej wartości i rośnie wraz z liczbą dozwolonych tokenów. Uruchom ollama list, aby odczytać rozmiar zarejestrowany przez Ollama dla danego modelu, porównaj go z free -h na serwerze i pozostaw margines dla systemu operacyjnego oraz pozostałych uruchomionych usług. Jeśli wolisz zapoznać się z obliczeniami wykonanymi dla rzeczywistego modelu, uruchomienie Nemotron 3.5 Lightning na VPS zawiera dokładny tag do pobrania, wymagania RAM oraz informację, czy serwer działający wyłącznie na CPU zapewni odpowiednią wydajność.

Kontekst jest elementem, o którym często się zapomina. Model ładowany z domyślnym oknem może przestać działać po zwiększeniu num_ctx, ponieważ alokacja ta skaluje się wraz z zadaną wielkością okna. Ustawianie num_ctx i jego koszt w pamięci zawiera szczegóły dotyczące szacowania rozmiaru. Gdy suma jest zbyt duża, rozwiązaniem jest zazwyczaj wybór mniejszej kwantyzacji tego samego modelu, co jest kompromisem omówionym w porównaniu Q4 z Q8.

Awaria jest wyraźna. Na serwerze VPS działającym tylko na CPU mechanizm out of memory killer jądra zatrzymuje proces, a journalctl -u ollama -n 50 wraz z dmesg wykazują to zdarzenie. Na serwerze z GPU, ollama ps wyświetla kolumnę PROCESSOR, która informuje, czy załadowany model trafił do pamięci GPU, pamięci systemowej, czy został rozdzielony między oba te zasoby. Model, który został przeniesiony do pamięci systemowej, nadal odpowiada, choć wolno. Pomiar tokenów na sekundę pozwala zamienić określenie "wolno" na liczbę, którą można porównać między różnymi kwantyzacjami.

Weryfikacja zaimportowanego modelu

Po każdym imporcie należy wykonać te cztery polecenia w podanej kolejności:

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

ollama list potwierdza istnienie modelu i wyświetla rozmiar zarejestrowany przez Ollama. ollama show potwierdza, że Ollama odczytała niezbędne metadane z pliku GGUF. ollama show --modelfile wskazuje, który szablon i parametry zostaną faktycznie użyte; jest to test pozwalający wykryć błędy generowania niepoprawnych danych, zanim napotkają je użytkownicy. Testowy prompt sprawdza cały łańcuch, ponieważ model z uszkodzonym szablonem zawiedzie nawet przy najkrótszym zapytaniu. Gdy prompt zwróci poprawną odpowiedź, nazwa nadana modelowi będzie tą samą, której należy używać w komunikacji z API Ollama, w tym w agencie programistycznym wskazanym na własny serwer. Nieudany import można usunąć za pomocą ollama rm my-model, a następnie przeprowadzić go ponownie. To polecenie usuwa kopię Ollama, pozostawiając plik źródłowy .gguf bez zmian.

FAQ

Czy można zaimportować GGUF do Ollama bez tworzenia pliku Modelfile?

Tak, jeśli plik znajduje się w repozytorium Hugging Face. ollama run hf.co/{username}/{repository} pobiera i uruchamia go bezpośrednio, a ollama run hf.co/{username}/{repository}:{quantization} pozwala wybrać konkretną kwantyzację. Plik Modelfile jest wymagany tylko w przypadku .gguf, który znajduje się już na dysku lokalnym; w takiej sytuacji wystarczy pojedyncza linia FROM /path/to/file.gguf, po której następuje ollama create my-model.

Którą kwantyzację pobiera Ollama, jeśli nie określę jej samodzielnie?

Dokumentacja Hugging Face, sprawdzona 25 sierpnia 2026, podaje, że Q4_K_M jest używane, gdy ten wariant kwantyzacji znajduje się w repozytorium. W przeciwnym razie Ollama wybiera jeden z dostępnych w repozytorium wariantów uznawanych za rozsądne. Aby wymusić konkretny wariant, należy dodać tag, taki jak :Q8_0. Weryfikację pobranego pliku można przeprowadzić za pomocą ollama show <model>, co pozwala odczytać kwantyzację z metadanych pliku, a nie z jego nazwy.

Dlaczego zaimportowany model powtarza się lub nie kończy generowania tekstu?

Szablon czatu nie jest zgodny z modelem. Ollama automatycznie wybiera szablon na podstawie metadanych tokenizer.chat_template zawartych w pliku GGUF. Jeśli te metadane są nieobecne lub nierozpoznane, stosowany jest ogólny szablon, przez co model nie otrzymuje znacznika końca tury, na którym był trenowany. Bieżący szablon można wyświetlić za pomocą ollama show --template <model>, a następnie dodać blok TEMPLATE oraz linię PARAMETER stop do pliku Modelfile i ponownie wykonać ollama create. Szablon należy zapisać w formacie Go template. Szablony Jinja z oryginalnego repozytorium nie będą działać.

Czy należy używać --quantize dla pobranego pliku GGUF?

Nie. --quantize dokonuje konwersji źródła FP16 lub FP32 podczas ollama create, a plik, którego nazwa zawiera już oznaczenie kwantyzacji (np. Q4_K_M), został już przekonwertowany. Precyzji nie można odzyskać poprzez ponowną kwantyzację i nie ma ścieżki powrotnej do wyższej jakości. Flagi tej należy używać tylko wtedy, gdy samodzielnie przekonwertowano pliki safetensors do formatu GGUF o pełnej precyzji i wymagane jest uzyskanie mniejszego pliku.

Jak pobrać prywatne repozytorium GGUF?

Należy dodać klucz publiczny SSH usługi Ollama do konta w serwisie Hugging Face. Klucz można wyświetlić za pomocą sudo cat /usr/share/ollama/.ollama/id_ed25519.pub w standardowej instalacji Linux lub z ~/.ollama/id_ed25519.pub, jeśli serwer jest uruchomiony na koncie użytkownika, a następnie dodać go w ustawieniach kluczy SSH na koncie. Po wykonaniu tej czynności ollama run hf.co/{username}/{repository} będzie działać dla własnych prywatnych repozytoriów oraz repozytoriów w organizacjach, do których użytkownik należy.