llamafile 完整指南：单文件部署本地 LLM，从下载到接 API 只要 5 分钟

llamafile 完整指南单文件部署本地 LLM从下载到接 API 只要 5 分钟【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile你在客户现场对方递来一台没装任何环境的笔记本只丢给你一个.llamafile文件跑起来我们要一个 AI 接口。 没有 Python、没有 Docker、没有 CUDA 安装脚本——这正是 llamafile 的设计目标把大语言模型LLM的模型权重和运行时打包进一个可执行文件本地运行、即开即用。本文是一份完整的 llamafile 使用教程讲清它为什么只有一个文件、给你一条 30 秒上线路径并按你想拿它做什么拆解四种典型用法最后附上调参与避坑清单。为什么一个文件就是一整套 AI 服务一句话定位llamafile 是 Mozilla 开源项目将 llama.cpp 推理引擎、模型权重和默认参数打包为单个跨平台可执行文件实现用一个文件分发并运行 LLM。它的几个核心卖点换个角度理解就是免安装不依赖系统里的 Python、库或显卡驱动环境GPU 相关代码在首次运行时按需现场编译见 llamafile/cuda.c、llamafile/metal.c。一份二进制跑多平台同一个文件在 Windows、macOS、Linux 上直接执行AMD64 与 ARM64 通吃。数据不出机器所有推理在本地完成敏感数据不经过任何云端。可打开检查它本质是 APE 格式的可执行文件内嵌 ZIP用unzip -vl xxx.llamafile就能看到里面打包了什么。底层原理APE 格式 mmap()内存映射权重可深入阅读官方文档 docs/technical_details.md。30 秒首次体验三条命令跑通 最快的上手路径只有三步——下载、给权限、运行# 1. 下载官方示例 llamafileQwen3.5-0.8B约 1.77 GB # 下载地址与更多预构建模型见 docs/quickstart.md # 2. 赋予执行权限macOS / LinuxWindows 用户改为给文件名加 .exe 后缀 chmod x Qwen3.5-0.8B-Q8_0.llamafile # 3. 运行 ./Qwen3.5-0.8B-Q8_0.llamafile运行后终端直接进入交互式聊天同时自动在http://localhost:8080启动 Web 界面——两种入口同时可用。完成后按Ctrl-C退出。完整步骤说明见 docs/quickstart.md。按使用目的选玩法四种典型场景场景 A终端里聊天顺便让它看图最新的 llamafile 默认是组合模式终端聊天 8080 端口服务同时启动。聊天中可以用/upload上传本地图片提问输入/help查看全部命令。想脚本化地问一张图直接用--cli模式./your-model.llamafile --cli --image ~/Pictures/demo.jpg -p 用一句话描述这张图片更多模式差异--chat/--cli/ 默认组合见 docs/running_llamafile.md。场景 B浏览器里用 Web 聊天界面无需任何额外操作运行后打开http://localhost:8080即可这是继承自 llama.cpp 的完整 Web UI支持多轮会话、参数在线调整。场景 C给内部工具接一个 OpenAI 兼容 APIllamafile 服务端同时暴露 OpenAI 与 Anthropic 风格接口现有应用改个base_url就能接进来。启动时指定网络监听./your-model.llamafile --server --host 0.0.0.0 --port 8081Python 端最小接入示例from openai import OpenAI client OpenAI(base_urlhttp://localhost:8081/v1, api_keyno-key) print(client.chat.completions.create( modellocal, messages[{role: user, content: 用一句话介绍 llamafile}], ).choices[0].message.content)要给 AI Agent / 框架供模型建议加--jinja并把--ctx-size调大到内存允许的范围。场景 D用你已有的 GGUF 权重不必非得用官方预打包文件。下载独立版 llamafile 运行时后-m指向任意 GGUF 文件即可外部权重模式还能绕开 Windows 的 4GB 文件限制llamafile -m Qwen3.5-9B-Q5_K_S.gguf -ngl 9999进阶玩法调参、打包与源码构建常用参数速查参数作用-ngl N/--gpu-layers卸载到 GPU 的层数9999表示尽量多--gpu auto/nvidia/amd/apple/vulkan显式选择 GPU 后端auto为自动-c N/--ctx-size上下文窗口大小--host/--port服务监听地址与端口-t NCPU 生成线程数完整参数分模式罗列--server --help、--chat --help、--cli --help见 docs/cli_arguments.md。打包自己的 llamafile有 GGUF 权重 一个.args默认参数文件用项目自带的zipalign工具就能把两者塞进同一个可执行文件流程详见 docs/creating_llamafiles.md。从源码构建含 Windows CUDA需要定制编译时git clone https://gitcode.com/GitHub_Trending/ll/llamafile cd llamafile makeWindows 下用 Visual Studio 构建 CUDA 版本的参考界面如下源码安装细节见 docs/source_installation.md。用 LocalScore 给你的硬件打个分仓库里附带 localscore/ 基准工具能测出你的机器跑 LLM 的实际 tokens/s帮你判断该选多大的模型避坑指南最容易卡住的四个地方 ⚠️Windows 4GB 上限Windows 拒绝执行超过 4GB 的二进制大模型请走独立运行时 外部 GGUF 权重模式上节场景 D。macOS 提示开发者无法验证去 系统设置 → 隐私与安全性 里允许运行Apple Silicon 首次运行还需安装 Xcode 命令行工具。老版本 zsh 有兼容 bug可改用sh -c ./xxx.llamafile启动。Linux 报run-detectors/WINE 相关错误是binfmt_misc未注册 APE 格式按 docs/troubleshooting.md 中的三行注册命令处理即可。内存不足直接 OOM先降量化等级Q8 → Q4_K或减小模型规格再谈调参。适合谁 / 不适合谁适合不适合快速分发演示、内网离线环境、隐私敏感场景需要多租户高并发生产服务请直接用 llama.cpp server不想维护依赖环境的开发者和终端用户追求极限性能、需要频繁换权重的重度微调场景选型建议与下一步行动清单模型怎么选首次体验用最小的 0.8B 示例验证环境有独显或大内存再上 7B–9B 的 Q4_K/Q5_K 量化追求质量上 Q8。原则文件越小越省心显存越大越从容。行动清单按 docs/quickstart.md 下载最小示例模型完成 30 秒启动打开http://localhost:8080熟悉 Web 界面加--server --host 0.0.0.0让局域网内应用通过 OpenAI 兼容 API 接入用-m换上你自己的 GGUF 权重或按 docs/creating_llamafiles.md 打包一个专属 llamafile 分发给同事。遇到问题时第一站永远是 docs/troubleshooting.md想了解构建体系与版本演进可阅读 README_0.10.0.md。【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考