LocalAI 文本生成（GPT）实战全指南：OpenAI / Anthropic Messages / Open Responses 三套接口与 llama.cpp、vLLM、SGLang 等多后端配置详解

LocalAI 将 GPT 类文本生成能力统一封装为与 OpenAI 兼容的 HTTP 接口，并在此基础上额外提供了 Anthropic Messages 与 Open Responses 两套现代接口协议。本文以 docs/content/features/text-generation.md 为主线，系统讲解 Chat Completions、Edit、Completions、模型列表等基础用法，深入剖析 llama.cpp、ik-llama-cpp、turboquant、vLLM、SGLang、vllm.cpp、Transformers 等文本生成后端的模型 YAML 配置、参数调优与推理加速玩法，并辅以 core/http/endpoints 下真实端点代码与 core/schema 数据结构作为佐证。读完本文，你将能独立为任意一种 GGUF / HuggingFace / OpenVINO 模型编写可运行的模型配置，并熟练使用四类生成 API 完成对话、改写、补全、工具调用与后台任务。

写在前面：LocalAI 文本生成的整体能力边界

LocalAI 支持使用 llama.cpp 及其他后端（如 rwkv.cpp）进行 GPT 文本生成，支持的具体模型家族列表以 模型兼容表 为准。使用时有两点默认行为值得注意：

• 模型名可用作 OpenAI token 的一部分：即模型标识既可以通过请求体 model 字段指定，也可以拼接进鉴权 token（例如 API Key 的 model-name 段），由服务端在鉴权时解析。
• 单模型自动兜底：如果当前只部署了一个模型，API 会自动把它用于所有请求，即使请求中没有显式携带 model 字段。

从源码结构看，这两类约定背后是统一的"请求 → 模型配置解析 → 后端推理"链路：所有端点都会先从请求上下文取出 ModelConfig（见 core/config/model_config.go），再交给对应 backend 执行，若请求头缺少有效模型配置则会直接返回 400。

Chat Completions：多轮对话的标准姿势

Chat Completions 对应 OpenAI 的 Chat 接口语义。向 /v1/chat/completions 发送 POST 请求，把指令放在 messages 数组即可：

curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "ggml-koala-7b-model-q4_0-r2.bin",
  "messages": [{"role": "user", "content": "Say this is a test!"}],
  "temperature": 0.7
}'

除 temperature 外，可用的附加采样参数还包括：

• top_p —— 核采样概率阈值；
• top_k —— 仅从概率最高的 K 个 token 中采样；
• max_tokens —— 生成的最大 token 数。

从实现上看，该路由对应 core/http/endpoints/openai/chat.go，内部会将请求解析为 schema.OpenAIRequest，先经模板评估（chat 模板）再送入后端生成，流式与工具调用也走同一入口。

关于推理模型的说明：支持思维链的推理模型（reasoning model）会把思考内容放在响应的 reasoning 字段返回；当一个模型在同一轮里既进行推理又调用工具时，请参考 Interleaved Thinking with Tool Calls（思维与工具调用交错） 一节了解其消息编排方式。

Edit Completions：指令驱动的文本改写

Edit Completions 面向"给定一段文本 + 一条改写指令"的场景，请求发送到 /v1/edits：

curl http://localhost:8080/v1/edits -H "Content-Type: application/json" -d '{
  "model": "ggml-koala-7b-model-q4_0-r2.bin",
  "instruction": "rephrase",
  "input": "Black cat jumped out of the window",
  "temperature": 0.7
}'

其中 instruction 是要执行的操作指令，input 是待处理的源文本。附加参数同样包括 top_p、top_k、max_tokens。

该端点实现在 core/http/endpoints/openai/edit.go：请求会按模型配置中的每个输入串（config.InputStrings）逐一调用模板求值器，优先使用 templates.EditPromptTemplate 完成"instruction + input"的拼装，再经由 ComputeChoices 调用后端推理，最终聚合成一个 Object: "edit" 的响应并统计 prompt/completion token 用量。可见 Edit 本质上是一种"带专用提示模板的补全"。

Completions：原生文本补全

对不需要角色消息结构的原始续写任务，使用 /v1/completions 端点：

curl http://localhost:8080/v1/completions -H "Content-Type: application/json" -d '{
  "model": "ggml-koala-7b-model-q4_0-r2.bin",
  "prompt": "A long time ago in a galaxy far, far away",
  "temperature": 0.7
}'

附加参数同样为 top_p、top_k、max_tokens。对应实现位于 core/http/endpoints/openai/completion.go，它按 completion 提示模板处理 prompt 后交给后端。

List Models：查看当前可用模型

curl http://localhost:8080/v1/models

返回当前服务可用的全部模型 ID 列表。其实现 core/http/endpoints/openai/list.go 还暴露了两个实用查询参数：filter（按名称过滤，支持正则/子串过滤，见 config.BuildNameFilterFn）与 excludeConfigured（是否排除已被 YAML 配置文件引用的松散模型文件，默认 true 即排除）。开启鉴权后，非管理员用户看到的模型还会进一步被其个人 allowlist 白名单裁剪。

Anthropic Messages API：Claude 客户端的兼容入口

LocalAI 兼容 Anthropic Messages API，可与基于 Claude 协议的客户端直接对接，支持工具调用、流式响应与多模态内容。端点：POST /v1/messages 或 POST /messages，协议结构遵循 Anthropic Messages 规范。

基础用法

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Say this is a test!"}
    ]
  }'

实现上，core/http/endpoints/anthropic/messages.go 会在进入推理前校验两点：请求必须携带 model，且 max_tokens 必须大于 0，否则返回带 invalid_request_error 类型的 400 错误。请求体结构定义在 core/schema/anthropic.go。

请求参数

参数	类型	必填	说明
model	string	是	模型标识符
messages	array	是	由 role 与 content 组成的消息对象数组
max_tokens	integer	是	最大生成 token 数（必须 > 0）
system	string	否	设定助手行为风格的 system 消息
temperature	float	否	采样温度（0.0 到 1.0）
top_p	float	否	核采样参数
top_k	integer	否	Top-k 采样参数
stop_sequences	array	否	命中即停止生成的字符串数组
stream	boolean	否	是否开启流式响应
tools	array	否	用于函数调用的工具定义数组
tool_choice	string/object	否	工具选择策略："auto"、"any"、"none" 或指定某个工具
metadata	object	否	透传给后端的按请求元数据（如 {"enable_thinking": "true"}）

消息格式：文本与结构化内容块

content 既可以是纯文本字符串，也可以是结构化内容块数组。例如多模态场景中同时携带文本与 base64 图片：

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/jpeg",
              "data": "base64_encoded_image_data"
            }
          }
        ]
      }
    ]
  }'

工具调用（Function Calling）

Anthropic 协议通过 tools 数组声明可调用函数，工具采用 JSON Schema 描述入参：

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": "auto",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ]
  }'

从 messages.go 的实现可以看到，端点会把 Anthropic 格式的消息与工具先转换为内部 OpenAI 格式与 pkg/functions 的函数结构，复用同一套后端推理与函数解析链路，因此文本生成类后端均可获得工具调用能力。

流式响应

设置 stream: true 开启流式输出：

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Tell me a story"}
    ]
  }'

流式响应采用 Server-Sent Events（SSE）格式，事件类型依次为：message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。

响应格式

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This is a test!"
    }
  ],
  "model": "ggml-koala-7b-model-q4_0-r2.bin",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 5
  }
}

Open Responses API：支持后台任务的新一代统一接口

LocalAI 支持 Open Responses API 规范——一个面向 AI 模型交互的标准化接口，内置后台处理、流式、工具调用及 reasoning 等进阶能力。端点：POST /v1/responses 或 POST /responses。

基础用法

curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "input": "Say this is a test!",
    "max_output_tokens": 1024
  }'

入口实现在 core/http/endpoints/openresponses/responses.go，请求结构定义在 core/schema/openresponses.go，其中 input 类型为 string 或结构化的 []ORItemParam，同时支持 previous_response_id 链路拼接与 store 持久化开关。

请求参数

参数	类型	必填	说明
model	string	是	模型标识符
input	string/array	是	输入文本或输入项数组
max_output_tokens	integer	否	最大生成 token 数
temperature	float	否	采样温度
top_p	float	否	核采样参数
instructions	string	否	System 指令
tools	array	否	工具定义数组
tool_choice	string/object	否	工具选择策略："auto"、"required"、"none" 或指定工具
stream	boolean	否	开启流式响应
background	boolean	否	后台执行请求（立即返回）
store	boolean	否	是否存储该响应
reasoning	object	否	推理配置，含 effort 与 summary
parallel_tool_calls	boolean	否	允许并行工具调用
max_tool_calls	integer	否	最大工具调用次数
presence_penalty	float	否	存在惩罚（-2.0 到 2.0）
frequency_penalty	float	否	频率惩罚（-2.0 到 2.0）
top_logprobs	integer	否	返回的 top logprobs 数量
truncation	string	否	截断模式："auto" 或 "disabled"
text_format	object	否	文本格式配置
metadata	object	否	自定义元数据

输入格式

input 可以是简单字符串，也可以是结构化消息项数组：

curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "What is the weather?"
      }
    ],
    "max_output_tokens": 1024
  }'

后台处理（Background Processing）

对长耗时任务可开启 background: true，请求立即返回，不阻塞客户端：

curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "input": "Generate a long story",
    "max_output_tokens": 4096,
    "background": true
  }'

响应会携带一个 response ID 供轮询完成状态：

{
  "id": "resp_abc123",
  "object": "response",
  "status": "in_progress",
  "created_at": 1234567890
}

状态机常量在 core/schema/openresponses.go 中定义为：queued、in_progress、completed、failed、incomplete、cancelled。

获取后台响应

使用 GET 端点获取已提交的后台响应：

# Get response by ID
curl http://localhost:8080/v1/responses/resp_abc123

# Resume streaming with query parameters
curl "http://localhost:8080/v1/responses/resp_abc123?stream=true&starting_after=10"

取消后台响应

curl -X POST http://localhost:8080/v1/responses/resp_abc123/cancel

store 与 TTL 相关逻辑见 core/http/endpoints/openresponses/store.go：响应的全局存储 TTL 可由应用配置 OpenResponsesStoreTTL 控制。

多副本（分布式模式）下的行为约定

在分布式模式下，LocalAI 会跨前端副本复制响应元数据，因此按 ID 获取、previous_response_id 链式拼接与取消操作与负载均衡选中的副本无关：

• GET /v1/responses/{id} 可从任意副本返回该响应。
• POST /v1/responses/{id}/cancel 会通过 NATS 委托给实际正在生成的副本执行，从而真正停止生成；若该副本已消失，响应会被标记为 cancelled 而不阻塞调用方。
• 流式续传（?stream=true）只由创建该响应的副本提供服务。 事件缓冲区只存在于该进程内存中、不做复制。续传请求若落到其他副本，会返回 HTTP 409 并指明所属副本，而不是静默返回被截断的流。此时应改用轮询方式获取结果，或通过会话亲和路由让续传请求始终到达原副本。

工具调用

curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "input": "What is the weather in San Francisco?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": "auto",
    "max_output_tokens": 1024
  }'

推理配置（Reasoning Configuration）

通过 reasoning 对象配置推理强度与摘要风格：

curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-koala-7b-model-q4_0-r2.bin",
    "input": "Solve this complex problem step by step",
    "reasoning": {
      "effort": "high",
      "summary": "detailed"
    },
    "max_output_tokens": 2048
  }'

响应格式

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1234567890,
  "completed_at": 1234567895,
  "status": "completed",
  "model": "ggml-koala-7b-model-q4_0-r2.bin",
  "output": [
    {
      "type": "message",
      "id": "msg_001",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "This is a test!",
          "annotations": [],
          "logprobs": []
        }
      ],
      "status": "completed"
    }
  ],
  "error": null,
  "incomplete_details": null,
  "temperature": 0.7,
  "top_p": 1.0,
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0,
  "usage": {
    "input_tokens": 10,
    "output_tokens": 5,
    "total_tokens": 15,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

注意 usage.output_tokens_details.reasoning_tokens 单独统计了推理（thinking）token，便于观测思维链开销。

文本生成后端全景

LocalAI 的文本生成能力由多个后端承载，模型家族覆盖情况见 模型兼容表。下面按后端逐一讲解配置方式。

RWKV

RWKV 支持目前经由 llama.cpp（见下文）实现，无需单独的专用后端配置。

llama.cpp：默认的 GGUF 推理后端

llama.cpp 是 Facebook LLaMA 模型的知名 C/C++ 移植版本，也是 LocalAI 中最常用的文本生成后端。

格式与后端弃用提示：ggml 文件格式已被弃用。如果你在使用 ggml 模型并通过 YAML 配置模型，请使用低于 v2.25.0 的 LocalAI 版本。对 gguf 模型，请使用 llama 后端。旧的 go 后端同样已弃用，但仍以 go-llama 名称可用。

支持的特性：

• 文本生成（GPT）
• 向量嵌入（Embeddings），详见 embeddings.md
• OpenAI 函数调用，详见 openai-functions.md
• 受约束文法输出（Constrained grammars），详见 constrained_grammars.md

手动部署：只需把 ggml 或 gguf 模型文件拷入 models 目录，即可在 API 请求的 model 参数中按文件名引用。可选地创建一份关联的 YAML 模型配置文件（完整字段说明见 model-configuration.md）来调节模型参数或应用提示词模板——对于针对特定提示微调过的模型，提示词模板尤其有用。

自动部署（模型画廊）：LocalAI 支持模型画廊（gallery）机制，例如 HuggingFace gallery 维护了一个经筛选的 ggml/gguf 模型大索引。画廊开启且 LocalAI 运行时，可直接"边聊边下载"：

curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
     "model": "TheBloke/WizardLM-13B-V1.2-GGML/wizardlm-13b-v1.2.ggmlv3.q2_K.bin",
     "messages": [{"role": "user", "content": "Say this is a test!"}],
     "temperature": 0.1
   }'

LocalAI 会自动把模型下载并配置到 models 目录。模型画廊的完整机制（预加载、按需下载等）见 model-gallery.md，仓库根目录的 gallery 目录即内置画廊索引的真实样例。

YAML 配置：使用 llama-cpp 作为 YAML 中的 backend 字段：

name: llama
backend: llama-cpp
parameters:
  # Relative to the models path
  model: file.gguf

后端选项（Backend Options）：llama.cpp 后端支持在 YAML 的 options 字段中附加大量调优选项：

选项	别名	类型	说明	示例
use_jinja	jinja	boolean	启用模型自带 Jinja2 对话模板处理；开启后使用模型内的 Jinja2 chat template 格式化消息	use_jinja:true
context_shift	-	boolean	启用上下文滑动（context shifting），动态调整上下文窗口占用	context_shift:true
cache_ram	-	integer	服务端提示词缓存（host RAM 中的空闲 slot KV 状态池，命中提示前缀时热加载，对应 llama.cpp 上游 PR #16391）的预算（MiB）。默认 -1（不限）；0 完全禁用该缓存。与 kv_unified、cache_idle_slots 配合是重复 system prompt 跳过 prefill 的关键	cache_ram:4096
parallel	n_parallel	integer	并行请求处理。>1 时开启 continuous batching，并发处理多个请求	parallel:4
grpc_servers	rpc_servers	string	逗号分隔的 gRPC 服务地址列表，用于把负载分发到多个 llama.cpp worker 上进行分布式推理	grpc_servers:localhost:50051,localhost:50052
fit_params	fit	boolean	依据可用设备内存自动调节模型/上下文参数。默认 true	fit_params:true
fit_params_target	fit_target	integer	使用 fit_params 时为每个设备保留的目标内存余量（MiB）。默认 1024（1GB）	fit_target:2048
fit_params_min_ctx	fit_ctx	integer	fit_params 可设置的最小上下文长度。默认 4096	fit_ctx:2048
n_cache_reuse	cache_reuse	integer	通过 KV 滑动尝试复用缓存的最小块大小。默认 0（关闭）	cache_reuse:256
slot_prompt_similarity	sps	float	请求提示词需与某个 slot 提示词匹配到什么程度才复用该 slot。默认 0.1；设 0 关闭	sps:0.5
swa_full	-	boolean	使用完整尺寸的 SWA（滑动窗口注意力）缓存。默认 false	swa_full:true
cont_batching	continuous_batching	boolean	开启 continuous batching 处理多条序列。默认 true	cont_batching:true
check_tensors	-	boolean	模型加载时校验张量数据是否有非法值。默认 false	check_tensors:true
warmup	-	boolean	模型加载后执行 warmup。默认 true	warmup:false
no_op_offload	-	boolean	关闭将 host 张量算子卸载到设备。默认 false	no_op_offload:true
device	devices	string	选择要使用的 llama.cpp 后端设备。可重复写该项或传逗号分隔列表，未列出的设备被排除。设备名以 llama-server --list-devices 输出为准	devices:CUDA1,CUDA2,CUDA3
kv_unified	unified_kv	boolean	使用跨所有序列共享的统一 KV 缓冲。默认 true（LocalAI 覆盖值；上游默认 false，但在 slot 数自动时自动开启）。cache_idle_slots 与 scoring 的前置条件：不开启则服务端在初始化时强制关闭空闲 slot 保存，且 load 时拒绝启用 score 的模型	kv_unified:false
cache_idle_slots	idle_slots_cache	boolean	新任务到来时把上一 slot 的 KV 状态存入提示词缓存并清空 slot，使后续同前缀请求可热加载。默认 true；若 kv_unified=false 或 cache_ram=0 服务端会自动禁用	cache_idle_slots:false
n_ctx_checkpoints	ctx_checkpoints	integer	每个 slot 的最大上下文检查点数量（用于部分前缀恢复，如 SWA）。默认 32	ctx_checkpoints:16
checkpoint_min_step	checkpoint_min_spacing（别名 checkpoint_every_nt、checkpoint_every_n_tokens）	integer	上下文检查点之间的最小 token 间隔；0 关闭最小间隔门控。默认 256。上游已将原名 checkpoint_every_nt 从"固定节奏"语义改为"最小间隔"	checkpoint_min_step:1024
split_mode	sm	string	多 GPU 模型切分方式：none（仅单卡）、layer（默认，按层和 KV 跨卡切分）、row（按行跨卡切分）、tensor（实验性张量并行，需 flash_attention: true、手动设置 context_size，并需包含上游 #19378 的 llama.cpp 构建；历史上还要求关闭 KV-cache 量化，但上游 #23792 解除了限制，cache_type_k/cache_type_v 量化可在包含该 PR 的构建上与张量并行组合）	split_mode:tensor

带 options 的示例配置：

name: llama-model
backend: llama
parameters:
  model: model.gguf
options:
  - use_jinja:true
  - context_shift:true
  - cache_ram:4096
  - parallel:2
  - devices:CUDA1,CUDA2,CUDA3
  - fit_params:true
  - fit_target:1024
  - slot_prompt_similarity:0.5

环境变量快捷方式：parallel 也可通过 LLAMACPP_PARALLEL 环境变量设置，grpc_servers 可通过 LLAMACPP_GRPC_SERVERS 环境变量设置；YAML 中显式指定的选项优先级高于环境变量。

硬件自动调优（及如何覆盖）：在检测到 GPU 时，LocalAI 会为模型配置中未显式设置的项填入若干性能相关默认值——在 NVIDIA Blackwell 上使用更大的物理 batch，以及按显存规模扩展的 parallel slot 数用于并发服务。两者都受每个设备在模型上下文下的显存门控：当大上下文已占满单卡（例如 27B 模型在 2×16GiB 上跑 200k 上下文）时，batch 提升与额外 parallel slot 会被抑制，以免把显存更紧张的卡推向 CUDA OOM。

模型 YAML 中任何显式设置总是优先，想固定某个值直接写即可（如 batch: 512 或 options: ["parallel:1"]）。模型加载时有效值会以 INFO 级别日志输出（effective runtime tuning …）。若想彻底关闭硬件自动调优、完全使用 llama.cpp 原生行为，设置：

LOCALAI_DISABLE_HARDWARE_DEFAULTS=true

服务端提示词缓存（应对重复 system prompt）：Agent、编码助手及 Anthropic/OpenAI 兼容 CLI 每轮都会重发同一大段 system prompt。llama.cpp 服务端可以把空闲 slot 的 KV 状态暂存到 host RAM，命中时免去匹配前缀的 prefill。三个设置相互作用：

设置	默认值	作用
cache_ram:N	-1（不限）	分配 host 侧提示词缓存；0 禁用
kv_unified:true	true	统一 KV 缓冲（空闲 slot 保存的前置条件）
cache_idle_slots:true	true	任务切换时把空闲 slot 的 KV 持久化到提示词缓存

三者自 LocalAI v4.3 起默认全部开启，因此常见单 slot 场景下提示词缓存开箱即用。若你使用旧版本或曾显式关闭其中之一，可加回如下配置恢复该行为：

options:
  - cache_ram:4096       # or -1 for no limit
  - kv_unified:true
  - cache_idle_slots:true

设置 cache_ram:0 可完全退出提示词缓存（节省 host RAM，代价是重复提示需重新 prefill）。

ik_llama.cpp：面向 CPU 与异构 GPU/CPU 的 llama.cpp 硬分叉

ik_llama.cpp 是 Iwan Kawrakow 对 llama.cpp 的硬分叉，聚焦于更优的 CPU 与混合 GPU/CPU 性能，带来额外的量化类型（IQK 量化）、自定义量化混合、面向 DeepSeek 模型的多头潜在注意力（MLA），以及细粒度张量卸载控制——尤其适合在普通 CPU 硬件上运行超大模型。

硬件要求：ik-llama-cpp 后端要求 CPU 支持 AVX2。IQK 内核不兼容更老的 CPU。

支持的特性：

• 文本生成（GPT）
• 向量嵌入（Embeddings）
• IQK 量化类型，带来更好的 CPU 推理性能
• 多模态模型（经由 clip/llava）

部署与 YAML 配置：该后端以独立容器镜像发布，可从 LocalAI 后端画廊安装，或直接在模型配置中指定。加载 GGUF 模型时可受益于其优化过的 CPU 内核——对 MoE 模型以及原本受 GPU 显存限制的大量化模型尤其明显。

name: my-model
backend: ik-llama-cpp
parameters:
  # Relative to the models path
  model: file.gguf

别名 ik-llama 与 ik_llama 同样被接受。

turboquant：带 TurboQuant KV-cache 的 llama.cpp 分叉

turboquant 是一个在 llama.cpp 上游代码库基础上增加 TurboQuant KV-cache 量化方案的 llama.cpp 分叉，作为 LocalAI 内可即插即用的替代后端发布，与标准 llama-cpp 后端共享同一套 gRPC server 源码——因此任何能在 llama-cpp 上运行的 GGUF 模型都能在 turboquant 上运行。

选择 turboquant 的场景：希望降低 KV-cache 内存占用（同样的显存跑更长上下文），或在标准 cache_type_k/cache_type_v 之外试验该分叉的量化 KV 表示。

支持的特性：

• 与上游 llama.cpp 完全兼容的 GGUF
• TurboQuant KV-cache 量化（可用的 cache_type_k/cache_type_v 取值见分叉 README）
• 与 llama-cpp 后端一致的特性面：文本生成、嵌入、工具调用、经 mmproj 的多模态
• 支持 CPU（AVX/AVX2/AVX512/fallback）、NVIDIA CUDA 12/13、AMD ROCm/HIP、Intel SYCL f32/f16、Vulkan 与 NVIDIA L4T

部署：以独立容器镜像随 LocalAI 后端画廊发布，安装方式与其它后端一致：

local-ai backends install turboquant

也可挑选对应硬件的具体 flavor（示例 tag：cpu-turboquant、cuda12-turboquant、cuda13-turboquant、rocm-turboquant、intel-sycl-f16-turboquant、vulkan-turboquant）。

YAML 配置：

name: my-model
backend: turboquant
parameters:
  # Relative to the models path
  model: file.gguf
# Use TurboQuant's own KV-cache quantization schemes. The fork accepts
# the standard llama.cpp types (f16, f32, q8_0, q4_0, q4_1, q5_0, q5_1)
# and adds three TurboQuant-specific ones: turbo2, turbo3, turbo4.
# turbo3 / turbo4 auto-enable flash_attention (required for turbo K/V)
# and offer progressively more aggressive compression.
cache_type_k: turbo3
cache_type_v: turbo3
context_size: 8192

cache_type_k/cache_type_v 字段对应 llama.cpp 的 -ctk/-ctv 参数。标准 llama-cpp 后端只接受 llama.cpp 的标准类型——想用 turbo2/turbo3/turbo4 必须使用 turboquant 后端（分叉的 TurboQuant 代码路径才会真正生效）。此处选 q8_0 等价于跑标准 llama.cpp KV 量化；选 turbo* 才是跑 TurboQuant。

vLLM：Python 侧高性能推理引擎

vLLM 是一个快速易用的 LLM 推理库。LocalAI 内置了 vLLM 集成，可用来运行模型。

部署：为要使用的模型创建 YAML，只需给出模型名即可：

name: vllm
backend: vllm
parameters:
    model: "facebook/opt-125m"

后端会在首次加载时自动下载运行所需文件。

使用：通过 completions 端点指定 vllm 模型：

curl http://localhost:8080/v1/completions -H "Content-Type: application/json" -d '{
   "model": "vllm",
   "prompt": "Hello, my name is",
   "temperature": 0.1, "top_p": 0.1
 }'

用 engine_args 传任意 vLLM 参数：AsyncEngineArgs 的一个子集已暴露为带类型的 YAML 字段（tensor_parallel_size、gpu_memory_utilization、quantization、max_model_len、dtype、trust_remote_code、enforce_eager 等），其余一切均可通过通用 engine_args: 映射透传。键会原样转发给 vLLM 引擎；未知键在加载时失败并提示最接近的合法名。嵌套映射会物化为 vLLM 的嵌套配置数据类（SpeculativeConfig、KVTransferConfig、CompilationConfig 等）。

推测解码（speculative decoding：DFlash、ngram、eagle、deepseek_mtp 等）即用这种方式配置：

name: qwen3.5-4b-dflash
backend: vllm
parameters:
  model: Qwen/Qwen3.5-4B
context_size: 8192
max_model_len: 8192
trust_remote_code: true
quantization: fp8
template:
  use_tokenizer_template: true
engine_args:
  speculative_config:
    method: dflash
    model: z-lab/Qwen3.5-4B-DFlash
    num_speculative_tokens: 15

speculative_config 的形状遵循 vLLM 的 SpeculativeConfig 定义——method 选择算法，其余键依算法而异。z-lab 发布的 drafter 与特定 target 模型配对，请按你的目标模型挑选匹配项。drafter 以其原生精度加载，不受目标模型 quantization: 设置影响。

另一个例子——手动指定非默认 attention 后端（例如默认 cutlass 内核不支持的硬件上）：

engine_args:
  attention_backend: TRITON_ATTN

用 options 写 CLI 风格引擎参数：引擎参数也可以按 vLLM 自己的 CLI 拼写写在 options: 中，方便直接从 vLLM 文档复制命令行：

options:
  - --quantization:gptq_marlin
  - --enable-prefix-caching
  - --kv-cache-dtype:fp8_e5m2
  - --reasoning-parser:qwen3

规则如下：

• 只有 -- 前缀的条目被当作引擎 flag；options: 中的其它条目（tool_parser:、reasoning_parser: 等）保持原有含义。--flag:value 与 --flag=value 两种写法都接受。
• 连字符转为下划线（--enable-prefix-caching → enable_prefix_caching），值会被强转到目标字段类型。裸 --flag 把布尔字段置为 true。
• 未知或无法强转的 flag 只在后端 stderr 记录日志并跳过，不会导致加载失败；engine_args: 保持严格校验且最后应用，冲突时以 engine_args: 为准。

因此：engine_args: 适合一切结构化配置（嵌套 config、map）；options: 是扁平 flag 的便捷写法。

多节点数据并行：engine_args.data_parallel_size > 1 配合 local-ai p2p-worker vllm follower，可以让单个模型横跨多个 GPU 节点。head/follower 配置及 Kimi-K2.6 完整示例见 分布式模式文档中的 vLLM 多节点（数据并行）小节。

SGLang：面向前缀缓存与推测解码的服务框架

SGLang 是面向 LLM 与 VLM 的快速服务框架，聚焦前缀缓存、推测解码与多模态生成。LocalAI 附带一个 gRPC 后端封装 SGLang 的异步 Engine，包含其原生函数调用与推理解析器。

部署：

name: sglang
backend: sglang
parameters:
  model: "Qwen/Qwen3-4B"
template:
  use_tokenizer_template: true

后端首次加载时会从 HuggingFace 拉取模型。

用 engine_args 传任意 SGLang 参数：vLLM 后端接受的同一个 engine_args: 映射同样适用于 SGLang 后端。键会对照 SGLang 的 ServerArgs（其中心配置数据类）校验，并原样转发给 Engine(**kwargs)；未知键在加载时报错并提示最接近的合法名。与 vLLM 不同，ServerArgs 是扁平的：推测解码字段是顶层字段（speculative_algorithm、speculative_draft_model_path 等），而非嵌套在 speculative_config: 字典下。

与 vLLM 共享的带类型 YAML 字段会映射到 SGLang 等价字段（gpu_memory_utilization → mem_fraction_static、enforce_eager → disable_cuda_graph、tensor_parallel_size → tp_size、max_model_len → context_length）。其它一切（含全部推测解码 flag）放进 engine_args:。

推测解码：Gemma 4 + Multi-Token Prediction（MTP）：Google 为每个 Gemma 4 尺寸都发布了配对的 "assistant" drafter。drafter 用 MTP 在每个目标步一次性提出多个候选 token，SGLang 再并行验证。面向 16–24 GB 消费级 GPU 使用 E4B（8B 总量 / 4B 有效参数）：

name: gemma-4-e4b-mtp
backend: sglang
parameters:
  model: google/gemma-4-E4B-it
context_size: 4096
template:
  use_tokenizer_template: true
options:
  - tool_parser:gemma4
  - reasoning_parser:gemma4
engine_args:
  mem_fraction_static: 0.85
  speculative_algorithm: NEXTN
  speculative_draft_model_path: google/gemma-4-E4B-it-assistant
  speculative_num_steps: 5
  speculative_num_draft_tokens: 6
  speculative_eagle_topk: 1

更小的卡（8–12 GB）可换 E2B（5B 总量 / 2B 有效）：把模型路径换成 google/gemma-4-E2B-it 与 google/gemma-4-E2B-it-assistant，其余 flag 保持不变。仓库 gallery 目录中的 sglang-gemma-4-e4b-mtp.yaml、sglang-gemma-4-e2b-mtp.yaml 即为本文档同源的内置画廊配方。

要点：NEXTN 在 ServerArgs.__post_init__ 内部会归一化为 EAGLE，两种写法都可用（cookbook 用 NEXTN）。mem_fraction_static 是 SGLang 为"模型 + KV 池"预留的 GPU 显存比例，0.85 是 cookbook 默认值，可适配后端所在的任意单卡。31B 稠密与 26B-A4B MoE 版 Gemma 4 在同一 cookbook 中存在，但要求 --tp-size 2，因此不作为单卡配方进入画廊。

SGLang 版本要求：Gemma 4 支持经 SGLang PR #21952 合入。LocalAI 的 sglang 后端钉住了包含该 PR 的版本；若你把钉住的版本改旧，本配方会在加载时报 "model architecture not recognised"。

其它推测算法：speculative_algorithm: 还接受 EAGLE/EAGLE3（搭配 EAGLE 式 draft head）、DFLASH（z-lab 为 Qwen3 家族发布的 block-diffusion drafter）、STANDALONE（用较小的 draft LLM 验证较大 target）以及 NGRAM（无 draft 模型——纯前缀历史推测）。完整算法矩阵见 SGLang 的推测解码文档。

工具调用与推理解析器：SGLang 的原生解析器会把 tool_calls 与 reasoning_content 流式送入 ChatDelta——LocalAI 的 Python 后端按请求接线，而非经由 engine_args:。按名挑选解析器：

options:
  - tool_parser:hermes
  - reasoning_parser:deepseek_r1

已注册解析器的完整列表位于 SGLang 的 sglang.srt.function_call 与 sglang.srt.parser.reasoning_parser 中。

vllm.cpp：无 Python 的 vLLM C++ 移植

vllm.cpp 是 LocalAI 团队对 vLLM 的 C++ 移植：同样的 continuous-batching 调度器、paged KV cache 与前缀缓存，但推理时无 Python。它既吃 HuggingFace safetensors 模型目录，也吃 .gguf 文件，并在引擎侧应用模型的 chat template、工具调用解析与推理切分。

本小节是配置参考；后端安装与画廊内置的现成模型见 vllm-cpp 后端页面。

部署：

name: vllm-cpp
backend: vllm-cpp
parameters:
  model: "Qwen/Qwen3-4B"
context_size: 8192
template:
  use_tokenizer_template: true

用 engine_args 配置引擎：vLLM 与 SGLang 后端接受的 engine_args: 映射在此同样生效，键的拼写与 vLLM 自身 CLI flag 完全一致——为 vLLM 写的 speculative_config 或 kv_transfer_config 块可原样复用。未知键被忽略而非致命；引擎会校验交给它的配置文档，并在加载时报出精确错误。

name: qwen35-a3b
backend: vllm-cpp
parameters:
  model: "Qwen/Qwen3.5-A3B"
context_size: 16384
template:
  use_tokenizer_template: true
engine_args:
  # KV cache sizing: num_blocks * block_size tokens of cache.
  block_size: 32
  num_blocks: 1024
  # Concurrency and the per-step chunked-prefill token budget.
  max_num_seqs: 32
  max_num_batched_tokens: 8192
  # Automatic prefix caching. Omit to keep the model's own default
  # (on for dense models, off for hybrid / attention-free ones).
  enable_prefix_caching: true
  # Scheduler admission order: fcfs (default), priority, or lpm
  # (cache-aware longest-prefix-match; needs prefix caching to have any effect).
  scheduling_policy: lpm

键	含义	默认
block_size	KV-cache 块大小（每块 token 数）	32
num_blocks	分配的 KV-cache 块数	256
max_model_len	最大序列长度；也可通过 context_size / max_model_len 设置	模型配置
max_num_seqs	调度器允许的最大并发序列数	8
max_num_batched_tokens	每步 chunked-prefill token 预算	按架构（dense 2048，MoE 4096/8192）
enable_prefix_caching	自动前缀缓存；enable_radix_attention 是接受的别名	模型默认
enable_jump_forward	Jump-forward 解码，可在无模型步的情况下吐出文法强制的 token。只影响受约束请求（grammar、JSON schema）	关闭
scheduling_policy	fcfs、priority 或 lpm	fcfs
tool_parser / reasoning_parser	强制指定解析器，替代 chat-template 自动探测	auto
tokenizer_config	覆盖读取 chat template 的 tokenizer_config.json	<model_dir>/tokenizer_config.json
speculative_config	推测解码（见下）	disabled
kv_transfer_config	外部 KV 连接器 / LMCache（见下）	none

调高 max_num_batched_tokens 可让更多 prefill 在同一步内完成，代价是排在后面的请求的解码延迟上升。默认值刻意不与 max_num_seqs 联动——这正是防止大并发 prefill 在混合架构上撑爆每步激活量的原因。

enable_prefix_caching 与 enable_jump_forward 在引擎边界是三态的：省略键遵循默认（前缀缓存看模型自身能力，jump forward 看环境变量），显式 false 则强制关闭。二者含义确实不同——前缀缓存对 dense 模型默认开启——因此只在你有意覆盖默认时才写该键。

推测解码：speculative_config: 接受与 vLLM --speculative-config 相同的 JSON 对象，支持三种方法。

架构限制：在当前引擎 pin 下，mtp 与 dflash 仅支持 Qwen3.5 / Qwen3.6。引擎会为这些家族直接构建加宽的推测 KV 缓存（而非经由模型注册表），因此对其它架构（Llama、GLM、Gemma、Mistral……）无论 checkpoint 格式如何都无法生效。ngram 不需要 draft 权重，不受此限制。

格式支持：mtp 与 dflash 现在同样支持从 .gguf target 出发（不只 safetensors）。当文件声明 <arch>.nextn_predict_layers 时，MTP head 从 GGUF 的 nextn.* 张量读取；未携带 head 导出的 GGUF（以 --no-mtp 转换，或早于 llama.cpp 的 Qwen3.5 MTP 支持）在加载时会被拒绝并指明原因。DFlash draft 本身可以是 dflash 架构的 GGUF，target 也可以是 GGUF。ngram 无需 draft 权重，任何格式可用。

MTP（Multi-Token Prediction）使用内置于 target checkpoint 自身 mtp.* 张量中的 draft head，无需下载第二个模型。它要求 safetensors checkpoint——mtp.* 张量无法在 GGUF 转换中保留，因此对 .gguf 模型配置 MTP 会在加载时被拒绝：

engine_args:
  speculative_config:
    method: mtp
    # Optional; defaults to the checkpoint's own head depth, which is
    # usually the right value. Must be a multiple of that depth.
    num_speculative_tokens: 1

DFlash 使用独立的 block-diffusion drafter，在一次非自回归前向中提出整块 token。与 MTP 不同，draft 是独立 checkpoint，因此 model: 必填：

engine_args:
  speculative_config:
    method: dflash
    model: z-lab/Qwen3.6-27B-DFlash
    num_speculative_tokens: 4

draft 与 target 共享 embed_tokens 与 lm_head，因此二者必须来自同一模型家族，且 target 必须是 safetensors。

引擎不会下载 draft。model: 按如下顺序解析：先作为给定路径；然后作为 LocalAI models 目录下的末段路径（z-lab/Qwen3.6-27B-DFlash → <models>/Qwen3.6-27B-DFlash，正是 LocalAI 自带下载器的产物）；再作为 models 目录下的完整引用。请先自行把 draft 装进 LocalAI，或给出含 config.json 的目录的绝对路径。若全部失败，加载会立即失败并逐一列出尝试过的位置，而不是报引擎内部缺 checkpoint 的错误。

N-gram 完全不需要 draft 模型——它从提示自身的后缀历史提出候选。num_speculative_tokens 必填：

engine_args:
  speculative_config:
    method: ngram
    num_speculative_tokens: 4
    prompt_lookup_min: 5
    prompt_lookup_max: 5

导入时自动配置：当你以 backend: vllm-cpp 导入 safetensors 仓库时，LocalAI 会读取 checkpoint 的 config.json；若其声明了 MTP head（mtp_num_hidden_layers），会替你把 speculative_config: {method: mtp} 写进生成的 engine_args。你显式配置的 speculative_config 永不被覆盖。导入 DFlash draft 仓库会被拒绝并告警：drafter 不能独立服务，应导入 target 模型并把 speculative_config.model 指向 draft。

用 LMCache 做外部 KV 缓存：kv_transfer_config: 接受 vLLM 的 --kv-transfer-config JSON，选择外部 KV-cache 连接器。lm:// LMCache 客户端可把 prefill 的 KV 存入并从共享的 lmcache.v1.server 重新加载，使一个副本算过的前缀无需被下一个副本重算：

engine_args:
  kv_transfer_config:
    kv_connector: LMCacheConnector
    kv_role: kv_both          # required whenever kv_connector is set
    kv_connector_extra_config:
      host: 127.0.0.1
      port: 65432

kv_role 取值为 kv_producer（只存）、kv_consumer（只读）或 kv_both。未注册的连接器名、缺失 role 或畸形文档都会以显式错误使加载失败，而非静默无缓存运行。

旧的 options: 列表：早期版本通过扁平的 options: 列表配置此后端，这类配置仍然可用。上表每个键仍可从其中以 key:value 形式读取；两处都设置时 engine_args 优先：

options:
  - max_num_seqs:32
  - enable_prefix_caching:true

新配置应优先使用 engine_args:——它是唯一能自然书写嵌套 speculative_config / kv_transfer_config 文档（而非单行 JSON 字符串）的地方。

Transformers：PyTorch / OpenVINO 全家桶

Transformers 是为 PyTorch、TensorFlow、JAX 提供 SOTA 模型的机器学习库。LocalAI 内置其集成。这是一个额外后端——在容器镜像（extra 镜像已包含 Transformers 的 Python 依赖）中开箱即用，无需额外安装。

部署：创建 YAML 并指定模型名：

name: transformers
backend: transformers
parameters:
    model: "facebook/opt-125m"
type: AutoModelForCausalLM
quantization: bnb_4bit # One of: bnb_8bit, bnb_4bit, xpu_4bit, xpu_8bit (optional)

后端会自动下载运行所需文件。

参数——Type（模型类型）：

Type	说明
AutoModelForCausalLM	用于序列生成；适配 NVIDIA CUDA 与带 Intel Extensions for PyTorch 加速的 Intel GPU
OVModelForCausalLM	用于 Intel CPU/GPU/NPU 上的 OpenVINO 文本生成模型
OVModelForFeatureExtraction	用于 Intel CPU/GPU/NPU 上的 OpenVINO 嵌入加速
缺省	默认使用 AutoModel

• OVModelForCausalLM 需要 HuggingFace 上的 OpenVINO IR 文本生成模型；
• OVModelForFeatureExtraction 可用于任意 Safetensors 的 Transformers 特征提取（Embedding）模型。

注意：流式输出目前未在 Intel GPU 上的 AutoModelForCausalLM 中实现；AMD GPU 支持未实现；OpenVINO 虽不官方支持 AMD CPU，但有报告称可运行（YMMV）。

Embeddings：若模型是嵌入模型，使用 embeddings: true。

推理设备选择：Transformer 后端会自动挑选最佳推理设备，也可用 main_gpu 参数手动覆盖：

推理引擎	可取值
CUDA	cuda、cuda.X（X 为 nvidia-smi -L 输出中的设备号）
OpenVINO	AUTO、CPU、GPU、NPU、MULTI、HETERO 等任何适用值

示例（CUDA）：main_gpu: cuda.0 示例（OpenVINO）：main_gpu: AUTO:-CPU

该参数同时作用于文本生成与特征提取（Embeddings）模型。

推理精度：Transformer 后端按设备支持自动挑选最快的可用推理精度。CUDA 后端在硬件支持时可用如下参数手动开启 bfloat16：

f16: true

量化（Quantization）：

量化	说明
bnb_8bit	8-bit 量化
bnb_4bit	4-bit 量化
xpu_8bit	面向 Intel XPU 的 8-bit 量化
xpu_4bit	面向 Intel XPU 的 4-bit 量化

Trust Remote Code：部分模型（如 Microsoft Phi-3）需要 Transformer 库之外的第三方代码。出于安全默认关闭，可用以下配置手动开启：

trust_remote_code: true

最大上下文长度：context_size 参数以字节为单位指定最大上下文；不要设置超过模型支持的值。示例：context_size: 8192。

自动提示模板：对话模板通常由模型作者定义在 tokenizer_config.json 中，在 template 节使用 use_tokenizer_template: true 开启：

template:
  use_tokenizer_template: true

自定义停止词：停用词通常定义在 tokenizer_config.json，必要时可用 stopwords 覆盖（例如 llama3-Instruct 模型）：

stopwords:
- "<|eot_id|>"
- "<|end_of_text|>"

使用：通过 completions 端点指定 transformers 模型：

curl http://localhost:8080/v1/completions -H "Content-Type: application/json" -d '{
   "model": "transformers",
   "prompt": "Hello, my name is",
   "temperature": 0.1, "top_p": 0.1
 }'

示例——OpenVINO + Starling：下面是一份完整可用的 OpenVINO 文本生成模型配置（注意自定义 chat/completion 模板与停止词、缓存路径的配合）：

name: starling-openvino
backend: transformers
parameters:
  model: fakezeta/Starling-LM-7B-beta-openvino-int8
context_size: 8192
threads: 6
f16: true
type: OVModelForCausalLM
stopwords:
- <|end_of_turn|>
- <|endoftext|>
prompt_cache_path: "cache"
prompt_cache_all: true
template:
  chat_message: |
    {{if eq .RoleName "system"}}{{.Content}}<|end_of_turn|>{{end}}{{if eq .RoleName "assistant"}}<|end_of_turn|>GPT4 Correct Assistant: {{.Content}}<|end_of_turn|>{{end}}{{if eq .RoleName "user"}}GPT4 Correct User: {{.Content}}{{end}}

  chat: |
    {{.Input}}<|end_of_turn|>GPT4 Correct Assistant:

  completion: |
    {{.Input}}

小结：如何为你的场景选择后端与协议

综合上述内容，可以归纳出几条实用的选型路径：

• 接口协议层面：需要 OpenAI 生态（含各类 AI 编码助手、Chat 客户端）时首选 /v1/chat/completions；对接 Claude 生态客户端或想用 system+max_tokens 的 Anthropic 语义时用 /v1/messages；需要后台任务、previous_response_id 会话拼接与统一工具/推理语义时用 /v1/responses。三套入口在源码层面都汇入同一模型配置解析与后端推理管线（core/http/endpoints/openai、anthropic/messages.go、openresponses/responses.go）。
• 后端引擎层面：单机 CPU/GPU 跑 GGUF 首选 llama-cpp；追求 CPU 极致性能或有 AVX2 且想用 IQK 量化选 ik-llama-cpp；想压 KV-cache 显存、用 TurboQuant 量化缓存选 turboquant；需要高吞吐并发服务或 vLLM 家族特性选 vllm/vllm-cpp/sglang（注意各自的推测解码适用范围）；需要 PyTorch 生态或 Intel OpenVINO 硬件加速选 transformers。

配置任何一个模型后，都可以用 /v1/models 验证它已被服务端正确发现，随后即可在上文任一生成端点中通过 model 字段引用。各模型的 GPU 显存适配细节可继续参考 vram-management.md 与 GPU 加速指南。