llama-server：支持本地OpenAI API的 llama.cpp

#为什么选择 llama-server？

Ollama, LM Studio 或 Jan 均基于相同的底层引擎：llama.cpp。该引擎内置了自身 HTTP 服务器 llama-server，无需依赖其他层级。只需指定一个 GGUF 文件，即可获得 API 和 Web 界面。无需额外操作。

其价值并不只是表面上的。Ollama 会替您决定将多少层交给 GPU、上下文长度以及如何拆分模型，而 llama-server 则通过命令行开放每一个参数。您可以看到实际运行情况，并自行调整。这就是本地 AI 的“手动模式”——需要写更多命令和参数，但没有黑箱。

兼容 OpenAI 的 API

接口 /v1/chat/completions, /v1/completions, /v1/models, /v1/embeddings。任意 OpenAI 客户端无需修改即可接入。

控制模型层向 GPU 的卸载（offloading）

--n-gpu-layers 严格指定进入VRAM的层数。当模型超过显存容量时必不可少。

内置网页界面

直接通过服务器根路径提供的聊天界面，无需安装 Open WebUI 或 Docker。

无需重量级依赖

仅一个二进制文件（几十MB）。无需Python、容器或系统服务。

批处理与并行处理

连续批处理默认启用，通过多个槽位支持并发请求。

#先决条件

一个GGUF格式文件

llama.cpp 的格式。可从 Hugging Face 获取，或通过 llama-server 的 -hf 参数直接下载（详见下文）

VRAM或RAM

在Q4_K_M量化下，3B模型约需2 GB，7B模型约需5 GB，14B模型约需9 GB，32B模型约需19 GB，70B模型约需40 GB。

一块 GPU（强烈推荐）

RTX 3060 12 GB 用于入门，RTX 4070/4080 用于中端，RTX 4090 24 GB 或 Mac M4 Pro 用于大模型。仅使用 CPU 可运行，但速度较慢。

一个终端

llama-server 通过命令行操作。这并不难掌握，但它不像 LM Studio 那样是双击就能启动的应用。

#1. 获取 llama-server

有三种方式，从最省时的到性能最佳的。在 macOS 上，Homebrew 只需一条命令即可安装二进制程序：

brew install llama.cpp

# le binaire s'appelle llama-server
llama-server --version

在 Windows 和 Linux 上，最简单的方法是从 llama.cpp 的官方 GitHub 发布版本中获取预编译二进制文件（请选择与您的硬件相匹配的版本：CUDA 适用于 NVIDIA，Vulkan 适用于通用 GPU，CPU 适用于 CPU）。

https://github.com/ggml-org/llama.cpp/releases

要获得最高的每秒 token 数，请使用与您的 GPU 对应的后端从源码编译。以 NVIDIA GPU 搭配 CUDA 为例：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

# le binaire se trouve dans build/bin/
./build/bin/llama-server --version

#2. 通过单条命令启动一个GGUF模型

最简命令指定一个模型并启动服务器。这里使用的是 Q4_K_M 量化的 Qwen 3.5 9B（2026 年 8 GB 显存配置的标杆选择，256k 上下文），所有层均放到 GPU 上运行：

llama-server -m ./qwen3.5-9b-instruct-q4_k_m.gguf -ngl 99 -c 8192

-m

用于提供模型服务的 GGUF 文件路径。

-ngl 99

在GPU上卸载的层数。99 = 「全部」（模型层数更少则以实际层数为准，多余部分被忽略且不报错）

-c 8192

上下文长度（以 token 计）。默认通常为 4096；请根据实际需求和 VRAM 进行调整。

您手头没有文件？llama-server可直接从Hugging Face下载并缓存该文件，如同 ollama pull mais 集成功能一样：

llama-server -hf bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M -ngl 99 -c 8192

启动后，服务器默认监听 http://127.0.0.1:8080。请确认它正在运行：

curl http://localhost:8080/health
# {"status":"ok"}

#3. 兼容 OpenAI 的 API：可连接任意应用程序

这是 llama-server 的核心优势。它支持 OpenAI 协议，因此任何为 OpenAI API 设计的工具，只需简单修改基础 URL 即可兼容。通过 curl 直接调用聊天接口：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Explique le format GGUF en une phrase."}
    ],
    "temperature": 0.7
  }'

model 字段可以任意填写：llama-server 一次只提供一个模型的服务，基本上会忽略这个值。使用 OpenAI 的 Python SDK 时，只需将 base_url 指向您的服务器。如果没有设置 --api-key，API 密钥可以是任意字符串：

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="local",
    messages=[
        {"role": "user", "content": "Donne-moi trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

/v1/chat/completions

对话模式，自动应用该模型的聊天模板。

/v1/completions

原始文本补全，不使用角色格式。

/v1/models

列出已加载的模型——方便那些会先查询可用模型的客户端使用。

/v1/embeddings

如果服务器启动时使用了 --embedding，则生成嵌入向量（方便构建自己的 RAG 系统）。

#4. n-gpu-layers：Ollama 隐藏的精细化 GPU 卸载控制

模型由多层（layers）堆叠而成。放入显存的每一层都由 GPU 计算，速度很快；留在系统内存中的层则由 CPU 计算，速度较慢。--n-gpu-layers（或 -ngl）决定有多少层放到 GPU 上。这是影响速度最重要的设置。

-ngl 99

全部放在 GPU 上。如果模型能完全装入显存，应优先采用这种配置。速度最快。

-ngl 20

部分卸载：20 层在 GPU 上运行，其余层在 CPU 上运行。这是模型所需显存超过 VRAM 容量时的折中方案。

-ngl 0

全部在 CPU 上运行。速度较慢，但能运行远超显卡容量的模型。

策略是：在不占满显存的前提下，尽可能提高 -ngl 的值。Q4 量化的 14B 模型（约 9 GB）在设置 -ngl 99 时，可以完整放入配备 12 GB 显存的 RTX 3060。Q4 量化的 Qwen 3.8 27B（约 18 GB）则放不下；在同一张显卡上，只能将部分模型层卸载到 GPU——例如设置 -ngl 40——并接受运行速度下降。

# Qwen 3.8 27B Q4 (~18 Go) sur un GPU 12 Go : une partie sur GPU, le reste sur CPU
llama-server -m ./qwen3.8-27b-instruct-q4_k_m.gguf -ngl 40 -c 4096

为监控模型加载时实际占用的VRAM，请在另一窗口中持续关注nvidia-smi：

nvidia-smi -l 1

#5. 内置网页界面

无需 Open WebUI 也无需 Docker 即可进行对话：llama-server 直接在根路径提供聊天界面。只需在浏览器中打开服务器地址即可。

http://localhost:8080

这里提供完整的聊天界面：包含对话历史、温度和采样参数设置、系统提示词功能，以及 Markdown 渲染。它足以满足个人日常使用，无需安装任何额外组件。

#何时应优先选择 llama-server，何时应继续使用 Ollama

llama-server 和 Ollama 运行相同的引擎。选择本质上是控制力与便利性的权衡。

选择 llama-server

当您想精细调整卸载设置、测试由某个指定量化方提供的特定 GGUF、避免常驻守护进程，或在服务器上部署一个无需依赖的单一二进制文件时。

选择 llama-server

当模型超出您的VRAM时：直接控制-ngl参数及内存选项，将决定模型是‘无法运行’还是‘运行缓慢但可工作’。

继续使用Ollama

当你需要随时在多个模型之间切换，无需重启进程，通过 ollama pull/list 管理模型库，或根据需求自动加载/卸载模型时。

继续使用Ollama

当多个应用通过同一个 11434 端口访问不同模型时，Ollama 会为您处理请求路由和模型切换，而 llama-server 的每个进程只运行一个模型。

#故障排除

加载时出现「CUDA out of memory」

您的 -ngl 设置过高，超出了显存容量。请降低该值（仅将部分层卸载到 GPU），减小 -c，或改用更轻量的量化方式（用 Q4_K_M 替代 Q5/Q8）。

GPU 未被使用

您使用的二进制程序可能是 CPU 版本。请检查是否使用了 CUDA/Metal/Vulkan 构建版本，以及 -ngl 是否大于 0。nvidia-smi 应显示有显存被占用。

回答不连贯或出现可见标记

聊天模板未生效。请使用 --jinja 参数重新启动，以启用GGUF文件内嵌的模板。

客户端未找到模型

有些客户端会先查询 /v1/models。请使用 -a 设置别名，并在应用的 model 字段中填写这个完全一致的名称。

上下文截断 / 响应截断

-c 设置过小。请增大上下文长度，但需注意大上下文会消耗更多 VRAM。

#深入了解

编译得当的 llama.cpp 和精心选择的 GGUF 才能充分发挥 llama-server 的价值。本网站的以下指南可作为部署过程的补充：

使用 CUDA 编译 llama.cpp

用于获得针对 NVIDIA 优化的二进制程序，并让您的显卡达到最高的每秒 token 数。

Q4、Q5、Q8：选择哪种量化

在下载 GGUF 模型前，用于权衡质量、速度与 VRAM。

llama.cpp 与 vLLM、Exllama 对比

帮助您根据吞吐量需求，比较 llama-server 与其他推理引擎。