llamafile 命令速查表 - 单文件本地 LLM 运行与推理
llamafile 是 Mozilla 提出的"单个可执行文件跑本地 LLM"方案，面向想要零依赖、拷贝即运行模型，尤其适合分发/离线/演示场景的开发者。它把模型权重与 llama.cpp 打包进一个跨平台可执行文件，并内置 OpenAI 兼容服务；本表帮你掌握单文件启动、--server 服务化、-m 加载 GGUF、-ngl 设置 GPU 层数与 --temp 采样温度。
获取与运行 5
curl -L <release-url> > llamafile && chmod +x llamafile./mistral.llamafile./llamafile --helpWindows 改名为 llamafile.exesh -c ./llamafileOpenAI 兼容服务 5
./xxx.llamafile --server --nobrowser./xxx.llamafile --server --port 8081./xxx.llamafile --server --host 0.0.0.0curl http://localhost:8080/v1/modelsopenai_api_base=http://localhost:8080/v1加载外部权重 5
./llamafile -m ~/weights/foo.gguf./llamafile -m model.gguf --temp 0.7 -p "..."./llamafile -m model.gguf --n-gpu-layers 35./llamafile -m model.gguf --image photo.jpg -p "描述这张图"./llamafile -m model.gguf --grammar 'root ::= "yes" | "no"'嵌入与离线 5
./embed.llamafile --server --embedding --port 8081offline 完全本地，无数据出网./llamafile -m w.gguf --no-display-promptzipalign 把 .args 嵌进可执行单文件分发，跨平台（mac/win/linux/bsd）实用技巧 5
服务默认 :8080--ngl 越多越快但吃显存自带权重版起 Web UI离线优先选它--grammar 控输出命令示例
自带权重的文件直接跑，起 Web UI
./mistral.llamafile不起 --server 时它会自己拉起 :8080 上的界面，浏览器打开就能聊。端口被占用时改用 --server --port 另开一个。
起无头服务并确认暴露的模型
./xxx.llamafile --server --nobrowser
curl http://localhost:8080/v1/models返回里带的是服务实际加载的模型标识，客户端写模型名时要用它。openai_api_base=http://localhost:8080/v1 把 SDK 指过来。
加载外部权重并打开 GPU 加速
./llamafile -m model.gguf --n-gpu-layers 35层数是偏好的量：全部放上 GPU 最快，也最吃显存。报显存不足就把 35 往下调，一步步试。
用 BNF 把输出锁死在固定取值上
./llamafile -m model.gguf --grammar 'root ::= "yes" | "no"'脚本里要比对返回字符串时，这是最省心的做法：模型只能在 yes 和 no 里选。再配上 --no-display-prompt，输出里连提示符都不会有。
常见坑与注意事项
- Windows 上必须把文件改名为 llamafile.exe 才认得出来执行，改完先用 ./llamafile --help 确认能跑通再往下走。
- --server --host 0.0.0.0 会把一个没有鉴权的推理端点暴露到局域网甚至公网，任何人拿到地址就能用它跑推理；只在你信任的网络里这么开。
- --n-gpu-layers 设得超过显存承受范围会直接加载失败或把系统拖到交换；按显卡实际显存逐级调，别照抄别人的 35。
- -m 路径写错、或 GGUF 与 llama.cpp 版本不兼容都会在加载阶段报错而不是在生成阶段；先用 ./llamafile --help 确认参数名与当前版本一致。
- 自带权重版直跑同样会占用 8080，和已经在跑的服务撞端口；脚本里别忘了 --no-display-prompt，否则管道里会混进提示符。sh -c ./llamafile 只是 zsh 老版本的兜底写法，别当成通用启动方式照抄。
提示
- llamafile 把 llama.cpp + Cosmopolitan Libc 打包成"单文件可执行"，构建一次跨 macOS/Windows/Linux/BSD 运行，是本地/离线跑 LLM 最省事的方案。
- 带权重的 server 版直接起 Web UI（:8080）；用外部 GGUF 时
-m指定路径，--ngl控制 GPU 层数（越多越快但越吃显存）。 - OpenAI 兼容服务默认 :8080（注意不是 vLLM 的 :8000），客户端改
base_url即可接入；嵌入模型用--embedding起服务做 RAG。 - 完全本地、数据不出网——隐私/涉密/无网环境首选；
--grammar能用 BNF 约束输出格式，脚本化调用更稳。
常见问题
直接运行和 --server 有什么区别？
自带权重的可执行文件直接跑（./mistral.llamafile）会在 :8080 起一个浏览器能打开的 Web UI，适合演示和随手聊。--server --nobrowser 则是起 OpenAI 兼容的无头服务，不开浏览器，供程序通过 HTTP 调用。两者默认端口都是 8080。
默认端口是多少，接 OpenAI SDK 要改哪里？
默认 8080，注意这和 vLLM 常用的 8000 不同，抄别人配置时很容易踩。把 openai_api_base 指向 http://localhost:8080/v1 即可；用 curl http://localhost:8080/v1/models 确认服务真的起来了、暴露的模型名是什么。端口冲突时用 --server --port 改。
怎么用外部的 GGUF 权重，并控制速度？
用 -m 指定权重文件路径，例如 ./llamafile -m ~/weights/foo.gguf。速度靠 --n-gpu-layers 调：层数越多越快，也越吃显存，从能跑的层数往上加，显存不够时会直接加载失败。采样随机性用 --temp 控制。
脚本化调用时输出里混进了提示符和闲聊，怎么处理？
加 --no-display-prompt 去掉提示符噪声，剩下的就是模型正文。如果脚本还需要稳定的结构化输出，用 --grammar 写一段 BNF 把可选值限死，例如只允许 yes 或 no，这样每次返回都能被下游程序解析。
要做 RAG 或者看图，参数怎么加？
RAG 用嵌入服务：./embed.llamafile --server --embedding --port 8081，把端口和主服务错开避免冲突。多模态用 ./llamafile -m model.gguf --image photo.jpg -p "Describe this image"，这要求权重本身支持视觉，通常还需要配套的 mmproj 文件。
由 巧匠 维护
公开更新于 2026年8月23日，内容持续校对官方文档。