llama.cpp Local Test Stack

这个仓库是一个本地 llama.cpp 部署与测试示例，包含两部分：

• 服务端：用 Docker 启动 llama.cpp 模型服务
• 客户端：用 scallions 发起 chat 和 image 两类测试请求

如果你是第一次接触这个项目，建议直接按下面的步骤顺序执行。

先看结果

你最终会得到两个可运行命令：

make chat
make image

它们分别用于：

• make chat: 发起一次文本流式对话测试
• make image: 发起一次多图并发结构化提取测试

---

Step 1. 确认机器是否满足要求

1.1 硬件要求

按当前仓库配置，建议满足以下条件：

项目	要求	说明
GPU 架构	>= sm_75	当前配置默认尽量把模型层放到 GPU 上执行
显存	约 20 GB	基于当前模型和当前参数的实测占用推导
系统内存	>= 2 GB	主要用于容器进程和 prompt cache

这些要求是本仓库当前配置下的部署建议，不是 llama.cpp 的通用最低要求。

参考：

• NVIDIA CUDA GPU 计算能力表: https://developer.nvidia.com/cuda-gpus

1.2 驱动和 CUDA

建议环境：

项目	要求
NVIDIA Driver	已正确安装并可正常工作
CUDA Runtime	已正确安装并可正常工作

当前仓库验证通过的环境：

项目	版本
NVIDIA Driver	580.126.09
CUDA Version	13.0

1.3 软件要求

需要先安装以下软件：

软件	用途	参考
Docker	启动 llama.cpp 服务容器	https://docs.docker.com/
Docker Compose	编排和启动容器	https://github.com/docker/compose
uv	管理 Python 环境与运行客户端	https://github.com/astral-sh/uv

当前仓库验证通过的版本：

软件	版本
Docker	29.1.3
Docker Compose	v5.0.0
uv	0.9.18

---

Step 2. 准备配置文件

这个仓库只有一个配置入口：根目录 .env。

先复制模板：

cp .env.example .env

然后编辑 .env。

示例：

MODEL_NAME=Qwen3.6-35B-A3B-APEX-I-Compact.gguf
VISION_MODEL_NAME=mmproj-F16.gguf
LLAMA_CPP_SERVER_HOST=127.0.0.1
LLAMA_CPP_SERVER_PORT=34011

变量说明：

变量名	作用
MODEL_NAME	主模型文件名
VISION_MODEL_NAME	多模态 projector 文件名
LLAMA_CPP_SERVER_HOST	服务监听地址
LLAMA_CPP_SERVER_PORT	服务监听端口

---

Step 3. 下载模型文件

模型文件统一放在 llamacpp-deploy/models。

3.1 下载主模型

目标文件：

llamacpp-deploy/models/Qwen3.6-35B-A3B-APEX-I-Compact.gguf

命令：

uvx modelscope download \
  --model mudler/Qwen3.6-35B-A3B-APEX-GGUF \
  Qwen3.6-35B-A3B-APEX-I-Compact.gguf \
  --local_dir llamacpp-deploy/models

3.2 下载多模态投影模型

目标文件：

llamacpp-deploy/models/mmproj-F16.gguf

命令：

uvx modelscope download \
  --model mudler/Qwen3.6-35B-A3B-APEX-GGUF \
  mmproj-F16.gguf \
  --local_dir llamacpp-deploy/models

说明：

• MODEL_NAME 对应主模型
• VISION_MODEL_NAME 对应多模态投影模型（多模态场景必须同时具备投影模型）

---

Step 4. 同步 Python 依赖

执行：

make sync

这个命令会进入 scallions/ 子项目并执行 uv sync，用于准备客户端依赖。

---

Step 5. 启动服务

执行：

make up

查看日志：

make logs

停止服务：

make down

---

Step 6. 发起测试调用

6.1 文本对话测试

直接运行：

make chat

自定义 prompt：

make chat ARGS='--prompt "你好"'

6.2 多图并发测试

测试图片目录：

scallions/images

直接运行：

make image

自定义并发数：

make image ARGS='--concurrency 2'

说明：

• 默认并发数是 2
• 图片数量必须不少于并发数

---

Step 7. 如果你想直接用 uv 运行

scallions 是一个独立的 uv Python 项目，定义位于 scallions/pyproject.toml。

文本测试：

uv run --project scallions python -m scallions.cli chat
uv run --project scallions python -m scallions.cli chat --prompt "你好"

图片测试：

uv run --project scallions python -m scallions.cli image
uv run --project scallions python -m scallions.cli image --concurrency 2

---

Step 8. 理解 llama.cpp 服务启动参数

服务配置位于 llamacpp-deploy/docker-compose.yml。

当前 llama-server 的核心启动参数如下：

command:
  - -m
  - "/models/${MODEL_NAME}"
  - --mmproj
  - "/models/${VISION_MODEL_NAME}"
  - --port
  - "8080"
  - --host
  - "0.0.0.0"
  - --n-gpu-layers
  - "auto"
  - --alias
  - "${MODEL_NAME}"
  - --metrics
  - --ctx-size
  - "32768"
  - --parallel
  - "2"
  - --reasoning-budget
  - "9830"
  - --reasoning-budget-message
  - " ... reasoning budget exceeded, need to answer.\n"
  - --cache-ram
  - "2048"

参数说明：

参数	作用	为什么这样填
-m "/models/${MODEL_NAME}"	指定主模型文件	主模型从挂载进容器的 /models 目录读取
--mmproj "/models/${VISION_MODEL_NAME}"	指定多模态投影模型	image 场景需要视觉投影模型
--port "8080"	指定容器内部服务端口	外部访问端口由 Docker 端口映射负责
--host "0.0.0.0"	监听容器内所有网卡地址	否则外部无法通过端口映射访问
-ngl "99"	尽可能把模型层放到 GPU	目标是尽量全量上 GPU，减少 CPU 回退
--alias "${MODEL_NAME}"	指定模型别名	与客户端请求里的 model 名称保持一致
--metrics	开启指标输出	便于观察服务状态和性能
--ctx-size "32768"	总上下文长度	在当前显存条件下兼顾长上下文和可运行性
--parallel "2"	并发 slot 数	支撑双并发测试，最大化sm_75的输出性能
--reasoning-budget "9830"	reasoning token 预算	按每个 slot 上下文的约 60% 计算 ，按需调整， 避免 qwen 系列模型思考溢出全部上下文空间
--reasoning-budget-message " ... reasoning budget exceeded, need to answer.\n"	reasoning 预算耗尽时注入提示语	尽量让模型从思考切换到回答
--cache-ram "2048"	prompt cache 的内存上限，单位 MiB	为 cache 预留约 2 GB 内存

--reasoning-budget "9830" 的计算方式：

9830 ≈ (32768 / 2) * 60%

解释：

• 总上下文是 32768
• parallel=2 时，每个 slot 大约可用 16384
• 16384 * 0.6 = 9830.4
• 因此这里取 9830

这样做的目的，是在支持较长 reasoning 的同时，仍然给 system prompt、用户输入、视觉 token 和最终回答保留足够空间。

---