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 dapat 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 library Ollama lokal Anda yang dapat ollama run dan disajikan melalui 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. Ini adalah format yang dibaca oleh llama.cpp, dan Ollama dibangun di atas llama.cpp. Karena itu, hampir setiap model terbuka memiliki konversi GGUF dari komunitas. Ollama juga dapat mengimpor direktori berisi bobot .safetensors, tetapi itu merupakan jalur terpisah. Bagian tentang --quantize di bawah ini menjelaskan penggunaannya.

Semua langkah di bawah ini mengasumsikan Ollama sudah terpasang dan servicenya sedang berjalan. Jika belum, mulai dari 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 pertama: jalankan GGUF dari Hugging Face tanpa Modelfile

Ollama dapat mengambil GGUF langsung dari repositori Hugging Face. Perintahnya menggunakan path repositori dengan prefix 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 akan diunduh. Karena itu, prompt chat baru muncul setelah pengunduhan selesai. Setelah itu, model tersimpan di library lokal Anda dan dapat dijalankan dengan cepat. Buka shell kedua, lalu jalankan ollama list untuk melihat nama penyimpanannya. Nama tersebut adalah seluruh string hf.co/... beserta tag-nya, sehingga terlalu panjang untuk diketik setiap kali. Berikan alias 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 dan tidak menyediakan format lain tidak menyediakan file yang dapat diambil melalui rute ini. Anda perlu menggunakan salah satu metode import lokal yang dijelaskan di bawah.

Kuantisasi mana yang dipilih Ollama?

Dokumentasi Ollama dari Hugging Face, yang dibaca pada 10 October 2026, menjelaskan default ini secara tegas: "Secara default, skema kuantisasi Q4_K_M digunakan jika tersedia di dalam repositori model. Jika tidak tersedia, kami memilih satu tipe kuantisasi yang wajar dari yang tersedia di dalam repositori." Jadi, repositori yang menerbitkan sepuluh quant akan memberi Anda Q4_K_M. Repositori tanpa Q4_K_M akan memberi Anda pilihan yang ditentukan Ollama. Baca kembali halaman tersebut sebelum mengandalkannya karena default dapat berubah.

Minta quant 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 menggunakan nama file lengkap sebagai tag. Ini adalah bentuk yang aman jika nama singkat dalam repositori tidak jelas. Tag tersebut harus merujuk ke file yang benar-benar ada di repositori itu. Karena itu, buka tab Files and versions dan baca nama file yang sebenarnya sebelum mengetikkannya. Kuantisasi yang dipilih bergantung pada kebutuhan memori dan kualitas. Perbedaan antara Q4, Q8, dan FP16 membahas kompromi tersebut secara menyeluruh.

Rute dua: impor file .gguf dari disk Anda sendiri

Jika file sudah berada 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 modelnya:

ollama create my-model

ollama create secara default 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 menggunakannya:

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

ollama list kini seharusnya menyertakan my-model. ollama show my-model menampilkan arsitektur, jumlah parameter, panjang konteks, dan kuantisasi yang dibaca Ollama dari metadata file itu sendiri. Baca nilai-nilai tersebut, bukan nama file, karena nama file hanyalah string yang diketik secara manual. Jika model menjawab prompt pengujian Anda dalam bahasa normal lalu berhenti, proses impor berhasil. Jika tidak, buka bagian template di bawah, karena hampir selalu itulah penyebabnya.

Satu hal yang perlu diketahui tentang ruang disk: ollama create menyalin GGUF ke penyimpanan model milik Ollama, bukan merujuk ke file di lokasi asalnya. Bobot model akan 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 model di disk menjelaskan struktur direktori dan cara memindahkannya.

Kapan --quantize berlaku dan kapan tidak

ollama create memiliki flag --quantize, dan saat ini flag tersebut hanya berlaku untuk satu kasus: model yang diimpor dari direktori berisi bobot .safetensors. Teks bantuan dalam source Ollama saat ini, yang diperiksa pada 10 October 2026, berbunyi "Quantize safetensors model to this level (e.g. nvfp4)", dan nilai yang diterima adalah int4, int8, nvfp4, mxfp4, dan mxfp8. Nama kuantisasi GGUF seperti q8_0 atau q4_K_M ditolak sebagai tipe yang tidak didukung. Dokumentasi impor Ollama menjelaskan sisi GGUF secara tegas: "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

Perintah tersebut mengasumsikan Modelfile yang baris FROM-nya menunjuk ke direktori yang berisi file .safetensors.

Jangan berikan flag tersebut jika FROM merujuk ke .gguf, apa pun presisinya. GGUF FP16 atau FP32 ditolak dengan cara yang sama seperti Q4_K_M, dengan error yang diawali "create-time quantization is only supported for safetensors imports". .gguf yang namanya memuat Q4_K_M atau Q5_K_S sudah dik uantisasi, dan presisi yang telah dibuang tidak dapat dikembalikan. llama-quantize milik llama.cpp dapat melakukan encoding ulang file tersebut ke tipe lain, termasuk Q8_0, jika Anda memberikan --allow-requantize, tetapi manualnya memperingatkan bahwa proses ini "can severely reduce quality compared to quantizing from 16bit or 32bit", dan file Q4 yang ditulis ulang sebagai Q8 akan berukuran lebih besar tanpa menjadi lebih baik. Untuk mengecilkan GGUF dengan presisi penuh, jalankan llama-quantize terlebih dahulu pada file tersebut. Itulah tool yang dirujuk oleh dokumentasi Ollama. Setelah itu, impor file yang dihasilkan. Jika sumber Anda adalah repository Hugging Face berisi file .safetensors, Anda dapat mengarahkan FROM ke direktori tersebut dan membiarkan ollama create mengimpornya, dengan --quantize jika Anda ingin ukurannya lebih kecil. Alternatifnya, konversikan file tersebut dengan convert_hf_to_gguf.py dari repository llama.cpp, lalu impor GGUF yang dihasilkan oleh script tersebut. Hubungan Ollama dan llama.cpp menjelaskan alasan tool-tool tersebut 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, diikuti oleh ollama create my-model.

Quantization apa yang diunduh Ollama jika saya tidak menentukannya?

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

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

Chat template tidak cocok 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>, lalu tambahkan blok TEMPLATE dan baris PARAMETER stop ke Modelfile, kemudian jalankan kembali ollama create. 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 hanya berfungsi pada impor safetensors selama ollama create. Perintah tersebut menolak semua sumber GGUF, termasuk sumber FP16 atau FP32, dan menampilkan error yang meminta Anda melakukan quantization pada model GGUF sebelum mengimpornya. File yang namanya sudah memuat quant seperti Q4_K_M telah dikonversi. Melakukan quantization sekali lagi tidak dapat memulihkan presisi yang hilang: llama-quantize --allow-requantize dapat menulis ulang file tersebut sebagai Q8_0, tetapi hasilnya lebih besar tanpa menjadi lebih baik. Untuk mendapatkan file yang lebih kecil dari GGUF dengan presisi penuh, jalankan llama-quantize milik llama.cpp pada file tersebut, lalu impor hasilnya.

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 dari ~/.ollama/id_ed25519.pub jika Anda menjalankan server sebagai pengguna Anda sendiri. Setelah itu, tambahkan kunci tersebut pada halaman pengaturan kunci SSH akun Anda. Setelah itu, ollama run hf.co/{username}/{repository} berfungsi pada repositori privat milik Anda sendiri dan pada repositori dalam organisasi yang Anda menjadi anggotanya.