llama.cpp 模型獲取與量化完全指南從 -hf 一行下載命令到自建 GGUF 量化【免費(fèi)下載鏈接】llama.cppLLM inference in C/C項目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp本文以 llama.cpp 官方文檔 模型獲取與量化說明 為主線系統(tǒng)講解三種獲得可用模型的路徑通過-hf user/model[:quant]參數(shù)從模型倉庫一鍵下載、使用本地已下載的 GGUF 文件、以及用倉庫內(nèi)convert_*.py腳本自行轉(zhuǎn)換并量化模型并結(jié)合 common/download.cpp、common/arg.cpp 等源碼還原量化選擇、緩存、斷點(diǎn)續(xù)傳等底層機(jī)制讀完即可獨(dú)立完成從「拉取模型」到「自制量化」的完整工作流。llama.cpp 的模型獲取路徑概覽llama.cpp 的運(yùn)行前提只有一條模型必須以 GGUF 文件形式存儲。圍繞這一前提官方文檔給出了三條互補(bǔ)的路徑遠(yuǎn)程下載模型托管在與 Hugging Face API 兼容的平臺上官方默認(rèn)指向 Hugging Face其上托管了成千上萬個 GGUF 格式的社區(qū)模型通過-hf參數(shù)直接下載并運(yùn)行本地運(yùn)行把已經(jīng)下載到文件系統(tǒng)上的 GGUF 文件交給命令行工具本地加載自行轉(zhuǎn)換其他數(shù)據(jù)格式如 PyTorch 權(quán)重的模型用倉庫根目錄下的convert_*.py系列 Python 腳本轉(zhuǎn)換為 GGUF再按需量化。此外模型托管平臺還提供了若干在線工具用于免本地環(huán)境的轉(zhuǎn)換、量化、LoRA 適配與元數(shù)據(jù)編輯后文單獨(dú)介紹。使用 -hf 參數(shù)一鍵下載并運(yùn)行模型最簡單的方式是在任意命令行工具后追加-hf user/model[:quant]。官方示例如下llama cli -hf ggml-org/gemma-3-1b-it-GGUF其中[:quant]是可選的量化標(biāo)簽用于指定倉庫中要下載的具體量化版本。從參數(shù)定義的源碼 common/arg.cpp 可以看到完整的參數(shù)語義參數(shù)別名-hf、-hfr、--hf-repo也可通過環(huán)境變量LLAMA_ARG_HF_REPO設(shè)置quant 可省略且不區(qū)分大小寫缺省時優(yōu)先選擇Q4_K_M若倉庫中不存在該量化則回退到倉庫里的第一個可用模型文件mmproj 自動下載如果倉庫中存在與模型配套的多模態(tài)投影文件mmproj會自動一并下載加--no-mmproj可禁用官方給出的帶量化標(biāo)簽示例為ggml-org/GLM-4.7-Flash-GGUF:Q4_K_M。量化選擇的源碼邏輯「默認(rèn) Q4_K_M、回退第一個文件」并不是簡單猜測common/download.cpp 中的find_best_model()實現(xiàn)了完整的候選策略顯式指定 quant 時用正則不區(qū)分大小寫在倉庫文件列表中匹配形如...-Q4_K_M.gguf的文件未指定 quant 時按Q4_K_M→Q8_0的優(yōu)先級依次嘗試兩者都找不到時回退到倉庫中第一個「看起來像主模型」的 GGUF 文件匹配時會先經(jīng)gguf_filename_is_model()過濾掉mmproj、imatrix、mtp-、eagle3-等配套文件保證選中的是模型本體。-hf 配套的 CLI 參數(shù)common/arg.cpp 中還注冊了若干配套參數(shù)實際使用時值得知曉參數(shù)別名作用-hff--hf-file指定倉庫內(nèi)的具體文件名優(yōu)先級高于-hf中的 quant 標(biāo)簽-hft--hf-tokenHugging Face 訪問令牌缺省讀取HF_TOKEN環(huán)境變量私有倉庫需要--mtp—若倉庫存在 multi-token predictionMTP頭文件則一并下載--spec-draft-hf-hfd與-hf相同語法但用于投機(jī)解法的 draft 模型--offline—離線模式強(qiáng)制只使用本地緩存禁止發(fā)起網(wǎng)絡(luò)請求其中--offline的實現(xiàn)位于 common/download.cpp開啟后若文件不在緩存中直接報錯命中緩存則返回一個「偽 304」?fàn)顟B(tài)表示命中。通過 MODEL_ENDPOINT 指向其他模型平臺-hf參數(shù)并不綁定 Hugging Face 站點(diǎn)。官方文檔指出把MODEL_ENDPOINT環(huán)境變量指向任何兼容 Hugging Face API 的端點(diǎn)同一命令行即可從其他站點(diǎn)下載。源碼 common/common.cpp 中的common_get_model_endpoint()印證了這一優(yōu)先級鏈讀取MODEL_ENDPOINT環(huán)境變量若為空回退讀取舊變量HF_ENDPOINT向后兼容兩者皆空時使用默認(rèn)端點(diǎn)https://huggingface.co/若自定義端點(diǎn)末尾沒有/會自動補(bǔ)齊。這意味著私有鏡像、內(nèi)部模型倉庫只需實現(xiàn) HF API 的倉庫文件列表與文件下載接口即可被 llama.cpp 的所有工具復(fù)用無需改動代碼。運(yùn)行本地下載的模型下載到本地的 GGUF 文件可以直接交給命令行工具加載例如llama cli -m ./model-Q4_K_M.gguf --prompt Hello若模型是多模態(tài)的可同時加載 mmproj 投影文件llama cli -m ./model.gguf --mmproj ./mmproj-model-Q8_0.gguf --image input.jpg --prompt Describe this image離線場景下配合-hf與--offline還能讓工具直接解析本地 HF 緩存快照并運(yùn)行而不需要重復(fù)下載——緩存解析邏輯見 common/download.cpp 的common_download_resolve_path()與 common/hf-cache.h 中定義的緩存文件結(jié)構(gòu)hf_file含path、local_path、final_path等字段快照創(chuàng)建采用鏈接/移動方式避免重復(fù)占盤。GGUF 格式要求與模型轉(zhuǎn)換llama.cpp 只接受 GGUF 容器格式的模型文件。其他格式的原始權(quán)重需要兩步走轉(zhuǎn)換量化官方文檔明確指向 tools/quantize/README.md其完整流程如下。第一步轉(zhuǎn)換為 GGUF先安裝 Python 依賴python3 -m pip install -r requirements.txt或使用uvuv pip install -r requirements.txt --index-strategy unsafe-best-match然后運(yùn)行倉庫根目錄的 convert_hf_to_gguf.py該腳本內(nèi)置約 80 個模型的架構(gòu)定義位于 conversion/ 目錄python convert_hf_to_gguf.py --outfile gemma-4-E2B-it-bf16.gguf --outtype bf16 --remote google/gemma-4-E2B-it官方給出的三條注意事項模型以 16-bit 格式分發(fā)時--outtype auto或省略--outtype均可若模型已下載到本地改為指定本地目錄并去掉--remote參數(shù)出于兼容考慮Python 依賴默認(rèn)安裝 transformers 4但新模型可能要求 transformers 5可按需pip install -U transformers。第二步量化 GGUF拿到高比特F32/BF16的 GGUF 后用llama-quantize工具量化./build/bin/llama-quantize gemma-4-E2B-it-bf16.gguf gemma-4-E2B-it-Q4_K_M.gguf Q4_K_M量化的本質(zhì)是降低權(quán)重精度如 32-bit 浮點(diǎn)降到 4-bit 整數(shù)換取更小的模型體積和更快的推理速度代價是可能的精度損失通常用困惑度ppl或 KL 散度kld度量使用合適的imatrix重要性矩陣文件可以把損失降到最低。llama-quantize 完整選項表以下參數(shù)完整繼承自 tools/quantize/README.md常規(guī)選項選項說明--allow-requantize允許對已量化張量再次量化。警告相比從 16/32-bit 量化質(zhì)量可能顯著下降--leave-output-tensor保留output.weight不量化。增大體積但在 requantize 場景下可能提升質(zhì)量--pure禁用 k-quant 混合所有張量量化為同一類型--imatrix file_name使用指定文件中的重要性矩陣importance matrix優(yōu)化量化--include-weights tensor_name僅對指定張量使用 imatrix可多次指定--exclude-weights tensor_name對未列出的張量使用 imatrix與 include 不可混用--output-tensor-type為output.weight指定特定量化類型--token-embedding-type為詞嵌入張量指定特定量化類型--keep-split按輸入文件的分片結(jié)構(gòu)輸出而不是合并為單一文件高級選項選項說明--tensor-type用正則表達(dá)式將特定張量量化為特定類型可多次指定--prune-layers裁剪刪除列表中的層--override-kv按 key 覆蓋量化后模型的元數(shù)據(jù)可多次指定多模態(tài)組件的轉(zhuǎn)換與量化對支持圖像/音頻輸入的模型多模態(tài)編碼器與投影器需要單獨(dú)轉(zhuǎn)換并量化生成所謂mmprojmultimedia projector文件。官方建議將其保留在 bf16 或 q8 這樣的高比特格式這類組件體積遠(yuǎn)小于 LLM 本體速度/內(nèi)存開銷可以忽略但它直接決定送入 LLM 的輸入質(zhì)量——輸入越接近訓(xùn)練分布生成質(zhì)量越好python convert_hf_to_gguf.py --mmproj --outfile mmproj-gemma-4-E2B-it-Q8_0.gguf --outtype q8_0 --remote google/gemma-4-E2B-it量化示例命令集以下為 tools/quantize/README.md 給出的典型用法覆蓋 imatrix、張量級正則、層裁剪與元數(shù)據(jù)覆蓋# 默認(rèn)配置、8 CPU 線程的樸素 Q4_K_M 量化輸出 ggml-model-Q4_K_M.gguf ./llama-quantize input-model-f32.gguf q4_k_m 8 # 啟用再量化、保留 output 張量不量化、其余張量統(tǒng)一 Q4_K ./llama-quantize --allow-requantize --leave-output-tensor --pure input-model-f32.gguf q4_k_m 8 # 僅對 attn_v 與 ffn_down 張量使用重要性矩陣 ./llama-quantize --imatrix imatrix.gguf --include-weights attn_v --include-weights ffn_down input-model-f32.gguf q4_k_m 8 # output 張量 Q5_K、詞嵌入 Q3_K并保持輸入分片 ./llama-quantize --imatrix imatrix.gguf --output-tensor-type q5_k --token-embedding-type q3_k --keep-split input-model-f32.gguf q4_k_m 8 # 正則量化奇數(shù)層 attn_k 用 Q5_K_M偶數(shù)層 attn_q 用 Q3_K_M ./llama-quantize --imatrix imatrix.gguf --tensor-type \.(\d*[13579])\.attn_kq5_k --tensor-type \.(\d*[02468])\.attn_qq3_k input-model-f32.gguf q4_k_m 8 # attn_v 與 ffn_down 提升為 Q5_K_M并裁剪第 20、21、22 層 ./llama-quantize --imatrix imatrix.gguf --tensor-type attn_vq5_k --tensor-type ffn_downq5_k --prune-layers 20,21,22 input-model-f32.gguf q4_k_m 8 # 覆蓋 expert 計數(shù)元數(shù)據(jù)、裁剪層不做量化copy 模式 ./llama-quantize --imatrix imatrix.gguf --override-kv qwen3moe.expert_used_countint:16 --prune-layers 20,21,22 input-model-f32.gguf pruned-model-f32.gguf copy 8內(nèi)存與磁盤需求由于模型當(dāng)前會被完整載入內(nèi)存轉(zhuǎn)換/量化大模型時需要同時預(yù)留與模型同級的磁盤空間和 RAM。以 Llama 3.1 系列為例引自官方量化文檔模型原始大小量化后大小Q4_K_M8B32.1 GB4.9 GB70B280.9 GB43.1 GB405B1,625.1 GB249.1 GB量化方法速覽體積、速度與比特數(shù)不同量化方法在磁盤體積與推理速度上表現(xiàn)各異。官方文檔以 Llama 3.1 8B 為例給出了對比數(shù)據(jù)節(jié)選可作為選型參考指標(biāo)IQ2_XXSQ2_KQ3_K_SQ4_K_MQ5_K_MQ6_KQ8_0F16bits/weight2.38243.15933.64294.89445.70366.56338.500816.0005體積 (GiB)2.232.953.414.585.336.147.9514.96提示處理 t/s 512852.39784.45752.17821.81758.69812.01865.09923.49文本生成 t/s 12879.8679.8569.8471.9367.2358.6750.9329.17可以看出比特數(shù)越高體積越大、生成速度越慢但質(zhì)量通常越好Q4_K_M 在體積與速度之間取得常見平衡這也是-hf缺省優(yōu)先選擇它的原因。完整的多組數(shù)據(jù)含 IQ1IQ4 全系列及誤差范圍見 tools/quantize/README.md 的「Quantization」一節(jié)。下載子系統(tǒng)的工程細(xì)節(jié)從源碼結(jié)構(gòu)看-hf背后的下載器在 common/download.cpp 中還實現(xiàn)了若干健壯性機(jī)制理解它們有助于排查下載問題ETag 緩存每個已下載文件旁寫入.etag文件下次請求先HEAD比對ETag 一致則直接復(fù)用緩存返回 304斷點(diǎn)續(xù)傳臨時文件命名為file.downloadInProgress若服務(wù)器響應(yīng)Accept-Ranges續(xù)傳時攜帶Range: bytesN-請求頭要求服務(wù)器返回 206否則重新下載自動重試失敗后按指數(shù)退避重試初始間隔 2 秒最多 3 次嘗試分片模型識別xxx-00001-of-00005.gguf命名格式get_split_files()會把同一前綴的所有分片納入下載計劃由common_download_get_all_parts()展開完整分片列表并行下載std::async并發(fā)見 common/download.cpp配套文件自動匹配find_best_sibling()按「目錄深度共享最長 → 精確匹配 quant 標(biāo)簽 → 比特數(shù)最接近」三級策略挑選 mmproj / mtp / eagle3 等兄弟文件Docker 鏡像中的模型除 HF 倉庫外common_docker_resolve_model()還支持從 Docker registry 拉取以application/vnd.docker.ai.gguf.v3媒體類型封裝的 GGUF 層對應(yīng) CLI 的--docker-repo參數(shù)見 common/arg.cpppreset 快捷方式若倉庫根目錄存在preset.ini則只下載該文件并按其內(nèi)容解析模型配置見 common/download.cpp。模型解析與下載行為有專門的測試覆蓋 tests/test-model-resolution.cpp可作為理解各分支邏輯的入口。在線工具免本地環(huán)境的轉(zhuǎn)換與量化除了本地 Python 腳本模型平臺還提供了一系列在線工具適合不想搭建 Python 環(huán)境的用戶GGUF-my-repo 空間在線完成「轉(zhuǎn)換為 GGUF 量化權(quán)重」官方量化文檔還提到它每 6 小時從 llama.cpp 主分支同步一次構(gòu)建GGUF-my-LoRA 空間把 LoRA 適配器轉(zhuǎn)換為 GGUF 格式GGUF-editor 空間在瀏覽器中直接編輯 GGUF 元數(shù)據(jù)Inference Endpoints直接在云端托管 llama.cpp 服務(wù)。這些工具與本地腳本產(chǎn)出的是同一格式的文件因此轉(zhuǎn)換完成后即可按本文「運(yùn)行本地下載的模型」一節(jié)的命令行方式在任意 llama.cpp 工具中加載使用。小結(jié)llama.cpp 的模型鏈路可以概括為一句話一切皆 GGUF。日常使用-hf user/model[:quant]一行命令覆蓋絕大多數(shù)場景缺省自動選 Q4_K_M、自動帶 mmproj、支持 ETag 緩存與斷點(diǎn)續(xù)傳需要私有端點(diǎn)時用MODEL_ENDPOINT切換需要自定義量化或從原始權(quán)重出發(fā)時走convert_hf_to_gguf.py轉(zhuǎn)換 llama-quantize量化的兩步流程并用 imatrix 控制精度損失。所有行為均可以從 common/ 目錄下的源碼與 tests/ 中的測試用例逐行驗證?！久赓M(fèi)下載鏈接】llama.cppLLM inference in C/C項目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考