shoehorn

shoehorn 是一款开源工具，解决本地运行大语言模型时的核心痛点：如何在不浪费显存也不导致 OOM（显存溢出）的前提下，最大化模型质量？ 传统的预设量化（如 Q4_K_M）往往忽略硬件差异，导致要么留下数百 MB 的未利用空间，要么因估算不准而无法加载。shoehorn 通过求解一个复杂的每张量混合精度分配方案，将模型的每一兆字节都用在刀刃上，实现 99.9% 以上的显存利用率。

核心亮点：从“猜大小”到“精确拟合”

• 硬件感知预算：
  • 自动探测你的 GPU 可用显存（macOS Metal, NVIDIA NVML, AMD ROCm）。
  • 精确计算 KV 缓存、计算缓冲区和安全余量，得出真实的权重预算。
• 重要性矩阵（imatrix）驱动：
  • 利用 imatrix 识别对模型输出影响最大的权重列。
  • 在预算限制下，优先为重要权重分配更高精度（如 F16/Q8_0），为次要权重分配更低精度（如 IQ2_XXS）。
• 拉格朗日背包求解器：
  • 将量化问题转化为多重选择背包问题。
  • 为每个张量独立选择最优量化格式，确保总大小在舍入误差内严格落在预算范围内。
• 无缝集成 llama.cpp：
  • 输出标准的 GGUF v3 文件，可直接被 llama.cpp、LM Studio、Ollama 等工具加载。
  • 内置 llama-server 启动功能，一键提供服务。

快速开始

1. 安装

• macOS (Apple Silicon):

  brew install notactuallytreyanastasio/shoehorn/shoehorn
  

• Linux/Windows:
  需先安装带有 CUDA/ROCm 支持的 llama.cpp，然后通过 cargo install 安装 shoehorn。

2. 一行命令适配并运行

# 自动下载 BF16 模型，生成 imatrix，求解混合方案，量化并启动服务
shoehorn fit unsloth/Qwen3-4B-GGUF --serve

3. 手动分步执行

# 1. 探测显存
shoehorn vram

# 2. 针对特定预算量化（例如 1.75 GiB）
shoehorn quantize -m Qwen3-0.6B-BF16.gguf -i qwen3.imatrix \
    --ctx 4096 --budget 1.75GiB -o fitted.gguf

# 3. 运行
shoehorn run -m fitted.gguf --ctx 4096

Web UI：可视化你的显存预算

shoehorn 提供了一个直观的 Web 界面 (shoehorn ui)，让你无需记忆命令行参数即可操作：

• 机器卡片：显示实测可用显存。
• 发现模型：根据预算排名 Hugging Face 上的可适配模型。
• 卷尺视图：实时展示权重、KV 缓存和安全余量的占比。
• 预览混合方案：在写入文件前查看每张量的量化类型分布。
• 困惑度评估：直接对比适配模型与原始模型的 PPL 增量，诚实回答“牺牲了多少质量”。

性能实测：小预算跑大模型

为什么选择 shoehorn？

1. 极致利用率：不再浪费宝贵的显存，每一比特都用于提升模型质量。
2. 自动化流程：从下载、imatrix 生成到量化、服务，全流程自动化。
3. 透明可控：提供详细的每张量表和预算分解，让量化过程不再黑盒。
4. 广泛兼容：支持多种量化格式（IQ, K-quant, F16 等），输出标准 GGUF。