资源描述
Llamafile CLI Runner 是一款轻量级命令行工具，可将开源大语言模型（如 Llama、Phi、Gemma 等）一键打包为单文件可执行程序，并在本地 CPU/GPU 上高效运行。支持 Q4_K_M 等主流量化格式、CUDA/Vulkan 加速、内置 HTTP API 服务及 system prompt 注入，适用于开发者快速原型验证、离线推理与私有化部署。
详细内容
# Llamafile CLI Runner
## 工具定位与核心价值
Llamafile CLI Runner（简称 `llamafile`）是由 Janus Research 团队开发的开源工具，其核心理念是「模型即二进制」——将 LLM 模型、推理引擎（llama.cpp）、权重文件与运行时依赖全部打包为单一跨平台可执行文件（`.llamafile`）。无需 Python 环境、不依赖包管理器，开箱即用，显著降低本地 LLM 部署门槛，兼顾安全性（无网络外连）、隐私性（完全离线）与便携性（U 盘即跑）。
## 主要功能列表
- ✅ **单文件封装**：自动下载/转换模型权重，生成自包含 `.llamafile` 可执行文件（Linux/macOS/Windows x64/arm64）
- ✅ **多后端加速**：默认启用 llama.cpp，支持 CUDA（NVIDIA）、Vulkan（AMD/Intel GPU）、Metal（macOS）及纯 CPU 推理
- ✅ **高效量化支持**：原生兼容 GGUF 格式，推荐 Q4_K_M（平衡精度与内存占用），亦支持 Q5_K_M、Q6_K、Q8_0 等量化级别
- ✅ **HTTP API 服务**：内置 `/v1/chat/completions`、`/v1/completions` 等 OpenAI 兼容接口，支持 streaming、temperature、max_tokens 等参数
- ✅ **系统提示注入**：通过 `--system-prompt "..."` 参数或环境变量 `LLAMA_SYSTEM_PROMPT` 动态设定角色指令
- ✅ **资源可控**：支持显存/内存限制（`--gpu-layers`、`--numa`）、线程数控制（`--threads`）、上下文长度配置（`--ctx-size`）
## 典型使用场景
- 🔧 **本地开发调试**：快速加载不同模型（如 `phi-3-mini`, `tinyllama`, `gemma-2b`）进行 prompt 工程测试
- 🛡️ **企业内网部署**：在无外网环境的服务器或终端设备上运行私有模型，满足数据合规要求
- 📦 **边缘设备推理**：在低配笔记本、NUC 或树莓派等设备上运行量化模型（Q4_K_M + CPU）
- 🌐 **API 快速托管**：作为轻量级替代方案，替代 Ollama 或 LM Studio，提供标准 OpenAI API 接口供前端调用
## 上手步骤与操作要点
1. **获取 llamafile**：从 [GitHub Releases](https://github.com/jart/llamafile/releases) 下载对应平台的 `llamafile` 二进制（如 `llamafile-0.9.2-x86_64-linux`），赋予可执行权限：`chmod +x llamafile`
2. **运行预编译模型**：直接执行官方提供的 `.llamafile` 文件（如 `./phi-3-mini-4k-instruct.Q4_K_M.llamafile`），自动启动 HTTP 服务（默认 `http://localhost:8080`）
3. **自定义打包模型**：
```bash
# 下载 GGUF 模型（如来自 Hugging Face）
wget https://huggingface.co/jart/phi-3-mini-4k-instruct-GGUF/resolve/main/phi-3-mini-4k-instruct.Q4_K_M.gguf
# 打包为 llamafile（含 HTTP 服务）
./llamafile --file phi-3-mini-4k-instruct.Q4_K_M.gguf --name phi3-mini --quantize Q4_K_M
```
4. **启动并调用**：
```bash
# 启动服务（指定 GPU 层、系统提示、端口）
./phi3-mini.llamafile --gpu-layers 20 --system-prompt "你是一个严谨的技术助手" --port 3000
# 使用 curl 测试
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"phi3-mini","messages":[{"role":"user","content":"你好，请介绍自己"}]}'
```
> 💡 提示：首次运行会自动下载基础运行时（约 20MB），后续启动秒级响应；可通过 `--verbose` 查看详细日志；所有模型文件均保留在本地，不上传至任何远程服务。