llama-server - 从命令行到HTTP Server

前言

llama-server是llama.cpp中用于发布大模型服务的工具。它通过极简的命令行配置，将复杂的模型推理过程封装为通用的 HTTP 接口；在底层，它选择以纯 C++ 编写的 cpp-httplib 作为服务框架的底层。本章分为应用实战与底层架构两部分。首先，我们将介绍不同参数下的大模型服务发布；接着，我们将详细解析 cpp-httplib 在项目中的具体实现，帮助读者掌握该服务端在网络调度层面的运行逻辑。

---

目录

• 1 应用实战：启动大模型服务
• 2 架构解析：基于cpp-httplib的运行机制

---

1 应用实战：启动大模型服务

llama-server是一款轻量级、兼容 OpenAI API、用于提供大语言模型服务的 HTTP 服务器。在上节中，我们启动了llama-server，构建了本地的大模型服务。本节将在此基础上，进一步深入llama-server启动过程的参数设置，同时演示如何利用curl工具发起网络请求，以实测并验证服务的接口响应。

1.1 模型服务参数设置

llama-server支持自定义端口号，发布大模型服务。如下，llama-server通过--port参数设置端口号为8080。

llama-server -m gemma-3-1b-it-Q4_K_M.gguf  --port 8080

llama-server 支持多用户并行解码。多用户并行解码是指模型服务器通过资源切分，同时处理多路独立的用户推理请求，以实现任务的高并发生成。如下所示，llama-server 通过 -np 参数设置模型服务的并发请求数为 4，并配合 -c 参数指定全局最大上下文长度为 16384 个 Token，这意味着总上下文空间将被划分为 4 个独立的槽位(Slots)，使每个并发请求所能占用的最大上下文配额为 4096 个 Token。

llama-server -m gemma-3-1b-it-Q4_K_M.gguf -c 16384 -np 4

llama-server支持推测解码。推测解码是一种利用小型"草稿模型"先行预测、并由大型'主模型'进行并行验证，从而在不损耗生成质量的前提下显著提升推理效率的技术。如下，llama-server通过参数指定"草稿模型"，辅助-m指定的"主模型"进行推理。

llama-server -m gemma-3-1b-it-f16.gguf -md gemma-3-1b-it-Q4_K_M.gguf

llama-server 支持启用文本嵌入(embedding)模式。在此模式下，服务端用于接收文本输入并输出对应的特征向量，以实现对文本语义的数值化表征。如下所示，llama-server 通过添加 --embedding 标记激活该模式，并配合 --pooling cls 参数指定使用 CLS 池化策略来提取文本特征，同时利用 -ub 8192 参数将物理批处理大小(ubatch-size)设为 8192，以优化大规模文本处理时的执行效率。

llama-server -m gemma-3-1b-it-f16.gguf --embedding --pooling cls -ub 8192

llama-server 支持启用重排序(Reranking)模式。在此模式下，服务端将开放重排序接口，用于接收查询请求及多个候选文档片段，并输出该查询与各片段之间的相关性分值。如下，llama-server通过添加--reranking标记启用重排序模式。

llama-server -m gemma-3-1b-it-f16.gguf --reranking

1.2 模型服务请求

本小节将利用 curl 工具发起的网络请求，除涉及针对上节配置端口的基础访问以及重排序(Reranking)服务请求外，还将重点涵盖兼容 OpenAI 标准的接口调用，包括对话补全(Chat Completions)、数据响应(Responses)及文本嵌入(Embeddings)三类标准网络请求。其中curl工具(curl.exe)需读者自行下载，curl相关地命令行可在vscode中TERMINAL->Git Bash环境下运行，如下图所示，vscode中TERMINAL->Git Bash环境打开过程。

1.2.1 模型信息获取

服务:

llama-server -m gemma-3-1b-it-Q4_K_M.gguf  --port 8080

请求：

curl http://127.0.0.1:8080/models

响应：

1.2.2 Chat Completions

服务:

llama-server -m gemma-3-1b-it-Q4_K_M.gguf  --port 8080

请求：

curl.exe http://127.0.0.1:8080/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{
         "messages": [
         {
             "role": "user",
             "content": "Hello!"
          }
          ]
       }'

响应：

返回内容为json字符串，其中"choices"->"messages"->"content"为模型返回的对话内容。

1.2.3 Responses

服务:

llama-server -m gemma-3-1b-it-Q4_K_M.gguf  --port 8080

请求：

curl.exe  http://127.0.0.1:8080/v1/responses \
                  -H "Content-Type: application/json" \
                  -d '{
                    "input": "Hello!"
                  }'

响应：

返回内容为json字符串，其中"output"->"content"->"text"为模型返回的对话内容。

1.2.4 Embeddings

服务:

llama-server -m gemma-3-1b-it-f16.gguf --embedding --pooling cls -ub 8192

请求：

  curl.exe http://127.0.0.1:8080/v1/embeddings \
     -H "Content-Type: application/json" \
     -d '{
        "input": "Hello!",
        "encoding_format": "float"
     }'

响应：

返回内容为json字符串，其中"data"->"embedding"为模型返回文本嵌入向量，维度为1*1152。

1.2.5 Reranking

为了确保重排序(Reranking)服务的效果，本文选用轻量且专业的 jina-reranker-v1-tiny-en 模型进行本地快速实验，可通过 Hugging Face 官方仓库或国内镜像站(hf-mirror.com)将其克隆至本地。

git clone https://huggingface.co/jinaai/jina-reranker-v1-tiny-en
git clone https://hf-mirror.com/jinaai/jina-reranker-v1-tiny-en#镜像地址

随后，利用 llama.cpp 提供的工具链将模型转换为 GGUF 格式。首先定位至 llama.cpp 源码目录并配置所需的 Python 环境依赖；接着执行转换脚本convert_hf_to_gguf.py，将jina-reranker-v1-tiny-en模型完整输出为 jina.gguf。具体执行命令如下。一个已转换好的模型jina.gguf可从此下载。

cd llama.cpp
pip install -r requirements.txt
python convert_hf_to_gguf.py ./jina-reranker-v1-tiny-en/ --outfile jina.gguf

服务:

llama-server -m jina.gguf --reranking

请求：

curl.exe http://127.0.0.1:8080/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "some-model",
    "query": "How much does a catty of apples cost?",
    "top_n": 3,
    "documents": [
      "Apples are red.",
      "Apples are a type of fruit.",
      "Apples cost 3 yuan per catty.",
      "Apple leaves are oval or broadly elliptical."
    ]
  }'

响应：

返回内容为json字符串，包含排名前三的返回内容。其中第三个(index为2)得分最高。

2 架构解析：基于cpp-httplib的运行机制

在上篇文章(初识llama.cpp - 轻量级推理引擎-CSDN博客)的最后，我们在浏览器中通过http://127.0.0.1:8080访问可视化交互界面，正式开启与本地大模型的零延迟对话体验。本机将深入llama-server与前端(UI)的交过过程，llama-server选择了轻量级的头文件库cpp-httplib作为llama-server的通信底层依赖，本节将深入代码具体的实现，探讨基于cpp-httplib的模型服务运行机制,进一步理解用户从输入对话文本到界面响应对话的交互逻辑。

具体的代码实现将涉及到llama-server、server-context、cpp-httplib(底层依赖)三个项目。整体的架构如下图所示：

整体的架构主要分为server_http_context与server_context，其中server_http_context用于接收用户输入文本以及向用户返回模型推理的结果(以文本的形式返回)，server_context用于对模型的推理进行管理。

server_context通过server_response_reader将模型推理生成的文本(Token)传递给server_http_context，而server_http_context通过httplib::DataSink将模型推理实时生成的文本以流式传输(streaming)的形式返回到客户端(UI)，相较于传统的一次性整体响应，这种流式机制允许服务端将生成的Token实时推送到界面，从而确保了从用户输入到指令响应的极速交互体验。同时server_http_context将用户请求转换为模型推理的任务server_task，为后端模型推理提供输入。

在 llama-server 项目中，通过为 httplib::Server 注册POST和GET类型的回调函数，实现了对特定网络请求的处理与响应。注册的回调函数如下：

其中横线处的文字表示网络请求名称。以get_health为例，用户可通过http://127.0.0.1:8080/health网络地址请求，而服务器则由get_health方法处理并响应，果如下图所示：

文末

本文深入讲解了llama-server，从命令行到HTTP Server的过程，具体地从"应用实战:启动大模型服务"与"结构解析:基于cpp-httplib的运行机制"两方面说明，从工具的使用到模型服务框架的代码具体实现，由浅入深地说明了从用户输入对话文本到界面响应对话的交互逻辑。在下一章中，我们将进一步探索在接收用户输入后，模型推理前的核心准备环节------模型加载与初始化。