llama.cpp本地部署Qwen3.8大语言模型完整教程

llama.cpp 是一款基于 C/C++ 编写的开源大语言模型推理引擎，配合 GGUF 格式的量化模型，可以在消费级显卡上高效运行大语言模型。本教程使用 a4agent 一键安装包完成部署，它按显卡后端提供 CUDA 12.4、CUDA 13.3 与 Vulkan 三种预编译版本，并针对 8G 至 24G 及以上不同显存给出 Ornith-1.5-9B、Ornith-1.5-35B 与 Qwen3.8-27B 三款可选模型。教程以 Qwen3.8-27B 模型为主线，完整演示从选择安装包、下载模型、图形化启动 OpenAI 兼容 API 服务，到工具调用、思考模式控制、KV cache 显存优化与 MTP 投机解码加速的全过程。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• OpenAI兼容API的概念与用法详解，本教程启动的 llama-server 对外暴露的正是 OpenAI 兼容 API，两者概念完全一致。
• Ollama本地部署大语言模型完整教程，同为本地部署大语言模型的方式，可与 llama.cpp 进行对比学习。
• LM Studio本地部署大语言模型完整教程，同为基于 GGUF 格式的本地部署方案，可对比不同工具的实现差异。

资源下载

根据显卡选择一个 a4agent 安装包即可，多个版本之间互不冲突，无需重复安装：

• a4agent cu12.4 安装包 v0.1.2，NVIDIA 显卡首选版本，要求驱动版本 551 及以上。
• a4agent cu13.3 安装包 v0.1.2，面向驱动已支持 CUDA 13.3 的最新 NVIDIA 驱动环境。
• a4agent vulkan 安装包 v0.1.2，NVIDIA、AMD、Intel Arc 通吃版本。
• llama.cpp 官方 GitHub Releases 发布页，希望手动部署原版 llama.cpp 的高级用户参考。

请根据显存情况，选择对应模型下载：

• Ornith-1.5-9B-Q4_K_M.gguf，约 5.7 GB，面向 8G 及相近显存的轻量模型。
• Ornith-1.5-35B-A3B-IQ4_XS.gguf，约 19 GB，面向 16G 及以上显存的编码 Agent 主力模型。
• Qwen3.8-27B-Uncensored-Q4_K_M.gguf，约 16.8 GB，面向 22G 及以上显存的完整体验模型。

1. 认识 a4agent 与 llama.cpp

1.1 llama.cpp 与 a4agent 的关系

llama.cpp 是社区最流行的本地大语言模型推理引擎之一，具有以下特点：

不过原版 llama.cpp 在 Windows 上以压缩包形式发布，需要自己区分 CUDA 版本、补齐 CUDA 运行库 DLL、手写启动命令，对新手不够友好。a4agent 是 llama.cpp 的图形化封装工具，它把上述工作全部自动化：

a4agent 本质上仍然在调用 engine 目录下的 llama-server.exe，因此命令行知识依然适用——第 4 章会同时讲解图形界面启动与命令行直接启动两种方式。

1.2 GGUF 格式与量化

GGUF 是 llama.cpp 使用的模型存储格式，将模型权重与元数据（词表、对话模板、配置信息）打包在单一文件中，并支持多种量化精度：

量化数值越低，模型文件越小、显存占用越少，但质量会相应下降。Q4_K_M 是 27B 级别模型在 22GB 显存显卡上的最佳选择，可以完整放入显存实现全量 GPU 推理。

本教程配套三款模型：Ornith-1.5-9B 采用 Q4_K_M 量化，权重约 5.7 GB，适合小显存；Ornith-1.5-35B 采用 IQ4_XS 量化，适合中高端显存；Qwen3.8-27B-Uncensored 是社区微调的无限制版本，采用 Q4_K_M 量化，权重约 16.8 GB，适合大显存完整体验。

1.3 确认你的显卡与驱动

选安装包前先弄清自己的硬件。NVIDIA 用户打开 PowerShell 执行：

nvidia-smi

输出表格右上角有一个 CUDA Version 字样，它表示当前驱动最高支持的 CUDA 版本：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.97       Driver Version: 580.97       CUDA Version: 13.3                 |
+-----------------------------------------------------------------------------------------+

记录两件事：显卡型号（判断性能档次）与这个 CUDA Version 数值（决定选 cu13.3 还是 cu12.4）。如果提示找不到该命令，说明没有 NVIDIA 显卡或驱动未安装，请改用 Vulkan 版安装包。AMD 与 Intel 显卡用户可在任务管理器的「性能」页确认显卡型号。

1.4 三种安装包怎么选

三个安装包内置了分别针对不同图形后端编译的 llama.cpp 引擎，选错后端会导致无法调用显卡加速：

AMD 显卡建议 RDNA 架构（RX 6000 系列及以上）搭配较新的 Adrenalin 驱动；Intel Arc 需要最新驱动；更老的卡仍可运行，但建议搭配小模型与小上下文。NVIDIA 用户即使能跑 Vulkan 版，也更建议用 CUDA 版以获得更好性能。

选择流程如下图所示：

选择建议：拿不准选哪个包时，先下 cu12.4。它兼容所有较新驱动，几乎不会遇到兼容性问题。

1.5 按显存分档选择模型

模型选择取决于显存容量。核心原则是让模型权重尽可能完整放入显存实现全量 GPU 推理，剩余显存留给上下文缓存。本教程提供的三个模型覆盖四档显存：

16G 档的取舍逻辑：追求响应速度与长上下文，选 Ornith-1.5-9B 方案一；必须使用 27B 模型能力时选方案二，接受约每秒几个 token 的生成速度。8G 以下显存或没有独立显卡时，仍可用 CPU 模式运行 Ornith-1.5-9B，但速度受限。

Ornith 系列 35B 是 MoE 架构，文件名中的 A3B 即表示每 token 仅激活约 3B 参数，配合极小的 KV cache 占用，中端显卡即可获得接近旗舰的编码 Agent 能力（SWE-Bench Verified 79.0 分）。Ornith-1.5-9B 则是混合架构模型，每 4 层才有一层全注意力携带 KV cache，上下文的显存代价同样极小。关于该模型系列的背景，可阅读Ornith-1.5 开源发布：自进化 Agentic Coding 模型。

1.6 整体部署架构

按本教程完成部署后，整体架构如下：

• a4agent 控制台负责检测显卡、推荐预设、拼装启动参数并管理 llama-server 进程。
• 客户端（浏览器、Python 脚本、Agent 框架）通过 HTTP 调用 llama-server 的 /v1/chat/completions 等接口。
• llama-server 将模型权重加载到 GPU 显存，上下文信息（KV cache）同样存储在显存中，上下文越长占用越多。

2. 下载模型文件

2.1 从网盘下载模型文件

本教程的模型文件统一通过资源下载区的网盘链接获取，按 1.5 节的显存分档下载对应文件即可：

建议将模型统一存放在单独目录（如 C:\models），后续向导和启动命令都指向这一目录，便于管理。下载完成后可通过文件大小核对完整性。

3. 安装 a4agent

3.1 运行安装向导

双击下载好的安装包（如 a4agent-cu12.4-setup-v0.1.2.exe），按向导完成安装：

1. 接受许可协议，安装位置保持默认（用户目录下的 a4agent-cu12.4 文件夹），也可自行修改。
2. 「附加任务」页可选创建桌面快捷方式。
3. 完成页勾选「立即运行 a4agent 配置向导」，进入首次配置。

安装完成后，目录结构如下：

a4agent-cu12.4\
├── a4agent.exe        控制台主程序
└── engine\            内置 llama.cpp 引擎
    ├── llama-server.exe
    └── ggml、cudart 等全套依赖 DLL

与手动部署原版 llama.cpp 不同，CUDA 运行库（cudart、cublas 等 DLL）已随引擎一并打包，不会出现「缺 DLL 静默回退 CPU」这类问题。三个版本的安装包相互独立，可并存于同一台机器，便于对比测试。

3.2 首次配置向导

首次启动会进入四步配置向导：

若步骤 3 提示「未找到有效的 .gguf 模型文件」，请确认所选目录下确实存在模型文件且扩展名为 .gguf。

3.3 验证 GPU 识别

进入控制台主界面，「状态」页会显示引擎状态与显卡信息。想进一步确认引擎对 GPU 的识别情况，可在 engine 目录下打开命令行执行：

llama-server.exe --list-devices

CUDA 版正常输出示例：

Available devices:
  CUDA0: NVIDIA GeForce RTX 2080 Ti (22527 MiB, 21308 MiB free)

Vulkan 版正常输出示例：

Available devices:
  Vulkan0: AMD Radeon RX 7900 XTX (24576 MiB, 23000 MiB free)

如果输出为 (none)：CUDA 版请检查驱动版本是否满足要求（见 1.4 节）；Vulkan 版请将显卡驱动升级到最新。

3.4 更换版本与卸载

发现选错安装包（例如 cu13.3 报 PTX 错误）时，直接再安装对应版本即可，两个版本互不干扰。卸载通过 Windows 设置进入「应用」页面，搜索 a4agent，按后缀名（如 a4agent (cu12.4)）选择对应条目卸载。

4. 启动 OpenAI 兼容 API 服务

4.1 图形界面一键启动

在「状态」页点击「启动」按钮，日志区依次输出启动命令、模型加载进度，看到 [就绪] health ok 即说明服务已就绪：

[启动] C:\Users\you\AppData\Local\Programs\a4agent-cu12.4\engine\llama-server.exe
[参数] -m C:\models\Qwen3.8-27B-Uncensored-Q4_K_M.gguf --host 127.0.0.1 --port 8080 ...
[就绪] health ok —— http://127.0.0.1:8080/

服务就绪约 90 秒后，日志会出现一条「内存裁剪完成」记录，系统内存占用明显下降。这是 a4agent 自动释放模型文件占用的文件缓存，属于正常现象，不影响推理服务。

点击「停止」即可结束服务；关闭主窗口时程序会最小化到托盘，服务继续在后台运行。

4.2 设置项与 llama-server 参数对照

「设置」页的可视化选项与底层 llama-server 参数一一对应，理解这张表就同时掌握了两种启动方式：

修改后点击「保存设置」即生效，下次启动服务时按新参数运行。

4.3 命令行直接启动（进阶）

希望脱离图形界面（如配置开机脚本、远程服务器）的用户，可直接运行 engine 目录中的 llama-server.exe。三种显存档位的参考命令如下。

22G 及以上显存，全量 GPU 推理：

C:\Users\you\AppData\Local\Programs\a4agent-cu12.4\engine\llama-server.exe -m C:\models\Qwen3.8-27B-Uncensored-Q4_K_M.gguf --host 0.0.0.0 --port 8080 -ngl 99 -c 57344 --alias Qwen3.8-27B-Uncensored-Q4_K_M --parallel 1 -fa on --reasoning off

12G 至 16G 显存，27B 部分 CPU 卸载（-ngl 按启动日志中的显存余量微调）：

C:\Users\you\AppData\Local\Programs\a4agent-cu12.4\engine\llama-server.exe -m C:\models\Qwen3.8-27B-Uncensored-Q4_K_M.gguf --host 0.0.0.0 --port 8080 -ngl 28 -c 16384 -ctk q8_0 -ctv q8_0 --alias Qwen3.8-27B-Uncensored-Q4_K_M -fa on --reasoning off

6G 至 8G 显存，Ornith-1.5-9B 全量 GPU 推理：

C:\Users\you\AppData\Local\Programs\a4agent-cu12.4\engine\llama-server.exe -m C:\models\Ornith-1.5-9B-Q4_K_M.gguf --host 0.0.0.0 --port 8080 -ngl 99 -c 32768 -ctk q4_0 -ctv q4_0 --alias Ornith-1.5-9B-Q4_K_M --parallel 1 -fa on

常用参数含义汇总：

也可以将启动命令写入批处理脚本，双击即可启动、关闭窗口即停止：

@echo off
setlocal
chcp 65001 >nul
set "SERVER=C:\Users\you\AppData\Local\Programs\a4agent-cu12.4\engine\llama-server.exe"
set "MODEL=C:\models\Qwen3.8-27B-Uncensored-Q4_K_M.gguf"

"%SERVER%" -m "%MODEL%" --host 0.0.0.0 --port 8080 -ngl 99 -c 57344 --alias Qwen3.8-27B-Uncensored-Q4_K_M --parallel 1 -fa on --reasoning off

echo.
echo Server stopped.
pause

停止服务时直接关闭启动窗口，或在命令行执行 Stop-Process -Name llama-server -Force。注意不要与 a4agent 图形界面同时启动同一个端口的服务。

4.4 验证服务

curl http://127.0.0.1:8080/health

返回 {"status":"ok"} 即服务正常。「接入」页可直接复制 Base URL、Chat URL 与 Model ID 三项信息给客户端使用。查看模型列表：

curl http://127.0.0.1:8080/v1/models

5. 调用 OpenAI 兼容 API

5.1 对话补全

llama-server 提供的接口与 OpenAI 完全兼容，base_url 为 http://127.0.0.1:8080/v1，模型名默认是 GGUF 文件名去掉扩展名（即启动时的 --alias 值）。服务未启用鉴权，API Key 随便填非空字符串即可：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen3.8-27B-Uncensored-Q4_K_M","messages":[{"role":"user","content":"1+1=?"}]}'

使用 OpenAI Python SDK 调用：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8080/v1",
    api_key="any-non-empty-string",  # llama-server 不校验密钥
)
resp = client.chat.completions.create(
    model="Qwen3.8-27B-Uncensored-Q4_K_M",
    messages=[{"role": "user", "content": "1+1=?"}],
)
print(resp.choices[0].message.content)

5.2 工具调用

llama-server 原生支持 OpenAI 格式的工具调用，可用于 Agent 场景。请求中传入 tools 参数即可：

{
  "model": "Qwen3.8-27B-Uncensored-Q4_K_M",
  "messages": [{"role": "user", "content": "北京现在天气怎么样？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "城市名称"}
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

模型会返回 finish_reason: "tool_calls" 及结构化参数，Agent 据此执行工具后将结果以 role: "tool" 消息回传，模型即可生成最终回答，形成完整的工具调用闭环。Ornith-1.5-9B 同样支持工具调用，其定位本身就是 Agentic Coding 模型，可作为低配机器上的轻量 Agent 底座。

5.3 思考模式控制

Qwen3.8 默认开启思考模式，会先输出大段推理内容再给出答案，token 消耗较大。可以在请求中临时关闭：

{
  "chat_template_kwargs": {"enable_thinking": false}
}

也可以在启动层面全局关闭：命令行加 --reasoning off；a4agent 生成的启动参数默认已附带 --reasoning off 与 --reasoning-budget 0，无需额外设置。关闭后模型直接输出答案，实测生成速度可提升约一倍，工具调用场景下尤为推荐。

6. 上下文与显存优化

6.1 显存去哪了：权重与 KV cache

推理时的显存开销主要由两部分构成：模型权重（由量化档位和参数规模决定，加载后基本固定）与 KV cache（随上下文长度线性增长）。以 Qwen3.8-27B 为例，每个 token 需要约 64 KB 显存（FP16 精度），因此：

KV 显存占用 = 64 KB × 上下文长度
56k 上下文    → 约 3.5 GB 显存

而 Ornith-1.5-9B 采用混合架构，仅约四分之一的层携带 KV cache 且每层只有 2 个 KV 头，q4_0 量化下每千 token 仅约 5.6 KB，32k 上下文的 KV cache 只占约 0.2 GB——这就是小显存也能开大上下文的原因。

6.2 KV cache 量化

通过 -ctk 与 -ctv 参数将 KV cache 从 FP16 压缩为低位量化，可大幅降低长上下文的显存占用。a4agent 中只需在「设置」页切换「KV 缓存级别」。以 27B 模型为例，改为 q8_0 后每个 token 的占用从 64 KB 降到 32 KB，质量几乎无损：

llama-server.exe -m C:\models\Qwen3.8-27B-Uncensored-Q4_K_M.gguf -ngl 99 -c 131072 -ctk q8_0 -ctv q8_0

实测对比（Qwen3.8-27B，22 GB 显存）：

KV cache 量化后，128k 上下文的显存占用反而低于之前 56k 的 FP16 配置，这是 22 GB 显卡上实现超长上下文的关键手段。

6.3 各显存档位推荐配置

综合前述原则，给出一张可以直接照抄的配置速查表（对应 a4agent 首次启动时自动推荐的预设档位）：

6.4 OOM 排查思路

a4agent 会读取 GGUF 元数据估算当前配置的显存需求，并在设置页实时给出风险提示（例如预计需求超过显存九成时会提醒余量偏小）。若启动失败或生成中断报 OOM，按以下顺序逐级降级：

1. 降低上下文长度（效果最直接）。
2. 将 KV 缓存级别从 f16 降到 q8_0 或 q4_0。
3. 极端情况下减小 GPU 层数 -ngl，让部分层回到 CPU 计算。

上下文窗口越大，能处理的文本越长，但显存占用也越高。长文本请求的预填充时间与输入长度成正比，实际使用时建议根据场景在 64k 至 128k 之间选择。

7. MTP 投机解码加速

7.1 投机解码原理

Qwen3.8 模型内置了多 token 预测头（MTP），可用于投机解码加速。投机解码的核心思想是「先预测、后验证」：

• MTP 头预测的 token 不会被直接采信，必须与主模型自己的选择一致才被接受。
• 因此投机解码对生成质量理论无损，输出分布与关闭投机时完全一致。

7.2 开启方式

a4agent 在「设置」页提供「MTP 投机步数」输入框，设为大于 0 的整数即开启（对应命令行参数 --mtp 步数）。启动服务时 a4agent 会先探测当前引擎是否支持 MTP 参数，不支持时自动忽略该设置并在日志中提示，不会导致启动失败。命令行方式启用示例：

llama-server.exe -m C:\models\Qwen3.8-27B-Uncensored-Q4_K_M.gguf --mtp 2

7.3 步数调优

投机解码默认关闭。步数表示每次验证时 MTP 头预测的候选 token 数量，并非越大越好，实测数据如下（Qwen3.8-27B-Uncensored，300 token 生成任务）：

对 Qwen3.8 这类混合架构模型，MTP 步数取 1 到 2 效果最好。步数越多，被拒绝的候选越多，MTP 头的计算就越浪费。

8. 总结

8.1 核心内容回顾

• a4agent 是 llama.cpp 的图形化封装，安装包按显卡后端分为 cu12.4、cu13.3、vulkan 三种，CUDA 运行库已内置，避免了手动部署时因缺失 DLL 导致的 CPU 回退问题。
• 选包原则：AMD 与 Intel 显卡选 vulkan；NVIDIA 用户看 nvidia-smi 的 CUDA Version，不低于 13.3 可选 cu13.3，其余一律 cu12.4。
• 模型按显存分档：8G 档用 Ornith-1.5-9B 全量卸载；12G 至 16G 档可用 9B 开大上下文或让 27B 部分 CPU 卸载；16G 以上可全量卸载 Ornith-1.5-35B-A3B；22G 及以上用 Qwen3.8-27B-Uncensored 全量卸载。
• llama-server 原生提供 OpenAI 兼容 API，支持工具调用与思考模式控制，可直接对接 Agent 框架。
• KV cache 量化（-ctk q8_0 -ctv q8_0）是突破显存限制、实现 128k 超长上下文的关键；Ornith 混合架构的 KV 占用极小，小显存也能开大上下文。
• MTP 投机解码需显式开启，步数取 1 时接受率最高，速度可提升约 50%。

8.2 常见问题与解答

问：我是 AMD 显卡，可以用这套方案吗？

答：可以，选择 vulkan 安装包即可。建议 RX 6000 系列及以上的 RDNA 架构显卡搭配较新的 Adrenalin 驱动；更老的卡性能有限，建议搭配 Ornith-1.5-9B 小模型与小上下文。

问：cu13.3 版启动时报 PTX toolchain 相关错误怎么办？

答：说明显卡驱动尚不支持 CUDA 13.3。执行 nvidia-smi 查看 CUDA Version，低于 13.3 就改装 cu12.4 版本，两者功能完全一致。

问：启动后生成速度很慢，只有每秒 1 个 token 左右，是什么原因？

答：模型没有加载到 GPU，回退到了 CPU 推理。在 engine 目录执行 llama-server.exe --list-devices 检查，如果显示 (none)：CUDA 版检查驱动版本是否满足 1.4 节要求；Vulkan 版升级显卡驱动后再试。

问：为什么我设置了较大的 max_tokens，实际输出却被截断？

答：输入与输出共享同一个上下文窗口，最大输出等于上下文窗口减去本次输入长度。例如 56k 窗口下输入 1 万 token，则最多输出约 4.7 万 token。

问：提示端口 8080 被占用怎么处理？

答：可能已有实例在运行（注意托盘图标）。确认没有重复实例后，在设置页修改服务端口即可，客户端同步更换 base_url 中的端口号。

问：服务启动约 90 秒后，系统内存占用突然下降，是出问题了吗？

答：不是。这是 a4agent 的自动内存裁剪功能，释放的是模型文件占用的操作系统文件缓存，日志中会有「内存裁剪完成」记录，推理服务不受影响。

问：Ornith-1.5-35B 与 Qwen3.8-27B 应该怎么选？

答：看使用场景。35B 是 MoE 架构，每 token 仅激活约 3B 参数，生成速度快，Agentic Coding 与工具调用能力强（SWE-Bench Verified 79.0 分），是 Agent 场景的首选；27B-Uncensored 是稠密通用模型，适合日常对话与非代码任务。两者显存要求相近：16G 以上显卡可全量卸载 35B 的 IQ4_XS 档位，27B 则建议 22G 以上。

问：MTP 投机解码会影响生成质量吗？

答：理论上无损。投机解码采用验证制，候选 token 必须与主模型自己的选择一致才被接受，输出分布与关闭投机时一致。极少数情况下，批量验证与逐 token 推理的浮点计算路径差异可能导致个别 token 不同，但语义质量无感知差异。