Soup导出GGUF完全教程：一键转Ollama/llama.cpp可用的量化模型

Soup导出GGUF完全教程一键转Ollama/llama.cpp可用的量化模型【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/SoupSoup 是一个「一份 YAML 搞定大模型微调」的开源工具除了训练它还内置了GGUF 导出功能一条命令就能把 LoRA 微调结果转成 Ollama、llama.cpp 可直接加载的量化 GGUF 模型文件支持 q4_0、q4_k_m、q5_k_m、q8_0 等常见量化档位还能顺手一键部署到本地 Ollama。本教程带你从零完成 Soup 导出 GGUF 的全流程。为什么要用 GGUF 格式维度训练产物SafetensorsGGUF加载工具需要 PyTorch 环境Ollama / llama.cpp 直接加载文件大小较大4-bit 量化后约为原来的 1/4部署场景云端 API笔记本、树莓派、离线设备易用性需要写代码ollama run一句话开聊简单说GGUF 是本地部署大模型最通用的「便携格式」。Soup 的卖点在于——你不用手动装转换脚本也不用自己合并 LoRA一条命令全搞定。第一步安装 SoupGGUF 导出依赖训练栈安装时带上[train]扩展注意用双引号这样在 Windows、PowerShell、bash 下都兼容pip install soup-cli[train] 只需要转导出、不需要训练的话装轻量版pip install soup-cli也可以导出所需依赖gguf、sentencepiece 等Soup 会在首次导出时自动补装。安装完成后建议先跑一下环境体检确认 GPU 与依赖都没问题soup doctor第二步一条命令导出 GGUF假设你之前用 Soup 训练完模型或 LoRA 适配器保存在./output那么核心命令就一行soup export --model ./output --format gguf --quant q4_k_m这条命令背后Soup 自动替你做了三件事自动合并 LoRA检测到adapter_config.json后先找到基座模型并把适配器合并成完整模型全程无需手动soup merge自动准备 llama.cpp首次使用会自动克隆到~/.soup/llama.cpp固定版本供应链安全转换 量化先转出 f16 中间文件再按你指定的档位量化临时文件自动清理。最终得到一个形如output.q4_k_m.gguf的单文件模型。怎么选量化档位Soup 支持 6 种档位q4_0、q4_k_m、q5_k_m、q8_0、f16、f32。新手推荐直接记下面这张对照表档位体积质量适用场景q4_0最小可用树莓派、8GB 内存设备q4_k_m⭐小良好日常首选速度与质量均衡q5_k_m中等很好内存 16GB 以上追求更高质量q8_0较大接近无损内存充裕、对质量敏感f16最大原始精度仅转换不量化时使用切换档位只需改一个参数模型目录不用动soup export --model ./output --format gguf --quant q8_0⭐ 默认就是q4_k_m所以不写--quant也是它——这也是社区最广泛使用的本地部署档位。第三步一键部署到 Ollama导出完 GGUF 之后Soup 可以在同一条命令里直接部署到本地 Ollamasoup export --model ./output --format gguf --deploy ollama --deploy-name my-model执行完ollama run my-model就能直接聊天零额外配置。如果你更喜欢手动控制三步也很简单# 1. 写一个 Modelfile echo FROM ./my-model.q4_k_m.gguf Modelfile # 2. 创建 Ollama 模型 ollama create my-model -f Modelfile # 3. 开聊 ollama run my-model部署时还可以顺带指定系统提示词和推理参数模板会自动识别 chatml、llama、mistral、vicuna 等soup deploy ollama --model ./output/model.q4_k_m.gguf --name soup-chat \ --system You are a helpful assistant. \ --parameter temperature0.7 --parameter top_p0.9管理已部署的模型同样方便soup deploy ollama --list查看列表soup deploy ollama --remove 名称删除。进阶用 llama.cpp 直接跑如果你的目标不是 Ollama而是 llama.cpp 生态Soup 提供了soup llama代理命令帮你安全地调用系统里已安装的 llama.cpp 可执行文件自动过滤敏感环境变量避免泄露 API Keysoup llama server -m model.gguf # 启动本地推理服务器 soup llama cli -m model.gguf -p Hello # 命令行对话两个值得知道的小细节量化导出需要构建一次 llama.cpp纯 f16/f32 转换只靠 Python 脚本即可但q4_0/q4_k_m等量化档位需要llama-quantize二进制。只需构建一次cd ~/.soup/llama.cpp cmake -B build -DGGML_NATIVEOFF -DLLAMA_CURLOFF -DCMAKE_BUILD_TYPERelease cmake --build build --config Release --target llama-quantize -j 4BitNet 1.58-bit 模型专用通道训练了 BitNet 的模型可以用soup export --model ./output --format bitnet直接导出 TQ1_0 三值量化 GGUF体积再打对折。常见问题速查Q1导出时报llama-quantize找不到A说明还没构建量化工具链按上面「进阶」一节跑一次 cmake 即可已有现成目录可用--llama-cpp /path/to/llama.cpp指定。Q2LoRA 适配器没有adapter_config.jsonSoup 还能识别吗A不能。此时用--base手动指定基座模型或者先执行soup merge合并后再导出完整模型目录。Q3导出前想验证质量损失A跑一下量化前后对比评测Soup 会给出 OK / MINOR / MAJOR 判定soup eval quant-check --before ./output --after ./merged-model --tasks eval.jsonlQ4还有其他导出格式吗A有。除 GGUF 外还支持 ONNX、TensorRT-LLM、AWQ、GPTQ、BitNet 等同一套命令换--format参数即可。相关资源完整导出与服务文档docs/serving-and-export.md全量命令参考docs/commands.md导出命令源码src/soup_cli/commands/export.pyOllama 部署实现src/soup_cli/commands/deploy.py导出格式测试用例tests/test_awq_gptq_export.py总结成一句话soup export --model ./output --format gguf --deploy ollama训练产物到本地可聊的量化模型中间所有脏活累活都交给 Soup 了。【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考