Cách import model GGUF vào Ollama và sửa chat template

Hai cách import model GGUF vào Ollama

Có hai cách import model GGUF vào Ollama. Cách phù hợp phụ thuộc vào vị trí hiện tại của file. Nếu model nằm trong một repository trên Hugging Face, một lệnh ollama run sẽ tải và chạy model đó, không cần Modelfile. Nếu file .gguf đã có trên disk của server, bạn viết một Modelfile gồm 2 dòng rồi chạy ollama create.

Cả hai cách đều cho cùng một kết quả: một model có tên trong Ollama library cục bộ, để ollama run và Ollama API có thể serve. Dùng cách đầu tiên khi file do người khác publish. Dùng cách thứ hai khi bạn tự quantize model, khi file được chuyển đến qua scp hoặc rsync, hoặc khi máy không thể kết nối đến Hugging Face.

File GGUF là một binary chứa chung weights, tokenizer và metadata của model. Đây là format mà llama.cpp đọc được. Ollama được xây dựng trên llama.cpp, nên gần như mọi open model đều có bản chuyển đổi GGUF do community thực hiện. Ollama cũng có thể import một directory chứa weights .safetensors, nhưng đó là một quy trình riêng. Phần về --quantize bên dưới sẽ giải thích quy trình này phù hợp ở đâu.

Toàn bộ nội dung bên dưới giả định Ollama đã được cài đặt và service đang chạy. Nếu chưa, hãy bắt đầu với cài đặt Ollama trên VPS rồi quay lại đây. Trước tiên, chạy ollama list. Nếu lệnh trả về một table, kể cả table rỗng, thay vì lỗi kết nối, server đang hoạt động và phần còn lại của hướng dẫn này sẽ chạy được.

Cách 1: chạy GGUF từ Hugging Face mà không cần Modelfile

Ollama có thể pull trực tiếp một GGUF từ repository trên Hugging Face. Lệnh này dùng đường dẫn repository với tiền tố hf.co/:

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

Cả hf.co và huggingface.co đều hoạt động dưới dạng domain name. Ví dụ thực tế từ tài liệu Hugging Face:

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

Lần chạy đầu tiên sẽ download file, nên prompt chat chưa xuất hiện cho đến khi quá trình download hoàn tất. Sau đó, model nằm trong local library và khởi động nhanh. Mở shell thứ hai rồi chạy ollama list để xem tên mà Ollama đã lưu. Tên đó là toàn bộ chuỗi hf.co/... kèm tag, nên mỗi lần nhập lại sẽ khá dài. Hãy đặt cho model một alias ngắn:

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

Cách này chỉ hoạt động với repository thực sự chứa file GGUF. Repository chỉ publish weight .safetensors mà không có loại file nào khác sẽ không có gì để cách này fetch, và bạn cần dùng một trong các cách import local được mô tả bên dưới.

Ollama chọn quantization nào?

Tài liệu Ollama của Hugging Face, được đọc vào ngày 10 October 2026, nêu rõ giá trị mặc định: “Mặc định, Ollama dùng scheme quantization Q4_K_M khi scheme này có trong model repo. Nếu không có, Ollama sẽ chọn một quant type hợp lý có trong repo.” Vì vậy, repository publish 10 quant sẽ cung cấp cho bạn Q4_K_M; còn repository không có Q4_K_M sẽ để Ollama tự chọn một quant thay bạn. Hãy đọc lại trang đó trước khi dựa vào hành vi này, vì giá trị mặc định có thể thay đổi.

Để yêu cầu một quant cụ thể, thêm quant đó làm 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

Tên quantization không phân biệt chữ hoa chữ thường, nên :iq3_m và :IQ3_M có cùng ý nghĩa. Bạn cũng có thể truyền chính xác tên file làm tag. Đây là cách an toàn khi các tên ngắn trong repository không rõ ràng. Tag phải chỉ đến một file thực sự tồn tại trong repository, vì vậy hãy mở tab Files and versions và đọc tên file thực tế trước khi nhập. Việc chọn quant nào phụ thuộc vào dung lượng memory và chất lượng. Sự khác biệt giữa Q4, Q8 và FP16 giải thích đầy đủ trade-off này.

Cách 2: import file .gguf từ ổ đĩa của bạn

Khi file đã có sẵn trên server, bạn cần một Modelfile. File này có thể chỉ gồm một dòng. Tạo một thư mục, đặt Modelfile vào đó rồi trỏ FROM đến file:

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

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

Lưu nội dung đó thành Modelfile, rồi build model:

ollama create my-model

Theo mặc định, ollama create đọc file có tên Modelfile trong thư mục hiện tại. Dùng -f khi file có tên khác hoặc nằm ở vị trí khác, như trong ollama create my-model -f /home/you/models/my-model/Modelfile. Chạy ollama create --help để xem flag và giá trị mặc định của nó trên bản build bạn đang dùng. Path trong FROM có thể là absolute hoặc relative so với Modelfile, vì vậy FROM ./my-model-Q4_K_M.gguf hoạt động khi cả hai nằm trong cùng một thư mục. Dùng absolute path sẽ loại bỏ hoàn toàn vấn đề này.

Kiểm tra kết quả trước khi tin tưởng model:

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

ollama list bây giờ phải bao gồm my-model. ollama show my-model in ra architecture, số lượng parameter, context length và quantization mà Ollama đọc từ metadata của chính file. Hãy đọc các giá trị này thay vì tin vào filename, vì filename chỉ là chuỗi do một người nhập thủ công. Nếu model trả lời prompt kiểm tra bằng ngôn ngữ bình thường rồi dừng lại, quá trình import đã thành công. Nếu không, hãy chuyển đến phần template bên dưới, vì đây gần như luôn là nguyên nhân.

Có một điểm cần lưu ý về dung lượng đĩa: ollama create sao chép GGUF vào model store riêng của Ollama thay vì tham chiếu đến file hiện có. Weights sẽ chiếm dung lượng 2 lần trên đĩa cho đến khi bạn xóa file gốc. Xóa source file sau khi ollama run my-model hoạt động, hoặc giữ nó ở nơi bạn không phải trả phí dung lượng 2 lần. vị trí Ollama lưu model trên đĩa mô tả layout và cách di chuyển model.

Khi --quantize được áp dụng và khi không được áp dụng

ollama create có flag --quantize, nhưng hiện tại flag này chỉ áp dụng cho một trường hợp: model được import từ một thư mục chứa weights .safetensors. Help text trong source Ollama hiện tại, được kiểm tra vào 10 October 2026, ghi là "Quantize safetensors model to this level (e.g. nvfp4)", và các giá trị được chấp nhận là int4, int8, nvfp4, mxfp4 và mxfp8. Các tên GGUF quant như q8_0 hoặc q4_K_M sẽ bị từ chối vì là type không được hỗ trợ. Tài liệu import của Ollama nói rõ về GGUF: "Ollama does not quantize GGUF models during import."

ollama create --quantize int8 my-model

Lệnh này giả định Modelfile có dòng FROM trỏ đến thư mục chứa các file .safetensors.

Không truyền flag đó khi FROM chỉ đến một .gguf, bất kể precision của file là gì. GGUF FP16 hoặc FP32 cũng bị từ chối giống Q4_K_M, với lỗi bắt đầu bằng "create-time quantization is only supported for safetensors imports". Một .gguf có tên chứa Q4_K_M hoặc Q5_K_S đã được quantize, và precision đã bị loại bỏ không thể khôi phục. llama-quantize của llama.cpp có thể re-encode file đó thành type khác, bao gồm Q8_0, khi bạn truyền --allow-requantize, nhưng manual cảnh báo rằng thao tác này "can severely reduce quality compared to quantizing from 16bit or 32bit"; file Q4 được ghi lại thành Q8 sẽ lớn hơn nhưng không tốt hơn. Để thu nhỏ một GGUF full precision, trước tiên chạy llama-quantize trên file đó. Đây là tool mà tài liệu Ollama hướng dẫn sử dụng. Sau đó import file do tool này tạo ra. Nếu source của bạn là một repository Hugging Face chứa các file .safetensors, bạn có thể trỏ FROM đến thư mục đó để ollama create tự import, dùng --quantize nếu muốn file nhỏ hơn; hoặc convert bằng convert_hf_to_gguf.py từ repository llama.cpp rồi import GGUF do script đó tạo ra. Ollama và llama.cpp liên quan với nhau như thế nào giải thích vì sao các tool đó thuộc project còn lại.

Vì sao GGUF đã import lại trả lời rác hoặc không bao giờ dừng?

Đây là lỗi mà hầu hết các tutorial import đều bỏ qua, và bạn sẽ gặp lỗi này. Triệu chứng trông giống như model bị hỏng. Các control token xuất hiện dưới dạng văn bản hiển thị trong câu trả lời, chẳng hạn như <|im_start|>assistant hoặc <|end|>. Model trả lời xong rồi tự viết một câu hỏi mới của user và tiếp tục trả lời câu hỏi đó. Quá trình generate chạy mãi cho đến khi bạn nhấn Ctrl+C.

Model không bị lỗi. Chat template bị sai. Chat template là wrapper chuyển message của bạn thành đúng chuỗi token mà model đã được train, với các marker riêng để xác định vị trí kết thúc system prompt và bắt đầu lượt của user. Ollama tự chọn một template cho bạn: tài liệu nói rằng một template “sẽ được tự động chọn từ danh sách các template thường dùng”, dựa trên metadata tokenizer.chat_template tích hợp bên trong file GGUF. Khi metadata bị thiếu hoặc không khớp với template nào trong danh sách, bạn sẽ nhận một wrapper generic. Khi đó model thấy prompt có cấu trúc khác với mọi dữ liệu trong quá trình train, nên không bao giờ gặp end-of-turn marker mà nó đã học để dừng.

In template mà Ollama thực sự đã chọn:

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

Template rỗng hoặc rõ ràng là generic sẽ xác nhận lỗi này. Tự viết template trong 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|>"

Build lại bằng ollama create my-model rồi gửi lại cùng prompt test. Parameter stop là lớp bảo vệ của bạn: nó yêu cầu Ollama dừng generation khi chuỗi đó xuất hiện. Nhờ vậy, triệu chứng không dừng sẽ chấm dứt ngay cả khi bạn vẫn đang tinh chỉnh wrapper. Nếu câu trả lời vẫn tiếp tục vì không xuất hiện marker nào bạn đã chỉ định, giới hạn num_predict sẽ dừng output ở số token cố định, bất kể template tạo ra nội dung gì.

Template phải là Go template, không phải Jinja template. Tài liệu Hugging Face nói rõ điều này. Đây là điểm quan trọng vì field tokenizer.chat_template trong repository gốc của model chứa Jinja. Dán nguyên nội dung đó vào sẽ không hoạt động. Syntax của Ollama có 3 biến: {{ .System }} cho system prompt, {{ .Prompt }} cho message của user và {{ .Response }} cho câu trả lời của model. Tìm các turn marker thực tế của model trong model card hoặc tokenizer_config.json, rồi tự chuyển chúng sang Go syntax.

Có một cách tắt giúp giảm phần lớn công việc này. Nhiều model dùng chung một prompt format. Nếu một model khác trong library của bạn dùng cùng format, hãy chạy ollama show --template với model đó rồi copy nội dung được in ra.

Các file template, system và params trong repo Hugging Face

Cách dùng Hugging Face cung cấp các tùy chỉnh giống như các file trong repository, thay vì các instruction trong Modelfile. Nếu bạn sở hữu repository hoặc đang phát hành quant của mình, hãy thêm các file đó vào repository. Mọi ollama run hf.co/... sẽ tự động sử dụng chúng.

• File có tên template chứa Go template. Quy tắc vẫn vậy: dùng Go, không dùng Jinja.
• File có tên system chứa system prompt.
• File có tên params chứa sampling parameters và phải ở định dạng JSON.

Một file params tối thiểu:

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

Nếu không sở hữu repository, bạn không thể thêm các file đó. Hãy pull model một lần, chạy ollama show --modelfile hf.co/... để dump nội dung đã nhận, rồi lưu output đó thành một Modelfile. Dòng FROM của file trỏ đến blob mà Ollama đã download, nên bạn chỉ cần chỉnh các dòng TEMPLATE và PARAMETER rồi chạy ollama create để build một bản local đã sửa mà không cần download lại. Đây là cách chuẩn để sửa quant bị lỗi của người khác.

Cách import repo GGUF private

Repo private cần SSH key của Ollama trong tài khoản Hugging Face của bạn. Phương thức được tài liệu hóa cho cách này dùng SSH key thay vì API token, nên token bạn đang có sẽ không mở được repo.

In public key. Trên Linux server cài Ollama bằng script chính thức, service chạy dưới user ollama, nên key nằm trong thư mục home của user đó:

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

Nếu bạn tự khởi động ollama serve bằng user của mình, path sẽ là ~/.ollama/id_ed25519.pub. Copy toàn bộ dòng, mở phần cài đặt tài khoản Hugging Face tại https://huggingface.co/settings/keys, rồi thêm dòng đó dưới dạng SSH key mới. Sau đó command thông thường sẽ hoạt động với các repo private của bạn:

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

Nếu pull vẫn fail sau khi thêm key, có thể bạn đã in nhầm file. Server thực hiện việc download và gửi key của chính nó; service được systemd khởi động không bao giờ đọc ~/.ollama của user của bạn, nên key trong thư mục home của bạn không phải key mà Hugging Face nhìn thấy.

Mô hình có vừa với VPS của bạn không?

Con số quyết định điều này là kích thước file trên disk cộng với lượng memory cần cho context window. Weights được load vào memory với kích thước gần bằng dung lượng của chúng trong file, còn phần cấp phát cho context nằm bên trên và tăng theo số token bạn cho phép. Chạy ollama list để xem kích thước Ollama đã ghi nhận cho model, so sánh với free -h trên máy, và chừa headroom cho operating system cùng mọi thứ khác đang chạy trên server. Nếu muốn xem phép tính này đã được áp dụng cho một model thực tế, chạy Nemotron 3.5 Lightning trên VPS sẽ cho biết tag chính xác cần pull, lượng RAM cần dùng và liệu một máy chỉ chạy CPU có đáp ứng kịp hay không.

Context là phần nhiều người quên. Một model load được với window mặc định có thể fail khi bạn tăng num_ctx, vì phần cấp phát này tăng theo window bạn yêu cầu. Cấu hình num_ctx và chi phí memory trình bày cách tính dung lượng. Khi tổng lượng memory quá lớn, cách xử lý thường là dùng quant nhỏ hơn của cùng model. Đây là trade-off được trình bày trong so sánh Q4 với Q8.

Lỗi này không khó nhận biết. Trên VPS chỉ có CPU, kernel out-of-memory killer sẽ dừng process. journalctl -u ollama -n 50 cùng với dmesg cho biết process đã bị kill. Trên máy có GPU, ollama ps in ra cột PROCESSOR, cho biết model đã load vào GPU memory, system memory hay được chia trên cả hai. Model bị spill sang system memory vẫn trả lời được, nhưng chậm. Đo số token mỗi giây biến “chậm” thành một con số để bạn so sánh giữa các quant.

Kiểm tra những gì bạn đã import

Chạy 4 lệnh này sau mỗi lần import, theo đúng thứ tự:

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

ollama list xác nhận model tồn tại và hiển thị kích thước mà Ollama đã ghi nhận. ollama show xác nhận Ollama đã đọc được metadata cần thiết từ GGUF. ollama show --modelfile xác nhận template và các parameter mà Ollama thực sự sẽ dùng. Đây là bước kiểm tra giúp phát hiện lỗi đầu ra rác trước khi người dùng của bạn gặp phải. Prompt kiểm thử chạy qua toàn bộ chuỗi xử lý, vì model có template bị hỏng sẽ lỗi ngay cả với request ngắn nhất. Khi prompt đó trả về bình thường, tên bạn đặt cho model sẽ là tên bạn truyền cho mọi thành phần khác giao tiếp với Ollama API, bao gồm coding agent trỏ đến server riêng của bạn. Xóa một import bị lỗi bằng ollama rm my-model rồi build lại. Lệnh đó xóa bản sao của Ollama nhưng giữ nguyên source .gguf của bạn.

FAQ

Tôi có thể import một GGUF vào Ollama mà không cần viết Modelfile không?

Có, khi file nằm trong một repository trên Hugging Face. ollama run hf.co/{username}/{repository} sẽ pull và chạy trực tiếp file đó, còn ollama run hf.co/{username}/{repository}:{quantization} dùng để chọn một quant cụ thể. Chỉ cần Modelfile khi .gguf đã có sẵn trên disk của bạn. Khi đó, Modelfile có thể chỉ gồm một dòng FROM /path/to/file.gguf, sau đó chạy ollama create my-model.

Ollama sẽ download quantization nào nếu tôi không chỉ định?

Tài liệu của Hugging Face, được đọc vào ngày 10 October 2026, cho biết Q4_K_M sẽ được dùng nếu repository có quant đó. Nếu không, Ollama sẽ chọn một quant type hợp lý đang có trong repo. Thêm một tag như :Q8_0 để kiểm soát lựa chọn này. Dùng ollama show <model> để xác nhận file thực tế đã nhận. Lệnh này đọc quantization từ metadata của file, không đọc từ tên file.

Vì sao model import của tôi lặp lại nội dung hoặc không bao giờ dừng sinh text?

Chat template không khớp với model. Ollama tự động chọn template từ metadata tokenizer.chat_template bên trong GGUF. Khi metadata này bị thiếu hoặc không được nhận diện, Ollama dùng một wrapper chung. Vì vậy, model không nhận được end-of-turn marker mà nó đã được train. In template hiện tại bằng ollama show --template <model>, sau đó thêm block TEMPLATE và dòng PARAMETER stop vào Modelfile rồi chạy lại ollama create. Hãy viết template dưới dạng Go template. Jinja template từ repository gốc sẽ không hoạt động.

Tôi có nên dùng --quantize trên GGUF đã download không?

Không. --quantize chỉ hoạt động với safetensors import trong quá trình ollama create. Lệnh này từ chối mọi GGUF source, bao gồm cả file FP16 hoặc FP32, và báo lỗi yêu cầu bạn quantize GGUF model trước khi import. File có tên chứa quant như Q4_K_M đã được convert. Quantize lại không thể khôi phục precision đã mất: llama-quantize --allow-requantize có thể rewrite file thành Q8_0, nhưng kết quả sẽ lớn hơn mà không tốt hơn. Để tạo file nhỏ hơn từ GGUF full precision, chạy llama-quantize của llama.cpp trên file đó rồi import kết quả.

Làm thế nào để pull một GGUF repository private?

Thêm SSH public key của Ollama vào tài khoản Hugging Face của bạn. In key bằng sudo cat /usr/share/ollama/.ollama/id_ed25519.pub trên bản cài Linux tiêu chuẩn, hoặc bằng ~/.ollama/id_ed25519.pub khi bạn chạy server bằng user của chính mình. Sau đó, thêm key tại trang cài đặt SSH key của tài khoản. Tiếp theo, ollama run hf.co/{username}/{repository} sẽ hoạt động với các repository private của bạn và các repository thuộc organisation mà bạn là thành viên.