1.2 基础使用：首次运行和基本操作

1.2 基础使用：首次运行和基本操作

本节导读：环境就绪后，本节带你完成Llamafile的"第一次对话"——从命令行交互模式到浏览器图形界面，再到OpenAI兼容API调用，三种使用方式一次讲透。

学习目标

• 掌握Llamafile的两种启动方式（对话模式与服务模式）
• 学会使用内置Web界面进行对话交互
• 能够通过OpenAI兼容API从其他程序调用本地模型
• 了解多文件llamafile的加载方法

核心概念

Llamafile有两种典型运行形态：

• 对话模式：直接运行文件，进入终端命令行对话（类似llama.cpp的main程序），适合快速验证；
• 服务模式：添加 --server 参数后，在本地启动HTTP服务（默认端口8080），同时提供Web聊天界面与OpenAI兼容API，适合日常使用和程序集成。

llamafile
   ├── 直接运行 ──→ 终端对话模式（CLI REPL）
   └── --server ──→ HTTP服务
                      ├── 浏览器打开 http://127.0.0.1:8080 → Web聊天界面
                      └── POST /v1/chat/completions        → OpenAI兼容API
​

分步实战

步骤 1：首次启动（对话模式）

# Linux / macOS
chmod +x qwen2.5-7b-instruct-q4_k_m.llamafile   # 首次赋权
./qwen2.5-7b-instruct-q4_k_m.llamafile          # 进入终端对话

# Windows
.\qwen2.5-7b-instruct-q4_k_m.llamafile
​

启动后会看到模型加载进度。加载完成后出现 > 提示符，直接输入问题回车即可对话：

> 用一句话介绍你自己
我是一个开源的大语言模型，运行在你自己的电脑上，数据不出本机。
​

常用交互指令：输入 /exit 或按 Ctrl+C 退出；生成过程中按 Ctrl+C 可中断当前输出。

步骤 2：切换到服务模式（推荐日常使用）

./qwen2.5-7b-instruct-q4_k_m.llamafile --server
​

看到 please browse http://127.0.0.1:8080 字样即启动成功。浏览器打开该地址，即可使用内置Web聊天界面——支持多轮对话、对话历史管理、生成参数调节面板。

步骤 3：通过API调用（程序集成）

Llamafile服务模式暴露OpenAI兼容端点，任何为OpenAI API编写的代码只需替换base_url即可：

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="sk-no-key-needed")

resp = client.chat.completions.create(
    model="local",
    messages=[
        {"role": "system", "content": "你是一个简洁的中文技术助手。"},
        {"role": "user", "content": "什么是内存映射？"}
    ],
    temperature=0.7,
)
print(resp.choices[0].message.content)
​

等价的curl调用：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "你好"}],
    "temperature": 0.7
  }'
​

步骤 4：加载外部权重文件（多文件形态）

Windows下超过4GB的模型通常拆分为"引擎+权重"两部分，用 -m 指定权重路径：

./llamafile.exe -m qwen2.5-14b-q4_k_m.gguf --server
​

基本操作速查表

常见问题 FAQ

Q1：启动服务后浏览器打不开页面？
依次检查：端口是否被占用（换 --port）；防火墙是否拦截；确认终端日志出现 please browse 字样而非报错信息。

Q2：API调用返回连接拒绝？
确认客户端访问的地址端口与服务监听一致；若从其他机器访问，服务需以 --host 0.0.0.0 启动。api_key 任意非空字符串即可（本地服务默认不校验）。

Q3：模型加载很慢正常吗？
首次加载需把权重读入内存，机械硬盘上40GB级模型可能需要数分钟。SSD与更大内存（启用内存映射缓存）可显著改善。

最佳实践与避坑

• 避坑一：--host 0.0.0.0 会把模型服务暴露给局域网，公共网络环境慎用，或配合防火墙限制来源IP；
• 避坑二：对话模式与服务模式不要同时双击启动同一文件，会重复占用数GB内存；
• 实践：日常使用建议固定用服务模式+浏览器界面，体验接近云端产品且完全离线。

本节小结

Llamafile把"用上大模型"的门槛压缩到了一次双击：对话模式适合快速验证，服务模式（Web界面+OpenAI兼容API）适合日常使用与程序集成。下一节将深入参数配置，解决"跑得慢、占内存、答得偏"三大问题。

延伸阅读

• Llamafile命令行参数文档
• 相关章节：1.3 参数配置、3.1 API服务部署

关键词：Llamafile, 首次运行, 服务模式, Web界面, OpenAI兼容API, 本地大模型
难度：入门
预计阅读：20分钟