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 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 hai 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ộ, có thể được ollama run và Ollama API phục vụ. Dùng cách thứ nhất 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òn Ollama được xây dựng trên llama.cpp. Vì vậy, hầu hết open model đều có bản chuyển đổi sang GGUF do cộng đồng thực hiện. Ollama không load trực tiếp một thư mục chứa weights .safetensors, nên bước chuyển đổi là cần thiết.

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. Trước tiên, chạy ollama list. Nếu lệnh trả về một bảng, kể cả bảng 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 GGUF trực tiếp từ một repository trên Hugging Face. Lệnh này gồm đườ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 tên miền. 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ỉ xuất hiện sau khi quá trình download hoàn tất. Sau đó, model được lưu trong library cục bộ và khởi động nhanh. Mở shell thứ hai rồi chạy ollama list để xem tên model được lưu dưới dạng nào. Tên đó là toàn bộ chuỗi hf.co/... kèm tag, khá dài nếu phải nhập mỗi lần. Hãy đặt 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ỉ phát hành weight .safetensors mà không có định dạng nào khác thì không cung cấp file để Ollama fetch, và bạn cần thực hiện bước chuyển đổi được mô tả ở phần dưới.

Ollama chọn quantization nào?

Tài liệu Ollama của Hugging Face, được đọc vào ngày 25 August 2026, nêu rõ giá trị mặc định: "Theo mặc định, Ollama sử dụng scheme quantization Q4_K_M nếu scheme này có trong model repo. Nếu không có, Ollama sẽ chọn một quant type hợp lý đang có trong repo." Vì vậy, repository có 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 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ể, hãy 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 quant 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ể dùng chính xác tên file làm tag. Đây là cách an toàn khi tên ngắn trong repository không rõ ràng. Tag phải trỏ đế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 đúng tên file trước khi nhập. Việc chọn quant nào phụ thuộc vào bộ nhớ và chất lượng; phần so sánh Q4, Q8 và FP16 giải thích đầy đủ sự đánh đổi này.

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

Khi file đã có 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 directory, đặ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 directory 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ó trong bản build bạn đang dùng. Path trong FROM có thể là absolute path hoặc relative path tính từ Modelfile, nên FROM ./my-model-Q4_K_M.gguf hoạt động khi cả hai nằm trong cùng một directory. 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 lúc này 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 ai đó tự đặt. 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ề disk space: ollama create sao chép GGUF vào model store riêng của Ollama thay vì tham chiếu đến file đang có trên disk. Weights sẽ chiếm disk hai lần 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ữ file đó ở nơi bạn không phải trả chi phí cho hai bản sao. vị trí Ollama lưu model trên disk mô tả layout và cách di chuyển model.

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

ollama create có flag --quantize, và flag này chỉ dùng cho một trường hợp: source model ở dạng FP16 hoặc FP32, tức weights full precision. Tài liệu import của Ollama liệt kê q8_0 cùng các biến thể k-means q4_K_S và q4_K_M là các target.

ollama create --quantize q4_K_M my-model

Không dùng flag đó với file đã được quantize. Một .gguf có tên chứa Q4_K_M hoặc Q5_K_S đã trải qua bước này, nên flag không còn việc gì để làm. Quantization là quá trình chuyển một chiều từ precision cao xuống thấp, nên không có cách chuyển từ Q4 ngược lên Q8. Nếu source của bạn là một repository trên Hugging Face chứa các file .safetensors, trước tiên hãy chuyển đổi bằng convert_hf_to_gguf.py từ repository llama.cpp. Đây là tool mà tài liệu Ollama hướng dẫn sử dụng. Sau đó import file 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 conversion script thuộc project khác.

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 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 file đó trực tiếp, 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 25 August 2026, cho biết Q4_K_M sẽ được dùng nếu quant đó có trong repository. Nếu không, Ollama sẽ chọn một quant type hợp lý đang có trong repository. 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, vì lệnh này đọc quantization từ metadata của file thay vì từ tên file.

Tại sao model đã import của tôi lặp lại hoặc không bao giờ dừng sinh output?

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 thấy end-of-turn marker mà nó đã được train để sử dụng. 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 chuyển đổi source FP16 hoặc FP32 trong quá trình ollama create. File có tên đã chứa quant như Q4_K_M thì đã được chuyển đổi. Không thể khôi phục precision bằng cách quantize lần nữa, và không có cách chuyển ngược lên precision cao hơn. Chỉ dùng flag này khi bạn tự chuyển safetensors thành GGUF full precision và muốn tạo một file nhỏ hơn.

Làm cách nào để pull một repository GGUF 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. Khi hoàn tất, 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.