llamafile：下载即跑的跨平台模型可执行文件，一条命令起动推理

不需要安装，直接运行模型：llamafile 全指南

无需安装任何包，也无需配置运行时环境。下载一个已经包含权重的可执行文件，赋予执行权限，然后直接运行。在网速正常的情况下，整个过程只需要两条命令和一次下载。

Mozilla 在 Hugging Face 上发布了现成的 llamafile。项目官方快速入门用的是一个小模型，这样选择是正确的，因为第一次运行应该先排除内存因素的干扰：

curl -LO https://huggingface.co/mozilla-ai/llamafile_0.10/resolve/main/Qwen3.5-0.8B-Q8_0.llamafile

这个文件约 1.77 GB，基本上全是权重：运行时本身只占很小一部分。注意命名规范——模型、量化级别、.llamafile——因为文件下载到本地后，这就是唯一说明里面装了什么的方式。同一个系列里也有更大的模型；在 Windows 上使用超过 4 GB 的文件之前，先读一下格式说明，那里有一个平台限制需要注意。

macOS、Linux、BSD。赋予执行权限然后运行：

chmod +x Qwen3.5-0.8B-Q8_0.llamafile
./Qwen3.5-0.8B-Q8_0.llamafile

Windows。将文件重命名以 .exe 结尾，然后双击或在终端中运行。Windows 否则不会执行它，因为扩展名才是它判断这是一个程序的依据。

无论哪种方式。在 0.10 版本线上，文件会直接在终端中打开聊天界面。输入问题并按回车；这就是你的第一次回复，整个过程只下载了一个文件，没有安装任何其他东西。

这个终端界面有自己的命令，而不是一个裸提示符：/help 列出所有命令，/upload 可以在支持图像的模型上附加一张图片。用 Control-C 停止它。

在提示符之前出现的是一段启动输出，包括模型名称、量化级别、上下文大小以及它选择的硬件后端。最后一行需要记住：它告诉你是否找到了 GPU。如果一台有 GPU 的机器上显示的是 CPU，模型仍然会回答，只是会慢很多，而原因几乎总是宿主机的驱动而不是 llamafile——一个便携文件保证代码能运行，但不保证你的供应商计算栈已安装。不会向当前目录以外的地方写入任何东西，所以如果你决定不用了，删除这一个文件就是完整的卸载。

Web UI 和两个 API

进程运行的同时会在 8080 端口提供 HTTP 服务。打开 http://localhost:8080/ 就能用浏览器聊天界面访问同一个加载的模型——终端聊天和 Web UI 是同一个进程的两个前端，而不是模型的两份副本。

同一个端口提供两个 API 层面：一个 OpenAI 兼容的，一个 Anthropic Messages 兼容的。第二个在本地运行时中并不常见，但确实有用，因为用 Anthropic SDK 编写的客户端通常完全没有本地选项。将任一 SDK 指向基础 URL 并给它任意一个非空密钥：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [{"role": "user", "content": "one sentence on memory mapping"}],
    "max_tokens": 128
  }'

对于流式输出，两个层面都使用各自提供者的事件格式，在假设客户端可以直接工作之前需要先检查这个——参见流式响应。两个层面是同一个模型前面套了两套请求和响应模式，所以它们之间的输出差异来自于你的消息如何被组装成提示词，而不是生成引擎有什么不同。

用自己的 GGUF 搭配裸运行时

发布包也单独发布了运行时，不包含权重。用这个运行时来运行你已有的任何 GGUF：

./llamafile -m ~/models/qwen3-8b-q4_k_m.gguf -ngl 999

-ngl 是 GPU 层数，一个很大的数字意味着"所有层，能装多少装多少"。有两个发布变体值得了解：标准 llamafile 绑定了 GPU 库，体积更大，而 llamafile-thin 则没有。同样是这些发布包，还包含 whisperfile 和 transcribefile 用于语音，diffusionfile 用于图像，它们都建立在同一套便携化机制之上。这种外部权重模式也是 Windows 大小限制的官方解决方案。

把运行时和权重分开会改变更新策略，值得提前规划。一个打包好的 llamafile 把一个运行时和一个模型永久绑定在一起，这在你把它交给别人时正是你想要的，但在你自己的机器上却恰恰相反：新版本发布意味着要重新下载你已经有的权重。把你的 GGUF 放在一个目录里，只更新运行时，升级就变成每个模型几百兆而不是几 GB。项目的 zipalign 工具走的是另一个方向，把你已经有的 GGUF 打包进裸运行时，产生一个属于你自己的单文件构建。

容易出问题的三个地方

Linux 或 WSL 报告 run-detectors 相关的错误。内核把你的 llamafile 交给了错误的解释器，通常是因为 WINE 已经为以 MZ 开头的文件注册了 binfmt_misc 处理器，而 llamafile 正是以 MZ 开头的。官方修复方法是将 APE 加载器显式注册到内核；在 WSL 上，互操作设置是等价的选择。下载本身没有问题。判断依据是错误信息中提到的解释器根本不是你要用的。

macOS 拒绝运行它。Gatekeeper 会把它当作下载的软件来处理，所以在安全设置中批准它；故障排除文档也涵盖了需要 Xcode 命令行工具的情况，以及调用时的一个 zsh 特有的小问题。

Windows 无法运行大文件。超过 4 GB 的可执行文件在 Windows 上根本无法运行。使用上面的 -m 裸运行时而不是去找更大的单一文件。

默认端口、终端优先的行为和打包好的发布产物是针对 0.10 版本的，写这篇文章时该版本是当前版本。早期版本会打开浏览器而不是终端聊天。根据你下载的版本检查 Mozilla 的 llamafile 文档。

llamafile 解析：一个可执行文件里的模型和运行时

GPT4All，首次响应时间

LocalAI，首次请求时间