Qwen 本地部署记录

相比在线 API，本地模型最大的吸引力不是“免费”，而是数据留在本机、参数可控、服务接口稳定，并且能够直接接入自己的 Agent 与自动化系统。

这次使用 llama.cpp + Qwen GGUF + RTX 4060 Laptop 搭建本地推理服务。下面保留我的设备与参数记录，同时把显存、上下文和网络暴露这些容易忽略的取舍说清楚。

一、设备与目标

项目	配置
设备	Honor MagicBook Pro 16
GPU	RTX 4060 Laptop，8 GB 显存
系统	Windows 11 / WSL2 Ubuntu 22.04
推理框架	llama.cpp
模型格式	GGUF

我的目标不是追求最大参数量，而是在有限显存下获得稳定的中文问答和本地 API。8 GB 显存更适合较小模型或较低量化；运行 27B 量级模型通常需要部分 CPU 卸载，速度和上下文长度都要做取舍。

二、为什么选择 Qwen 与 llama.cpp

Qwen 的中文表达、技术问答和 GGUF 生态比较适合本地使用。llama.cpp 则提供 CUDA 加速、量化模型支持、命令行工具和 OpenAI 兼容服务接口，既能直接聊天，也能作为其他程序的模型后端。

这套组合的优势是依赖相对克制、部署方式多、参数透明；代价是需要自己处理模型量化、显存预算、提示模板与服务安全。

三、编译 CUDA 版本

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j 8

Windows 使用 Visual Studio 工具链时，需要安装“使用 C++ 的桌面开发”、CMake 工具、MSVC 与 Windows SDK，并从 Developer PowerShell 运行编译命令。

构建完成后，先确认 llama-cli 或 llama-server 位于 build/bin 对应的配置目录中。项目更新较快，实际可执行文件路径应以当前构建输出为准。

四、选择模型与量化

GGUF 文件名中的 Q4、Q5 等通常代表量化精度和体积等级。量化越低，显存与内存压力通常越小，但模型质量也可能下降。

我的测试模型包括 Q4_K_M 与 Q5_K_M。选择时不能只看文件能否装进显存，还要为 KV Cache、上下文和运行开销留空间。建议先从较短上下文启动，再观察实际占用：

1	nvidia-smi

如果启动时已经接近显存上限，应减少 GPU 层数或上下文，而不是等待运行中随机报错。

五、启动本地服务

Windows 下可以先用一行命令减少转义问题：

1	llama-server.exe -m Qwen3.5-27B-Q4_K_M.gguf --n-gpu-layers 99 --ctx-size 8192 --threads 22 --host 127.0.0.1 --port 8000

常用参数含义：

参数	作用	调整建议
`-m`	GGUF 模型路径	使用绝对路径可减少工作目录问题
`--n-gpu-layers`	尝试卸载到 GPU 的层数	显存不足时逐步降低
`--ctx-size`	上下文长度	越大越占 KV Cache
`--threads`	CPU 推理线程	不必机械等于全部逻辑线程
`--host`	监听地址	仅本机使用时绑定 `127.0.0.1`
`--port`	服务端口	与调用端配置保持一致

99 表示尽量卸载更多层，并不保证 27B 模型能完整驻留在 8 GB 显存中。最终应以启动日志、生成速度和显存占用为准。

六、验证服务

先检查健康状态：

1	curl http://127.0.0.1:8000/health

再调用 OpenAI 兼容接口：

1
2
3

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"local","messages":[{"role":"user","content":"用三句话解释本地模型的优势"}]}'

如果其他 Agent 能调用接口但返回异常，优先检查模型的 chat template、上下文预算与请求格式，而不是只调整温度。