前言
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
请求:


