如何將 GGUF 模型匯入 Ollama

將 GGUF 模型匯入 Ollama 的兩種方式

將 GGUF 模型匯入 Ollama 有兩種方式，應採用哪一種取決於檔案目前的位置。如果模型位於 Hugging Face 儲存庫中，只要執行一個 ollama run 指令即可下載並執行，不需要使用 Modelfile。如果 .gguf 檔案已存在於伺服器磁碟上，則建立只有兩行的 Modelfile，並執行 ollama create。

兩種方式最後都會得到相同結果：模型會以指定名稱加入本機 Ollama 程式庫，並可由 ollama run 與 Ollama API 提供服務。檔案由其他人發布時，請使用第一種方式。若模型是自行量化、檔案透過 scp 或 rsync 傳入，或該機器無法連線至 Hugging Face，請使用第二種方式。

GGUF 檔案是單一二進位檔，會將權重、分詞器與模型中繼資料放在一起。這是 llama.cpp 讀取的格式，而 Ollama 建構於 llama.cpp 之上，因此幾乎所有開放模型都有社群製作的 GGUF 轉換版本。Ollama 不會直接載入資料夾中的 .safetensors 權重，因此需要進行轉換。

以下內容假設 Ollama 已安裝且其服務正在執行。若尚未完成，請先參閱 在 VPS 上安裝 Ollama，再返回此處。先執行 ollama list。如果該指令回傳資料表，即使是空表，而不是連線錯誤，表示伺服器已啟動，接下來的步驟即可正常執行。

路徑一：不使用 Modelfile，直接從 Hugging Face 執行 GGUF

Ollama 可以直接從 Hugging Face 儲存庫拉取 GGUF。指令格式是在儲存庫路徑前加上 hf.co/：

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

hf.co 和 huggingface.co 都可作為網域名稱。以下是 Hugging Face 文件中的實際範例：

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

第一次執行時會先下載檔案，因此必須等下載完成後才會出現聊天提示。之後模型會儲存在本機程式庫中，啟動速度會較快。開啟第二個 shell，執行 ollama list，查看模型儲存時使用的名稱。該名稱是完整的 hf.co/... 字串及其標籤，每次輸入都很冗長。請為它建立簡短別名：

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

此路徑僅適用於實際包含 GGUF 檔案的儲存庫。若儲存庫只發布 .safetensors 權重，沒有其他檔案，Ollama 就沒有可拉取的內容。此時必須使用後文所述的轉換步驟。

Ollama 會選擇哪種量化格式？

截至 25 August 2026 閱讀的 Hugging Face Ollama 文件，已明確說明預設行為：「預設會使用 Q4_K_M 量化格式，但前提是模型儲存庫中存在該格式。若不存在，則會從儲存庫中選擇一個合理的量化格式。」因此，發布十種量化格式的儲存庫會提供 Q4_K_M；若儲存庫沒有 Q4_K_M，Ollama 就會代替你選擇其他格式。依賴此行為前，請重新閱讀該頁面，因為預設值可能變更。

在標籤中指定量化格式：

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

量化名稱不區分大小寫，因此 :iq3_m 和 :IQ3_M 表示相同內容。你也可以將完整檔名作為標籤；當儲存庫中的簡短名稱可能產生歧義時，這是較安全的寫法。標籤必須指定該儲存庫中存在的檔案，因此請先開啟 Files and versions 分頁，確認實際檔名後再輸入。量化格式的選擇取決於記憶體與品質需求；Q4、Q8 與 FP16 的差異會完整說明這項取捨。

從自己的磁碟匯入 .gguf 檔案

檔案已在伺服器上時，您需要一個 Modelfile。它可以只有一行。建立目錄，將 Modelfile 放入其中，然後讓 FROM 指向該檔案：

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

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

將內容儲存為 Modelfile，然後建置模型：

ollama create my-model

ollama create 預設會讀取目前目錄中名為 Modelfile 的檔案。若檔案使用其他名稱或位於其他位置，請使用 -f，例如 ollama create my-model -f /home/you/models/my-model/Modelfile。執行 ollama create --help，即可查看建置時該旗標及其預設值。FROM 中的路徑可以是絕對路徑，也可以是相對於 Modelfile 的路徑，因此當兩者位於同一目錄時，FROM ./my-model-Q4_K_M.gguf 可以正常運作。使用絕對路徑即可完全避免路徑判定問題。

在信任結果前，先檢查結果：

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

現在 ollama list 應包含 my-model。ollama show my-model 會列出 Ollama 從檔案自身中繼資料讀取到的架構、參數數量、上下文長度與量化格式。請查看這些值，不要只相信檔名，因為檔名只是有人手動輸入的字串。如果模型能以正常語言回答測試提示，接著停止輸出，表示匯入成功。如果無法正常回答，請查看下方的範本區段，因為問題幾乎總是出在範本。

另外請注意磁碟空間：ollama create 會將 GGUF 複製到 Ollama 自己的模型儲存區，而不是參照原始檔案所在的位置。在您移除原始檔案前，權重會同時佔用兩份磁碟空間。確認 ollama run my-model 可正常運作後，刪除來源檔案；或將來源檔案存放在不會重複計費的位置。Ollama 在磁碟上的模型儲存位置說明其配置方式與搬移方法。

--quantize 何時適用，以及何時不適用

ollama create 具有 --quantize 旗標，且此旗標只適用於一種情況：來源模型使用 FP16 或 FP32，也就是完整精度權重。Ollama 的匯入文件將 q8_0 以及 k-means 變體 q4_K_S 和 q4_K_M 列為目標格式。

ollama create --quantize q4_K_M my-model

請勿對已量化的檔案傳入該旗標。檔名包含 Q4_K_M 或 Q5_K_S 的 .gguf 已經完成此步驟，該旗標不會執行任何處理。量化是從較高精度向下轉換的單向程序，因此無法將 Q4 還原為 Q8。如果來源是由 .safetensors 檔案組成的 Hugging Face 儲存庫，請先使用 llama.cpp 儲存庫中的 convert_hf_to_gguf.py 進行轉換。這是 Ollama 文件指定使用的工具。接著匯入該指令碼寫出的 GGUF。Ollama 與 llama.cpp 的關係說明為何轉換指令碼屬於另一個專案。

為什麼匯入的 GGUF 會回覆亂碼，或永遠不停止？

這是大多數匯入教學略過的失敗情況，也是你實際上會遇到的問題。症狀看起來像是模型損壞。回覆中會直接顯示控制 token，例如 <|im_start|>assistant 或 <|end|>。模型先回答，接著又產生一個新的使用者問題，並回答那個問題。生成會持續執行，直到你按下 Ctrl+C。

模型本身沒有問題。錯的是 chat template。chat template 是一層包裝，會將你的訊息轉換成模型訓練時使用的確切 token 序列，並包含模型專用的標記，用來表示 system prompt 結束及 user turn 開始的位置。Ollama 會替你選擇 chat template：文件表示，系統會根據儲存在 GGUF 檔案中的內建 tokenizer.chat_template metadata，從「常用模板清單中自動選擇」模板。當缺少該 metadata，或其內容與清單中的模板都不相符時，Ollama 會使用通用包裝。模型接收到的 prompt 形狀便與訓練資料完全不同，因此找不到訓練時學會用來停止的 end-of-turn 標記。

列出 Ollama 實際選用的模板：

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

如果輸出為空，或明顯是通用模板，即可確認問題所在。在 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|>"

使用 ollama create my-model 重新建置，然後再次傳送相同的測試 prompt。stop 參數是你的安全機制：當指定的字串出現時，Ollama 會停止生成。即使你仍在調整模板本身，也能先終止生成持續不停止的症狀。如果回覆仍持續生成，因為你指定的標記始終沒有出現，num_predict 上限 會依固定 token 數量截斷輸出，不受模板產生內容的影響。

模板必須是 Go template，而不是 Jinja template。 Hugging Face 文件明確說明了這一點。原因是原始模型 repository 中的 tokenizer.chat_template 欄位存放的是 Jinja。直接原樣貼上並不會運作。Ollama 的語法包含 3 個變數：{{ .System }} 代表 system prompt，{{ .Prompt }} 代表 user message，{{ .Response }} 代表 model 的回覆。在模型的 model card 或 tokenizer_config.json 中找出模型實際使用的 turn markers，再手動改寫成 Go 語法。

有一個捷徑可以省下大部分工作。許多模型共用相同的 prompt format。如果你的 library 中已有其他模型使用相同格式，請對該模型執行 ollama show --template，然後複製其輸出。

Hugging Face 儲存庫中的 template、system 與 params 檔案

Hugging Face 路徑提供與儲存庫檔案相同的控制項，而不是透過 Modelfile 中的指示設定。如果你擁有該儲存庫，或正在發布自己的 quant，請將這些檔案加入其中，之後每個 ollama run hf.co/... 都會讀取這些設定。

• 名為 template 的檔案包含 Go template。規則相同：使用 Go，不使用 Jinja。
• 名為 system 的檔案包含 system prompt。
• 名為 params 的檔案包含 sampling parameters，且必須使用 JSON 格式。

最小的 params 檔案如下：

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

如果你不擁有該儲存庫，就無法加入這些檔案。先拉取模型，執行 ollama show --modelfile hf.co/... 匯出收到的內容，並將輸出儲存為 Modelfile。其 FROM 行會指向 Ollama 已下載的 blob，因此你可以編輯 TEMPLATE 和 PARAMETER 行，然後執行 ollama create，建立不需再次下載的固定本機副本。這是修正他人損壞 quant 的標準方式。

如何匯入私有 GGUF 儲存庫

私有儲存庫需要在您的 Hugging Face 帳戶中加入 Ollama 的 SSH 金鑰。這條路徑的文件方法使用 SSH 金鑰，而不是 API token，因此您現有的 token 無法開啟該儲存庫。

列印公開金鑰。在透過官方指令碼安裝 Ollama 的 Linux 伺服器上，服務會以 ollama 使用者身分執行，因此金鑰位於該使用者的家目錄中：

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

如果您以自己的使用者身分自行啟動 ollama serve，路徑則是 ~/.ollama/id_ed25519.pub。複製完整的一行，開啟 Hugging Face 帳戶設定中的 https://huggingface.co/settings/keys，再將其新增為 SSH 金鑰。接著即可對私有儲存庫執行一般指令：

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

如果新增金鑰後 pull 仍然失敗，可能是列印了錯誤的檔案。伺服器會執行下載並提供自己的金鑰，而由 systemd 啟動的伺服器不會讀取您使用者的 ~/.ollama，因此家目錄下的金鑰不是 Hugging Face 實際看到的金鑰。

VPS 能容納此模型嗎？

決定因素是磁碟上的檔案大小，加上內容視窗所需的記憶體。權重載入記憶體後，所占空間通常接近檔案中的大小；內容配置則會額外占用記憶體，並隨允許的 token 數量增加。執行 ollama list，查看 Ollama 記錄的模型大小，再與該主機上的 free -h 比較，並為作業系統及伺服器執行的其他工作保留餘裕。如果想直接查看實際模型的計算結果，在 VPS 上執行 Nemotron 3.5 Lightning 會提供要拉取的確切 tag、所需的 RAM，以及僅使用 CPU 的主機是否能維持處理速度。

內容視窗是最容易被忽略的部分。模型以預設視窗載入時可能正常運作，但提高 num_ctx 後就會失敗，因為該配置會隨指定的視窗大小增加。設定 num_ctx 及其記憶體成本說明了容量估算方式。總需求過大時，通常可改用同一模型較小的 quant；這項取捨詳見Q4 與 Q8 的比較。

故障現象很明確。在僅使用 CPU 的 VPS 上，核心的 out-of-memory killer 會停止該程序，而 journalctl -u ollama -n 50 搭配 dmesg 可顯示遭到終止的程序。在配備 GPU 的主機上，ollama ps 會列出 PROCESSOR 欄位，指出載入的模型位於 GPU 記憶體、系統記憶體，或分散於兩者之間。模型若使用了系統記憶體，仍能回應，但速度會較慢。測量每秒 token 數可將「較慢」轉換成數值，方便比較不同 quant。

檢查匯入的內容

每次匯入後，依照以下順序執行這 4 個命令：

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

ollama list 可確認模型存在，並顯示 Ollama 記錄的大小。ollama show 可確認 Ollama 已從 GGUF 讀取所需的中繼資料。ollama show --modelfile 可確認實際使用的範本與參數；這項檢查能在使用者遇到無意義輸出前，先發現該問題。測試提示會驗證整個流程，因為範本損壞的模型連最短的請求也無法正常處理。測試提示正常回應後，您指定的模型名稱就是其他與 Ollama API 通訊的元件所使用的相同名稱，包括指向您自己伺服器的程式碼代理程式。使用 ollama rm my-model 移除錯誤的匯入，然後重新建置。此命令會刪除 Ollama 的副本，但不會修改來源 .gguf。

FAQ

我可以不撰寫 Modelfile，直接將 GGUF 匯入 Ollama 嗎？

可以，前提是檔案位於 Hugging Face 儲存庫中。ollama run hf.co/{username}/{repository} 會直接提取並執行該檔案，ollama run hf.co/{username}/{repository}:{quantization} 可選取特定量化版本。只有在 .gguf 已位於本機磁碟時，才需要使用 Modelfile；此時 Modelfile 可以只包含單行 FROM /path/to/file.gguf，接著執行 ollama create my-model。

未指定量化版本時，Ollama 會下載哪一種量化版本？

Hugging Face 的文件（截至 25 August 2026 查閱）指出，如果儲存庫中存在 Q4_K_M，就會使用該量化版本；否則，Ollama 會從儲存庫中選擇一種合理的量化類型。加入 :Q8_0 等標籤即可控制選用的版本。使用 ollama show <model> 確認實際取得的檔案；此命令會從檔案中繼資料顯示量化資訊，而不是從檔名判斷。

為什麼我匯入的模型會重複內容，或一直產生文字而不停止？

聊天範本與模型不相符。Ollama 會根據 GGUF 內的 tokenizer.chat_template 中繼資料自動選取範本。若缺少這些中繼資料，或 Ollama 無法識別，便會套用通用包裝範本，因此模型看不到訓練時使用的回合結束標記。使用 ollama show --template <model> 顯示目前的範本，接著在 Modelfile 中加入 TEMPLATE 區塊和 PARAMETER stop 行，再次執行 ollama create。請使用 Go template 語法。原始儲存庫中的 Jinja 範本無法使用。

我應該對下載的 GGUF 使用 --quantize 嗎？

不應該。--quantize 會在 ollama create 期間轉換 FP16 或 FP32 來源，而檔名已包含 Q4_K_M 等量化標記的檔案，代表它已經完成轉換。再次量化無法恢復精度，也無法將檔案轉回較高精度。只有在你自行將 safetensors 轉換為完整精度 GGUF，且現在要產生較小的檔案時，才應使用此旗標。

如何提取私有 GGUF 儲存庫？

將 Ollama 的 SSH 公開金鑰加入 Hugging Face 帳戶。在標準 Linux 安裝中使用 sudo cat /usr/share/ollama/.ollama/id_ed25519.pub 顯示金鑰；若以自己的使用者身分執行伺服器，則使用 ~/.ollama/id_ed25519.pub。接著前往帳戶的 SSH 金鑰設定頁面加入該金鑰。完成後，ollama run hf.co/{username}/{repository} 可用於你自己的私有儲存庫，以及你所屬組織中的儲存庫。