llama.cpp 本地部署完全指南

适用读者： 技术极客 / AI Agent / 想复刻的同道中人

本文目标： 从零开始，在本地 GPU 环境完成 llama.cpp 编译、模型部署、验证对比、Agent 接入的完整链路。

注释说明： 本文中有两类特殊注释，分别服务不同读者：

📖 给人看： 帮助理解背景、为什么这样做、额外的细节

🤖 {AGENT} 给 Agent 看： 精确的复刻指令、检查点、避免踩坑的关键信息

环境信息

🤖 {AGENT} 以下为本文所有操作的基准环境，复刻时需逐项确认。

类别	项目	版本/参数
系统	OS	Ubuntu 22.04.5 LTS (WSL2)
	内核	6.6.87.2-microsoft-standard-WSL2
CPU	型号	AMD Ryzen 7 8845H (6C/12T, Zen 4, AVX-512)
GPU	型号	NVIDIA GeForce RTX 4060 Laptop GPU
	显存	8 GB GDDR6
	CUDA	12.1 (Toolkit), 13.1 (Driver)
	驱动	591.74
内存	总量	30 GB (~28 GB 可用)
磁盘	可用	~870 GB
编译工具	gcc/g++	11.4.0
	cmake	3.22.1
	make	4.3
核心软件	llama.cpp	b9859 (2026-06 构建)
	OpenClaw	2026.6.11

第一章安装配置手册

📖 给人看：本章是纯操作指南，按顺序执行即可完成全部部署。每一步只给出最终方案和选择依据，问题的排查细节见第二章。

1.1 环境准备

1.1.1 检查硬件

🤖 {AGENT} 执行以下命令确认 GPU 可用：

bash 复制代码

# 检查 NVIDIA 驱动和 CUDA
nvidia-smi

# 检查 CUDA 编译器
nvcc --version

预期输出：

nvidia-smi 应显示 GPU 型号、驱动版本、CUDA 版本
nvcc --version 应显示 CUDA 编译工具版本

📖 给人看：如果 nvidia-smi 报错 "command not found"，说明没有安装 NVIDIA 驱动，需要先安装驱动和 CUDA Toolkit。WSL2 下可直接使用 Windows 侧的 GPU 驱动。

1.1.2 检查编译依赖

bash 复制代码

gcc --version      # 需要 >= 8.0
cmake --version    # 需要 >= 3.14
make --version

🤖 {AGENT} 如果缺少工具，安装：

bash 复制代码

sudo apt update
sudo apt install -y build-essential cmake git

1.1.3 创建工作目录

bash 复制代码

mkdir -p ~/workspace/projects/local-llm/{llamacpp,models}

🤖 {AGENT} 本文后续所有路径以此为基准。如使用不同路径，全局替换。

1.2 编译 llama.cpp（CUDA 后端）

1.2.1 获取源码

bash 复制代码

cd ~/workspace/projects/local-llm/llamacpp
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

📖 给人看：如果 GitHub 访问慢，可以使用镜像或下载 release 包。我们用的是 b9859 版本。

1.2.2 CMake 配置

bash 复制代码

mkdir -p build && cd build

cmake .. \
  -DGGML_CUDA=ON \
  -DCMAKE_CUDA_ARCHITECTURES="89" \
  -DGGML_CUDA_F16=ON

参数说明：

参数	值	说明
`GGML_CUDA`	ON	启用 CUDA 后端
`CMAKE_CUDA_ARCHITECTURES`	89	RTX 4060 的 CUDA 计算能力
`GGML_CUDA_F16`	ON	启用 FP16 加速

📖 给人看：RTX 40 系列显卡的计算能力为 8.9（对应 89）。如果不确定自己显卡的架构版本，可以参考 NVIDIA CUDA GPUs 列表。常见的：RTX 30 系列 = 86，RTX 20 系列 = 75，GTX 16 系列 = 75。

🤖 {AGENT} 如果编译目标不是 RTX 4060，请根据目标 GPU 的 Compute Capability 修改 CMAKE_CUDA_ARCHITECTURES。如果同时需要兼容多种 GPU（比如要在不同机器上跑），可以设为 "75;86;89"，但编译时间会更长。

1.2.3 编译

bash 复制代码

make -j$(nproc)

-j$(nproc) 使用全部 CPU 核心并行编译。6C/12T 的机器约 3-5 分钟完成。

1.2.4 验证编译结果

bash 复制代码

./bin/llama-cli --version

🤖 {AGENT} 预期输出应包含 CUDA 相关信息。如果编译的二进制不包含 CUDA 支持，检查 cmake 输出中是否有 GGML_CUDA=ON 字样。

1.3 下载模型

1.3.1 选择模型来源：魔搭社区（ModelScope）

📖 给人看：HuggingFace 在国内经常超时或被墙，魔搭社区（modelscope.cn）是阿里维护的国内镜像，下载稳定且速度快。两个平台上有同一批 GGUF 模型。

🤖 {AGENT} 不要在本文所述的任何步骤中使用 HuggingFace 下载模型，全部走 ModelScope。如果发现某个模型只在 HF 上有，先确认 ModelScope 是否有同步。

1.3.2 安装下载工具

bash 复制代码

pip install modelscope

1.3.3 下载推荐模型

主力模型：Qwen3-8B Q4_K_M

bash 复制代码

python3 -c "
from modelscope import snapshot_download
snapshot_download(
    'Qwen/Qwen3-8B-GGUF',
    local_dir='~/workspace/projects/local-llm/models/Qwen3-8B',
    allow_patterns=['*q4_k_m*']
)
"

模型信息：

项目	值
参数量	8B
量化	Q4_K_M
文件大小	~4.68 GB
显存占用	~2 GB（含 KV Cache ~6.2 GB 空闲）
魔搭 ID	`Qwen/Qwen3-8B-GGUF`

📖 给人看：Q4_K_M 是 llama.cpp 推荐的标准量化格式，质量和速度最均衡。Q4_0/Q4_1 质量略低，Q5_K_M 质量略高但模型更大，Q2_K/IQ2 太小质量差、Q6_K/Q8_0 太大显存吃紧------Q4_K_M 是甜点。

编码专项模型：Qwen2.5-Coder-7B Q4_K_M

bash 复制代码

python3 -c "
from modelscope import snapshot_download
snapshot_download(
    'Qwen/Qwen2.5-Coder-7B-Instruct-GGUF',
    local_dir='~/workspace/projects/local-llm/models/Coder-7B',
    allow_patterns=['*q4_k_m*']
)
"

项目	值
参数量	7B
量化	Q4_K_M
文件大小	~4.36 GB
魔搭 ID	`Qwen/Qwen2.5-Coder-7B-Instruct-GGUF`

1.3.4 验证下载

bash 复制代码

ls -lh ~/workspace/projects/local-llm/models/Qwen3-8B/*.gguf
ls -lh ~/workspace/projects/local-llm/models/Coder-7B/*.gguf

🤖 {AGENT} 确认文件大小与预期一致。如果文件太小（几百 MB），可能是下载中断，需要重新下载。

1.4 启动模型并验证

1.4.1 启动 llama-server

bash 复制代码

~/workspace/projects/local-llm/llamacpp/llama.cpp/build/bin/llama-server \
  -m ~/workspace/projects/local-llm/models/Qwen3-8B/Qwen3-8B-Q4_K_M.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  --gpu-layers 99 \
  --ctx-size 32768 \
  --threads 6

参数说明：

参数	值	说明
`-m`	模型路径	指向 GGUF 文件
`--host`	127.0.0.1	仅本地访问
`--port`	8080	HTTP API 端口
`--gpu-layers`	99	全部层加载到 GPU（7-8B 模型 8GB 显存完全够）
`--ctx-size`	32768	32K 上下文窗口
`--threads`	6	CPU 线程数（6C/12T 留一半给系统）

📖 给人看：--gpu-layers 99 是一个技巧------直接设一个比实际层数大的值，llama.cpp 会自动把所有层加载到 GPU。实际 Qwen3-8B 只有 32 层，但写 99 可以一劳永逸，换模型也不用改。

🤖 {AGENT} 启动 llama-server 前，务必确认没有残留进程占用 8080 端口。详见第二章问题 1。

1.4.2 验证服务启动

bash 复制代码

# 检查健康端点
curl http://127.0.0.1:8080/v1/models

# 检查端口监听
ss -tlnp | grep 8080

🤖 {AGENT} 预期：/v1/models 返回包含模型信息的 JSON；ss 显示 127.0.0.1:8080 在 LISTEN。

1.4.3 冒烟测试

bash 复制代码

curl http://127.0.0.1:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "你好，请用一句话介绍你自己。",
    "max_tokens": 100,
    "temperature": 0.7
  }'

预期：返回包含中文回复的 JSON，choices[0].text 有内容。

🤖 {AGENT} 如果返回空或报错，不要直接调参数。先检查 llama-server 终端的日志输出。

1.4.4 性能基准

bash 复制代码

# 测试推理速度（非交互模式）
~/workspace/projects/local-llm/llamacpp/llama.cpp/build/bin/llama-cli \
  -m ~/workspace/projects/local-llm/models/Qwen3-8B/Qwen3-8B-Q4_K_M.gguf \
  --gpu-layers 99 \
  --ctx-size 8192 \
  --temp 0.7 \
  --threads 6 \
  -p "解释一下什么是机器学习" \
  -n 200

🤖 {AGENT} 查看输出末尾的性能统计，记录 prompt eval time（t/s）和 eval time（t/s）。预期 Qwen3-8B：~1700-1800 t/s prompt，~35 t/s generation。

1.5 模型对比验证

1.5.1 验证维度设计

为量化对比两个模型的真实能力，设计 5 个维度共 20 道题：

维度	权重	题数	考察内容
代码能力	25%	5	函数实现、代码审查、Bug 定位、SQL、方案设计
中文能力	20%	4	俗语理解、文案生成、中英混合、长文总结
指令跟随	25%	5	Markdown/JSON 格式、角色扮演、多步指令、否定约束
推理能力	20%	4	逻辑推理、数学计算、类比推理、反事实推理
文本质量	10%	2	风格连贯、专业准确性

📖 给人看：完整的 20 道测试用例见第五章附件。评分标准 1-5 分制，两模型统一参数运行。

1.5.2 验证结果

两模型分别在 RTX 4060 8GB 上，统一 --gpu-layers 99 --ctx-size 8192 --temp 0.7 --threads 6 参数下跑完 20 题。

性能对比：

指标	Qwen3-8B	Qwen2.5-Coder-7B
模型大小	4.68 GB	4.36 GB
Prompt 处理	1,787 t/s	1,939 t/s
Token 生成	35.64 t/s	38.22 t/s
显存占用	~2 GB	~1.8 GB

能力对比：

维度	Qwen3-8B	Coder-7B	满分
代码能力	18	20	25
中文能力	20	16	20
指令跟随	19	21	25
推理能力	19	16	20
文本质量	9	9	10
总分	85	82	100

1.5.3 结论与推荐

场景	推荐模型	理由
日常对话/调研	Qwen3-8B	中文最强、回答详尽、推理链可解释
编码/审查	Qwen2.5-Coder-7B	Bug 定位精准、SQL 质量高、输出简洁
Agent 工作	Qwen3-8B	指令跟随均衡、综合能力最强
资源敏感	Coder-7B	小 7%、快 7%、省显存

最终方案：Qwen3-8B 为主力，Coder-7B 为编码专项，两模型可按场景切换。

1.6 接入 OpenClaw Agent

1.6.1 配置 OpenClaw Gateway

编辑 ~/.openclaw/openclaw.json，在 models.providers 中添加 llamacpp 提供者：

json 复制代码

{
  "models": {
    "mode": "merge",
    "providers": {
      "llamacpp": {
        "baseUrl": "http://127.0.0.1:8080/v1",
        "apiKey": "llamacpp-local",
        "api": "openai-completions",
        "timeoutSeconds": 300,
        "localService": {
          "command": "/home/dav/.openclaw/workspace/projects/local-llm/llamacpp/llama.cpp/build/bin/llama-server",
          "args": [
            "-m", "/home/dav/.openclaw/workspace/projects/local-llm/models/Qwen3-8B-Q4_K_M.gguf",
            "--host", "127.0.0.1",
            "--port", "8080",
            "--gpu-layers", "99",
            "--ctx-size", "32768",
            "--threads", "6"
          ],
          "cwd": "/home/dav/.openclaw/workspace/projects/local-llm",
          "healthUrl": "http://127.0.0.1:8080/v1/models",
          "readyTimeoutMs": 180000,
          "idleStopMs": 0
        },
        "models": [
          {
            "id": "qwen3-8b",
            "name": "Qwen3-8B Q4_K_M (Local GPU)",
            "reasoning": true,
            "input": ["text"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 32768,
            "maxTokens": 8192,
            "compat": {"thinkingFormat": "qwen"},
            "api": "openai-completions"
          }
        ]
      }
    }
  }
}

🤖 {AGENT} 路径中包含 /home/dav/ 的部分需要修改为目标机器的实际用户目录。

同时确保 Agent 配置中也引用了该模型：

json 复制代码

{
  "agents": {
    "defaults": {
      "models": {
        "llamacpp/qwen3-8b": {"alias": "Qwen3 Local"}
      }
    },
    "list": [
      {
        "id": "long",
        "name": "Long",
        "model": "llamacpp/qwen3-8b"
      }
    ]
  }
}

1.6.2 重启 Gateway

bash 复制代码

openclaw gateway restart

1.6.3 验证 Agent 连接

重启后，在 OpenClaw 会话中切换模型到 llamacpp/qwen3-8b，发送测试消息，确认能正常回复。

🤖 {AGENT} 验证项：

llama-server 是否被 Gateway 自动拉起（ps aux | grep llama-server）

模型响应是否正常返回

推理速度是否在预期范围（35-38 t/s）

如果 localService 的 idleStopMs 设为 0，llama-server 会保持运行不会自动退出。

第二章可能遇到的问题处理

本章逐个拆解搭建过程中实际遇到的问题，包括现象、判断、分析和处理方案。

问题 1：llama-server 端口被占用

现象

复制代码

Failed to bind to 127.0.0.1:8080
Address already in use

或启动 llama-server 后 curl 测试返回异常内容（连到了旧进程）。

判断

bash 复制代码

# 查看 8080 端口占用
ss -tlnp | grep 8080

# 查看 llama-server 进程
ps aux | grep llama-server

分析

最常见的原因是上一次测试后忘记关闭 llama-server。llama.cpp 的 server 模式不会自动退出，即使终端关了，后台进程还在。

另外一种情况是 openclaw gateway 配置了 localService 自动拉起，但手动也起了一个，导致冲突。

处理方案

bash 复制代码

# 精准杀掉 llama-server
pkill -f llama-server

# 或指定端口杀掉
fuser -k 8080/tcp

# 验证端口已释放
ss -tlnp | grep 8080   # 应该无输出

📖 给人看：养成习惯------每次测试前先 pkill -f llama-server，或者在启动脚本里加一个 kill 前置步骤。这个坑踩了不止一次。
🤖 {AGENT} 你的执行流程中，启动 llama-server 之前必须先执行 pkill -f llama-server || true。|| true 确保即使没有进程也不会报错退出。

问题 2：HuggingFace 下载超时/被墙

现象

python 复制代码

# 使用 huggingface_hub 下载时
ConnectionError: (MaxRetryError(...), ...)
# 或
ReadTimeout: HTTPSConnectionPool(host='huggingface.co', port=443)

判断

连续 3 次以上超时即确认不是偶发网络波动。

分析

HuggingFace 从国内直连经常不稳定，且没有中国大陆 CDN 节点。部分 ISP 甚至会直接阻断。这是已知的长期问题。

处理方案

使用魔搭社区（ModelScope）作为替代。

python 复制代码

# ✅ 使用 ModelScope（国内可用，速度快）
from modelscope import snapshot_download
snapshot_download('Qwen/Qwen3-8B-GGUF', local_dir='./models')

# ❌ 避免使用 HuggingFace
# from huggingface_hub import snapshot_download
# snapshot_download('Qwen/Qwen3-8B-GGUF')

📖 给人看：ModelScope 是阿里维护的模型社区，与 HuggingFace 共享大量模型。大部分主流模型的 GGUF 文件都有同步。如果某个模型只在 HF 有，优先找替代方案而非硬着头皮翻墙。
🤖 {AGENT} 所有模型下载一律走 ModelScope。不要尝试 HuggingFace。如果 ModelScope 上没有对应的 GGUF 文件，报告给用户并询问替代方案，不要自行尝试翻墙下载。

问题 3：cmake 找不到 CUDA Toolkit

现象

复制代码

CMake Error: Could NOT find CUDAToolkit (missing: CUDAToolkit_INCLUDE_DIR)

判断

bash 复制代码

# 检查 CUDA Toolkit 是否完整安装
nvcc --version
ls /usr/local/cuda

分析

NVIDIA 驱动安装不等于 CUDA Toolkit 安装。驱动提供了运行时库，但编译需要头文件和 nvcc 编译器。在 WSL2 下尤其容易遗漏------Windows 侧的驱动被 WSL2 借用，但 CUDA Toolkit 需要在 WSL2 内部单独安装。

处理方案

bash 复制代码

# WSL2 Ubuntu 安装 CUDA Toolkit 12.x
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda-repo-wsl-ubuntu-12-1-local_12.1.0-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-12-1-local_12.1.0-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-12-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt update
sudo apt install -y cuda-toolkit-12-1

如果只是 nvcc 不在 PATH 中，加环境变量即可：

bash 复制代码

export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

🤖 {AGENT} 安装 CUDA Toolkit 后，务必重新运行 cmake（清掉 build 目录），否则缓存的 CMakeCache 会继续报错。

问题 4：模型加载时显存不足（OOM）

现象

复制代码

CUDA error: out of memory
ggml_cuda_set_main_device: failed to allocate ...

判断

bash 复制代码

# 查看显存状况
nvidia-smi

分析

8GB 显存跑 Q4_K_M 量化的 7-8B 模型（4-5GB）是完全够用的。出现 OOM 通常是以下原因：

有其他进程占用了显存（如另一个 llama-server 实例、Chrome GPU 加速、Jupyter 等）
上下文窗口设得太大，KV Cache 把剩余显存吃完了
量化级别太高（Q6_K 以上），模型本身就占 6-7GB，KV Cache 没空间了

处理方案

bash 复制代码

# 1. 清掉所有 GPU 进程
pkill -f llama-server
# 等几秒让显存释放
sleep 3

# 2. 确认显存空闲
nvidia-smi | grep MiB

# 3. 如果还是不够，降低 ctx-size
~/path/to/llama-server \
  -m model.gguf \
  --gpu-layers 99 \
  --ctx-size 8192 \    # 从 32768 降到 8192
  --threads 6

# 4. 极端情况：部分层走 CPU
  --gpu-layers 20 \    # 只把前 20 层放 GPU

📖 给人看：KV Cache 大小 ≈ ctx_size × n_layers × n_kv_heads × head_dim × 2（K+V）× 2 bytes（FP16）。32K 上下文 + 8B 模型 ≈ 2-3GB，加上模型 4-5GB，总共 6-8GB------这正是 8GB 显存的极限。如果你同时开着 Chrome 并且开了 GPU 加速，可能就差这几百 MB。

问题 5：模型响应速度异常慢

现象

Token 生成速度 < 5 t/s（正常 35-38 t/s）
首个 token 延迟数秒以上
启动就报 "BLAS=0" 或 "ggml_cuda" 未出现

判断

bash 复制代码

# 检查 llama.cpp 是否用了 CUDA
~/path/to/llama-cli --version 2>&1 | grep -i cuda

# 启动时观察日志是否出现 "ggml_cuda"

分析

最常见的原因是编译时 CUDA 没启用。cmake 阶段如果没检测到 CUDA Toolkit，会静默回退到 CPU-only 模式。CPU 模式的 token 生成速度通常是 5-10 t/s，明显比 GPU 慢。

另一个可能原因是模型太大，--gpu-layers 设少了，大部分层走 CPU，变成混合推理（也慢）。

处理方案

bash 复制代码

# 1. 确认编译时 CUDA 开启
cd ~/workspace/projects/local-llm/llamacpp/llama.cpp/build
cmake .. -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="89"
# 观察输出：应显示 "GGML_CUDA: ON"
make -j$(nproc)

# 2. 确认运行参数
llama-cli --gpu-layers 999  # 全部层上 GPU

# 3. 观察运行时日志
# 应出现类似：ggml_cuda_set_main_device: using device 0 (NVIDIA GeForce RTX 4060)

问题 6：验证测试中模型超时无输出

现象

运行验证脚本时，某些测试用例超时（30s+ 无输出），curl 连接被 shell timeout 命令杀死。

判断

检查是哪些题目超时、哪个模型：

Qwen3-8B：测试 3.4（多步指令）超时
Coder-7B：测试 1.1（简单函数）和 4.4（反事实推理）超时

分析

两个模型的超时原因不同：

Qwen3-8B： 该模型默认开启思考链（thinking），某些简单问题也会走完整的推理过程再输出。测试 3.4（多步指令）触发了一个特别长的思考链，在 40 秒内没有完成。不只是"慢"------是思考链本身让输出变得冗长。

Coder-7B： 部分题目完全无输出，不是因为慢，而是模型针对某些 prompt 格式没有正确处理。可能是 prompt 格式与 Coder 的对话模板不完全匹配。

处理方案

对于 Qwen3：

bash 复制代码

# 方案1：通过 prompt 关闭思考链
# 在 system prompt 中添加：/think off

# 方案2：在 OpenClaw 中使用时，利用 compat.thinkingFormat 控制

对于 Coder：

确保使用正确的 chat template 格式
简单回文函数这类题，Coder 有时直接跳过（可能认为太简单？），测试脚本需要做好超时处理和重试

🤖 {AGENT} 验证脚本中的超时时间应设 60s（而非 30s），并添加 shell timeout + curl --max-time 双重保险。对于无输出的情况，记录为 1 分（最低）。

问题 7：模型输出混入杂讯

现象

模型的 JSON 输出中混入了：

思考链（<thinking>...</thinking> 标记）
Prompt 回显（把用户的问题重复了一遍）
多余的前言后语（"好的，让我来回答你..."）

判断

当测试要求"只输出 JSON"但实际输出包含了其他内容时。

分析

这是本地模型（特别是推理型模型）的常见行为。Qwen3 默认开启 thinking 模式，思考过程会嵌入在输出中。同时，模型的对话模板可能导致它在回答前先"确认"收到的内容。

处理方案

对于 OpenClaw 配置，设置兼容模式：

json 复制代码

{
  "compat": {
    "thinkingFormat": "qwen"
  }
}

在验证脚本中，如果仍然出现混入，添加输出提取逻辑：

python 复制代码

# 提取纯 JSON（去掉 markdown 代码块标记和思考链）
import re
def extract_json(text):
    # 去掉 <thinking>...</thinking>
    text = re.sub(r'<thinking>.*?</thinking>', '', text, flags=re.DOTALL)
    # 提取 ```json ... ```或直接的 {...}
    m = re.search(r'```(?:json)?\s*(\{.*?\})\s*```', text, re.DOTALL)
    if m:
        return m.group(1)
    m = re.search(r'\{.*\}', text, re.DOTALL)
    return m.group(0) if m else text

📖 给人看：这不是 bug，是 feature。Qwen3 的思考链可以让你看到模型的推理过程------有时候 AI 说的"对"不一定是真的对，但推理链可以暴露它哪里想岔了。

问题 8：ModelScope 上找不到某模型的 GGUF 版本

现象

复制代码

# ModelScope 搜索不到 embeddinggemma-300m 的 GGUF 文件
# 或某个模型只有 safetensors 格式，没有 gguf

判断

搜索 modelscope.cn 上的 GGUF 相关仓库，看是否有该模型的 GGUF 版本。

分析

并非所有 HuggingFace 上的 GGUF 模型都会同步到 ModelScope。以下情况较常见：

小众模型（下载量 < 1000）
非 Qwen/Llama/GLM 等主流系列
Embedding 专用模型（如 embeddinggemma）
非常新的模型

处理方案

优先找替代模型------同功能的其他模型在 ModelScope 上很可能有 GGUF
如果确实无法替代------告知用户，由用户决定是否通过其他渠道获取
不要自行翻墙下载

🤖 {AGENT} 这是硬约束。如果在 ModelScope 上搜不到，报告给用户并附上可以替代的选项，不要自己做主去 HF 下载。

第三章参考文档

官方文档

文档	链接	说明
llama.cpp GitHub	https://github.com/ggerganov/llama.cpp	源码、编译指南、API 文档
llama.cpp 量化说明	https://github.com/ggerganov/llama.cpp/discussions/2094	Q4_K_M 等量化格式详解
llama.cpp server 文档	https://github.com/ggerganov/llama.cpp/tree/master/examples/server	llama-server 完整参数
CUDA Installation Guide (WSL)	https://docs.nvidia.com/cuda/wsl-user-guide/	WSL2 下安装 CUDA Toolkit
NVIDIA CUDA GPUs 列表	https://developer.nvidia.com/cuda-gpus	查询显卡 Compute Capability

模型来源

平台	链接	说明
魔搭社区	https://modelscope.cn	国内首选，GGUF 模型齐全
Qwen3-8B GGUF	https://modelscope.cn/models/Qwen/Qwen3-8B-GGUF	主力模型
Qwen2.5-Coder-7B GGUF	https://modelscope.cn/models/Qwen/Qwen2.5-Coder-7B-Instruct-GGUF	编码专项

参考博客/讨论

内容	链接	说明
llama.cpp CUDA 编译指南	https://github.com/ggerganov/llama.cpp/blob/master/docs/build.md	各后端编译参数
OpenClaw 配置文档	https://docs.openclaw.ai	Gateway 配置参考
GGUF 格式说明	https://github.com/ggerganov/ggml/blob/master/docs/gguf.md	模型文件格式

第四章 Tips & 小窍门

Tip 1：快速判断 llama-server 启动参数

思路： 按"硬件约束 → 模型大小 → 使用场景"的顺序确定参数。

复制代码

硬件约束：
  8GB 显存 → Q4_K_M 量化 → --gpu-layers 99（全部）
  16GB+    → Q5_K_M 或 Q6_K → --gpu-layers 99
  
模型大小：
  ≤5GB  → --ctx-size 32768
  5-7GB → --ctx-size 16384（给 KV Cache 留空间）
  7-8GB → --ctx-size 8192

使用场景：
  Agent 长会话 → 大 ctx-size（32768）
  单次问答     → 小 ctx-size（4096-8192，省显存）

📖 给人看：rule of thumb------模型文件 + KV Cache < 显存 × 0.9。留 10% 给框架开销。

Tip 2：验证 llama-server 启动成功的三步法

bash 复制代码

# 第 1 步：进程检查
ps aux | grep llama-server | grep -v grep

# 第 2 步：端口检查
ss -tlnp | grep 8080

# 第 3 步：API 检查
curl -s http://127.0.0.1:8080/v1/models | python3 -m json.tool

三步全过 = 服务正常。

Tip 3：判断模型响应是否在正常范围

指标	正常	异常	操作
Token 速度	30-40 t/s (GPU)	< 5 t/s	检查 CUDA 是否启用
首 token 延迟	0.5-2s	> 10s	检查 GPU 层数/上下文
显存占用	模型 + 2-3GB	接近 8GB	降低 ctx-size
输出质量	连贯、切题	乱码/重复	检查温度参数 (0.7)

Tip 4：OpenClaw 配置验证

修改 openclaw.json 后，验证三步：

bash 复制代码

# 1. JSON 语法检查
python3 -c "import json; json.load(open('/home/dav/.openclaw/openclaw.json')); print('OK')"

# 2. 重启 Gateway
openclaw gateway restart

# 3. 检查是否自动拉起模型
ps aux | grep llama-server

🤖 {AGENT} 如果第 3 步没有 llama-server 进程，检查 localService 配置中的 command 路径是否正确（做 ls 验证）。

Tip 5：故障排除的思维框架

遇到问题时按这个顺序排查：

复制代码

1. 日志优先 --- llama-server 终端输出 / Gateway 日志是最直接的信息源
2. 隔离变量 --- 一次只改一个参数，确认是哪个变量导致的
3. 回到基准 --- 先用最简单的参数跑通，再逐步加功能
4. 进程状态 --- 检查是否有残留进程（pkill → sleep 3 → restart）
5. 硬件监控 --- nvidia-smi 实时观察显存变化

📖 给人看：大多数问题不是"不会"，而是"忘了检查"。上面这个清单能帮你节省 80% 的排障时间。

Tip 6：用 `--gpu-layers 999` 代替精确计数

不需要每次换模型都去查它有多少层。--gpu-layers 999 会自动把所有层加载到 GPU。9/10 的情况下这就是你要的。

什么时候不能用 999？------当模型太大，显存放不下全部层的时候。这时候才需要精确计算。

Tip 7：测试脚本的健壮性设计

模型验证脚本需要考虑：

超时保护 ：shell timeout + curl --max-time 双重保险
重试机制：偶发超时自动重试 1 次
输出清洗：去掉思考链、markdown 标记、prompt 回显
结果保存：每道题跑完立刻写入 JSON，避免中断丢失全部数据

Tip 8：模型下载的断点续传

ModelScope 的 snapshot_download 支持断点续传。如果下载中断，重跑同一个命令即可------已下载的部分不会重新下载。

bash 复制代码

# 重试中断的下载
python3 -c "
from modelscope import snapshot_download
snapshot_download('Qwen/Qwen3-8B-GGUF', local_dir='./models/Qwen3-8B')
"

Tip 9：`--temp 0.7` 是最佳默认值

温度参数影响输出的随机性：

温度	适用场景
0.0 - 0.3	代码生成、数学、需要确定性输出的场景
0.5 - 0.8	通用对话、写作、翻译 ← 0.7 是甜点
0.9 - 1.2	创意写作、头脑风暴

日常 Agent 工作用 0.7，编码时可以临时降到 0.2。

Tip 10：保留 8-10% 的显存余量

不要试图把显存用到 100%。留 8-10% 给 CUDA 上下文切换和碎片管理。当你在 nvidia-smi 中看到 Used > 7.3GB（8GB 显存），就该考虑降 ctx-size 或 gpu-layers 了。

第五章附件

附件 A：Agent 执行清单

🤖 {AGENT} 以下清单用于在新机器上复刻部署。按顺序执行，每步完成后打勾确认。

A.1 前置检查

nvidia-smi 正常输出，显存 ≥ 8GB
nvcc --version 正常，CUDA Toolkit ≥ 12.0
gcc --version ≥ 8.0, cmake --version ≥ 3.14
磁盘可用空间 ≥ 30GB
pip install modelscope 已安装
工作目录 ~/workspace/projects/local-llm/{llamacpp,models} 已创建

A.2 编译 llama.cpp

git clone https://github.com/ggerganov/llama.cpp.git
mkdir build && cd build
cmake 配置：GGML_CUDA=ON, CMAKE_CUDA_ARCHITECTURES 设为目标 GPU 架构
cmake 输出确认 GGML_CUDA: ON
make -j$(nproc) 编译成功（无 error）
./bin/llama-cli --version 正常

A.3 下载模型

Qwen3-8B Q4_K_M 下载完成，文件大小 ≈ 4.68 GB
Qwen2.5-Coder-7B Q4_K_M 下载完成，文件大小 ≈ 4.36 GB
ls -lh 确认文件完整

A.4 冒烟测试

pkill -f llama-server || true 清理残留进程
启动 llama-server（Qwen3-8B, --gpu-layers 99, --ctx-size 32768）
curl /v1/models 返回模型信息
发送测试 prompt 收到正常回复
Token 生成速度 ≥ 30 t/s（GPU 模式）

A.5 接入 OpenClaw

openclaw.json 添加 llamacpp provider 配置
Agent 配置中 long agent 的 model 设为 llamacpp/qwen3-8b
openclaw gateway restart
Gateway 自动拉起 llama-server（ps aux | grep llama-server 有进程）
在 OpenClaw 中使用本地模型正常回复

A.6 可选：跑完整验证

准备验证脚本（20 题，5 维度）
对每个模型跑 20 题
结果写入 JSON，完成对比

附件 B：模型验证结果汇总

Qwen3-8B Q4_K_M

维度	得分	满分	备注
代码能力	18	25	回文函数推理正确但中断(-2)；SQL 未完成(-2)
中文能力	20	20	全面满分，俗语理解深度超越 Coder
指令跟随	19	25	多步指令超时(-3)；Markdown/JSON/角色扮演正常
推理能力	19	20	反事实推理小瑕疵(-1)
文本质量	9	10	连贯性好，风格一致
总计	85	100

Qwen2.5-Coder-7B Q4_K_M

维度	得分	满分	备注
代码能力	20	25	Go 并发竞争直接命中(+1)，SQL 正确完整(+1)；回文函数无输出(-2)
中文能力	16	20	各项均有小瑕疵，俗语理解逊于 Qwen3
指令跟随	21	25	多步指令唯一全对(+2)；JSON 多包了 markdown 标记(-1)
推理能力	16	20	反事实推理超时无输出(-3)；类比解释略浅(-1)
文本质量	9	10	同上
总计	82	100

文档版本： v1.0 | 日期： 2026-07-04

📖 给人看：本文档基于真实搭建经验，所有数据和现象均可复现。如有问题欢迎通过 CSDN 评论区交流。

🤖 {AGENT} 你是本文档的主要使用者之一。执行复刻部署时，严格按照附件 A 的检查清单逐项推进。遇到问题先查第二章，找不到再回头询问。

llama.cpp 本地部署完全指南

环境信息

第一章 安装配置手册

1.1 环境准备

1.1.1 检查硬件

1.1.2 检查编译依赖

1.1.3 创建工作目录

1.2 编译 llama.cpp（CUDA 后端）

1.2.1 获取源码

1.2.2 CMake 配置

1.2.3 编译

1.2.4 验证编译结果

1.3 下载模型

1.3.1 选择模型来源：魔搭社区（ModelScope）

1.3.2 安装下载工具

1.3.3 下载推荐模型

1.3.4 验证下载

1.4 启动模型并验证

1.4.1 启动 llama-server

1.4.2 验证服务启动

1.4.3 冒烟测试

1.4.4 性能基准

1.5 模型对比验证

1.5.1 验证维度设计

1.5.2 验证结果

1.5.3 结论与推荐

1.6 接入 OpenClaw Agent

1.6.1 配置 OpenClaw Gateway

1.6.2 重启 Gateway

1.6.3 验证 Agent 连接

第二章 可能遇到的问题处理

问题 1：llama-server 端口被占用

现象

判断

分析

处理方案

问题 2：HuggingFace 下载超时/被墙

现象

判断

分析

处理方案

问题 3：cmake 找不到 CUDA Toolkit

现象

判断

分析

处理方案

问题 4：模型加载时显存不足（OOM）

现象

判断

分析

处理方案

问题 5：模型响应速度异常慢

现象

判断

分析

处理方案

问题 6：验证测试中模型超时无输出

现象

判断

分析

处理方案

问题 7：模型输出混入杂讯

现象

判断

分析

处理方案

问题 8：ModelScope 上找不到某模型的 GGUF 版本

现象

判断

分析

处理方案

第三章 参考文档

官方文档

模型来源

参考博客/讨论

第四章 Tips & 小窍门

Tip 1：快速判断 llama-server 启动参数

Tip 2：验证 llama-server 启动成功的三步法

Tip 3：判断模型响应是否在正常范围

Tip 4：OpenClaw 配置验证

第一章安装配置手册

第二章可能遇到的问题处理

第三章参考文档

Tip 6：用 `--gpu-layers 999` 代替精确计数

Tip 9：`--temp 0.7` 是最佳默认值

第五章附件