# GGUF - llama.cpp 的量化格式 GGUF（GPT 生成的统一格式）是 llama.cpp 的标准文件格式，可通过灵活的量化选项在 CPU、Apple Silicon 和 GPU 上进行高效推理。 ## 何时使用 GGUF **在以下情况下使用 GGUF：** * 部署在消费类硬件（笔记本电脑、台式机）上 * 在具有 Metal 加速功能的 Apple Silicon (M1/M2/M3) 上运行 * 需要CPU推理，无需GPU * 想要灵活的量化（Q2_K 到 Q8_0） * 使用本地AI工具（LM Studio、Ollama、text-generate-webui） **主要优点：** * **通用硬件**：CPU、Apple Silicon、NVIDIA、AMD 支持 * **无 Python 运行时**：纯 C/C++ 推理 * **灵活的量化**：2-8 位，具有多种方法（K 量化） * **生态系统支持**：LM Studio、Ollama、koboldcpp 等 * **imatrix** ：更好的低位质量的重要性矩阵 **使用替代方案：** * **AWQ/GPTQ** ：在 NVIDIA GPU 上进行校准的最大精度 * **HQQ** ：HuggingFace 的快速免校准量化 * **bitsandbytes** ：与变压器库简单集成 * **TensorRT-LLM**：以最大速度进行生产 NVIDIA 部署 ## 快速开始 ### 安装 # 克隆 llama.cpp git 克隆 https://github.com/ggml-org/llama.cpp cd 骆驼.cpp # 构建（CPU）使 # 使用 CUDA 构建 (NVIDIA) 使 GGML_CUDA=1 # 使用金属构建（Apple Silicon）使 GGML_METAL=1 # 安装 Python 绑定（可选） pip 安装 llama-cpp-python ### 将模型转换为 GGUF # 安装要求 pip install -r 要求.txt # 将 HuggingFace 模型转换为 GGUF (FP16) python Convert_hf_to_gguf.py ./path/to/model --outfile model-f16.gguf # 或者指定输出类型 python Convert_hf_to_gguf.py ./path/to/model \ --outfile model-f16.gguf \ --outtype f16 ### 量化模型 # 基本量化为 Q4_K_M ./llama-量化模型-f16.gguf 模型-q4_k_m.gguf Q4_K_M # 使用重要性矩阵进行量化（质量更好） ./llama-imatrix -m model-f16.gguf -fcalibration.txt -o model.imatrix ./llama-quantize --imatrix model.imatrix model-f16.gguf model-q4_k_m.gguf Q4_K_M ### 运行推理 # CLI 推理 ./llama-cli -m model-q4_k_m.gguf -p "你好，你好吗？" # 交互模式 ./llama-cli -m model-q4_k_m.gguf --interactive # 使用 GPU 卸载 ./llama-cli -m model-q4_k_m.gguf -ngl 35 -p “你好！” ## 量化类型 ### K-quant 方法（推荐）类型 |比特|尺寸 (7B) |品质 |使用案例 ---|---|---|---|--- Q2_K | 2.5 | 2.5 〜2.8 GB |低|极度压缩 Q3_K_S | 3.0 | 〜3.0 GB |低中度|内存受限 Q3_K_M | 3.3 | 〜3.3 GB |中等|平衡 Q4_K_S | 4.0 | 〜3.8 GB |中高|平衡性好 Q4_K_M | 4.5 | 4.5 〜4.1 GB |高| **推荐默认** Q5_K_S | 5.0 | 〜4.6 GB |高|注重质量 Q5_K_M | 5.5 | 5.5 〜4.8 GB |非常高 |高品质 Q6_K | 6.0 | 〜5.5 GB |优秀|接近原版 Q8_0 | 8.0 | 〜7.2 GB |最佳|最高品质 ### 遗留方法类型 |描述 ---|--- Q4_0 | 4 位，基本 Q4_1 | 4 位带增量 Q5_0 | 5 位，基本 Q5_1 | 5 位带增量 **建议**：使用 K 定量方法（Q4_K_M、Q5_K_M）以获得最佳质量/尺寸比。 ## 转换工作流程 ### 工作流程 1：HuggingFace 到 GGUF # 1.下载模型 Huggingface-cli 下载meta-llama/Llama-3.1-8B --local-dir ./llama-3.1-8b # 2. 转换为 GGUF (FP16) python Convert_hf_to_gguf.py ./llama-3.1-8b \ --outfile llama-3.1-8b-f16.gguf \ --outtype f16 # 3. 量化 ./llama-量化 llama-3.1-8b-f16.gguf llama-3.1-8b-q4_k_m.gguf Q4_K_M # 4. 测试 ./llama-cli -m llama-3.1-8b-q4_k_m.gguf -p “你好！” -n 50 ### 工作流程 2：使用重要性矩阵（更好的质量） # 1. 转换为GGUF python Convert_hf_to_gguf.py ./model --outfile model-f16.gguf # 2.创建校准文本（多样化样本）猫 > 校准.txt << 'EOF' 敏捷的棕色狐狸跳过了那只懒狗。机器学习是人工智能的一个子集。 Python 是一种流行的编程语言。 # 添加更多样的文本样本... EOF # 3.生成重要性矩阵 ./llama-imatrix -m model-f16.gguf \ -f 校准.txt \ --块 512 \ -o 模型.imatrix \ -ngl 35 # GPU 层（如果可用） # 4. 使用 imatrix 进行量化 ./llama-quantize --imatrix model.imatrix \ 型号-f16.gguf \ 模型-q4_k_m.gguf \ Q4_K_M ### 工作流程 3：多次量化 #!/bin/bash 模型=“llama-3.1-8b-f16.gguf” IMATRIX="llama-3.1-8b.imatrix" # 生成一次矩阵 ./llama-imatrix -m $MODEL -f wiki.txt -o $IMATRIX -ngl 35 # 创建多个量化对于 Q4_K_M Q5_K_M Q6_K Q8_0 中的定量；做输出 =“llama-3.1-8b-${QUANT,,}.gguf” ./llama-quantize --imatrix $IMATRIX $MODEL $OUTPUT $QUANT echo“已创建：$OUTPUT（$（du -h $OUTPUT | cut -f1））” 完成 ## Python 用法 ### 骆驼-cpp-python 从 llama_cpp 导入 Llama # 加载模型 llm = 骆驼( model_path =“./model-q4_k_m.gguf”， n_ctx=4096, # 上下文窗口 n_gpu_layers=35, # GPU 卸载（0 仅适用于 CPU） n_threads=8 # CPU 线程） # 生成输出 = llm( “什么是机器学习？”，最大令牌=256，温度=0.7，停止=["", "\n\n"] ）打印（输出[“选择”][0][“文本”]） ### 聊天完成从 llama_cpp 导入 Llama llm = 骆驼( model_path =“./model-q4_k_m.gguf”， n_ctx=4096, n_gpu_layers=35, chat_format="llama-3" # 或“chatml”、“mistral”等。）消息 = [ {"role": "system", "content": "你是一个得力助手。"}, {"role": "user", "content": "什么是 Python？"} ] 响应 = llm.create_chat_completion( 消息=消息，最大令牌=256，温度=0.7 ） print(response["选择"][0]["消息"]["内容"]) ### 流媒体从 llama_cpp 导入 Llama llm = 骆驼（model_path =“./model-q4_k_m.gguf”，n_gpu_layers = 35） # 流令牌对于 llm 中的块（ “解释量子计算：”，最大令牌=256，流=真）：打印（块[“选择”] [0] [“文本”]，结束=“”，刷新= True） ## 服务器模式 ### 启动 OpenAI 兼容服务器 # 启动服务器 ./llama-server -m model-q4_k_m.gguf \ --主机0.0.0.0 \ --端口8080 \ -ngl 35 \ -c 4096 # 或者使用 Python 绑定 python -m llama_cpp.server \ --模型模型-q4_k_m.gguf \ --n_gpu_layers 35 \ --主机0.0.0.0 \ --端口8080 ### 与 OpenAI 客户端一起使用从 openai 导入 OpenAI 客户端 = OpenAI( base_url =“http://localhost:8080/v1”， api_key="不需要" ）响应 = client.chat.completions.create( 模型=“本地模型”， messages=[{"角色": "用户", "内容": "你好！"}], 最大令牌=256 ）打印（响应.选择[0].消息.内容） ## 硬件优化 ### 苹果硅（金属） # 用金属构建清理 && 使 GGML_METAL=1 # 以 Metal 加速运行 ./llama-cli -m model.gguf -ngl 99 -p “你好” # Python 与 Metal llm = 骆驼( model_path =“模型.gguf”， n_gpu_layers=99, # 卸载所有层 n_threads=1 # Metal 处理并行性） ### NVIDIA CUDA # 使用 CUDA 构建清理 && 使 GGML_CUDA=1 # 使用 CUDA 运行 ./llama-cli -m model.gguf -ngl 35 -p “你好” # 指定GPU CUDA_VISIBLE_DEVICES=0 ./llama-cli -m model.gguf -ngl 35 ### CPU优化 # 使用 AVX2/AVX512 构建使清洁&&使 # 使用最佳线程运行 ./llama-cli -m model.gguf -t 8 -p “你好” # Python CPU 配置 llm = 骆驼( model_path =“模型.gguf”， n_gpu_layers=0, # 仅CPU n_threads=8, # 匹配物理核心 n_batch=512 # 提示处理的批量大小） ## 与工具集成 ### 奥拉玛 # 创建模型文件猫 > 模型文件 << 'EOF' 来自./model-q4_k_m.gguf 模板“”“{{.系统}} {{ .提示}}""" 参数温度0.7 参数 num_ctx 4096 EOF # 创建 Ollama 模型 ollama 创建 mymodel -f 模型文件 # 运行 ollama 运行 mymodel “你好！” ### LM工作室 1. 将 GGUF 文件放入 `~/.cache/lm-studio/models/` 2.打开LM Studio并选择模型 3.配置上下文长度和GPU卸载 4. 开始推理 ### 文本生成-webui # 放入models文件夹中 cp model-q4_k_m.gguf 文本生成-webui/models/ # 从 llama.cpp 加载器开始 python server.py --model model-q4_k_m.gguf --loader llama.cpp --n-gpu-layers 35 ## 最佳实践 1. **使用 K-quants** ：Q4_K_M 提供最佳质量/尺寸平衡 2. **使用 imatrix** ：对于 Q4 及以下始终使用重要性矩阵 3. **GPU卸载**：卸载VRAM允许的尽可能多的层 4. **上下文长度**：从 4096 开始，根据需要增加 5. **线程数**：匹配物理CPU核心，而不是逻辑CPU核心 6. **批量大小**：增加n_batch以加快提示处理速度 ## 常见问题 **模型加载缓慢：** # 使用 mmap 来加快加载速度 ./llama-cli -m model.gguf --mmap **内存不足：** # 减少GPU层数 ./llama-cli -m model.gguf -ngl 20 # 从 35 减少 # 或者使用较小的量化 ./llama-量化模型-f16.gguf 模型-q3_k_m.gguf Q3_K_M **低位质量差：** # Q4 及以下版本始终使用 imatrix ./llama-imatrix -m model-f16.gguf -fcalibration.txt -o model.imatrix ./llama-quantize --imatrix model.imatrix model-f16.gguf model-q4_k_m.gguf Q4_K_M ## 参考文献 * **[高级用法]()** \- 批处理、推测解码、自定义构建 * **[故障排除]()** \- 常见问题、调试、基准测试 ## 资源 * **存储库**： * **Python 绑定** : * **预量化模型** ： * **GGUF 转换器** : * **许可证**：麻省理工学院

Gguf 量化

包含技能