Cara Mengimpor Model GGUF ke Ollama

Dua cara mengimpor model GGUF ke Ollama

Ada dua cara untuk mengimpor model GGUF ke Ollama. Cara yang tepat bergantung pada lokasi file saat ini. Jika model berada di repositori Hugging Face, satu perintah ollama run akan mengambil dan menjalankannya tanpa menggunakan Modelfile. Jika file .gguf sudah berada di disk server, buat Modelfile dua baris lalu jalankan ollama create.

Kedua cara tersebut menghasilkan hal yang sama: model bernama di pustaka Ollama lokal yang dapat dilayani oleh ollama run dan API Ollama. Gunakan cara pertama jika file tersebut dipublikasikan oleh pihak lain. Gunakan cara kedua jika Anda mengkuantisasi model sendiri, jika file diterima melalui scp atau rsync, atau jika mesin tidak dapat terhubung ke Hugging Face.

File GGUF adalah satu file biner yang menyimpan bobot, tokenizer, dan metadata model secara bersamaan. Format ini dibaca oleh llama.cpp, sedangkan Ollama dibangun di atas llama.cpp. Karena itu, hampir setiap model terbuka memiliki konversi GGUF dari komunitas. Ollama tidak memuat folder berisi bobot .safetensors secara langsung. Itulah alasan langkah konversi diperlukan.

Semua langkah di bawah ini mengasumsikan Ollama sudah terpasang dan servicenya sedang berjalan. Jika belum, mulai dengan menginstal Ollama pada VPS, lalu kembali ke sini. Jalankan ollama list terlebih dahulu. Jika perintah tersebut menampilkan tabel, termasuk tabel kosong, bukan error koneksi, berarti server sudah aktif dan panduan selanjutnya dapat dijalankan.

Rute satu: jalankan GGUF dari Hugging Face tanpa Modelfile

Ollama dapat mengambil GGUF langsung dari repositori Hugging Face. Perintahnya berupa path repositori dengan awalan hf.co/:

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

hf.co dan huggingface.co sama-sama dapat digunakan sebagai nama domain. Berikut contoh nyata dari dokumentasi Hugging Face:

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

Pada proses pertama, file diunduh. Karena itu, prompt chat belum muncul sampai proses unduhan selesai. Setelah itu, model tersimpan di library lokal dan dapat dijalankan dengan cepat. Buka shell kedua dan jalankan ollama list untuk melihat nama yang digunakan saat model disimpan. Nama tersebut adalah seluruh string hf.co/... beserta tag-nya, sehingga terlalu panjang untuk diketik setiap kali. Berikan alias yang lebih singkat:

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

Rute ini hanya berfungsi pada repositori yang benar-benar berisi file GGUF. Repositori yang hanya menerbitkan bobot .safetensors tidak memberi Ollama file yang dapat diambil. Anda perlu menjalankan langkah konversi yang dijelaskan lebih lanjut.

Kuantisasi mana yang dipilih Ollama?

Dokumentasi Ollama dari Hugging Face, yang dibaca pada 25 August 2026, menjelaskan default ini secara tegas: "By default, the Q4_K_M quantization scheme is used, when it's present inside the model repo. If not, we default to picking one reasonable quant type present inside the repo." Jadi, repositori yang menerbitkan sepuluh kuantisasi akan memberi Anda Q4_K_M. Jika repositori tersebut tidak memiliki Q4_K_M, Ollama memilihkan kuantisasi lain untuk Anda. Baca kembali halaman tersebut sebelum mengandalkannya karena default dapat berubah.

Minta kuantisasi tertentu dengan menambahkannya sebagai 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

Nama kuantisasi tidak membedakan huruf besar dan kecil. Jadi, :iq3_m dan :IQ3_M memiliki arti yang sama. Anda juga dapat memberikan nama file lengkap sebagai tag. Ini adalah bentuk yang aman jika nama singkat dalam repositori tidak jelas. Tag tersebut harus merujuk ke file yang ada di repositori. Karena itu, buka tab Files and versions dan baca nama file sebenarnya sebelum mengetikkannya. Kuantisasi yang dipilih bergantung pada kebutuhan memori dan kualitas. Perbedaan antara Q4, Q8, dan FP16 membahas pertimbangan tersebut secara lengkap.

Rute dua: impor file .gguf dari disk Anda sendiri

Jika file sudah ada di server, Anda memerlukan Modelfile. Isinya dapat hanya satu baris. Buat direktori, letakkan Modelfile di dalamnya, lalu arahkan FROM ke file tersebut:

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

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

Simpan sebagai Modelfile, lalu build model:

ollama create my-model

Secara default, ollama create membaca file bernama Modelfile di direktori saat ini. Gunakan -f jika file Anda memiliki nama lain atau berada di lokasi lain, seperti pada ollama create my-model -f /home/you/models/my-model/Modelfile. Jalankan ollama create --help untuk melihat flag tersebut dan nilai defaultnya pada build Anda. Path dalam FROM dapat berupa path absolut atau relatif terhadap Modelfile, sehingga FROM ./my-model-Q4_K_M.gguf berfungsi jika keduanya berada di direktori yang sama. Path absolut menghilangkan keraguan tersebut.

Periksa hasilnya sebelum mengandalkannya:

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

ollama list sekarang seharusnya menyertakan my-model. ollama show my-model menampilkan arsitektur, jumlah parameter, panjang context, dan quantization yang dibaca Ollama dari metadata file itu sendiri. Gunakan nilai tersebut, bukan nama file, karena nama file adalah string yang diketik seseorang secara manual. Jika model menjawab prompt pengujian Anda dalam bahasa yang normal lalu berhenti, impor berhasil. Jika tidak, buka bagian template di bawah karena itu hampir selalu menjadi penyebabnya.

Ada satu hal yang perlu diketahui tentang ruang disk: ollama create menyalin GGUF ke model store milik Ollama, bukan mereferensikan file di lokasi asalnya. Weights tersimpan dua kali di disk sampai Anda menghapus file asli. Hapus file sumber setelah ollama run my-model berfungsi, atau simpan file tersebut di lokasi yang tidak membuat Anda membayar penggunaan ruang dua kali. lokasi Ollama menyimpan modelnya di disk menjelaskan strukturnya dan cara memindahkannya.

Kapan --quantize berlaku dan kapan tidak

ollama create memiliki flag --quantize, dan flag ini hanya digunakan untuk satu kasus: source model dalam FP16 atau FP32, yang berarti weights dengan presisi penuh. Dokumentasi impor Ollama mencantumkan q8_0 serta varian k-means q4_K_S dan q4_K_M sebagai target.

ollama create --quantize q4_K_M my-model

Jangan gunakan flag tersebut pada file yang sudah di-quantize. .gguf yang namanya memuat Q4_K_M atau Q5_K_S sudah melalui tahap ini, sehingga flag tersebut tidak memiliki pekerjaan untuk dilakukan. Quantization adalah konversi satu arah dari presisi yang lebih tinggi ke presisi yang lebih rendah, sehingga tidak ada jalur dari Q4 kembali ke Q8. Jika source Anda adalah repository Hugging Face yang berisi file .safetensors, konversikan terlebih dahulu dengan convert_hf_to_gguf.py dari repository llama.cpp, yaitu tool yang dirujuk dalam dokumentasi Ollama, lalu impor GGUF yang dihasilkan script tersebut. Hubungan Ollama dan llama.cpp menjelaskan alasan script konversi berada di project lain.

Mengapa GGUF yang diimpor menghasilkan jawaban acak atau tidak pernah berhenti?

Ini adalah kegagalan yang sering dilewati oleh tutorial impor, dan masalah ini akan Anda temui. Gejalanya terlihat seperti model yang rusak. Token kontrol muncul sebagai teks yang terlihat dalam jawaban, misalnya string seperti <|im_start|>assistant atau <|end|>. Model menjawab, kemudian menulis pertanyaan pengguna baru dan menjawab pertanyaan itu juga. Proses generasi terus berjalan sampai Anda menekan Ctrl+C.

Modelnya tidak bermasalah. Chat template-nya yang salah. Chat template adalah pembungkus yang mengubah pesan Anda menjadi urutan token yang persis seperti yang digunakan saat model dilatih, termasuk penanda khusus untuk menunjukkan akhir system prompt dan awal giliran pengguna. Ollama memilihkan salah satunya untuk Anda: dokumentasi menyatakan bahwa sebuah template "will be selected automatically from a list of commonly used templates", berdasarkan metadata bawaan tokenizer.chat_template yang tersimpan di dalam file GGUF. Jika metadata tersebut tidak ada, atau tidak cocok dengan apa pun dalam daftar, Anda mendapatkan pembungkus generik. Model kemudian menerima prompt dengan bentuk yang tidak pernah ditemuinya saat pelatihan, sehingga tidak pernah menemukan penanda akhir giliran yang dipelajarinya sebagai tanda untuk berhenti.

Tampilkan template yang sebenarnya dipilih Ollama:

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

Template yang kosong atau jelas generik mengonfirmasi masalah tersebut. Tulis template itu sendiri dalam 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|>"

Bangun ulang dengan ollama create my-model, lalu kirimkan prompt pengujian yang sama. Parameter stop adalah pengaman Anda: parameter ini memberi tahu Ollama untuk menghentikan generasi ketika string tersebut muncul. Dengan demikian, gejala proses yang tidak pernah berhenti dapat diatasi meskipun Anda masih menyempurnakan wrapper-nya. Jika jawaban masih terus berjalan karena tidak ada penanda yang Anda tentukan yang pernah muncul, batas num_predict akan menghentikannya setelah jumlah token tertentu, terlepas dari keluaran template.

Template harus berupa template Go, bukan template Jinja. Dokumentasi Hugging Face menyatakan hal ini secara langsung. Hal ini penting karena field tokenizer.chat_template pada repositori model asli berisi Jinja. Menempelkan isinya tanpa perubahan tidak akan berfungsi. Sintaks Ollama memiliki tiga variabel: {{ .System }} untuk system prompt, {{ .Prompt }} untuk pesan pengguna, dan {{ .Response }} untuk jawaban model. Cari penanda giliran yang sebenarnya digunakan model dalam kartu model atau tokenizer_config.json, lalu tulis ulang penanda tersebut ke dalam sintaks Go secara manual.

Ada satu cara cepat yang dapat menghemat sebagian besar pekerjaan tersebut. Banyak model menggunakan format prompt yang sama. Jika model lain di library Anda menggunakan format yang sama, jalankan ollama show --template terhadap model tersebut dan salin hasilnya.

File template, system, dan params dalam repo Hugging Face

Rute Hugging Face menyediakan kontrol yang sama melalui file dalam repositori, bukan instruksi dalam Modelfile. Jika Anda memiliki repositori tersebut atau menerbitkan quant Anda sendiri, tambahkan file itu di sana agar setiap ollama run hf.co/... dapat menggunakannya.

• File bernama template berisi template Go. Aturan yang sama berlaku: gunakan Go, bukan Jinja.
• File bernama system berisi system prompt.
• File bernama params berisi parameter sampling dan harus dalam format JSON.

Contoh file params minimal:

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

Jika Anda tidak memiliki repositori tersebut, Anda tidak dapat menambahkan file itu. Pull model satu kali, jalankan ollama show --modelfile hf.co/... untuk mengekspor data yang Anda terima, lalu simpan output tersebut sebagai Modelfile. Baris FROM mengarah ke blob yang sudah diunduh oleh Ollama. Dengan demikian, Anda dapat mengedit baris TEMPLATE dan PARAMETER, lalu menjalankan ollama create untuk membuat salinan lokal yang sudah diperbaiki tanpa mengunduh ulang apa pun. Ini adalah cara standar untuk memperbaiki quant milik pihak lain yang bermasalah.

Cara mengimpor repo GGUF privat

Repository privat memerlukan kunci SSH Ollama pada akun Hugging Face Anda. Metode yang didokumentasikan untuk rute ini menggunakan kunci SSH, bukan token API. Karena itu, token yang sudah Anda miliki tidak dapat membuka repository tersebut.

Tampilkan kunci publik. Pada server Linux tempat Ollama diinstal menggunakan skrip resmi, service berjalan sebagai pengguna ollama. Karena itu, kunci berada di direktori home pengguna tersebut:

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

Jika Anda menjalankan ollama serve sendiri sebagai pengguna Anda, path-nya adalah ~/.ollama/id_ed25519.pub. Salin seluruh baris tersebut, buka pengaturan akun Hugging Face di https://huggingface.co/settings/keys, lalu tambahkan baris itu sebagai kunci SSH baru. Perintah normal kemudian dapat digunakan pada repository privat Anda:

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

Jika proses pull masih gagal setelah kunci ditambahkan, kemungkinan Anda menampilkan file yang salah. Server yang melakukan download dan mengirimkan kuncinya sendiri. Service yang dijalankan oleh systemd tidak pernah membaca ~/.ollama milik pengguna Anda, sehingga kunci di direktori home Anda bukan kunci yang dilihat Hugging Face.

Apakah model akan muat di VPS Anda?

Hal yang menentukan adalah ukuran file pada disk ditambah memori yang diperlukan oleh context window. Bobot dimuat ke memori dengan ukuran yang hampir sama seperti ukuran file-nya, sedangkan alokasi context berada di atasnya dan bertambah sesuai jumlah token yang Anda izinkan. Jalankan ollama list untuk membaca ukuran yang dicatat Ollama untuk model tersebut, bandingkan dengan free -h pada server, lalu sisakan kapasitas untuk sistem operasi dan proses lain yang berjalan di server. Jika Anda ingin melihat perhitungan tersebut secara langsung pada model nyata, menjalankan Nemotron 3.5 Lightning pada VPS mencantumkan tag yang tepat untuk di-pull, kebutuhan RAM, serta apakah server CPU-only dapat mengimbanginya.

Context adalah bagian yang sering terlupakan. Model yang berhasil dimuat dengan window default dapat gagal setelah Anda menaikkan num_ctx karena alokasi tersebut bertambah sesuai window yang diminta. Mengatur num_ctx dan dampaknya terhadap penggunaan memori menjelaskan perhitungannya. Jika total kebutuhan terlalu besar, solusi biasanya adalah menggunakan quant yang lebih kecil dari model yang sama. Trade-off ini dibahas dalam perbandingan Q4 dan Q8.

Kegagalannya terlihat jelas. Pada VPS CPU-only, kernel menjalankan out-of-memory killer untuk menghentikan proses. journalctl -u ollama -n 50 bersama dmesg menunjukkan proses yang dihentikan. Pada server dengan GPU, ollama ps menampilkan kolom PROCESSOR yang menunjukkan apakah model yang dimuat berada di memori GPU, memori sistem, atau terbagi pada keduanya. Model yang sebagian dimuat ke memori sistem tetap dapat memberikan respons, tetapi lebih lambat. Mengukur token per detik mengubah "lebih lambat" menjadi angka yang dapat Anda bandingkan antar-quant.

Periksa hasil impor

Jalankan empat perintah ini setelah setiap impor, dalam urutan berikut:

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

ollama list membuktikan bahwa model tersedia dan menampilkan ukuran yang dicatat Ollama. ollama show membuktikan bahwa Ollama berhasil membaca metadata yang diperlukan dari GGUF. ollama show --modelfile membuktikan template dan parameter yang benar-benar akan digunakan, sehingga kegagalan berupa output tidak valid dapat terdeteksi sebelum pengguna mengalaminya. Prompt pengujian ini memeriksa seluruh rangkaian karena model dengan template yang rusak akan gagal bahkan pada permintaan terpendek. Setelah prompt tersebut menghasilkan respons yang benar, nama yang Anda berikan kepada model menjadi nama yang digunakan oleh semua hal lain yang berkomunikasi dengan Ollama API, termasuk agen coding yang diarahkan ke server Anda sendiri. Hapus impor yang bermasalah dengan ollama rm my-model, lalu buat ulang. Perintah tersebut menghapus salinan Ollama dan membiarkan sumber .gguf Anda tetap utuh.

FAQ

Dapatkah saya mengimpor GGUF ke Ollama tanpa menulis Modelfile?

Ya, jika file tersebut berada di repositori Hugging Face. ollama run hf.co/{username}/{repository} mengambil dan menjalankannya secara langsung, sedangkan ollama run hf.co/{username}/{repository}:{quantization} memilih quant tertentu. Modelfile hanya diperlukan untuk .gguf yang sudah ada di disk Anda sendiri. Dalam kasus tersebut, isinya dapat berupa satu baris FROM /path/to/file.gguf yang diikuti ollama create my-model.

Quantization mana yang diunduh Ollama jika saya tidak menentukannya?

Dokumentasi Hugging Face, yang dibaca pada 25 August 2026, menyatakan bahwa Q4_K_M digunakan jika quant tersebut tersedia di repositori. Jika tidak, Ollama memilih jenis quant yang wajar dan tersedia di repositori. Tambahkan tag seperti :Q8_0 untuk mengendalikannya. Konfirmasikan file yang benar-benar Anda terima dengan ollama show <model>. Perintah ini mencetak quantization dari metadata file, bukan dari namanya.

Mengapa model yang saya impor mengulang respons atau tidak pernah berhenti menghasilkan teks?

Chat template tidak sesuai dengan model. Ollama memilih template secara otomatis dari metadata tokenizer.chat_template di dalam GGUF. Jika metadata tersebut tidak ada atau tidak dikenali, Ollama menggunakan wrapper generik. Akibatnya, model tidak pernah melihat penanda akhir giliran yang digunakan saat pelatihan. Cetak template saat ini dengan ollama show --template <model>. Kemudian, tambahkan blok TEMPLATE dan baris PARAMETER stop ke Modelfile, lalu jalankan ollama create lagi. Tulis template tersebut sebagai template Go. Template Jinja dari repositori asli tidak akan berfungsi.

Haruskah saya menggunakan --quantize pada GGUF yang saya unduh?

Tidak. --quantize mengonversi sumber FP16 atau FP32 selama ollama create. File yang namanya sudah memuat quant, seperti Q4_K_M, telah dikonversi. Presisi tidak dapat dipulihkan dengan melakukan quantization ulang, dan tidak ada jalur untuk mengembalikannya ke presisi yang lebih tinggi. Gunakan flag tersebut hanya jika Anda sendiri telah mengonversi safetensors menjadi GGUF dengan presisi penuh dan kini ingin membuat versi yang lebih kecil.

Bagaimana cara mengambil repositori GGUF privat?

Tambahkan kunci publik SSH Ollama ke akun Hugging Face Anda. Cetak kunci tersebut dengan sudo cat /usr/share/ollama/.ollama/id_ed25519.pub pada instalasi Linux standar, atau dengan ~/.ollama/id_ed25519.pub jika Anda menjalankan server sebagai user Anda sendiri. Kemudian, tambahkan kunci tersebut pada halaman pengaturan kunci SSH akun Anda. Setelah itu, ollama run hf.co/{username}/{repository} dapat digunakan pada repositori privat milik Anda dan pada repositori dalam organisasi yang Anda ikuti.