AI教程

使用 Splash 在 Apple 芯片上快速运行本地 AI 模型

了解如何在受支持的 Mac 上安装 Splash、启动模型服务器、调用兼容 OpenAI 的 API、连接编程代理、管理内存和上下文限制、启用身份验证，并优化高级本地推理工作流。

AI我搜编辑部2026年9月19日阅读约 11 分钟

什么是 Splash？

Splash 是一款专为 Apple 芯片设计的本地推理引擎。它为编码代理和支持 OpenAI 或 Anthropic API 的应用提供经过优化的语言模型。服务器在一台 Mac 上本地运行，并通过 127.0.0.1:8000 暴露 API。

与通用推理引擎不同，Splash 会针对每个受支持的模型，分别优化其内核、推测解码草稿模型、权重布局和内存方案。模型软件包开箱即可运行，因此无需安装 Xcode、编译器工具链或进行特定于模型的调优。

主要功能

本地 Apple 芯片推理： Splash 可直接在受支持的 Mac 上运行模型。
兼容 OpenAI： 它在 /v1/chat/completions 提供 Chat Completions，在 /v1/responses 提供 Responses。
兼容 Anthropic： Anthropic Messages 请求可通过 /v1/messages 使用。
高级请求支持： API 支持流式传输、工具调用、JSON Schema 输出、图像和内联 PDF。
编码代理集成： Splash 包含用于 OpenCode、Claude、Codex 和 Hermes 的命令。
特定于模型的加速： 每个模型软件包都包含用于推测解码的 DFlash 2 草稿模型，以及根据该模型确切维度调优的预编译 Metal 内核。
自动内存规划： Splash 会在启动时根据 Metal 可用的内存，计算上下文、KV 缓存容量和批处理限制。
提示词检查： /tokenize 和 /apply-template 端点可返回令牌 ID 或渲染后的提示词，而无需运行推理。

系统要求

安装 Splash 前，请确认系统满足以下所有要求：

Apple M3 或更新的处理器
macOS 26.4 或更高版本
Homebrew
至少 36 GB 统一内存
建议使用 48 GB 或更多统一内存

可用上下文容量取决于可用内存。虽然受支持的模型原生上下文窗口最高可达 256K，但完整窗口可能无法在每台 Mac 上容纳。

安装 Splash

通过 Inco Homebrew tap 安装打包版本：

brew install incoai/tap/splash

无需创建配置文件。Splash 使用命令行标志和环境变量提供可选设置。

启动模型服务器

使用以下命令提供经过优化的 Qwen3.8-27B 软件包：

splash serve --model incoai/Qwen3.8-27B-Splash

首次运行时，Splash 会下载并验证模型软件包、检查可用内存、创建内存方案，并在 127.0.0.1:8000 上启动服务器。Qwen3.8-27B 软件包大小为 17.4 GB，包含 4 位目标模型及其 DFlash 2 草稿模型。

等待终端显示 Ready。使用模型时请保持该终端打开。随后可以在浏览器中打开 http://127.0.0.1:8000，访问聊天页面。

需要停止 Splash 时，在服务器终端中按下 Ctrl+C。

使用备用模型

Splash 还发布了一个 20.9 GB 的软件包，其中包含 4 位 Qwen3.6-35B-A3B 模型及其 DFlash 2 草稿模型：

splash serve --model incoai/Qwen3.6-35B-A3B-Splash

--model 选项可以指向包含有效 Splash 软件包的其他 owner/repo 仓库。普通 MLX 和 Transformers 检查点不兼容。对于私有 Hugging Face 仓库，请提供适当的 HF_TOKEN。

连接编码代理

服务器报告已准备就绪后，打开另一个终端，启动下列已安装且受支持的编码代理之一：

splash opencode
splash claude
splash codex
splash hermes

只运行与你要使用的代理对应的命令。代理发送请求期间，原始服务器进程必须保持运行。

调用 OpenAI Chat Completions API

应用可以将 Splash 作为兼容 OpenAI 的本地服务器调用。以下请求会要求所提供的模型用一句话进行解释：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "incoai/Qwen3.8-27B-Splash",
    "messages": [
      {
        "role": "user",
        "content": "Explain speculative decoding in one sentence."
      }
    ]
  }'

model 属性是可选的。如果包含该属性，其值必须与当前提供的模型软件包匹配。

选择适当的 API 端点

OpenAI Chat Completions 客户端使用 /v1/chat/completions。
OpenAI Responses 客户端使用 /v1/responses。
Anthropic Messages 客户端使用 /v1/messages。
使用 /tokenize 获取令牌 ID，而无需运行模型。
使用 /apply-template 查看渲染后的提示词，而无需运行推理。

控制推理

推理默认启用。要禁用推理，请在请求正文中添加 "reasoning_effort": "none"。Qwen3.8-27B 还接受 low、medium 和 xhigh。

{
  "model": "incoai/Qwen3.8-27B-Splash",
  "reasoning_effort": "none",
  "messages": [
    {
      "role": "user",
      "content": "Summarize speculative decoding."
    }
  ]
}

当任务不需要扩展的推理过程时，禁用推理可能会很有用。对于确实受益于推理的 Qwen3.8-27B 任务，请根据工作负载选择受支持的推理强度级别。

配置内存和上下文限制

Splash 会自动确定合适的默认值，但 splash serve 提供了可选参数，以便进行更精细的控制：

--max-memory 28G 设置 Metal 分配的上限。
--max-context 100K 限制上下文窗口，最大不超过模型原生的 256K 限制。
--max-image-pixels 控制每张图片调整大小后的最大像素数。默认值为 4,194,304。
--allowed-host 允许额外的 HTTP Host 名称，例如代理使用的名称。此选项可以重复指定。
--no-webui 禁用浏览器聊天页面。

例如，以下命令会将 Metal 分配上限设为 28 GB，并将上下文限制为 100K：

splash serve \
  --model incoai/Qwen3.8-27B-Splash \
  --max-memory 28G \
  --max-context 100K

如果模型无法装入可用内存，Splash 会输出内存预算明细并停止，而不是启动一个无法正常使用的服务器。降低上下文或内存需求可能会有所帮助，但模型权重和所需的运行时状态仍必须能够装入内存。

保护本地 API

默认情况下，身份验证处于禁用状态。你可以在启动服务器的 shell 中设置 SPLASH_API_KEY 来要求提供密钥：

export SPLASH_API_KEY='replace-with-your-key'
splash serve --model incoai/Qwen3.8-27B-Splash

在用于启动由 Splash 管理的编码代理的 shell 中，也设置相同的环境变量：

export SPLASH_API_KEY='replace-with-your-key'
splash opencode

API 客户端可以将密钥作为 bearer token 提交，也可以通过 x-api-key 标头提交。你还可以通过服务器的 --api-key 选项直接提供密钥。健康检查和就绪探针仍保持公开。

高级技巧

规划模型缓存

下载的软件包会存储在 Hugging Face 缓存中。运行 brew upgrade splash 会保留这些软件包、模型链接和代理会话，因此升级引擎不需要删除它们。

通过代理使用主机允许列表

服务器会在本地绑定到 127.0.0.1:8000。如果本地代理发送了不同的 HTTP Host 值，请使用 --allowed-host 添加该主机名。需要接受多个主机名时，请重复指定此参数。

为仅使用 API 的场景禁用 Web 界面

如果 Splash 只为应用或代理提供服务，请使用 --no-webui 启动。此操作会关闭聊天页面，同时保留受支持的 API 端点。

在推理前检查提示词

需要令牌 ID 时使用 /tokenize，需要检查最终渲染的提示词时使用 /apply-template。由于这些端点不会运行模型，因此适合用于调试上下文大小和提示词格式。

试验 SSD 缓存卸载

拉取请求 3 中的实验性实现可以将 KV-cache 和 GDN 状态卸载到 SSD。构建该分支，并使用 --max-cache-disk 8G 启动服务器即可启用此功能。当 RAM 有限时，这可能会保留可复用的前缀，并减少重复的预填充工作。

SSD 卸载功能仍处于实验阶段，不属于快速入门中介绍的标准打包工作流。

了解 Splash 的性能

Splash 会针对每个模型专门优化大部分推理栈，从而提升速度。推测解码是标准的解码路径，而不是可选模式。针对模型的 DFlash 2 草稿模型会提出令牌块，再由目标模型并行验证。

其融合 Metal 内核会针对模型的确切形状进行编译，并直接读取从磁盘映射的特殊打包权重，无需额外复制。启动时，Splash 还会根据当前机器计算上下文、缓存和批处理限制。

根据项目在配备 16 核 GPU 和 48 GB 内存的 M5 Pro 上进行的测量，Qwen3.8-27B 在短提示词解码时达到每秒 74 个令牌；在重放缓存的 32K 上下文时，首个令牌返回时间为 282 ms。结果取决于模型、提示词、并发量、硬件和内存状况。Splash 发布文章介绍了基准测试方法和对比结果。

结语

Splash 为在新款 Apple silicon 上运行精选的高度优化模型提供了一种简化方式。使用 Homebrew 安装后，启动兼容的 Splash 模型包，然后通过浏览器、受支持的编码代理，或兼容 OpenAI 或 Anthropic 的 API 进行连接。自动默认值让初始设置更加简单，而内存、上下文、安全性、主机和界面选项则支持更可控的部署。