llama.cpp llama-server 完全指南：构建 OpenAI 兼容的本地 LLM 推理 HTTP 服务

【免费下载链接】llama.cpp LLM inference in C/C++ 【免费下载链接】llama.cpp 项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

本篇技术指南以 llama.cpp 仓库中 tools/server/ 模块的官方文档为主体，系统讲解 llama-server 的构建与启动、三大类命令行参数、完整的 REST API 端点（原生与 OpenAI/Anthropic 兼容）、多模型路由模式、服务器工具与 MCP 集成，以及空闲休眠等运维特性。读完后你能够独立部署一个生产可用的本地推理服务，理解其插槽（slot）并行与连续批处理的工作机制，并会用源码中的路由注册与测试套件验证各个端点行为。

一、llama-server 是什么

llama-server 是 llama.cpp 内置的 HTTP 推理服务器，基于纯 C/C++ 的 httplib、nlohmann::json 和 llama.cpp 库构建，没有任何 Python 运行时依赖。它同时提供一组 LLM REST API 和一个开箱即用的 Web UI，可用于与模型交互。

从 tools/server/server-http.cpp 可以看到，服务器内部就是一个 httplib::Server 实例（在启用 OpenSSL 时换成 SSL 变体），路由注册分散在 tools/server/server.cpp（核心端点）与 tools/server/server-models.cpp（路由/模型管理端点）中。

官方文档列出的核心特性（见 tools/server/README.md）：

  • GPU 与 CPU 上对 F16 及量化模型进行 LLM 推理；
  • OpenAI 兼容的 chat completions、responses、embeddings 路由；
  • Anthropic Messages API 兼容的聊天补全；
  • Reranking 端点；
  • 多用户并行的多插槽解码（-np/--parallel）；
  • 连续批处理（continuous batching）；
  • 多模态输入，并带 OpenAI 兼容 API 支持（详见 docs/multimodal.md）；
  • 监控端点（/slots、Prometheus 风格 /metrics）;
  • 基于 JSON Schema 的受约束响应格式；
  • 类似 Claude API 的 assistant 消息预填充（prefill）；
  • 面向几乎任意模型的 function calling / tool use（详见 docs/function-calling.md）；
  • 投机解码（speculative decoding，draft / ngram 等多种类型）；
  • 易用的 Web UI。

二、构建与启动

使用 CMake 构建

llama-server 随项目其余目标一起从仓库根目录构建：

cmake -B build
cmake --build build --config Release -t llama-server

生成的二进制位于 ./build/bin/llama-server。构建目标声明在 tools/server/CMakeLists.txt。

启用 SSL

llama-server 可以使用 OpenSSL 3 构建出支持 HTTPS 的版本：

cmake -B build -DLLAMA_OPENSSL=ON
cmake --build build --config Release -t llama-server

构建后配合 --ssl-key-file 与 --ssl-cert-file 两个 PEM 文件参数即可提供 TLS 服务。

快速启动

# Linux / macOS
./llama-server -m models/7B/ggml-model.gguf -c 2048

# Windows
llama-server.exe -m models\7B\ggml-model.gguf -c 2048

上述命令启动的服务默认监听 127.0.0.1:8080。你可以用 Postman、axios 或 curl 消费其端点，也可以在同一 URL 上直接打开 Web 前端。

Docker 部署

docker run -p 8080:8080 -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:server -m models/7B/ggml-model.gguf -c 512 --host 0.0.0.0 --port 8080

# 或带 CUDA：
docker run -p 8080:8080 -v /path/to/models:/models --gpus all ghcr.io/ggml-org/llama.cpp:server-cuda -m models/7B/ggml-model.gguf -c 512 --host 0.0.0.0 --port 8080 --n-gpu-layers 99

通过环境变量配置（docker compose 示例）

所有命令行参数都支持对应的 LLAMA_ARG_* 环境变量；同一参数同时设置命令行与环境变量时，命令行优先。docker compose 下可以完全不用命令行参数：

services:
  llamacpp-server:
    image: ghcr.io/ggml-org/llama.cpp:server
    ports:
      - 8080:8080
    volumes:
      - ./models:/models
    environment:
      # 也可以改用 "LLAMA_ARG_MODEL_URL" 直接下载模型
      LLAMA_ARG_MODEL: /models/my_model.gguf
      LLAMA_ARG_CTX_SIZE: 4096
      LLAMA_ARG_N_PARALLEL: 2
      LLAMA_ARG_ENDPOINT_METRICS: 1
      LLAMA_ARG_PORT: 8080

环境变量的取值规则：

  • 字符串型选项（如 --load-mode）：LLAMA_ARG_LOAD_MODE=auto|none|mmap|mlock|mmap+mlock|dio；
  • 布尔型选项（如 --kv-offload）：true / 1 / on / enabled 表示开启，false / 0 / off / disabled 表示关闭。

三、命令行参数

README 中的参数表由 llama-gen-docs 工具自动生成（对应示例程序 examples/gen-docs/gen-docs.cpp），因此与二进制 --help 输出严格一致。完整列表约 200 项，分为 Common、Sampling、Server-specific 三组。以下按组完整保留核心内容。

3.1 Common 参数（模型加载、上下文、设备、缓存）

参数说明
-h, --help打印用法
--version显示版本与构建信息
-t, --threads N生成阶段 CPU 线程数（默认 -1）；env: LLAMA_ARG_THREADS
-tb, --threads-batch N批/prompt 处理线程数（默认同 --threads）
-C, --cpu-mask M / -Cr, --cpu-range lo-hiCPU 亲和性掩码/范围（十六进制）
-c, --ctx-size N提示词上下文大小（默认 0 = 从模型读取）；env: LLAMA_ARG_CTX_SIZE
-n, --n-predict N预测 token 数（-1 = 无限）
-b, --batch-size N逻辑最大批大小（默认 2048）
-ub, --ubatch-size N物理最大批大小（默认 512）
--keep N初始提示保留 token 数（-1 = 全部）
-fa, --flash-attn [on\|off\|auto]Flash Attention 开关（默认 auto）
-kvo, --kv-offload是否启用 KV cache offload（默认启用）
-ctk, --cache-type-k TYPE / -ctv, --cache-type-v TYPEK/V cache 数据类型：f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1（默认 f16）
--rpc SERVERSRPC 服务器列表（host:port，逗号分隔）
-lm, --load-mode MODE模型加载模式：auto / none / mmap / mlock / mmap+mlock / dio（默认 auto）。旧的 --mlock、--mmap、-dio 已弃用，统一由它接管
-lzm, --lazy-mode MODE大张量按需读取：on / auto（>4 GiB 才生效）/ off
--numa TYPENUMA 优化：distribute / isolate / numactl
-dev, --device <dev1,dev2,..>参与 offload 的设备列表（none = 不 offload）
--list-devices打印可用设备并退出
-ot, --override-tensor PATTERN=TYPE覆盖指定张量的 buffer 类型
-cmoe, --cpu-moe所有 MoE 专家权重保留在 CPU
-ncmoe, --n-cpu-moe N / -ncffn, --n-cpu-ffn N前 N 层 MoE 专家 / 稠密 FFN 权重保留在 CPU
-ngl, --n-gpu-layers N存入 VRAM 的层数：具体数字、auto 或 all（默认 auto）
-sm, --split-mode {none,layer,row,tensor}多 GPU 切分方式：none / layer（默认，流水线）/ row（按行并行）/ tensor（实验性）
-ts, --tensor-split N0,N1,...每个 GPU 的模型占比
-mg, --main-gpu INDEX主 GPU（默认 0）
-fit, --fit [on\|off]自动调整未显式设置的参数以适配显存（默认 on）
-fitt, --fit-target每设备保留的显存余量（MiB，默认 1024）
-fitc, --fit-ctx N--fit 可设置的最小 ctx（默认 4096）
-m, --model FNAME模型路径；env: LLAMA_ARG_MODEL
-mu, --model-url / -dr, --docker-repo / -hf, --hf-repo三种模型下载来源：直接 URL、Docker Hub 仓库、Hugging Face 仓库（<user>/<model>[:quant]，quant 缺省 Q4_K_M，可用 -hff 指定具体文件、-hft 提供 token）
--offline离线模式：强制使用缓存，禁止网络访问
-v, --verbose / -lv, --log-verbosity N日志级别（0 通用输出 … 5 debug，默认 3）
--rope-scaling {none,linear,yarn} 及 --rope-scale、--yarn-* 系列RoPE 上下文扩展与 YaRN 长上下文参数组

要点解读：--fit 机制值得注意——它会在加载阶段探测设备显存，自动下调 ctx 与层数等未显式给定的参数，因此多数场景下你只需给出 -m 与 -c。-hf 下载时若仓库中存在 mmproj 文件会自动一并下载（可用 --no-mmproj 关闭）。

3.2 Sampling 参数

参数说明
--samplers SAMPLERS采样器链（以 ; 分隔），默认 penalties;dry;top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature
-s, --seed SEED随机种子（-1 = 随机）
--ignore-eos忽略 EOS 持续生成（隐含对 EOS 施加 --logit-bias EOS-inf）
--temp, --temperature N温度（默认 0.80）
--top-k Ntop-k（默认 40，0 = 禁用）
--top-p Ntop-p（默认 0.95，1.0 = 禁用）
--min-p Nmin-p（默认 0.05，0.0 = 禁用）
--top-nsigma N / --typical-p Ntop-n-sigma（默认 -1 禁用）/ locally typical（默认 1.0 禁用）
--xtc-probability N / --xtc-threshold NXTC 采样器移除 token 的概率（默认 0 禁用）与阈值（默认 0.10）
--repeat-last-n N惩罚回看 token 数（默认 64，0 = 禁用）
--repeat-penalty N重复惩罚（默认 1.00，1.0 = 禁用）
--presence-penalty N / --frequency-penalty N存在/频率惩罚（默认 0.00 禁用）
--dry-multiplier N / --dry-base N / --dry-allowed-length N / --dry-penalty-last-n N / --dry-sequence-breaker STRINGDRY 去重采样器参数组（默认 multiplier 0.0 禁用、base 1.75、allowed 2、last-n 64；序列断言符默认 '\n'、':'、'"'、'*'）
--adaptive-target N / --adaptive-decay Nadaptive-p 采样（目标概率、衰减率，默认 -1.0 禁用 / 0.90）
--dynatemp-range N / --dynatemp-exp N动态温度范围与指数（默认 0.0 禁用 / 1.00）
--mirostat N / --mirostat-lr N / --mirostat-ent NMirostat / 2.0 采样（0 禁用），学习率默认 0.10，目标熵默认 5.00
-l, --logit-bias TOKEN_ID(+/-)BIAS调整指定 token 的似然，如 --logit-bias 15043+1
--grammar GRAMMAR / --grammar-file FNAME类 BNF 语法约束（参考 grammars/ 目录示例）
-j, --json-schema SCHEMA / -jf, --json-schema-file FILEJSON Schema 约束生成，如 {} 表示任意 JSON 对象；支持外部 $ref 的 schema 需改用 --grammar 与转换脚本
-bs, --backend-sampling后端采样（实验性，默认禁用）

--json-schema 的转换实现可在 common/json-schema-to-grammar.cpp 中阅读，其行为覆盖范围由测试 tests/test-json-schema-to-grammar.cpp 固化。

3.3 Server-specific 参数（插槽、KV、多模态、安全与投机解码）

以下只列出高频项；完整列表（约 150 项）以仓库内自动生成的表格为准。

参数说明
-np, --parallel N服务器插槽数（默认 -1 = auto）；env: LLAMA_ARG_N_PARALLEL
-cb, --cont-batching连续批处理/动态批处理（默认启用）
--kv-unified-per-slot N每插槽上下文上限；设置后共享 KV 池按 n_parallel*N 定容
-kvu, --kv-unified所有序列共享单一统一 KV buffer（插槽数为 auto 时默认启用）
-ctxcp, --ctx-checkpoints N每插槽上下文检查点上限（默认 32）
-cram, --cache-ram N提示词缓存最大 MiB（默认 8192，-1 无限制，0 禁用）
--cache-idle-slots新任务到来时保存空闲插槽缓存并在统一 KV 下清除（默认启用，依赖 cache-ram）
--context-shift无限生成时的上下文移位（默认禁用）
--cache-prompt, --no-cache-prompt提示词缓存（默认启用）
--cache-reuse N通过 KV 移位复用缓存的最小块大小（默认 0 禁用）
--warmup, --no-warmup启动时空跑预热（默认启用）
-mm, --mmproj FILE / -mmu, --mmproj-url URL多模态 projector 文件/URL（见 tools/mtmd/README.md）
--mmproj-auto, --no-mmproj配合 -hf 时自动使用 mmproj（默认启用）
--mmproj-offload / --mmproj-device DEVICEprojector GPU offload（默认启用）/ 指定设备
--image-min-tokens N / --image-max-tokens N动态分辨率视觉模型单图 token 上下限（默认读模型元数据）
--mtmd-batch-max-tokens N图像编码时单批最大图像 token（默认 1024）
--video-fps N / --video-timestamp-interval N / --video-ffmpeg-dir DIR视频目标帧率（默认 4.0）、文本时间戳间隔（默认 5000 ms）、ffmpeg 目录
-a, --alias STRING模型别名（API 中使用的名称，逗号分隔可多个）
--tags STRING模型标签（仅信息性，不参与路由）
--host HOST监听地址；以 .sock 结尾则绑定 UNIX socket（默认 127.0.0.1）
--port PORT端口（默认 8080）
--reuse-port允许多 socket 绑定同一端口（默认禁用）
--api-prefix PREFIXAPI 路径前缀（不带尾部斜杠）
--path PATH静态文件根目录
--cors-origins / --cors-methods / --cors-headers / --cors-credentialsCORS 四元组（默认 origins=*、methods=GET,POST,DELETE,OPTIONS、headers=*、credentials 启用）
--api-key KEY / --api-key-file FNAMEAPI Key 认证（逗号分隔多个；文件每行一个，# 开头为注释）；env: LLAMA_API_KEY
--ssl-key-file / --ssl-cert-filePEM 格式 SSL 私钥/证书（需 OpenSSL 构建）
--ui, --webuiWeb UI 开关（默认启用）
--ui-config JSON / --ui-config-file PATHWeb UI 默认偏好 JSON（旧名 --webui-config* 仍作别名保留）；可用键见 tools/ui/src/lib/constants/settings-keys.ts
--embedding, --embeddings仅支持 embedding 用例（配合专用 embedding 模型）
--pooling {none,mean,cls,last,rank}embedding 池化方式（缺省用模型默认）
--rerank, --reranking启用 reranking 端点（默认禁用）
-to, --timeout N读/写超时秒数（默认 3600）
--sse-ping-interval NSSE 心跳间隔秒（-1 禁用，默认 30）
--threads-http NHTTP 请求处理线程数（默认 -1）
--metrics启用 Prometheus 兼容 /metrics 端点（默认禁用）
--props允许 POST /props 修改全局属性（默认禁用）
--slots, --no-slots插槽监控端点开关（默认启用）
--slot-save-path PATH插槽 KV cache 保存目录（默认禁用）
--media-path PATH本地媒体目录，允许 file:// 相对路径访问（默认禁用）
--models-dir / --models-preset / --models-max / --models-autoload路由模式参数：模型目录、INI 预设、同时加载上限（默认 4，0 无限）、自动加载（默认启用）
-r, --reverse-prompt PROMPT / -sp, --special反向提示停止 / 输出特殊 token
--spm-infillinfill 使用 SPM（Suffix/Prefix/Middle）模式
--embd-normalize Nembedding 归一化：-1 无 / 0 最大绝对值 / 1 曼哈顿 / 2 欧氏（默认 2）/ >2 p 范数
-ag, --agent同时启用 CORS 代理与全部内置工具（默认禁用，未受信环境勿开）
--tools TOOL1,TOOL2,...实验性内置工具：read_file, file_glob_search, grep_search, exec_shell_command, write_file, edit_file, get_info；all 表示全部
--tools-runtime OPTION工具运行沙箱：docker:<image>、podman:<image>、docker-container:<id>、ssh:<target>（默认 none 用宿主机环境）
--mcp-servers-config PATH / --mcp-servers-json JSONCursor 兼容格式的 MCP 服务器定义
--ui-mcp-proxy实验性 Web UI 侧 MCP CORS 代理（与内置 MCP 工具无关）
--jinja, --no-jinja是否用 Jinja 模板引擎处理 chat（默认启用）
--chat-template JINJA / --chat-template-file FILE自定义聊天模板；内置模板包括 chatml、llama3、deepseek、kimi-k2、gemma 等约 50 种
--chat-template-kwargs STRING传给模板解析器的附加 JSON 参数
--skip-chat-parsing强制纯内容解析器（reasoning/tool 调用全落在 content）
--prefill-assistant, --no-prefill-assistant末条为 assistant 消息时是否预填充（默认预填充）
-sps, --slot-prompt-similarity SIM请求提示与插槽提示的相似度阈值以复用插槽（默认 0.10）
-rea, --reasoning [on\|off\|auto]推理/思考模式开关（auto = 从模板检测）
--reasoning-format FORMATnone / deepseek / deepseek-legacy，控制思考内容如何解析返回
--reasoning-effort LEVEL传给模板的努力度级别（minimal … max）
--reasoning-budget N思考 token 预算（-1 不限，0 立即结束）
--reasoning-budget-message MESSAGE预算耗尽时注入的结束消息
--reasoning-preserve在完整历史中保留推理轨迹（需模板支持 supports_preserve_reasoning）
--spec-draft-model, -md FNAME / --spec-draft-hf投机解码 draft 模型路径 / HF 仓库
--spec-draft-ngl / --spec-draft-devicedraft 模型的 GPU 层数与设备
--spec-draft-n-max N / --spec-draft-n-min N每次 draft 的 token 上限（默认 3）/下限（默认 0）
--spec-draft-p-split P / --spec-draft-p-min P投机解码分裂概率（默认 0.10）/最小概率（默认 0.00）
--spec-type ...投机解码类型列表：none,draft-simple,draft-eagle3,draft-mtp,draft-dflash,draft-dspark,ngram-simple,ngram-map-k,ngram-map-k4v,ngram-mod,ngram-cache（默认 none）
--spec-ngram-*-size-n / size-m / min-hits / n-match / n-min / n-max各 ngram 策略的查表长度、draft 长度与命中阈值（如 ngram-simple 默认 N=12, M=48）
--spec-draft-type-k/vdraft 模型 KV cache 数据类型（默认 f16）
-lcs, --lookup-cache-static FNAME / -lcd, --lookup-cache-dynamic FNAMElookup 解码的静态/动态查找缓存
--lora FNAME / --lora-scaled FNAME:SCALELoRA 适配器（可多个）
--lora-init-without-apply加载 LoRA 但不应用，后续经 POST /lora-adapters 应用
--control-vector*控制向量及其缩放/层范围
--sleep-idle-seconds SECONDS空闲休眠秒数（-1 = 禁用，默认禁用）
--log-prompts-dir PATH调试用：把提示写入目录

多模态支持

多模态支持目前覆盖：OpenAI 兼容 chat 端点、非兼容 completions 端点、非兼容 embeddings 端点。细节请阅读 docs/multimodal.md。

四、原生（非 OpenAI 兼容）API 端点

GET /health

公开端点（不检查 API Key），/v1/health 亦可。模型加载中等状态返回 HTTP 503 与 {"error": {"code": 503, "message": "Loading model", "type": "unavailable_error"}}；就绪时返回 200 与 {"status": "ok"}。

POST /completion

注意：此端点不兼容 OpenAI 规范，OAI 客户端请使用 /v1/completions。

curl 示例：

curl --request POST \
    --url http://localhost:8080/completion \
    --header "Content-Type: application/json" \
    --data '{"prompt": "Building a website can be done in 10 simple steps:","n_predict": 128}'

prompt 可以是字符串、token 数组、二者混合，或带多模态数据的 JSON 对象（{"prompt_string": "...", "multimodal_data": ["<base64>"]}）。支持多 prompt（结果成数组）。当 cache_prompt 为 true 时，内部与上次补全比较，只评估"未见"后缀；若 prompt 首元素是字符串且模型元数据 tokenizer.ggml.add_bos_token 为 true，则自动插入 BOS。多模态 multimodal_data 的条数必须与 prompt 中的媒体占位标记一致，标记字符串可查询 /props 返回的 media_marker 字段；客户端应先经 /models 或 /v1/models 确认服务器具备 multimodal 能力。

主要请求选项与默认值（完整说明见 tools/server/README.md）：

  • temperature（0.8）、top_k（40）、top_p（0.95）、min_p（0.05）、typical_p（1.0 禁用）、dynatemp_range（0.0 禁用）、dynatemp_exponent（1.0）；
  • n_predict（-1 无限；0 表示只把 prompt 评估进缓存不生成）、n_keep（0；-1 保留全部 prompt）、n_cmpl（多补全数）、n_indent（代码补全最小缩进空格数）、n_cache_reuse（0 禁用）；
  • stream（SSE 流式）、stop（停止词数组，不会包含在输出里，需自行加入下次 prompt）；
  • repeat_penalty（1.1）、repeat_last_n（64）、presence_penalty / frequency_penalty（0.0）、DRY 参数组（multiplier 0.0、base 1.75、allowed_length 2、penalty_last_n 64、sequence_breakers ['\n',':','"', '*']）、xtc_probability（0.0）、xtc_threshold（0.1）、mirostat（0）/mirostat_tau（5.0）/mirostat_eta（0.1）；
  • grammar、json_schema（例如列表的 {"items": {"type": "string"}, "minItems": 10, "maxItems": 100}）；
  • seed（-1 随机）、ignore_eos（false）、logit_bias（支持 [15043,1.0]、[15043,false] 强制屏蔽、字符串 token、以及 OAI 兼容的对象形式）；
  • n_probs（>0 时每个生成 token 附带 top-N 概率）、min_keep（0）、t_max_predict_ms（生成阶段时间上限，适合 FIM，0 禁用）、id_slot（指定插槽，-1 用空闲插槽）、cache_prompt（true；注意不同批大小的 logits 不保证逐位一致，可能导致非确定性结果）；
  • return_tokens、timings_per_token、return_progress（流式下 prompt_progress 含 total/cache/processed/time_ms）、sse_ping_interval（覆盖服务器 --sse-ping-interval）；
  • post_sampling_probs（返回采样链之后的概率，字段名 logprob→prob、top_logprobs→top_probs）；
  • samplers（采样器顺序数组，默认 ["dry","top_k","typ_p","top_p","min_p","xtc","temperature"]，未列出的不启用，重复列出则多次应用）；
  • response_fields（投影响应字段，如 ["content","generation_settings/n_predict"]，斜杠字段会"解嵌套"到根）；
  • lora（本请求的适配器列表 [{"id": 0, "scale": 0.5}]，未列出的 scale 默认 0.0；不同 LoRA 配置的请求不会被批处理到一起，可能降低性能）。

响应关键字段：content、tokens（需 return_tokens/stream）、stop、generation_settings（过滤修正后的实际参数）、model（别名）、prompt（处理后的 prompt）、stop_type（none/eos/limit/word）、stopping_word、timings（含 predicted_per_second 等）、tokens_cached、tokens_evaluated、truncated（是否超过上下文）、completion_probabilities（每个生成 token 的 probs 与最多 n_probs 个 top_logprobs）。流式模式下用 SSE 逐 token 推送，注意浏览器 EventSource 不支持 POST，需用 fetch 流或 curl 消费。

POST /tokenize 与 /detokenize

/tokenize 选项：content（必填）、add_special（是否插 BOS，默认 false）、parse_special（是否解析特殊 token，默认 true）、with_pieces（默认 false）。返回 tokens 数组：纯 ID 或 {"id", "piece"} 对象；piece 为合法 unicode 时是字符串，否则是字节数组（例如输入 'á' 会被拆成两个字节级 token）。/detokenize 只需 tokens 字段。

POST /apply-template

用服务器的聊天模板把 messages（格式同 /v1/chat/completions）渲染为模型输入字符串，返回在 prompt 字段中，但不做推理。典型用途：拿到渲染后的 prompt 后自行改写（如在响应开头插入 "Sure!"），再提交 /completion。

POST /embedding 与 POST /embeddings

/embedding 非 OAI 兼容（OAI 请用 /v1/embeddings）。选项 content 与 embd_normalize（-1 不归一 / 0 最大绝对 / 1 曼哈顿 / 2 欧氏 / >2 p 范数）。该端点还支持多模态 embedding（发送方式同 /completions 的 multimodal_data）。/embeddings 支持所有 pooling 包括 --pooling none：pooling 为 none 时返回未归一化的每个输入 token 的 embedding 数组（形状为 [{"index": 0, "embedding": [[token0...],[token1...], ...]}]），其余 pooling 只返回归一化后的池化结果。注意其响应格式与 /v1/embeddings 不同。

POST /reranking

按查询重排文档，需要 reranker 模型（如 bge-reranker-v2-m3）并以 --embedding --pooling rank 启动。别名：/rerank、/v1/rerank、/v1/reranking。

curl http://127.0.0.1:8012/v1/rerank \
    -H "Content-Type: application/json" \
    -d '{
        "model": "some-model",
        "query": "What is panda?",
        "top_n": 3,
        "documents": [
            "hi",
            "it is a bear",
            "The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China."
        ]
    }'

POST /infill

代码补全（FIM）。选项：input_prefix、input_suffix、input_extra（{"filename","text"} 对象数组，插入 FIM 前缀之前）、prompt（追加在 FIM_MID 之后）；同时接受全部 /completion 选项，以流式返回。若模型含 FIM_REPO 与 FIM_FILE_SEP token，则采用仓库级模式：<FIM_REP>项目名 + 若干 <FIM_SEP>文件名/文本 块 + <FIM_PRE>前缀<FIM_SUF>后缀<FIM_MID>prompt；缺失这些 token 时 input_extra 直接前置在开头。

GET/POST /props

GET 返回服务器全局属性：default_generation_settings（与 /completion 响应同构）、total_slots、model_path、chat_template（模型原始 Jinja 模板）、chat_template_caps（模板能力位，参见 common/jinja/caps.h）、modalities（如 {"vision": false}）、media_marker、build_info、is_sleeping。POST /props 需以 --props 启动，当前尚无可修改项（Options: None yet）。

GET /slots

返回每个插槽的实时处理状态：id、id_task、n_ctx、speculative、is_processing、params（该任务生效的完整采样参数）、next_token（has_next_token、has_new_line、n_remain、n_decoded）。默认启用，--no-slots 可关；?fail_on_no_slot=1 时若无可用插槽返回 503。

GET /metrics

Prometheus 兼容指标导出，仅当 --metrics 启动后可用；路由模式下必须带 ?model={model_id}，否则返回 400。可用指标包括：

指标类型说明
llamacpp:prompt_tokens_totalCounter处理的 prompt token 总数
llamacpp:prompt_seconds_totalCounterprompt 处理总秒数
llamacpp:prompt_tokens_secondsGauge平均 prompt 吞吐 tokens/s
llamacpp:tokens_predicted_totalCounter生成 token 总数
llamacpp:tokens_predicted_seconds_totalCounter生成总秒数
llamacpp:predicted_tokens_secondsGauge平均生成吞吐 tokens/s
llamacpp:requests_processing / llamacpp:requests_deferredGauge处理中/被延后的请求数
llamacpp:n_tokens_maxCounter观测到的上下文大小高水位
llamacpp:n_decode_totalCounterllama_decode() 调用总数
llamacpp:n_busy_slots_per_decodeGauge每次 decode 平均忙碌插槽数
llamacpp:spec_decode_num_draft_tokens_total 等Counter投机解码 draft/接受 token 数、验证步数、按位置统计的接受数

插槽 prompt 缓存的保存/恢复/清除

需要 --slot-save-path 指定目录：

  • POST /slots/{id_slot}?action=save：body {"filename": "slot_save_file.bin"}，返回 n_saved、n_written、save_ms；
  • POST /slots/{id_slot}?action=restore：从同目录文件恢复，返回 n_restored、n_read、restore_ms；
  • POST /slots/{id_slot}?action=erase：清空该插槽缓存，返回 n_erased。

LoRA 适配器管理

  • GET /lora-adapters：列出已加载适配器（id、path、scale）。启动时用 --lora a.gguf --lora b.gguf 加载，默认 scale 1；加 --lora-init-without-apply 则全部以 0 初始化；
  • POST /lora-adapters：设置全局 scale，请求体如 [{"id": 0, "scale": 0.2}, {"id": 1, "scale": 0.8}]；从列表移除或 scale 置 0 即禁用。注意每个请求的 lora 字段会覆盖全局值。

五、OpenAI 兼容 API

GET /v1/models

返回加载模型的信息（列表恒含一个元素，模型加载中时 meta 可为 null）。id 默认为 -m 指定的路径，可用 --alias gpt-4o-mini 之类覆盖：

{
    "object": "list",
    "data": [
        {
            "id": "../models/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf",
            "object": "model",
            "created": 1735142223,
            "owned_by": "llamacpp",
            "meta": {
                "vocab_type": 2,
                "n_vocab": 128256,
                "n_ctx_train": 131072,
                "n_embd": 4096,
                "n_params": 8030261312,
                "size": 4912898304
            }
        }
    ]
}

POST /v1/completions

支持流式。除标准 OAI 字段外，还支持 llama.cpp 特有的 mirostat 等 /completion 选项。python openai 库用法：

import openai

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

completion = client.completions.create(
  model="davinci-002",
  prompt="I believe the meaning of life is",
  max_tokens=8
)

print(completion.choices[0].text)

POST /v1/chat/completions

接收 ChatML 格式 messages，支持同步与流式。默认使用 ChatML 模板；只有具备受支持聊天模板的模型才能最优利用此端点。

关键扩展选项（超出标准 OAI 的部分）：

  • response_format：支持纯 JSON 输出（{"type": "json_object"}）与 schema 约束 JSON（{"type": "json_object", "schema": {...}} 或 {"type": "json_schema", "schema": {...}}）；
  • chat_template_kwargs：附加模板参数，如 {"enable_thinking": false}；
  • reasoning_effort：none 禁用思考，否则值透传给 Jinja 模板；
  • reasoning_format：none 时输出原始文本；
  • reasoning_control：为本次补全开启实时推理控制（默认 false），可配合 control 端点提前结束思考；
  • generation_prompt：模板预填充的生成提示，解析前拼到模型输出前；
  • parse_tool_calls / parallel_tool_calls：是否解析工具调用、是否允许多工具并行（依赖模板能力）。

多模态 messages[i].content[j]：

  • type == "image_url"：image_url.url 可为远程 URL、base64（raw 或 data:image/...;base64）或本地文件路径；格式为 stb_image 支持的类型（jpeg/png/tga/bmp/gif 等）；
  • type == "input_audio"：input_audio.data 或 input_audio.url，格式为 miniaudio 支持的类型（mp3/wav/flac），input_audio.format 被忽略；
  • type == "input_video"：ffmpeg 支持的格式；
  • 本地文件需设置 --media-path，且路径必须带 file:// 前缀。

示例（curl 与 python 均可，此处为 curl）：

curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer no-key" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [
  {"role": "system", "content": "You are ChatGPT, an AI assistant."},
  {"role": "user", "content": "Write a limerick about python exceptions"}
]
}'

Function calling：OpenAI 风格函数调用需配合 --jinja（可能还需 --chat-template-file 覆盖为支持 tool-use 的模板；最坏情况下 --chat-template chatml 也可用），完整说明见 docs/function-calling.md。

Timings 与上下文占用：响应含 timings 对象：cache_n（缓存复用 token 数）、prompt_n（本次处理的 prompt token 数）、prompt_ms、predicted_n、predicted_ms 及各自 per-token / per-second 速率。当前上下文总占用 = prompt_n + cache_n + predicted_n。另有标准 usage 对象（prompt_tokens、completion_tokens、total_tokens、prompt_tokens_details.cached_tokens）。

Reasoning 支持：解析后的思考内容放在 reasoning_content 字段（类似 Deepseek API）；部分模板还支持在历史中保留推理轨迹（reasoning preserve）。

POST /v1/chat/completions/control

对正在流式返回的补全做实时控制：id（SSE 流中回传的 completion id，必填）、action（目前仅支持 reasoning_end，强制结束当前思考块，需原请求带 reasoning_control: true）、model（路由模式必填）。与 SSE 流并行处理；对已结束的补全调用是 no-op。返回 {"success": true|false, "message": "..."}。

POST /v1/responses

OpenAI Responses API 兼容端点，内部将 Responses 请求转换为 Chat Completions 请求处理：

curl http://localhost:8080/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer no-key" \
-d '{
"model": "gpt-4.1",
"instructions": "You are ChatGPT, an AI assistant.",
"input": "Write a limerick about python exceptions"
}'

POST /v1/embeddings

要求模型 pooling 非 none，embedding 以欧氏范数归一化。input 可以是字符串或字符串数组：

curl http://localhost:8080/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer no-key" \
-d '{"input": ["hello", "world"], "model": "GPT-4", "encoding_format": "float"}'

Token 计数端点

  • POST /v1/responses/input_tokens：Responses 请求体计数；
  • POST /v1/chat/completions/input_tokens：Chat Completions 请求体计数（非 OAI 官方端点，为便利而加）。

响应形如：

{
  "object": "response.input_tokens",
  "input_tokens": 11
}

六、Anthropic 兼容 API

POST /v1/messages

接收 messages 列表返回 assistant 响应，SSE 流式支持。主要选项：model（必填）、messages（必填）、max_tokens（默认 4096）、system（字符串或 content block 数组）、temperature（默认 1.0）、top_p（默认 1.0）、top_k、stop_sequences、stream（默认 false）、tools / tool_choice（工具调用需 --jinja，tool_choice 支持 auto / any / 指定 tool 名）。

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "model": "gpt-4",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

POST /v1/messages/count_tokens

与 /v1/messages 同参（max_tokens 非必填），只计数不生成，返回 {"input_tokens": 10}。

七、服务器工具与 MCP

内置 Server tools

服务器提供一组 server tools，让 LLM 直接访问本机文件系统（供 Web UI 调用）。启用方式：

llama-server -m model.gguf --tools all
# 或只启用部分：
llama-server -m model.gguf --tools read_file,grep_search

可用工具：read_file、file_glob_search、grep_search、exec_shell_command、write_file、edit_file、get_info。相关实现见 tools/server/server-tools.cpp。/tools REST API 供 Web UI 内部使用，不保证稳定，请勿在下游应用依赖。用 --tools-runtime docker:<image> 等选项可把工具放进容器/远端 SSH 环境执行，降低宿主机风险。

MCP servers

除内置工具外，服务器可加载外部 MCP 服务器暴露的工具。仅支持 stdio 传输：MCP 服务器是子进程，从 stdin 读 JSON-RPC 消息、向 stdout 写回复，无需在 llama-server 之外维持任何常驻进程。

在 Cursor 兼容的 JSON 文件中声明：

{
  "mcpServers": {
    "example": { "command": "/path/to/server", "args": [] }
  }
}

llama-server -m model.gguf --mcp-servers-config mcp.json

同一 JSON 也可用 --mcp-servers-json 内联传入。每个 mcpServers 条目支持：

键说明
command可执行文件，必填，缺失则跳过该条目
args参数数组
env与父环境合并的环境变量对象
cwd子进程工作目录
timeout_ms单次工具调用超时（默认 30000）

生命周期：启动时为枚举工具列表拉起一次各服务器、随即停止，调用工具时按需重新拉起。MCP 工具以 <server>_<tool> 命名与内置工具并列展示（Web UI 与 GET /tools 中可见）；重名冲突的条目被跳过。这与 --tools 相互独立——MCP 服务器可以是唯一工具来源。实现见 tools/server/server-mcp.cpp。

安全提示：子进程拥有与服务器相同权限，只声明你可信任的命令；与 --tools 一样，启用后 --cors-origins 默认收紧为 localhost。任何符合 MCP 规范的服务（无论是否用官方 SDK）都可直接工作：传输只是逐行 JSON-RPC，脚本包装既有程序也是合法服务器。注意 --ui-mcp-proxy 与此无关，它只是让浏览器端 Web UI 够到远程 MCP 服务器。

CORS 安全模型

默认行为是反射任意 Origin 头并允许凭据（等效于旧的恒开 *），这对只暴露无状态只读端点没问题。一旦启用 --tools 或 --agent（API 上暴露文件读写），--cors-origins 会自动默认收紧为 localhost。显式传 --cors-origins 可覆盖任一默认。按部署位置的建议：

部署位置建议
公网设置 API key + 反向代理，--cors-origins 可选
局域网--cors-origins 设为前端所在 origin
同机--cors-origins localhost（设置 --agent 后即为默认）

相关开关：--cors-origins、--cors-methods、--cors-headers、--cors-credentials / --no-cors-credentials。

八、多模型路由模式（Router）

不带任何模型参数启动 llama-server 即进入路由模式：

llama-server

主进程（router）负责动态加载/卸载模型，并把每个请求转发到正确的模型实例。从源码结构看，模型实例是独立子进程：tools/server/server-models.cpp 中既负责管理子进程生命周期（包括按模型路径卸载对应子进程），也承担路由前缀转发逻辑。

模型来源（三种）

  1. 缓存模型（由 LLAMA_CACHE 环境变量控制目录）；
  2. 自定义模型目录（--models-dir）；
  3. 自定义预设（--models-preset）。

默认从缓存找模型，用 llama-server -hf <user>/<model>:<tag> 把 HF 模型加入缓存——添加新模型后需重启服务器。

使用 --models-dir 指向本地 GGUF 目录时，单文件直接放目录里；多分片或多模态文件放入子目录，mmproj 文件名必须以 mmproj 开头：

models_directory
 │
 │  # 单文件
 ├─ llama-3.2-1b-Q4_K_M.gguf
 ├─ Qwen3-8B-Q4_K_M.gguf
 │
 │  # 多模态
 ├─ gemma-3-4b-it-Q8_0
 │    ├─ gemma-3-4b-it-Q8_0.gguf
 │    └─ mmproj-F16.gguf
 │
 │  # 多分片
 ├─ Kimi-K2-Thinking-UD-IQ1_S
 │    ├─ Kimi-K2-Thinking-UD-IQ1_S-00001-of-00006.gguf
 │    └─ ...

还可以给路由进程传全局默认参数（例如 llama-server -ctx 8192 -n 1024 -np 2），所有模型实例都会继承 router 的命令行参数与环境变量。

模型预设（INI）

llama-server --models-preset ./my-models.ini。每个 section 是一个预设，键对应命令行参数（不带前导短横线）；短参数（c、ngl）与环境变量名（LLAMA_ARG_N_GPU_LAYERS）也可作键：

version = 1

; 全局共享设置；同名键在特定预设中可覆盖此处的值
[*]
c = 8192
n-gpu-layers = 8

; 键对应服务器上已存在的模型时，作为该模型的默认配置
[ggml-org/MY-MODEL-GGUF:Q8_0]
chat-template = chatml        ; 字符串值
n-gpu-layers = 123            ; 数值
jinja = true                  ; flag（某些 flag 用 "no-" 前缀取反）
c = 4096                      ; 短参数
LLAMA_ARG_CACHE_RAM = 0       ; 环境变量名
model-draft = /abs/path/draft.gguf  ; 推荐绝对路径

; 键不对应已存在模型时，至少给 model 路径或 HF 仓库
[custom_model]
model = /Users/abc/my-awesome-model-Q4_K_M.gguf

优先级：命令行参数 > 模型特定 section > [*] 全局 section。注意 host、port、API key、HF repo、alias 等由 router 管控的参数在加载时会被移除/覆盖。预设有三个专属键（非命令行参数）：

  • load-on-startup（布尔）：是否开机自动加载；预设文件后续重载时新加模型只列出不加载；
  • stop-timeout（秒）：请求卸载后强制终止前的等待时间（默认 10）；
  • dedup-cache-models（布尔）：预设 hf-repo 指向已下载的缓存模型时，从 GET /models 中隐藏缓存条目（预设条目仍可见）。

请求路由规则

POST 端点（/v1/chat/completions、/v1/completions、/infill 等）按 JSON body 的 "model" 字段路由：

{
  "model": "ggml-org/gemma-3-4b-it-GGUF:Q4_K_M",
  "messages": [ { "role": "user", "content": "hello" } ]
}

GET 端点（/props、/metrics 等）按 URL 编码的 model 查询参数路由：GET /props?model=ggml-org%2Fgemma-3-4b-it-GGUF%3AQ4_K_M。模型未加载时默认自动加载；--no-models-autoload 可全局禁用，或在单次请求用 ?autoload=true|false 覆盖。

模型管理 API

  • GET /models：列出缓存全部模型，条目含 id、path、status、architecture（输入/输出模态）等。?reload=1 刷新列表：来源中已更新/删除的运行中模型会被卸载，未运行的按来源增改。status.value 取值：unloaded / loading（附 args）/ 失败态（"failed": true, "exit_code": 1）/ loaded / sleeping / downloading（附每个文件的 done/total 进度，可多文件并行）。模型已加载时，其实例的 /v1/models 信息会被转发到 router 的 /v1/models。
  • POST /models/load：{"model": "ggml-org/gemma-3-4b-it-GGUF:Q4_K_M"} → {"success": true}；
  • POST /models/unload：同参卸载；
  • POST /models：触发新模型下载（非阻塞），进度经 /models/sse 跟踪，向 /models/unload 发事件可取消；
  • DELETE /models?model={name}：从缓存删除（预设模型不可删），成功后广播 model_remove SSE 事件；
  • GET /models/sse：实时事件流，事件类型包括 model_status（loading 带 progress.stages/current/value 分阶段进度；loaded 首次加载带 info）、download_progress、download_finished / download_failed、model_remove，以及 model: "*" 的 models_reload。注释提醒：部分平台上 mmap 进度可能不准，需要精确进度可用 --load-mode none。

下载的标准流程：POST /models 发起 → 订阅 /models/sse → 收到 download_finished/download_failed → 再 GET /models 触发列表更新。

九、API 错误格式

错误响应与 OpenAI 格式一致：

{
    "error": {
        "code": 401,
        "message": "Invalid API Key",
        "type": "authentication_error"
    }
}

另有 llama.cpp 自定义错误类型，例如端点被禁用时（/metrics、/slots）：

{
    "error": {
        "code": 501,
        "message": "This server does not support metrics endpoint.",
        "type": "not_supported_error"
    }
}

/completions 收到非法语法时：

{
    "error": {
        "code": 400,
        "message": "Failed to parse grammar",
        "type": "invalid_request_error"
    }
}

十、空闲休眠（Sleeping on Idle）

服务器支持在指定时长无任务后自动休眠：--sleep-idle-seconds 300。进入休眠后模型及其关联内存（含 KV cache）从 RAM 卸载以释放资源；新任务到来时自动重新加载，单模型与路由多模型模式都适用，路由模式下模型 status 会出现 sleeping。休眠状态可从 GET /props（路由模式 GET /props?model=(model_name)）读取。注意以下端点不视为入站任务——不触发重载、不重置空闲计时器：GET /health、GET /props、GET /models、GET /metrics。

十一、交互示例与 Web UI 配置

仓库提供了两个交互客户端示例（位于 tools/server/ 下）：

  • chat.mjs：NodeJS 16+ 运行 node chat.mjs；
  • chat.sh：依赖 bash、curl、jq，运行 bash chat.sh。

Web UI 默认偏好可用 --ui-config / --ui-config-file 覆盖（旧名 --webui-config* 已弃用但仍可用）：

./llama-server -m model.gguf --ui-config '{"pasteLongTextToFileLen": 0, "renderUserContentAsMarkdown": true}'

可用偏好键的完整清单见 tools/ui/src/lib/constants/settings-keys.ts。

十二、如何验证行为：内置测试套件

tools/server/tests/ 附带了一整套针对运行中服务器实例的端到端 Python 测试，是核对上述端点行为最可靠的依据，例如：

十三、小结

llama-server 的价值在于把 llama.cpp 的推理能力封装成一套"本地 OpenAI"：原生端点（/completion、/infill、/tokenize、/slots、插槽缓存持久化等）保留 llama.cpp 全部特性，/v1/* 与 /v1/messages 端点则让现有 OpenAI/Anthropic 生态应用可以近乎零改造地指向本地模型；插槽并行、统一 KV、提示词缓存与连续批处理支撑多用户吞吐，而路由模式、休眠与 Prometheus 指标则补足了多模型运维能力。参数与端点的完整权威说明始终以 tools/server/README.md 为准——其中的参数表由 llama-gen-docs 自动生成，与二进制 --help 严格同步，升级版本后重新核对它是良好的工程习惯。

【免费下载链接】llama.cpp LLM inference in C/C++ 【免费下载链接】llama.cpp 项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

Logo
乐奇 Rokid 开放社区

更多推荐

听书阁：让你在 AR 眼镜上也可以读小说

戴上眼镜之后我才发现，"翻页"是个需要用手完成的动作。手机上有触屏，滑动、点按、长按选词，一整套肌肉记忆。到了 AR 眼镜上这些全没了：视野只有一小块，手上可能还拎着东西，能稳定输入的只剩嘴和眼镜腿上的几颗按键。把手机阅读器原样搬过来没有意义，得重新想一遍"读一本书"在眼镜上该拆成哪几个动作。听书阁就是这次重想的产物。它跑在 Rokid Craft 上，用 AIUI 的 Ink 写页面，四个页面加

avatar 乐奇 Rokid 开放社区
cover

Python 技术报告：从 2026 长沙 AI 构建者大会到 Rokid 生态的开发者实践

avatar 乐奇 Rokid 开放社区

AI 智能眼镜的柔性神经，开启轻量化人机交互新世代

AI 智能眼镜的核心诉求，是在接近传统眼镜的轻薄体积内，塞进 AI 主控芯片、摄像头、麦克风阵列、骨传导 / 扬声器、光波导显示模组、触控传感器、电池、蓝牙 / Wi-Fi 射频模块等大量器件。随着 AI 眼镜出货量快速上行，鹏鼎、弘信、则成等国内 FPC 厂商纷纷布局 AI 眼镜软板、软硬结合板量产方案，单机 FPC 价值量显著高于 TWS 耳机，带动国内柔性线路板供应链升级，倒逼国内厂商突破超

avatar 乐奇 Rokid 开放社区