前言
llama-server 是 llama.cpp 中用于发布大模型服务的工具。它通过极简的命令行配置，将复杂的模型推理过程封装为通用的 HTTP 接口；在底层，它选择以纯 C++ 编写的 cpp-httplib 作为服务框架的底层。本章分为应用实战与底层架构两部分。首先，我们将介绍不同参数下的大模型服务发布；接着，我们将详细解析 cpp-httplib 在项目中的具体实现，帮助读者掌握该服务端在网络调度层面的运行逻辑。
1 应用实战：启动大模型服务
llama-server 是一款轻量级、兼容 OpenAI API、用于提供大语言模型服务的 HTTP 服务器。本节将在此基础上，进一步深入 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 相关地命令行可在终端环境下运行。
1.2.1 模型信息获取
服务:
llama-server -m gemma-3-1b-it-Q4_K_M.gguf --port 8080
请求:
curl http://127.0.0.1:8080/models
响应:
返回 JSON 格式数据，包含模型元信息。
1.2.2 Chat Completions
服务:
llama-server -m gemma-3-1b-it-Q4_K_M.gguf --port 8080
请求:
