# llama-cpp-tool

**Repository Path**: ddxydbl/llama-cpp-tool

## Basic Information

- **Project Name**: llama-cpp-tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# llama.cpp 推理速度测试工具

一个基于 PyQt5 的 llama.cpp 本地大模型服务器管理和推理速度测试工具。

## 功能特性

### 服务器管理
- ✅ 可视化配置 llama-server 启动参数
- ✅ 支持多 GPU 配置（张量分割）
- ✅ MTP（Multi-Token Prediction）支持
- ✅ 启动前完整命令行预览与编辑
- ✅ 自定义参数输入框
- ✅ 预设配置（平衡/速度/内存模式）
- ✅ 配置持久化（自动保存上次设置）

### 推理测试
- ✅ 自定义测试提示词
- ✅ 多次重复测试取平均值
- ✅ 详细性能统计（Tokens/s、延迟等）
- ✅ 测试历史记录管理
- ✅ 结果导出

### 日志管理
- ✅ 实时服务器日志显示
- ✅ 自动保存日志文件
- ✅ 日志文件管理（打开目录、查看当前日志）
- ✅ 日志搜索功能

## 技术栈

- **语言**: Python 3.8+
- **框架**: PyQt5
- **后端**: llama.cpp (llama-server)

## 快速开始

### 环境要求

1. Python 3.8 或更高版本
2. llama.cpp 已编译，且 `llama-server.exe` 可用
3. NVIDIA GPU（推荐，支持 CUDA）

### 安装依赖

```bash
pip install -r requirements.txt
```

### 运行程序

```bash
python main.py
```

### 首次配置

1. **基础配置**
   - 设置 `llama-server.exe` 路径
   - 设置模型文件路径（.gguf 格式）
   - 设置端口（默认 8080）

2. **GPU配置**
   - 设置 GPU 数量
   - 配置张量分割比例（如 `5,2`）
   - 设置 GPU 层数（ngl）

3. **启动服务器**
   - 点击"启动服务器"按钮
   - 在预览对话框中核对命令行参数
   - 确认后启动

## 参数说明

### 基础参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| llama-server路径 | llama-server 可执行文件路径 | - |
| 模型文件路径 | GGUF 格式模型文件路径 | - |
| 端口 | 服务器监听端口 | 8080 |

### GPU配置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| GPU数量 | 使用的 GPU 数量 | 2 |
| 张量分割 | 每层在不同 GPU 上的分配比例 | 5,2 |
| GPU层数(ngl) | 卸载到 GPU 的层数，999 表示全部 | 99 |
| 启用-ngl | 是否在命令行中包含 -ngl 参数 | 启用 |

### 性能参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| 批处理大小(batch) | 影响吞吐量 | 512 |
| 统一批处理(ubatch) | KV 缓存管理 | 512 |
| CPU线程数(threads) | CPU 核心数 | 16 |
| Flash Attention | 启用 Flash Attention 优化 | 启用 |
| KV缓存键类型(ctk) | f16/q8_0 等 | q8_0 |
| KV缓存值类型(ctv) | f16/q8_0 等 | q8_0 |
| 上下文窗口(context) | 最大上下文长度 | 4096 |
| 并行请求数(parallel) | 支持的并发请求数 | 1 |

### 高级选项

| 参数 | 说明 | 默认值 |
|------|------|--------|
| 禁用日志(log_disable) | 减少 I/O 开销 | 禁用 |
| 内存映射(mmap) | 减少内存占用 | 启用 |
| 温度(temperature) | 推理温度 | 0.7 |
| MTP | 启用多 Token 预测 | 禁用 |
| MTP推测token数 | 每次推测最大 token 数 | 2 |
| 缓存复用大小(cache_reuse) | KV 缓存复用 | 0 |

### 自定义参数

在"自定义启动参数"输入框中可以添加额外的 llama-server 参数，例如：

```
--spec-draft-p-min 0.75 --kv-unified --fit off
```

## 使用示例

### 启动服务器

1. 在"配置与启动"标签页设置参数
2. 点击"启动服务器"
3. 在弹出的预览对话框中核对命令行
4. 点击"确认启动"

### 运行推理测试

1. 确保服务器已启动
2. 切换到"测试执行"标签页
3. 设置测试提示词和重复次数
4. 点击"开始测试"
5. 查看测试结果

### 查看服务器日志

1. 切换到"服务器日志"标签页
2. 实时查看服务器输出
3. 使用搜索功能查找关键信息

## 预设配置

程序提供三种预设配置：

- **平衡**: 均衡性能和显存占用，适合日常使用
- **速度**: 优先速度，使用更多显存
- **内存**: 优先显存节省，适合显存受限场景

## 配置文件

配置文件 `app_config.json` 会自动保存在程序目录下，记录上次使用的参数设置。

## 日志文件

服务器日志自动保存在 `server_logs/` 目录下，命名格式为 `server_YYYYMMDD_HHMMSS.log`。

## llama.cpp 安装指南

本工具需要配合 llama.cpp 使用。以下是安装步骤：

### 下载预编译版本（推荐）

访问 [llama.cpp GitHub Releases](https://github.com/ggml-org/llama.cpp/releases) 下载适合您系统的预编译版本：

| 版本类型 | 说明 |
|----------|------|
| `llama-bin-win-cuda-*-x64.zip` | Windows + CUDA 支持（推荐，需 NVIDIA GPU） |
| `llama-bin-win-x64.zip` | Windows 纯 CPU 版本 |
| `llama-bin-linux-cuda-*-x64.tar.xz` | Linux + CUDA 支持 |

### 编译源码版本

```bash
# 克隆仓库
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# Windows + CUDA 编译
mkdir build && cd build
cmake .. -DLLAMA_CUDA=ON
cmake --build . --config Release

# 编译完成后，llama-server.exe 位于 bin/Release/ 目录下
```

### 版本要求

- **最低版本**: b9821（2026年更新）
- **推荐版本**: 最新稳定版
- **CUDA 版本**: 12.0+（如使用 GPU 加速）

### 启用功能

确保编译时启用以下特性：
- ✅ CUDA 加速支持 (`-DLLAMA_CUDA=ON`)
- ✅ Flash Attention (`-DLLAMA_FLASH_ATTN=ON`)
- ✅ MTP（Multi-Token Prediction）
- ✅ 多 GPU 支持

### 配置路径

运行本工具时，在"llama-server路径"中设置为：
- 例如：`H:\llama.cpp\llama-server.exe`

## 项目结构

```
llama-cpp-tool/
├── main.py                  # 主程序文件
├── app_config.json          # 应用配置（自动生成）
├── server_logs/             # 服务器日志目录
├── reports/                 # 测试报告目录
├── test_history/            # 测试历史目录
├── requirements.txt         # Python 依赖
├── .gitignore               # Git 忽略文件
└── README.md                # 项目说明文档
```

## 许可证

MIT License