ggrun：让 llama.cpp 在多卡环境自动调优的智能启动器

ggrun 运行演示（交互式 TUI 自动选择并启动 GGUF 模型）

痛点故事：多卡玩家的调参地狱

如果你有多张不同型号的 GPU（比如 RTX 3090 Ti + 4070 + 3060 混搭），想跑一个大模型会遇到这样的困境：每次换模型都要手动算 --tensor-split 参数、调整 -ngl（GPU 层数）、为 MoE 专家模型规划 VRAM + RAM 混合加载——参数一改就崩，崩了再调，循环往复。

ggrun 正是为解决这个痛点而生：它自动探测你的硬件拓扑（GPU 型号、PCIe 带宽、RAM 大小），从 GGUF 元数据中读取张量精确尺寸，计算最优的 --tensor-split 和 MoE expert placement，一键启动 llama.cpp 的 llama-server，直接给出 OpenAI 兼容 API。

项目背景：作者的真实需求驱动

ggrun 的作者 raketenkater 有一台混搭 3 卡机器（3090 Ti + 4070 + 3060），每次跑新模型都要手写 -ngl、--tensor-split、-ot 参数，这套流程变得繁琐之后就写了一个自动化脚本，逐渐演变成了一个完整的 Go 语言项目。MIT 许可证，2026 年 3 月开源，社区增长迅速。

核心功能：从选模型到跑模型全链路自动化

ggrun 解决了多卡/MoE 场景下 llama.cpp 的 4 个老大难问题：

1. 张量自动分片：读取 GGUF 文件中的实际张量维度，结合 PCIe 拓扑，计算多卡间的最优 --tensor-split，无需手动指定。
2. MoE 专家智能放置：对于 MoE（Mixture of Experts）模型，精确计算每个专家应该落在哪张卡的 VRAM 或系统 RAM 中，让本来装不下的模型也能跑起来。
3. 硬件匹配模型推荐：根据你的 VRAM 大小，自动从 Hugging Face 拉取合适量化的 GGUF 模型（Q4/Q5/Q8 等），并直接下载。
4. AI Tune 自动调优：内置社区调优池提供默认最佳参数，可选开启 --ai-tune 自动 benchmark 多种参数组合并缓存最优结果。

底层支持多种后端：CUDA 加速的 ik_llama.cpp、Vulkan（AMD/Intel 通用）、Apple Metal、以及纯 CPU 模式，后端完全可插拔。

性能对比：比 Ollama 快 1.3到2倍

根据官方基准测试（RTX 3090 Ti + 4070 + 3060 三卡，128GB RAM，32k context）：

模型	Ollama 0.30.8	llama.cpp --fit	ggrun
Qwen3.5-4B Q4_K_M	124.8 tok/s	103.3	151.4
Qwen3.6-27B Q5_K_M	22.8	24.3	37.4
Qwen3.5-122B MoE UD-IQ4_XS	13.5	20.97	22.9
MiniMax-M3 MoE UD-IQ3_XXS	无法加载	无法加载	5.59

值得注意的是，3060 那张卡接在 PCIe x1 插槽上，多卡/MoE 的性能优势在这种弱带宽环境下反而更明显——说明 ggrun 的放置算法对 PCIe 拓扑有精细感知。

架构设计：Go 语言的模块化插件架构

项目采用 Go 语言开发（go.mod 要求 Go 1.24+），代码结构清晰，14 个 pkg 包各司其职：

• go/cmd/ggrun：CLI 入口，兼容参数解析。
• go/pkg/detect：CPU/RAM/CUDA/Vulkan 硬件探测。
• go/pkg/gguf：GGUF 元数据解析。
• go/pkg/placement：核心算法——张量分片、KV 规划、MoE 放置、推测解码参数、vision projector 查找。
• go/pkg/tune：AI Tune benchmark、候选验证、缓存管理。
• go/pkg/tui：Charmbracelet Bubbletea 构建的交互式 TUI。
• go/pkg/recommend：根据硬件推荐 HuggingFace 模型。
• go/pkg/download：模型下载。
• go/pkg/server：OpenAI 兼容 API 服务管理。
• go/pkg/recovery：崩溃检测与恢复。
• go/pkg/backends：多后端统一抽象。
• go/pkg/daemon：后台守护进程支持。
• go/pkg/update：自更新与后端更新。

前端 UI 使用 Charmbracelet Bubbletea（Go 语言 TUI 框架），依赖项非常轻量，仅 3 个直接依赖：bubbles、bubbletea、lipgloss。

部署方式：三条路，总有一条适合你

方式一：一条命令安装（推荐）

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/raketenkater/ggrun/main/setup.sh | bash

Windows (PowerShell)：

iwr -useb https://raw.githubusercontent.com/raketenkater/ggrun/main/install.ps1 | iex

安装脚本会自动检测环境、安装 Go（如果没有）、下载预编译的 llama.cpp 后端、复制 ggrun 二进制到 ~/.local/bin。

方式二：Docker 一键部署（完整聊天栈）

cd docker
MODEL=/models/qwen3.5-4b.gguf docker compose up

自带 open-webui（端口 3000），ggrun 提供 OpenAI 兼容 API（端口 8081），开箱即用的本地聊天界面。docker-compose 支持 GPU 直通（CUDA），Vulkan 模式可用 --device /dev/dri。

方式三：手动从源码构建

git clone https://github.com/raketenkater/ggrun
cd ggrun && ./setup.sh

setup.sh 会从源码编译 ggrun 和 llama.cpp 后端，适合高级用户自定义编译选项。

适用场景 vs 不适用场景

ggrun 真正擅长的场景：

• 多卡（尤其是混卡）环境，需要自动计算张量分片
• MoE 模型太大，单卡 VRAM 装不下，必须溢写到系统 RAM
• 需要频繁换模型，不想每次手动调参
• 想用 AI Tune 自动寻找最优 flag 组合

单卡玩家或小模型用户可能不需要 ggrun：直接用 Ollama 或 llama.cpp 本身就够了，ggrun 在单卡 + 模型完全装入 VRAM 的场景下没有明显优势。README 原文也说得很清楚："If you have a single GPU and a model that fits in its VRAM, plain llama.cpp or Ollama is simpler."

安全与隐私

ggrun 的 OpenAI 兼容 API 默认绑定 127.0.0.1（仅本地访问），API 本身不做认证。如果是内网多台机器共用，需要手动加防火墙，或通过环境变量改为 --host 0.0.0.0 并配合反向代理做认证。数据完全本地处理，无任何外部网络通信（除了从 HuggingFace 下载模型）。

行业意义：填补 llama.cpp 多卡管理的最后一块短板

llama.cpp 是本地 LLM 推理的底层引擎，但它的多卡/MoE 调参门槛一直很高。ggrun 通过自动化这个过程，让普通玩家也能用上多卡 + MoE 的配置，降低了本地部署大模型的硬件门槛。从 GitHub 趋势来看（18 个 topic、多平台支持），它正在成为 llama.cpp 生态中多卡场景下的标准工具之一——虽然还年轻（2026 年 3 月才发布），但已经展示了扎实的产品思维。