如何用 llama.cpp 在本地运行 Qwen3.8-27B(Unsloth GGUF 指南)

llama.cpp 刚刚迎来 1.0。本文教你用 Unsloth 的 GGUF 在自己的电脑上运行 Qwen3.8-27B:安装、选择量化版本、启动服务器并调用 API。

终端运行 llama-server 并在 9931 端口加载 Qwen3.8-27B 模型的示意图

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。
视频(英文):《Qwen3.8-27B GGUF: Run It Local with llama.cpp, Ollama & LM Studio》,作者 Fahd Mirza。

准备工作

  • 内存: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_XL13.15 GB16 GB 的机器,前提是能接受一定的质量损失
UD-Q4_K_XL17.66 GB推荐的默认选择(24 GB 的 Mac、24 GB 的 GPU)
UD-Q5_K_XL20.98 GB质量更高,前提是空间够用
Q8_029.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 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。