Skypool Token
Token online
Sign up
Docsllama.cpp

llama.cpp 本地模型准备

Provider Agent 接入 llama.cpp OpenAI-compatible 服务前，编译或安装 llama-server、准备 GGUF 模型、设置上下文窗口和验证可用性的操作说明。

Updated:

什么时候需要看这页

如果你的 Provider 节点准备用 llama.cpp 承接推理任务，先按这页把 llama-server 和 GGUF 模型启动起来。llama.cpp 的 HTTP Server 暴露 OpenAI-compatible /v1/models、/v1/chat/completions 等接口，Provider Agent 侧需要使用 --api-format llama.cpp。

Token 供应示例里的模型名，例如 qwen3.5:9b、gemma4:26b，是启动 Provider Agent 时使用的平台模型代码。llama.cpp 加载的是本地 .gguf 文件；控制台展示的“模型名称”用于确认模型来源，“模型 ID”建议作为 llama-server 的 API alias，并传给 Provider Agent 的 --runtime-model-id。

适用系统和特点

llama.cpp 适合希望直接运行 GGUF 模型的本地 Provider。它可以在 CPU、Metal、CUDA、Vulkan、ROCm 等多种后端上运行，具体性能取决于你编译或下载的版本、量化格式、显存/内存和上下文窗口大小。

主要优点：

  • 运行时轻量，适合本地机器、桌面工作站和专业节点
  • 支持 GGUF 模型、量化模型和多模态 projector 文件
  • llama-server 提供 OpenAI-compatible API，便于 Provider Agent 预检和调用
  • 可通过 --ctx-size 显式设置上下文窗口

主要限制：

  • GGUF 文件、量化等级和多模态 projector 需要自己准备并匹配
  • 长上下文窗口会显著增加 KV cache 占用，容易触发显存或内存不足
  • 不同硬件后端的构建方式和性能差异较大，需要按机器实测

安装 llama.cpp

推荐优先参考官方仓库说明选择安装方式。常见源码构建流程如下：

Bash
git clone https://github.com/ggml-org/llama.cppcd llama.cppcmake -B buildcmake --build build --config Release -j

构建完成后，llama-server 通常位于：

Bash
./build/bin/llama-server

如果你使用官方或社区提供的预编译包，请确认命令名是 llama-server，并能正常输出帮助：

Bash
./llama-server --help

准备 GGUF 模型

llama.cpp 的 -m / --model 接收本地 GGUF 模型文件路径。多模态模型还需要配套的 projector 文件，使用 -mm / --mmproj 指定。

实际使用时，先打开 Provider API 密钥页，在 Token 供应示例中选择目标模型和 llama.cpp 推理框架，然后分别点击“复制模型名称”和“复制模型 ID”。模型名称用于确认你下载的 GGUF 来源；模型 ID 应作为 llama-server 的 -a / --alias，并用于后面验证请求里的 model 和 Provider Agent 的 --runtime-model-id / PROVIDER_AGENT_RUNTIME_MODEL_ID。

建议做法如下，最终以页面里“模型名称 / 模型 ID”显示的值、你实际下载的 GGUF 文件和 /v1/models 返回为准：

Token 供应示例模型名llama.cpp 模型名称llama.cpp 模型 ID本地文件示例
qwen3.5:9bQwen/Qwen3.5-9BQwen/Qwen3.5-9BQwen3.5-9B-Q4_K_M.gguf
gemma4:26bgoogle/gemma-4-26B-A4B-itgoogle/gemma-4-26B-A4B-itgemma-4-26b-a4b-it-Q4_K_M.gguf

如果模型是多模态模型，通常还会有类似下面的 projector 文件：

Text
mmproj-Qwen3.5-9B.gguf

-m 和 -mm 必须指向同一模型系列的匹配文件，不要混用不同模型或不同版本的 GGUF / projector。

启动 llama-server

下面是单模型启动示例。-m 指向主模型 GGUF，-mm 指向多模态 projector，--ctx-size 指定上下文窗口，-a 指定对外暴露的模型名：

Bash
./llama-server \  -m Qwen3.5-9B-Q4_K_M.gguf \  --host 127.0.0.1 \  --port 8080 \  -mm mmproj-Qwen3.5-9B.gguf \  --ctx-size 131072 \  -a "Qwen/Qwen3.5-9B"

如果你希望给本地服务加一层推理框架 API Key，可以增加：

Bash
--api-key runtime-...

此时后续 curl 和 Provider Agent 都需要带同一个 token。

设置上下文窗口

llama.cpp 对应的上下文参数是 --ctx-size。这个值要根据目标模型要求的“上下文窗口”大小设置，不能默认所有模型都写成同一个数字。常见换算是：128K 对应 131072 tokens，256K 对应 262144 tokens。

注意：

  • --ctx-size 是模型加载时的上下文窗口
  • OpenAI 请求体里的 max_tokens 只是单次最多生成多少 token，不是上下文窗口
  • 上下文窗口越大，KV cache 占用越高；如果启动失败或运行中 OOM，先降低 --ctx-size、降低并发或更换量化文件
  • 模型本身必须支持你设置的目标上下文窗口大小

验证 llama.cpp 服务

查看模型列表：

Bash
curl http://127.0.0.1:8080/v1/models

做一次非流式推理。model 使用 -a 暴露的模型 ID：

Bash
curl http://127.0.0.1:8080/v1/chat/completions \  -H "Content-Type: application/json" \  --data-raw '{    "model": "Qwen/Qwen3.5-9B",    "messages": [      {        "role": "user",        "content": "用一句中文回复：llama.cpp 服务可用。"      }    ],    "max_tokens": 64,    "temperature": 0  }'

如果启动时配置了 --api-key runtime-...，所有请求都需要增加：

Bash
-H "Authorization: Bearer runtime-..."

启动 Provider Agent

llama.cpp 服务可用后，先跑预检：

Bash
./token-provider-agent preflight start \  --model qwen3.5:9b \  --base-url http://127.0.0.1:8080 \  --api-format llama.cpp \  --runtime-model-id Qwen/Qwen3.5-9B

预检通过后正式启动：

Bash
./token-provider-agent start \  --api-key stp-... \  --model qwen3.5:9b \  --base-url http://127.0.0.1:8080 \  --api-format llama.cpp \  --runtime-model-id Qwen/Qwen3.5-9B

如果 llama.cpp 启用了 --api-key，同时传入：

Bash
--runtime-api-key runtime-...

参考链接