KoboldCpp
一句话定位：llama.cpp 系的 C++ 本地 LLM 推理后端——单 exe 内置 CUDA，同时暴露 KoboldAI API、OpenAI 兼容 API、Ollama 模拟接口，是「本地模型跑团」的关键底座。 类型：本地 LLM 推理服务 · 开源 · 许可：AGPL-3.0 · 仓库：LostRuins/koboldcpp
1. 项目概述
KoboldCpp 由 KoboldAI 社区开发，目标是把「跑 LLM」这件事做到最省事：一个约 600MB 的 Windows 单文件 exe（PyInstaller 打包，内嵌 CUDA 运行时 DLL），双击/命令行即可加载 GGUF 量化模型，不需要 Python 环境、不需要显卡驱动外的任何依赖。它同时是 SillyTavern 等前端最常用的本地后端之一。
对 AI 跑团的定位：它不做故事，只做「模型伺服」。把 Qwen/Llama/Mistral 等指令模型的 GGUF 加载到显存后，任何支持 OpenAI 兼容协议的前端（SillyTavern、ChatRPG、ai-murder-mystery、diceframe……）都能直接连上它，实现全本地、零 API key 的 AI 跑团。
2. 核心功能
- 四套 API 同时暴露：KoboldCppApi（
/api）、OpenAI 兼容（/v1，含 chat/completions 与流式）、Ollama 模拟、Anthropic 兼容——一个模型全家桶。 - CUDA 加速：
--gpulayers 99全层卸载 GPU；RTX 3080 10GB 可跑 3B（占 ~1.8GB）到 7B（占 ~4.5GB）的 Q4 量化模型。 - GGUF 分片支持：自动识别
-00001-of-00002.gguf多分片模型。 - 内置 Web UI：KoboldAI Lite + llama.cpp UI（
/lcpp/），无需第三方前端也能直接聊。 - 上下文与批处理参数：
--contextsize、flash attention、KV 量化等 llama.cpp 全家参数可用。 - 支持分块加速、LoRA、多模态（mmproj）、嵌入（embeddings）等扩展能力。
3. 技术架构
- C++ 核心（llama.cpp/ggml）：GGUF 解析、CUDA 算子、KV cache、采样器。
- Python 包装层（打包进 exe）：API 服务器、适配器（chat-completion 模板 AutoGuess——按模型元数据自动选 ChatML/…模板）、KoboldAI 协议。
- 单进程：不 spawn 子进程，对受限环境友好；DLL 每次启动自解压到临时目录。
4. 本机实测记录（✅ 完整运行）
- 版本 v1.118.1（Windows exe 603MB）；模型：Qwen2.5-3B-Instruct Q4_K_M（1.95GB，ModelScope 镜像下载）与 Qwen2.5-7B-Instruct Q4_K_M（4.5GB 双分片）。
- 启动命令（工作区环境）：
koboldcpp.exe --model models\qwen2.5-7b-instruct-q4_k_m-00001-of-00002.gguf --port 5002 --host 127.0.0.1 --gpulayers 99 --contextsize 8192 - 实测数据：3B 全层上 GPU（显存 1834MiB）；中文 DM 开场（OpenAI 兼容接口）1.2 秒 / 158 tokens，质量可用；7B 加载成功（约 4.7GB 显存）。
- 下游验证：SillyTavern、ChatRPG（五智能体）、ai-murder-mystery（三层管线）、diceframe、loreweaver 全部指向
http://127.0.0.1:5002/v1跑通。 - 环境坑：沙箱拦截未知二进制进程写 DLL（自解压失败）——按提权流程放行一次即解决；PowerShell 发中文 JSON 必须用 UTF-8 字节。
5. 如何运行（复现）
- 下载 最新版 koboldcpp.exe（Windows 单文件）；
- 下载 GGUF 模型（HF 或 ModelScope，如 Qwen2.5-3B/7B-Instruct q4_k_m）；
koboldcpp.exe --model <模型.gguf> --gpulayers 99 --port 5001；- 前端接
http://127.0.0.1:5001/v1（OpenAI 兼容）或打开http://127.0.0.1:5001用内置 UI。
6. 优劣势分析
| 优势 | 劣势 |
|---|---|
| 零依赖单文件、Windows 开箱即用 | Windows 版启动需解压 DLL（受限环境需放行） |
| 一模型四协议，兼容几乎所有前端 | 单实例单模型（换模型需重启） |
| 显存利用高效（llama.cpp 核心） | 无模型管理/热加载（对比 Ollama） |
| 完全离线、数据不出本机 | 推理速度受硬件上限约束 |