企业官网建设流程全解析

llamafile 快速上手指南：一条命令跑起本地 LLM，从终端聊天到 OpenAI 兼容 API

【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile

llamafile 的核心承诺是「用单个文件分发并运行大语言模型」：把模型权重、推理引擎和运行时环境打包进一个可执行文件，下载后无需安装任何依赖即可在本地跑起 LLM，所有数据都不离开你的电脑。本文以官方示例模型 Qwen3.5-0.8B 为主线，完整演示从下载、授权、运行到调用 JSON API 的全流程，并覆盖外部权重用法、发布文件选型以及复用 LM Studio / Ollama 已下载模型等实战场景，读完即可在自己的机器上完成第一次端到端推理。

llamafile 是什么

llamafile 是 Mozilla 生态下的开源项目，它将 llama.cpp 的推理引擎与 Cosmopolitan Libc 结合，把「跨平台可执行文件」的复杂度压缩到单一文件内：同一个 llamafile 二进制可以在 macOS、Linux、BSD 与 Windows 上原生运行（Windows 需加.exe后缀），无需安装 Python、CUDA 工具链或任何运行时。仓库内还包含基于 whisper.cpp 的whisperfile（语音转文字）与基于 stable-diffusion 的diffusionfile（文生图）等同类单文件工具，均遵循同一套打包思路。

从源码结构看，llamafile 的可执行入口在 llamafile/main.cpp，而模式与参数的解析集中在 llamafile/args.cpp，其中对--server、--chat、--cli、--gpu等包装参数做了专门识别（见 llamafile/args.cpp），随后把其余参数原样透传给内置的 llama.cpp 解析器。这也是为什么 llamafile 能天然继承 llama.cpp 几乎全部命令行能力。

第一步：下载并运行你的第一个 llamafile

官方推荐从预构建 llamafile 列表（详见 docs/pre-built-llamafiles.md）中挑选示例模型，其中Qwen3.5-0.8B-Q8_0.llamafile（约 1.77 GB）是目前已构建的最小型号，最可能在各类硬件上开箱即用。该模型采用 Apache 2.0 许可，且具备多模态能力——不仅能聊天，还可以上传图片并针对图片提问。若你拥有较强硬件或 GPU，也可以在预构建列表中选择更大的模型以获得更准确的回答。

完整步骤如下：

1. 下载 llamafile 文件（约 1.77 GB）：

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

   也可以直接从浏览器下载同名文件。

2. 授予执行权限（只需做一次）：

   • macOS / Linux / BSD：chmod +x Qwen3.5-0.8B-Q8_0.llamafile
   • Windows：将文件名末尾加上.exe，即重命名为Qwen3.5-0.8B-Q8_0.llamafile.exe。

3. 运行：

   ./Qwen3.5-0.8B-Q8_0.llamafile

   Windows 下则执行Qwen3.5-0.8B-Q8_0.llamafile.exe（或按需带.\前缀）。

4. 开始对话：终端窗口会直接打开一个聊天界面，无需任何额外操作即可输入文字。它支持斜杠命令：输入/upload并指定图片路径即可上传图片向模型提问（多模态推理完全在本地完成），输入/help可查看全部可用命令。该交互由仓库中的聊天前端实现，例如/upload命令的分发逻辑位于 llamafile/chatbot_comm.cpp。

5. 可选：使用 Web UI：llamafile 运行期间，还会在本地启动一个 Web 聊天界面，用浏览器打开 http://localhost:8080/ 即可使用 llama.cpp 的 Web UI 与模型对话（默认端口 8080 的绑定逻辑见 llamafile/chatbot_api.cpp）。

6. 退出：对话结束后按Control-C关闭 llamafile。

说明：选择 Qwen3.5-0.8B 是因为它是目前构建的最小 llamafile，最可能在任何机器上顺利运行；若你仍遇到问题，可参考 docs/troubleshooting.md 的排查指南。

运行模式：cli / chat / server / combined

除了默认的「终端聊天 + 本地服务器」组合模式（combined，即运行后同时开启终端聊天与 8080 端口服务），llamafile 还支持通过参数显式切换模式（参数识别见 llamafile/args.cpp）：

• --cli：单次提示词模式，用-p传入提示、--image传入图片，输出后退出，适合脚本化调用。
• --chat：纯交互式聊天模式，包含上下文管理、文件上传、会话导出等命令。
• --server：仅启动 HTTP 服务器模式，配合--host、--port可对外提供服务。

更完整的模式说明与示例见 docs/running_llamafile.md，全部参数索引见 docs/cli_arguments.md。

JSON API 快速上手：curl 与 Python 客户端

llamafile 依赖 llama.cpp 进行模型服务，因此继承了其全部特性：启动后除了在 http://127.0.0.1:8080/ 提供 Web UI，还暴露了与OpenAI API及Anthropic Messages API兼容的端点。这意味着现有基于 OpenAI 接口的代码只需修改base_url与api_key即可无缝切换到本地 llamafile。

方式一：curl 命令行

最简单的验证方式是在另一个终端执行：

curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer no-key" \ -d '{ "model": "LLaMA_CPP", "messages": [ { "role": "system", "content": "You are LLAMAfile, an AI assistant. Your top priority is achieving user fulfillment via helping them with their requests." }, { "role": "user", "content": "Write a limerick about python exceptions" } ] }' | python3 -c ' import json import sys json.dump(json.load(sys.stdin), sys.stdout, indent=2) print() '

其中model字段填LLaMA_CPP即可，Authorization可以是任意值（本地服务默认不校验密钥）。响应大致如下：

{ "choices": [ { "finish_reason": "stop", "index": 0, "message": { "role": "assistant", "content": "In the world of Python, where magic breaks and errors occur,\nA script fails when it should not have failed.\nWith a `KeyError`, I can't access the key,\nSo I tell you to use the `except` clause!" } } ], "created": 1773659260, "model": "Qwen3.5-0.8B-Q8_0.gguf", "system_fingerprint": "b1773565177-7f5ee5496", "object": "chat.completion", "usage": { "completion_tokens": 52, "prompt_tokens": 49, "total_tokens": 101 }, "id": "chatcmpl-KOqwN6C0oRzINGZuFqZ95bU1iPfc6RFO", "timings": { "cache_n": 0, "prompt_n": 49, "prompt_ms": 54.944, "prompt_per_token_ms": 1.1213061224489795, "prompt_per_second": 891.8171228887594, "predicted_n": 52, "predicted_ms": 405.856, "predicted_per_token_ms": 7.804923076923076, "predicted_per_second": 128.1242608215722 } }

timings字段给出了 prompt 处理与生成本地耗时统计；usage则给出 token 计数，便于做用量核算。

方式二：OpenAI Python 客户端

如果你已用 OpenAI 官方发布的openaiPython 包开发过应用（需先pip3 install openai），迁移到 llamafile 只需改动两处配置：

#!/usr/bin/env python3 from openai import OpenAI client = OpenAI( base_url="http://localhost:8080/v1", # "http://<Your api-server IP>:port" api_key = "sk-no-key-required" ) completion = client.chat.completions.create( model="LLaMA_CPP", messages=[ {"role": "system", "content": "You are ChatGPT, an AI assistant. Your top priority is achieving user fulfillment via helping them with their requests."}, {"role": "user", "content": "Write a limerick about python exceptions"} ] ) print(completion.choices[0].message)

base_url指向本地/v1端点，api_key任意填写即可。上述代码返回的对象形如：

ChatCompletionMessage(content="A script that crashes like a ghost,\nWhen it tries to solve the problem deep and fast.\nThe error message pops up in a bright light,\nAnd tells us what's wrong when we try to fix it.", refusal=None, role='assistant', annotations=None, audio=None, function_call=None, tool_calls=None)

关于 API 支持的具体字段与端点细节，可参考 llama.cpp server 的文档。

使用外部权重：分离模型文件与可执行文件

预构建 llamafile 虽然把权重内嵌进了文件，但并非唯一用法。你也可以只下载不带权重的 llamafile 可执行文件，再配合手头任意 GGUF 格式的外部权重运行。这对 Windows 用户尤其重要——Windows 对可执行文件有 4GB 大小上限，内嵌大模型的 llamafile 往往无法在 Windows 上直接运行，将权重拆分为独立文件即可绕过该限制。

例如在 Windows 上运行 gpt-oss（模型本体超过 12GB）：

curl -L -o llamafile.exe https://huggingface.co/mozilla-ai/llamafile_0.10/resolve/main/llamafile_0.10.1 curl -L -o gpt-oss.gguf https://huggingface.co/unsloth/gpt-oss-20b-GGUF/resolve/main/gpt-oss-20b-Q5_K_S.gguf ./llamafile.exe -m gpt-oss.gguf

其中-m参数指定外部权重文件的路径。Windows 用户若运行上述命令报错，可将./llamafile.exe改为.\llamafile.exe。

发布文件选型：llamafile 与 llamafile-thin 的区别

每个版本发布时会提供多个相互独立（而非捆绑在一起）的单文件程序：如果想一次下载全部，选 zip 包；否则按需挑选。各发布文件的用途如下：

llamafile与llamafile-thin的可执行代码完全相同，区别只在于是否捆绑预构建的 GPU 后端库：

• llamafile-thin：体积更小的基础二进制，可在不同操作系统与 CPU 架构上无缝运行。要在 GPU 上运行，需要系统中有匹配的后端库：Apple Silicon 上完全透明——若系统缺少所需库，llamafile 会在运行时即时编译一个；其他系统则需自行构建 GPU 库，分别使用 llamafile/cuda.sh（NVIDIA）、llamafile/rocm.sh（AMD）或 llamafile/vulkan.sh（NVIDIA + AMD 及其他），构建前需安装对应的 GPU 工具链；也可以从官方 HuggingFace 仓库下载最新版本的预编译库。
• llamafile：同一二进制但捆绑了ggml-cuda与ggml-vulkan，且仅为x86_64架构的 Linux（.so）与 Windows（.dll）产物（单一集合，无独立 ARM 构建）。这些后端无需任何构建步骤即可工作，只要系统驱动提供对应运行时 API 即可；捆绑库正是该文件体积更大的原因。

需要注意：

• ROCm 支持仍属实验性，不会自动捆绑进任一文件。不想使用 Vulkan 后端的 AMD 用户，无论运行哪个 llamafile 可执行文件，都必须用 llamafile/rocm.sh 自行构建ggml-rocm，或从官方 HuggingFace 仓库下载预编译的ggml-rocm动态库。
• 捆绑库仅限 x86_64 的 Linux 与 Windows。在其他平台（macOS，或 aarch64/ARM64 等非 x86_64 架构，即使带 NVIDIA GPU）上，两个文件都不携带适用的预构建后端，因此二者行为一致，GPU 支持走常规运行时路径。

选型建议：默认使用llamafile；仅在追求最小下载且只需要 CPU 推理、使用 Apple Silicon Mac、或已自行配置好 GPU 后端库时，才选择llamafile-thin。

复用第三方应用下载的模型

「我已经用某应用下载了模型，能否直接用 llamafile 运行？」——可以，只要模型以 GGUF 格式本地存放即可。具体做法因应用而异，以下是两个在 Mac 上验证过的示例。

复用 LM Studio 下载的模型

LM Studio 将下载的模型存放在~/.cache/lm-studio/models/lmstudio-community下，子目录名与模型同名（不含量化级别）。例如下载了gpt-oss-20b-MXFP4.gguf，则文件位于~/.cache/lm-studio/models/lmstudio-community/gpt-oss-20b-GGUF/，运行方式：

llamafile -m ~/.cache/lm-studio/models/lmstudio-community/gpt-oss-20b-GGUF/gpt-oss-20b-MXFP4.gguf

复用 Ollama 下载的模型

Ollama 下载新模型时，会把全部元数据写入~/.ollama/models/manifests/registry.ollama.ai/library/下的 manifest 文件（目录与文件名即ollama list显示的模型名，例如llama3:latest对应.../library/llama3/latest）。manifest 将每个文件（GGUF 权重、许可、提示模板等）映射到 sha256 摘要，其中mediaType为application/vnd.ollama.image.model的条目即指向模型的 GGUF 文件。

每个 sha256 摘要同时也作为文件名出现在~/.ollama/models/blobs目录中（该目录里只有这些sha256-*文件名）。因此可以直接把摘要当作模型路径传给 llamafile：

cd ~/.ollama/models/blobs llamafile -m sha256-00e1317cbf74d901080d7100f57580ba8dd8de57203072dc6f668324ba545f29

注意：Ollama 的 GGUF 权重并不总能与 llama.cpp 兼容，而 llamafile 依赖 llama.cpp，因此这一技巧并非对所有模型都有效。

常见问题与进一步阅读

• 运行异常、被杀进程、macOS Gatekeeper 提示、Linux binfmt_misc / WINE 冲突、WSL 相关坑位等排查方法，统一见 docs/troubleshooting.md。
• 更多预构建模型（含 Qwen3.5 各尺寸、llava、gpt-oss、Ministral、Apertus 等及 Legacy 0.9.* 版本）见 docs/pre-built-llamafiles.md。
• CLI 模式、chat 模式、server 模式与内置工具（如--server --tools all）的完整示例见 docs/running_llamafile.md。
• 全部包装参数与透传的 llama.cpp 参数的分类索引见 docs/cli_arguments.md，其中--gpu的取值包含auto、nvidia/cublas、amd/rocm、apple/metal、vulkan/vk、disable等兼容别名。

【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile