KVSplit 项目启动与配置教程

1. 项目目录结构及介绍

KVSplit 项目是一个针对 Apple Silicon 优化的开源项目，其主要目的是通过不同的量化精度来减少注意力机制中的 KV 缓存内存使用。以下是项目的目录结构及各部分功能的介绍：

kvsplit/
├── llama.cpp/      # 优化后的 llama.cpp 构建
├── models/         # 语言模型文件
├── scripts/        # 实用脚本
│   ├── benchmark_kvsplit.py    # 综合性能基准工具
│   ├── install_kvsplit.sh      # 一键安装脚本
│   ├── quick_compare.py        # 快速比较工具
│   ├── capture_memory.sh       # 内存可视化的 GIF 创建
│   └── visualize_results.py    # 生成出版物质量的图表
├── results/        # 基准测试结果（CSV/JSON）
├── plots/          # 生成的可视化图表
└── README.md       # 项目说明文件

• llama.cpp/ 目录包含了针对 Apple Silicon 优化后的 llama.cpp 源代码。
• models/ 目录包含了用于测试的语言模型文件。
• scripts/ 目录包含了各种脚本，包括安装、性能测试、结果可视化等。
• results/ 目录用于存放基准测试的结果数据。
• plots/ 目录用于存放生成的图表。
• README.md 文件包含了项目的基本信息和说明。

2. 项目的启动文件介绍

项目的启动主要是通过 scripts 目录下的脚本文件来进行的。以下是一些主要的启动文件及其用途：

• install_kvsplit.sh：这是一键安装脚本，用于设置项目结构，克隆并构建支持 Metal 的 llama.cpp，配置量化缓存，以及设置 Python 环境用于可视化。
• quick_compare.py：快速比较工具脚本，用于展示不同配置下的模型性能、内存使用和品质指标。
• benchmark_kvsplit.py：综合性能基准工具脚本，用于进行全面的性能分析和测试。

启动项目时，首先需要执行 install_kvsplit.sh 脚本，然后可以使用 quick_compare.py 或 benchmark_kvsplit.py 来进行性能测试。

# 克隆仓库
git clone https://github.com/dipampaul17/KVSplit.git
cd kvsplit

# 运行安装脚本
chmod +x scripts/install_kvsplit.sh
./scripts/install_kvsplit.sh

3. 项目的配置文件介绍

KVSplit 项目的主要配置是通过命令行参数来完成的。以下是一些关键的命令行参数及其用途：

• -t N：设置线程数，通常设置为与 CPU 核心数相匹配的数值。
• --flash-attn：启用优化的注意力机制。
• --kvq N：设置键和值的量化位数。
• --kvq-key N：仅设置键的量化位数。
• --kvq-val N：仅设置值的量化位数。
• -c N：设置上下文大小，以标记为单位。
• -n N：设置生成的标记数。
• -f FILE：指定输入文件，用于处理文档。
• -m MODEL：指定模型路径，指向 .gguf 模型文件。

例如，以下命令使用了 8 位键和 4 位值的量化配置来运行模型：

./llama.cpp/build/bin/llama-cli -m models/your-model.gguf -p "Your prompt" -t 8 --flash-attn --kvq 8

通过调整这些参数，用户可以根据自己的需求和硬件配置来优化模型的性能和内存使用。