KoboldCpp：安装、配置（GGUF、ROCm、API）——以及对比 Ollama

#为何选择 KoboldCpp

KoboldCpp 是 llama.cpp 的一个分支版本，打包为单个独立可执行文件。您只需下载一个文件，运行它，即可立即在浏览器中获得一个聊天网页界面以及 HTTP API。无需安装守护进程，无需管理 Python 依赖，也无需使用专有模型管理器：只需将二进制文件指向从 Hugging Face 下载的 GGUF 模型文件即可。

与 Ollama 相比，KoboldCpp 的设计理念明显不同。Ollama 管理模型目录、后台守护进程（运行于 http://localhost:11434）以及自有打包格式。KoboldCpp 则不做这些管理：它直接运行您提供的 GGUF 文件。因此，当您想测试手动下载的某个特定量化版本、使用的机器无法安装任何软件，或您的 AMD GPU 在其他工具中支持不佳时，它尤其适合。

单个二进制文件

单个可执行文件，便携式，无需安装，无需管理员权限。

GGUF直接加载

可直接加载从 Hugging Face 下载的任意 .gguf 文件，无需转换。

对 AMD 提供一流支持

专用的 ROCm 构建版本和 Vulkan 后端，能真正发挥 Radeon 显卡的性能。

一应俱全

KoboldAI Lite 网页界面与 API（原生 API 及兼容 OpenAI 的 API）集成在同一个二进制文件中。

#先决条件

KoboldCpp 可在 Windows、Linux 和 macOS 上运行。它可以仅使用 CPU 运行，但 GPU 能显著加速推理。与所有 GGUF 运行器一样，关键在于可用显存：它决定了您能完整加载到显卡上的模型大小及量化规格。

系统 RAM

在 CPU 上运行小模型至少需要 8 GB 系统内存，16 GB 较为充裕，32 GB 可用于将大模型的部分计算和权重转移到系统内存中。

VRAM（Q4_K_M参考）

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB

NVIDIA GPU

CUDA 构建版本。RTX 3060 12GB（入门级）、4070 12GB、4080 16GB、4090 24GB。

AMD GPU

ROCm 构建版本（Radeon RX 6000/7000）或通用 Vulkan 后端。

一个GGUF格式文件

从 Hugging Face 获取（例如 bartowski，他是 GGUF 量化模型的主要提供者之一）。

#下载二进制文件

整个流程都从项目的 GitHub Releases 页面（LostRuins/koboldcpp）开始。选择适合您操作系统和 GPU 的二进制文件——没有安装程序，只有一个需要设为可执行的文件。

1. 01
   查看发布版本

   访问 github.com/LostRuins/koboldcpp/releases 并查找最新稳定版本。
2. 02
   选择正确的文件

   Windows NVIDIA环境：koboldcpp.exe（CUDA编译版）；无NVIDIA的Windows环境：koboldcpp_nocuda.exe（使用Vulkan/CLBlast）；Linux环境：koboldcpp-linux-x64；Linux下AMD平台：使用ROCm编译版koboldcpp-linux-x64-rocm（详见AMD部分）
3. 03
   赋予执行权限（Linux/macOS）

   下载文件后，赋予其可执行权限再启动。

# Récupérer le binaire (adaptez l'URL à la dernière release)
wget https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64

# Le rendre exécutable
chmod +x koboldcpp-linux-x64

# Vérifier qu'il se lance
./koboldcpp-linux-x64 --help

#加载 GGUF 并进行对话

核心操作只需一条命令：通过 --model 参数传入 GGUF 文件的路径。KoboldCpp 会启动本地服务器，并打开（或告知您）网页界面的 URL，默认地址为 http://localhost:5001。

# Lancer avec un modèle, en offloadant toutes les couches sur le GPU
./koboldcpp-linux-x64 \
  --model ./qwen3.5-9b-instruct-Q4_K_M.gguf \
  --gpulayers 999 \
  --contextsize 8192

--model

指向要加载的 .gguf 文件的路径。

--gpulayers

卸载到 GPU 上的模型层数。999 = 将显存能容纳的所有模型层都加载到 GPU。

--contextsize

上下文窗口的大小（以 token 为单位，例如 4096、8192、16384）

--port

监听端口（默认为 5001）。

--host

监听地址。设为 0.0.0.0 可让服务在局域网上对外开放。

启动后，在浏览器中打开http://localhost:5001，即可进入KoboldAI Lite。这是一个功能完整的聊天界面，提供历史记录、采样设置以及聊天、指令和写作模式。无需安装其他软件。

#AMD GPU：ROCm和Vulkan

这是 KoboldCpp 与 Ollama 差异最明显的领域。根据您的操作系统和显卡，有两种方式可以在 Radeon 上实现加速。

#ROCm 方案（Linux，最高性能）

ROCm 是 AMD 的 GPU 计算软件栈，相当于 CUDA。该项目提供专用的 ROCm 构建版本，可在 Radeon RX 6000/7000 上提供最佳性能。需要先在系统上安装 ROCm，然后像运行其他版本一样运行 ROCm 版可执行文件。

# Build ROCm dédié
chmod +x koboldcpp-linux-x64-rocm

# Certaines cartes non officiellement supportées nécessitent de forcer
# la version d'architecture GPU (ex. RX 6700 XT -> gfx1030)
export HSA_OVERRIDE_GFX_VERSION=10.3.0

./koboldcpp-linux-x64-rocm \
  --model ./gemma-4-12b-it-Q4_K_M.gguf \
  --usecublas \
  --gpulayers 999 \
  --contextsize 8192

#Vulkan方案（通用、简单）

如果您觉得 ROCm 难以上手，或者无法使用它（Windows、显卡过旧、集成显卡），Vulkan 后端是一个很好的替代方案。它不依赖特定厂商：无需厂商专用的计算软件栈，就能在 AMD、Intel 和 NVIDIA 上运行，代价是性能比 ROCm 或 CUDA 略低。

./koboldcpp-linux-x64 \
  --model ./granite-4.2-8b-instruct-Q4_K_M.gguf \
  --usevulkan \
  --gpulayers 999 \
  --contextsize 8192

#上下文与offloading

两个设置决定模型能否装进 GPU 显存以及响应速度：转移到 GPU 上的层数和上下文长度。合理调整这两个设置，可以避免模型因显存不足而部分转入系统 RAM，否则速度会大幅下降。

#层卸载（--gpulayers）

模型由多层（layers）组成。放在 VRAM 中的每一层都由 GPU 计算，其余层则在 CPU 上运行。--gpulayers 999 会尝试将所有层都放到 GPU 上。如果显卡的 VRAM 不足，请减小这个数值：模型随后会分布在 GPU 和 CPU 上运行（部分卸载），速度较慢，但仍能正常工作。

显存足以容纳整个模型

--gpulayers 999，最大速度，模型全部加载至 GPU

显存不足

降低数值（例如20、30），直到加载完成且不导致显存饱和。

无 GPU

--gpulayers 0，完全使用 CPU：速度慢但可在任何地方运行。

#上下文窗口（--contextsize）

上下文是模型保留在内存中的文本量（以 token 为单位），包括系统提示、历史记录和问题。上下文越长，KV 缓存占用的显存就越多。不要将上下文设置得超过实际需求：日常聊天用 4096–8192 即可，分析长文档则用 16384 及以上。

#集成API和网页界面

KoboldCpp 在同一端口（默认为 5001）上提供两个 API：其原生 KoboldAI API，以及位于 /v1 路径下、兼容 OpenAI 的 API。后者让您可以将 KoboldCpp 接入任何支持 OpenAI 协议的工具，作为其后端——连接方式与使用 Ollama 或 llama-server 端点完全一样。

curl http://localhost:5001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koboldcpp",
    "messages": [
      {"role": "user", "content": "Explique le offloading GPU en une phrase."}
    ]
  }'

在 Python 中，凭借 OpenAI 兼容性，只需更改基础 URL 并填入一个占位密钥，就能复用官方 SDK。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="koboldcpp",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="koboldcpp",
    messages=[{"role": "user", "content": "Bonjour en une phrase."}],
)
print(resp.choices[0].message.content)

网页界面

可通过 http://localhost:5001 访问 KoboldAI Lite：聊天、高级采样、角色设定、记忆功能。

OpenAI API

用于连接 Open WebUI、脚本或智能体的 /v1/chat/completions 接口。

原生 API

KoboldAI 的端点支持对采样和生成进行精细控制。

#故障排除

在 AMD 设备上加载失败

不被ROCm识别的显卡：请设置HSA_OVERRIDE_GFX_VERSION为相近架构（例如10.3.0），或切换至--usevulkan。

生成速度非常慢

模型的一部分已卸载到 CPU 上运行。请减小 --contextsize，减少 --gpulayers 以避免资源占满，或改用更低位数的量化格式（Q5 → Q4_K_M）。

启动时出现「out of memory」错误

模型和 KV 缓存已占满显存。请缩短上下文、降低 GPU 卸载量（offloading），或选择更轻量的量化版本。

端口已被占用

若5001端口被占用，请使用--port参数更改（例如--port 5002）。

从其他设备访问

添加 --host 0.0.0.0 以监听本地网络，并在防火墙中打开端口。

总之，如果您希望免安装、直接控制 GGUF 文件和卸载设置，或只是想让 AMD 显卡终于充分发挥性能，KoboldCpp 是务实的选择。如果您需要模型目录和开箱即用的系统集成，Ollama 仍然更省心；在可移植性和精细调节方面，KoboldCpp 更胜一筹。

#深入了解

这些指南是本指南的延伸，并涵盖相关组件：

Ollama搭配AMD GPU（ROCm）

Ollama 生态中使用 AMD GPU 的另一种方案，可用于比较 ROCm 在两个生态中的使用情况。

选择量化方案（Q4、Q5、Q8、FP16）

在下载GGUF模型前，用于权衡模型大小、VRAM占用与质量。

llama-server：基于llama.cpp的本地OpenAI API服务

如果您优先考虑 API，这是最接近的替代方案，同样基于 llama.cpp。