2026 年 11 月 13 日有两件事落地,让这一周成了上手强力本地模型的好时机:llama.cpp 背后的 ggml 库升到了 1.0.0 版,llama.cpp 自身也发布了 v1.0.0。在此两天前,Unsloth 更新了广受欢迎的 Qwen3.8-27B GGUF 版本,这是一款拥有 270 亿参数、支持视觉与推理的开源模型。本文将带你用 llama.cpp 在自己的电脑上运行它、与它对话,并通过兼容 OpenAI 的 API 对外提供服务。
文中命令来自 llama.cpp 文档、Unsloth 的 Qwen3.8 指南和 Qwen 模型卡,信息截至 2026 年 11 月 14 日。
你要安装的是什么
- Qwen3.8-27B 是阿里巴巴 Qwen 团队推出的 27B 稠密模型,采用 Apache 2.0 许可证发布。它能处理文本和图像,原生上下文长度为 262,144 个 token,并默认开启思考(逐步推理)。
- GGUF 是 llama.cpp 使用的模型文件格式。Unsloth 在
unsloth/Qwen3.8-27B-GGUF仓库中发布了压缩(即“量化”)版本。 - llama.cpp 是一款免费的开源引擎,可在 Mac、Windows 和 Linux 上运行 GGUF 模型,并会尽可能利用你的 GPU 或 Apple Silicon。
准备工作
- 内存:Unsloth 的指南称,4-bit 版本需要内存与显存合计 16–19 GB,例如 RTX 4090 或 5080,或者一台 24 GB 内存的 Mac。3-bit 版本则只需 12–14 GB。
- 磁盘空间:推荐的 4-bit 文件约占 18 GB。
- 终端:macOS 的 Terminal、Windows 的 PowerShell,或任意 Linux shell。
挑一个适合你机器的量化版本。以下是 Unsloth 仓库中各文件的大小:
| 量化版本 | 文件大小 | 适用场景 |
|---|---|---|
| UD-Q3_K_XL | 13.15 GB | 16 GB 的机器,前提是能接受一定的质量损失 |
| UD-Q4_K_XL | 17.66 GB | 推荐的默认选择(24 GB 的 Mac、24 GB 的 GPU) |
| UD-Q5_K_XL | 20.98 GB | 质量更高,前提是空间够用 |
| Q8_0 | 29.05 GB | 在 32 GB 及以上的机器上获得接近完整的质量 |
第 1 步:安装 llama.cpp
llama.cpp 的安装文档为各主流系统都列出了对应的安装包。
在 macOS 或 Linux 上,使用 Homebrew:
brew install llama.cpp
在 Windows 上:
winget install llama.cpp
安装完成后新开一个终端,确认服务器程序已在 PATH 中:
llama-server --version
llama.cpp 的 README 里还有一个新的一行式安装脚本(curl -LsSf https://llama.app/install.sh | sh),它会装好一个统一的 llama 命令,这样用 llama serve -hf <repo> 就能启动服务器。本文使用 llama-server,因为这个程序的选项有完整的文档说明。
第 2 步:下载并启动 Qwen3.8
-hf 选项会直接从 Hugging Face 下载模型。在冒号后面写上量化版本的名称:
llama-server -hf unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL -c 32768
首次运行会下载约 18 GB 的文件,你可以在终端里看到下载进度。视觉附加文件(即“mmproj”)会自动下载。-c 32768 将上下文设为 32K。上下文越小,占用的内存越少,之后可以再调大。
务必写明量化版本。llama.cpp 文档称,-hf 默认选用 Q4_K_M,找不到时则退而使用仓库中的第一个文件。Unsloth 的仓库里没有普通的 Q4_K_M 文件,所以如果省略不写,下载到的可能不是你想要的那个文件。
第 3 步:在浏览器中聊天
在 llama.cpp 1.0 中,服务器默认监听 127.0.0.1:9931,而不是旧教程里用的 8080。等终端提示模型已加载后,打开 http://127.0.0.1:9931 即可进入内置的聊天页面。如果想在另一个终端里确认它是否就绪:
curl http://127.0.0.1:9931/health
第 4 步:像调用 OpenAI API 一样调用它
服务器在 /v1/chat/completions 提供了一个兼容 OpenAI 的端点。下面这个请求使用了 Unsloth 推荐的思考模式参数:
curl http://127.0.0.1:9931/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "Explain what a GGUF file is in two sentences."}],
"temperature": 1.0,
"top_p": 0.95,
"top_k": 20,
"min_p": 0.0
}'
回答位于 choices[0].message.content 中。凡是支持自定义 OpenAI base URL 的工具,都可以填 http://127.0.0.1:9931/v1,而且大多数工具的 API 密钥随便填什么都行。
第 5 步:控制思考
思考模式在难题上能给出更好的答案,但耗时更长。Qwen 的模型卡写道,思考“默认开启,可按请求关闭”。在 JSON 请求体中加入下面这段即可关闭:
"chat_template_kwargs": {"enable_thinking": false}
关闭思考后,Unsloth 建议将 temperature 设为 0.7、top_p 设为 0.80、top_k 设为 20、min_p 设为 0.0、presence_penalty 设为 1.5。如果想保留思考但让它短一些,可以在启动服务器时设置推理强度(reasoning effort)。可选档位有 xhigh(默认)、medium、low 和 none:
llama-server -hf unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL -c 32768 --chat-template-kwargs '{"reasoning_effort":"medium"}'
在 Windows PowerShell 中,请按 Unsloth 指南的写法对引号进行转义:--chat-template-kwargs "{\"reasoning_effort\":\"medium\"}"。
备选方案:从源码编译(Unsloth 的方法)
Unsloth 的指南是从源码编译 llama.cpp,并用 Hugging Face CLI 下载文件,这种方式适合配有 NVIDIA GPU 的 Linux 机器。它的编译命令用到了 apt-get,因此适用于 Debian 或 Ubuntu。在 Mac 上,请把 -DGGML_CUDA=ON 改成 -DGGML_CUDA=OFF,因为 Metal 默认就是开启的。
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
-DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
pip install -U "huggingface_hub[cli]"
hf download unsloth/Qwen3.8-27B-GGUF \
--local-dir unsloth/Qwen3.8-27B-GGUF \
--include "*UD-Q4_K_XL*"
./llama.cpp/llama-cli \
--model unsloth/Qwen3.8-27B-GGUF/Qwen3.8-27B-UD-Q4_K_XL.gguf \
--temp 1.0 \
--top-p 0.95 \
--top-k 20 \
--min-p 0.0
更喜欢 Ollama?它也提供了这个模型。ollama run qwen3.8:27b 会下载一个 18 GB 的版本。安装配置可参考我们的 Ollama 入门指南。
常见错误与解决方法
llama-server: command not found。新开一个终端,让 PATH 生效。如果你用的是 llama.app 安装脚本,那就只有llama命令,请改用llama serve,或者通过 Homebrew 或 winget 安装。- 总是下载到错误的文件。在冒号后面加上量化版本(
:UD-Q4_K_XL),详见第 2 步。 - 内存不足导致崩溃,或输出非常慢。试试 3-bit 的
UD-Q3_K_XL,用-c 8192调小上下文,或者关掉其他占资源的应用。如果模型放不进显存,部分层会溢出到系统内存,速度会慢很多。 - 8080 端口提示“Connection refused”。llama.cpp 1.0 默认使用 9931 端口。如果某个工具需要旧端口,请加上
--port 8080。 - 思考没完没了,或回答啰嗦跑题。使用上文推荐的采样参数,调低
reasoning_effort,或者在处理简单任务时关闭思考。 - PowerShell 中的 JSON 参数报错。按第 5 步所示对内层引号进行转义。
总结
有了 llama.cpp 1.0 和一条 -hf 命令,在本地运行一个能力不俗的 27B 模型,只需要一次安装、一条命令。先从 4-bit 版本开始,在自己的工具里调用 9931 端口上的 API,用不着的时候就把思考调低。如果接下来想让 AI 编程智能体操控浏览器或其他工具,可以看看我们的 Chrome DevTools MCP 指南。
参考来源
链接最后检查于 2026 年 11 月 15 日。





写评论