noreff/lmstudio-dsv4-patch

来源：https://github.com/noreff/lmstudio-dsv4-patch

在 LM Studio（Mac）中侧载 DeepSeek V4 Flash

将 antirez 的 deepseek_v4 llama.cpp 分支（https://github.com/antirez/llama.cpp）侧载到 LM Studio 中，从而在 128 GB 统一内存的 Mac 上运行 DeepSeek V4 Flash（https://huggingface.co/antirez/deepseek-v4-gguf）——256 专家 MoE，常驻约 80 GB，支持最高 100 万 token 上下文。

这是一种变通方案。上游 llama.cpp 尚不支持 deepseek_v4 架构（讨论 #22376（https://github.com/ggml-org/llama.cpp/discussions/22376））。LM Studio 的 MLX 运行时拒绝 V4 GGUFs（bug #1872（https://github.com/lmstudio-ai/lmstudio-bug-tracker/issues/1872））。在这些修复落地之前，这是从 LM Studio 的 UI / OpenAI 兼容服务器驱动 V4-Flash 的唯一可行路径。

已在 MacBook Pro M5 Max，128 GB，macOS 26.4 上测试。在 M2/M3/M4 Max 128 GB 上应该也能工作。

你将获得

• DeepSeek V4 Flash 作为普通模型加载到 LM Studio 中
• OpenAI 兼容 API，地址为 http://localhost:1234
• 完整的 1 048 576 token 上下文
• 约 190 tok/s 提示词处理速度，约 26 tok/s 生成速度
• 可与任何 OpenAI API 客户端配合使用（包括 pi（https://github.com/badlogic/pi-mono）、Open WebUI、你自己的脚本）

为什么需要补丁

LM Studio 的闭源桥接层（libllm_engine.dylib）是针对较旧的 llama.h 构建的。当你换入 antirez 较新的 libllama.dylib 时，桥接层会崩溃或产生乱码。本仓库中的补丁处理以下问题：

1. llama_context_params 结构体布局漂移 —— 桥接层写入旧偏移量，我们在新偏移量处读取，因此大多数 ctx 字段会变成垃圾数据（其中最关键的是 yarn_attn_factor，它会静默破坏 YARN 缩放模型上的 RoPE）。我们通过 isnan(rope_freq_base) 检测桥接层调用，并覆盖该结构体。
2. 桥接层将提示词分块为多次 llama_decode() 调用。 V4 的压缩注意力索引器会跨调用保持状态，分块时会损坏，因此我们缓冲分块并将它们作为一个批次重新提交（同时正确处理图像嵌入批次的合并，让 Gemma 4 31B 等视觉模型继续工作）。
3. 探测解码 桥接层发出的 common_context_can_seq_rm 在 V4 的混合内存上会触发 SIGBUS —— 直接提前返回。
4. Metal mpp::tensor_ops 内核 在 LM Studio 进程内无法解析 —— 硬编码 has_tensor=false，从而编译 simdgroup 回退路径。
5. cplan->abort_callback 上的 PAC 不匹配（Element Labs 签名的 arm64e 桥接层与临时签名的 arm64 ggml-cpu 之间）—— 已绕过。
6. 桥接层期望的 ABI 符号缺失（llama_memory_breakdown_print、llama_n_rs_seq、llama_get_embeddings_pre_norm*、mtmd_get_memory_usage）—— 已添加为无操作桩函数。

另外：代码签名。LM Studio 使用了强化运行时（hardened-runtime）、Element Labs Developer ID 签名，且没有 disable-library-validation —— 默认会拒绝加载我们的 dylib。需要用添加了该权利（entitlement）的配置重新签名 LM Studio 的二进制文件。

操作步骤

你需要：Xcode CLT、cmake、约 100 GB 空闲磁盘空间、已安装 LM Studio。

# 1. 克隆 antirez 的分支
git clone https://github.com/antirez/llama.cpp ~/llama-ds4
cd ~/llama-ds4

# 2. 应用此补丁 + 放入两个桩文件
git apply /path/to/this/repo/patches/01-lms-bridge-shims.diff
cp /path/to/this/repo/patches/llama-lms-stubs.cpp src/
cp /path/to/this/repo/patches/mtmd-lms-stubs.cpp tools/mtmd/

# 3. 使用 Metal 构建共享库
cmake -B build-shared \
  -DBUILD_SHARED_LIBS=ON -DGGML_METAL=ON -DGGML_METAL_EMBED_LIBRARY=ON \
  -DLLAMA_CURL=OFF
cmake --build build-shared --target llama llama-server -j

# 4. 将 LM Studio 运行时克隆到新的同级目录，保持原目录不变
RUNTIME_SRC=~/.lmstudio/extensions/backends/llama.cpp-mac-arm64-apple-metal-advsimd-2.17.0
RUNTIME=$RUNTIME_SRC  # 如果你接受固定这个版本，可以直接用原目录
# （或者复制到 -antirez 并在 backend-manifest.json 中升级版本号 —— 见说明）

# 5. 将我们的 dylib 覆盖到运行时中
for f in libllama libggml-base libggml-cpu libggml-blas libggml-metal libmtmd libllama-common; do
  cp ~/llama-ds4/build-shared/bin/${f}.dylib "$RUNTIME/${f}.dylib"
  install_name_tool -id @rpath/${f}.dylib "$RUNTIME/${f}.dylib"
done

# 重写带版本号后缀的依赖（例如 libfoo.0.dylib → libfoo.dylib）
for d in "$RUNTIME"/lib*.dylib; do
  otool -L "$d" | awk '/@rpath.*\.0\..*\.dylib/ {print $1}' | while read dep; do
    new=$(echo "$dep" | sed 's/\.0\.0\.1\.dylib/.dylib/;s/\.0\.dylib/.dylib/')
    install_name_tool -change "$dep" "$new" "$d" 2>/dev/null
  done
  codesign --force --sign - "$d"
done

# 6. 替换运行时中的 llama-server 二进制（LM Studio 2.16+ 使用子进程模式）
cp ~/llama-ds4/build-shared/bin/llama-server "$RUNTIME/llama-server"
codesign --force --sign - "$RUNTIME/llama-server"

# 7. 用 disable-library-validation 重新签名 LM Studio 二进制文件
# （一次性操作；LM Studio 应用更新后如需要请重新执行）
APP=/Applications/LM\ Studio.app
xattr -dr com.apple.quarantine "$APP"

# 对以下每个文件：主程序 "LM Studio"、四个 Helper、~/.lmstudio/.internal/utils/{node,deno}
# 以及 /Applications/LM Studio.app/Contents/Resources/app/.webpack/bin/{node,deno}：
# - 提取权利：codesign -d --entitlements - --xml > ent.plist
# - 添加键：PlistBuddy -c "Add :com.apple.security.cs.disable-library-validation bool true" ent.plist
# - 重新签名：codesign --force --sign - --options runtime --entitlements ent.plist

# 8. 下载 GGUF
huggingface-cli download antirez/deepseek-v4-gguf \
  DeepSeek-V4-Flash-IQ2XXS-w2Q2K-AProjQ8-SExpQ8-OutQ8-chat-v2.gguf \
  --local-dir ~/.lmstudio/models/antirez/deepseek-v4-gguf

然后在 LM Studio 的运行时选择器（⌘⇧R）中确保选中 2.17.0 运行时，并执行：

~/.lmstudio/bin/lms load antirez/deepseek-v4-flash \
  --gpu max --context-length 1048576 --identifier dsv4 --exact

完成。该模型会像 LM Studio 中的其他模型一样，通过 http://localhost:1234/v1/chat/completions 回答。

调优说明

补丁中硬编码了以下 cparams（可通过环境变量 LMS_UBATCH、LMS_THREADS_BATCH、LMS_KV_TYPE 覆盖）：

• n_ubatch = 512 —— 在 M5 Max 128 GB 上是甜点值。1024+ 会在 1M 上下文时导致 sched_reserve 崩溃（计算暂存区溢出）。
• n_batch = min(max(n_ctx, 4096), 16384) —— 必须设上限；提示词评估的 logits 输出缓冲区大小为 n_batch × vocab × 4 B（不设上限的话约为 480 GB）。
• n_threads_batch = 6 —— Metal 受 GPU 限制；这个值无所谓。
• type_k = type_v = F16 —— F32 在生成阶段慢约 8%（受内存带宽限制）。
• kv_unified = true、swa_full = false、flash_attn = AUTO。

注意事项

• LM Studio 会自动更新其内置运行时。当运行时版本超过 2.17.0 后，请对新文件夹重复步骤 5–6，或在 ⌘⇧R 中固定 2.17.0。
• 长提示词（远大于 16 k token）会触及 n_batch 上限，并按 16 k 分块进行刷新。V4 的混合状态会略有退化；输出仍然连贯。大多数聊天场景远低于此值。
• 这是 hack，不是官方支持的扩展路径。参见 bug-tracker #1843（https://github.com/lmstudio-ai/lmstudio-bug-tracker/issues/1843）中对公开真实后端 SDK 的请求。

致谢

这完全是因为 @antirez（https://github.com/antirez）在他的 llama.cpp 分支（https://github.com/antirez/llama.cpp）中实现了 deepseek_v4 架构并发布了 IQ2XXS GGUF。这里的补丁只是他分支与 LM Studio 闭源桥接层之间的粘合剂。

许可证

MIT。