llama.cpp 快速上手指南

在这里插入图片描述

从编译到跑通全流程记录

Qwen3.6-35B-A3B-UDT × GTX 1660 × CUDA 12.8

Windows 10 × i5-12600K × 16GB RAM

2026-07-03

目录

1. 环境概览

1.1 硬件配置在这里插入图片描述

配置项 值
CPU 12th Gen Intel Core i5-12600K (16 线程)
内存 16 GB DDR4
GPU NVIDIA GeForce GTX 1660 (6 GB VRAM)
驱动版本 NVIDIA 591.86
操作系统 Windows 10 (AMD64)
磁盘 D 盘 (llama.cpp 及模型所在)

1.2 软件栈

软件 版本 用途
llama.cpp b9601 推理引擎
CUDA Toolkit 12.8.93 GPU 加速
MSVC 14.44.35207 Windows 编译器
MSYS2 / MinGW GCC 16.1.0 备用编译链
CMake 4.3.4 构建系统
Ninja latest 高效构建

2. 环境准备

2.1 基础软件安装

  • Google Chrome： 浏览器，默认搜索引擎设为必应 (Bing)
  • Node.js： v24.18.0，用于各类前端工具链
  • Git： v2.55.0，版本控制和源码管理
  • OpenClaw： npm install -g openclaw，个人 AI 助手框架
  • MSYS2： 安装至 C:\msys64，配置清华镜像源，安装 ucrt64 工具链：gcc / cmake / make / git
  • CUDA Toolkit 12.8： 通过 winget 安装 Nvidia.CUDA
  • VS 2022 BuildTools： winget 安装后需运行 vs_BuildTools.exe 添加 Microsoft.VisualStudio.Workload.VCTools 工作负载

2.2 国内网络配置

由于部分国际网站无法直连，设置以下镜像：

  • HuggingFace 镜像： 环境变量 HF_ENDPOINT=https://hf-mirror.com
  • GitHub 代理： git config --global url."https://gh.ddlc.top/".insteadOf "https://github.com/"

    • ⚠️ 该代理仅支持 raw 文件和 zip 下载，不支持 git clone smart 协议

  • MSYS2 源： 添加清华镜像 https://mirrors.tuna.tsinghua.edu.cn/msys2/

3. llama.cpp 编译

3.1 获取源码

从官方发行版下载最稳定版本的源码包，本次使用 b9601。解压到 D:\llama.cpp-b9601。

3.2 MinGW 非 CUDA 编译（纯 CPU）

在 MSYS2 UCRT64 环境中执行（没有 GPU 加速，纯 CPU 推理）：

cd /d/llama.cpp-b9601
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DLLAMA_CUDA=OFF
cmake --build . --config Release -j$(nproc)

产物： build\bin，含 92 个可执行文件，其中 llama-server.exe (15 MB)

3.3 MSVC + CUDA 编译

需要先运行 vcvarsall.bat x64 初始化 Visual Studio 环境。必须使用 Ninja 生成器！

cd D:\llama.cpp-b9601
mkdir build_cuda_msvc && cd build_cuda_msvc
cmake .. -G "Ninja" ^
  -DCMAKE_BUILD_TYPE=Release ^
  -DLLAMA_CUDA=ON ^
  -DCMAKE_CUDA_COMPILER="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin\nvcc.exe"
cmake --build . --config Release -j8
关键编译参数说明
参数 说明
LLAMA_CUDA=ON 启用 CUDA GPU 加速
CMAKE_BUILD_TYPE=Release 发布模式优化
Ninja 生成器 避免 VS CUDA 集成问题。CUDA 12.8 未提供 VS 2022 17.14 的集成插件
CMAKE_CUDA_COMPILER 指定 CUDA 编译器路径

产物： build_cuda_msvc\bin，含 llama-server.exe (10 KB 启动器) + 多个 .dll 文件（含 ggml-cuda.dll、cudart64_12.dll、cublas64_12.dll 等）

4. 模型部署

4.1 模型文件

将模型文件放置在 D:\llama.cpp-b9601\models\ 目录下：

文件名 大小 用途
Qwen3.6-35B-A3B-UDT-Q4_K_XL_MTP.gguf 22.0 GB 主模型（MoE 架构，35B 总参/3B 活跃）
mmproj-BF16.gguf 902 MB 多模态投影层

模型规格： Qwen3.6-35B-A3B（MoE 架构，35B 总参数 / 3B 活跃参数），Q4_K_XL 量化，80K 上下文窗口。

4.2 启动脚本

创建 start_server.bat 在 D:\llama.cpp-b9601：

@echo off
title Qwen3.6 Inference Server
cd /d "D:\llama.cpp-b9601"

:: DLL 都在 exe 目录中，PATH 只需最简
set "PATH=D:\llama.cpp-b9601\build_cuda_msvc\bin;%SystemRoot%\system32;%SystemRoot%"

set "SERVER=D:\llama.cpp-b9601\build_cuda_msvc\bin\llama-server.exe"
set "MODEL=D:\llama.cpp-b9601\models\Qwen3.6-35B-A3B-UDT-Q4_K_XL_MTP.gguf"
set "MMPROJ=D:\llama.cpp-b9601\models\mmproj-BF16.gguf"

"%SERVER%" --model "%MODEL%" --mmproj "%MMPROJ%" ^
  --host 0.0.0.0 --port 8080 ^
  --temp 0.6 --top-p 0.95 --top-k 20 ^
  --min-p 0.0 --repeat-penalty 1.0 ^
  --presence-penalty 0.0 ^
  --ctx-size 81920 --n-gpu-layers 999 ^
  --cpu-moe --fit off --no-mmap ^
  --threads 16 --threads-batch 16
启动参数详解
参数 值 说明
--host 0.0.0.0 监听所有网络接口
--port 8080 HTTP API 端口
--temp 0.6 生成温度（越低越确定）
--top-p 0.95 核采样阈值
--top-k 20 Top-K 采样
--repeat-penalty 1.0 重复惩罚（1.0=关闭）
--ctx-size 81920 上下文窗口大小
--n-gpu-layers 999 GPU 层数（全部非 MoE 专家层）
--cpu-moe MoE 专家层在 CPU 上计算
--fit off 关闭自动 n_gpu_layers 适配
--no-mmap 禁用内存映射（改善 CPU offload）
--threads 16 推理线程数
--threads-batch 16 批处理线程数

5. 排坑记录（重点）

以下是本次遇到的所有问题及解决方案，供后续参考。

5.1 cublasLt64_12.dll 缺失 → DLL_NOT_FOUND

现象

STATUS_DLL_NOT_FOUND (0xC0000135)，exe 启动就崩溃，无法输出 --version。

原因

cublas64_12.dll 依赖 cublasLt64_12.dll，但该 DLL 未被复制到编译产物目录。编译 cmake 只自动复制了 cudart64_12.dll 和 cublas64_12.dll，漏掉了 cublasLt64_12.dll。

解决

复制缺失的 DLL：

copy "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin\cublasLt64_12.dll" "D:\llama.cpp-b9601\build_cuda_msvc\bin" /Y
验证
llama-server.exe --version

正确输出：version: 0 (unknown) / built with MSVC 19.44.35228.0 for Windows AMD64

5.2 echo 中的管道符 → 诡异的"CUDA"报错

现象
'CUDA' is not recognized as an internal or external command,
operable program or batch file.

这个错误让排查走了大量弯路——源码、PATH、VS 环境、CUDA 安装都检查了一遍。

原因

在批处理文件的信息输出中使用了类似这样的语句：

echo    CPU+GPU Hybrid | CUDA 12.8 | GTX 1660

CMD 将 | 解释为管道符！ 实际上执行了 echo "CPU+GPU Hybrid"，然后将输出通过管道传给 CUDA 命令，而 CUDA 不是可执行文件，所以报错。

💀 这个问题浪费了最多时间——因为每个人都以为 PATH 或环境有问题，没人会怀疑是 echo 语句的问题。

解决
  • 删除 echo 中的 | 符号，改用逗号或括号替代
  • 或使用 ^ 转义：echo CPU+GPU Hybrid ^| CUDA 12.8
  • 最终版本改用更安全的写法：echo CPU+GPU Hybrid (CUDA 12.8, GTX 1660)

5.3 PATH 缺少 MSYS2 → MinGW 运行时缺失

现象

MinGW 编译的 exe 报 STATUS_DLL_NOT_FOUND（0xC0000135），此前能正常运行的版本突然崩溃。

原因

MSYS2 的 ucrt64\bin 目录不在系统 PATH 中。MinGW 编译的 exe 需要 libgcc_s_seh-1.dll、libstdc++-6.dll、libwinpthread-1.dll 等运行时 DLL。这些 DLL 在 C:\msys64\ucrt64\bin 下，但 PATH 中缺少该路径。

解决

将 MSYS2 的 bin 目录添加到 PATH：

set "PATH=C:\msys64\ucrt64\bin;%PATH%"

5.4 批处理中的 ^ 符号转义

建议

在批处理文件中使用长命令时，要么把所有参数写在一行，要么确保 ^ 后面没有空格或特殊字符。对于复杂参数，推荐使用变量拼接：

set "ARGS=--model %%MODEL%% --host 0.0.0.0 --port 8080"
set "ARGS=%%ARGS%% --temp 0.6 --top-p 0.95"
"%%SERVER%%" %%ARGS%%

5.5 vcvarsall.bat 自动检测 CUDA 的潜在问题

现象

调用 vcvarsall.bat x64 后，它会自动检测 CUDA 安装路径并添加到 PATH 中。如果 CUDA 路径包含特殊字符（如 &），会影响后续命令解析。

解决方案（最终版）

最终的 start_server.bat 完全不依赖 vcvarsall.bat。因为所有必需的 DLL 已经复制到了 exe 所在目录，Windows 加载器会自动搜索该目录。只需将 exe 目录加入 PATH 即可。

6. 启动与验证在这里插入图片描述

6.1 启动服务器

双击 start_server.bat 或桌面快捷方式 Qwen3.6 Server，等待模型加载。首次加载约 30 秒~5 分钟（取决于磁盘速度）。

服务器启动后的典型日志输出：

0.00.045.235 I log_info: verbosity = 3
0.00.273.559 I   - CUDA0   : NVIDIA GeForce GTX 1660 (6143 MiB, 5134 MiB free)
0.00.273.567 I   - CPU     : 12th Gen Intel(R) Core(TM) i5-12600K (16173 MiB)
0.00.292.548 I system_info: n_threads = 16 | CUDA : ARCHS = 750 | ...
0.00.328.954 I srv  llama_server: loading model

6.2 验证 API

打开浏览器访问 http://localhost:8080/health，返回 {"status":"ok"} 表示服务器就绪。

更多验证方式：

  • curl http://localhost:8080/v1/models → 查看已加载模型信息
  • curl -X POST http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d "{...}"

也可双击桌面上的 Qwen3.6 API Test 快捷方式自动运行测试。

6.3 常用端点

端点 方法 说明
/health GET 健康检查
/v1/models GET 列出模型
/v1/chat/completions POST 聊天补全（类 OpenAI API）
/v1/completions POST 文本补全
/v1/embeddings POST 文本嵌入
/infill POST 代码填充（FIM）
/tokenize POST 分词
/detokenize POST 逆分词

7. 总结

本文档记录了在一台 Windows 10 系统（i5-12600K / 16GB RAM / GTX 1660 6GB）上，从零搭建 llama.cpp 推理服务器的全过程。

核心经验

  • 教训 1： 环境变量永远是最先需要排查的——PATH 的微小变化可能导致连锁故障
  • 教训 2： 批处理文件中的特殊字符（|、&、^、% 等）需要格外小心，它们可能在最意想不到的地方引发错误
  • 教训 3： CUDA 依赖链：cublas64_12.dll → cublasLt64_12.dll，漏掉一个就全盘崩溃
  • 教训 4： VS 环境（vcvarsall.bat）不是必须的——只要所有运行时 DLL 就位，MSVC 编译的 exe 也能独立运行
  • 教训 5： 22GB 模型在 16GB 系统上能跑，但首次加载需要较长时间的交换

关键路径总览

源码准备 → MinGW 编译（验证）→ CUDA 安装 → MSVC 编译（主力）
→ DLL 补齐 → 脚本编写 → 模型加载 → API 验证

总耗时： 约 2 天（含环境安装、排坑、编译等待）。

桌面快捷方式

名称 用途
Qwen3.6 Server.lnk 启动服务器
Qwen3.6 Models.lnk 打开模型目录
Qwen3.6 API Test.lnk 运行 API 测试
Logo
亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

avatar 亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

avatar 亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

avatar 亚马逊云科技技术品牌专区