Welcome to Firefly
切换语言
切换语言
Firefly文档中心
最近更新: 2026-08-14 16:48:17

API 接口详解

llamapi-server 提供 OpenAI 兼容的对话、Embedding 和模型查询接口，以及用于端侧模型实例管理和硬件平台查询的 LlamaPi 扩展接口。

接口概览

项目说明
Base URLhttp://127.0.0.1:9265
API 前缀OpenAI 兼容接口和管理接口使用 /v1；健康检查除外
请求格式POST 使用 JSON body；GET 不需要 body
响应格式普通接口返回 JSON；流式对话返回 SSE；健康检查返回纯文本
请求体上限64 MiB
鉴权无鉴权要求
CORS允许跨域请求

当前服务默认不要求鉴权，并允许跨域访问。将服务暴露到不可信网络前，应增加防火墙、反向代理或其他访问控制。

快速调用

加载模型：

curl -s http://127.0.0.1:9265/v1/models/load \
  -H 'Content-Type: application/json' \
  -d '{
    "model_id": "Qwen3",
    "model_path": "/var/lib/llamapi/models/rkllm/rk3588/qwen3-4b"
  }'

调用对话接口：

curl -s http://127.0.0.1:9265/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3",
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

通用约定

项目说明
模型 IDmodel 或 model_id 必须对应已加载模型
流式响应对话请求设置 "stream": true 后返回 SSE，结束时发送 data: [DONE]
多模态输入协议可接收 text、image_url 和 input_audio
错误响应普通错误使用 OpenAI 风格 { "error": ... } JSON
SSE 错误流式生成中途失败时发送 event: error

客户端应通过 /v1/models 和 /v1/platforms 发现模型与平台，不要写死运行时模型 ID、平台名称、芯片型号或模型路径。

数据取值约定

闭合集合

以下字段可以按固定集合处理：

字段取值说明
messages[].rolesystem、user、assistant、tool对话消息角色
messages[].content[].typetext、image_url、input_audio支持的 content part
image_url.url 的 data URL 格式png、jpeg、jpg、webp本地路径不使用该枚举
input_audio.formatwav、mp3具体模型可能只支持其中一部分
encoding_formatfloat、base64Embedding 输出编码
model_kindchat、embedding模型能力类型
error.typeinvalid_request_error、rate_limit_exceeded、server_error错误类型

已知但可扩展的响应值

字段当前已知值客户端处理建议
choices[].finish_reasonstop、length、tool_calls兼容未来新增字符串
objectchat.completion、chat.completion.chunk、list、embedding、model根据接口和字段结构处理
error.code见错误响应未知值按通用错误处理

开放值

以下字段不应当作为固定枚举：

字段说明
model、model_id由加载模型时的 ID 决定
idllamapi-server 生成的响应 ID
platform通过平台接口发现
owned_by当前形式为 llamapi/{platform}，客户端不应依赖固定格式
model_pathllamapi-server 文件系统路径
detected_chips[].chip_type当前主机检测到的芯片型号
message人类可读文本，不建议程序解析
tool_call_id、tool_calls[].id由模型输出或请求上下文决定
tools[].type建议使用 function，但服务端按字符串解析
tools[].function.name由客户端定义

接口列表

MethodPath类型说明
POST/v1/chat/completionsOpenAI 兼容对话补全，支持 JSON 和 SSE
POST/v1/embeddingsOpenAI 兼容文本向量，支持单条和批量输入
GET/v1/modelsOpenAI 兼容列出已加载模型
GET/v1/models/{model_id}OpenAI 兼容查询单个已加载模型
POST/v1/models/loadLlamaPi 扩展动态加载模型
POST/v1/models/resizeLlamaPi 扩展调整模型实例数
POST/v1/models/unloadLlamaPi 扩展卸载模型
GET/v1/platformsLlamaPi 扩展查询平台和检测到的芯片
GET/health健康检查检查 HTTP 服务是否运行

错误响应

应用错误使用 OpenAI 风格结构：

{
  "error": {
    "message": "Model 'demo' not found",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
HTTP 状态typecode触发条件
400invalid_request_errorunsupported_platform模型平台不受支持
400invalid_request_errorplatform_detection_failed无法从模型目录识别平台
400invalid_request_errorwrong_model_type对话接口调用 Embedding 模型，或反过来
400invalid_request_errorunsupported_content_part_type包含不支持的 content part
400invalid_request_errorinvalid_content_part图片、音频等 content part 格式非法
400invalid_request_errorcontext_length_exceeded输入超过模型上下文上限
400invalid_request_errorinvalid_instance_count实例数为 0
404invalid_request_errormodel_not_found模型未加载
409invalid_request_errormodel_already_exists模型 ID 已存在
429rate_limit_exceededqueue_full模型实例和等待队列都已满
500server_errornull引擎、配置或内部错误

负数实例数会在 JSON 解析阶段失败。

Chat Completions

POST /v1/chat/completions

对话补全接口。stream 缺省为 false，模型必须是 chat 类型。

请求字段

字段类型必填说明
modelstring是已加载模型 ID
messagesarray是对话消息数组
streamboolean否true 时返回 SSE
temperaturenumber否覆盖默认采样温度
top_pnumber否覆盖默认 top-p
top_kinteger否覆盖默认 top-k
repeat_penaltynumber否覆盖默认重复惩罚
frequency_penaltynumber否覆盖默认频率惩罚
presence_penaltynumber否覆盖默认存在惩罚
max_tokensinteger否最大生成 token 数
max_completion_tokensinteger否与 max_tokens 等价；两者同时传入时优先使用本字段
stopstring array否停止序列
toolsarray否OpenAI 风格 function tools
tool_choicestring否会被解析，但当前 llamapi-server 不使用该值
enable_thinkingboolean否覆盖模型思考模式配置

消息字段

messages[] 支持：

字段类型必填说明
rolestring是system、user、assistant 或 tool
contentstring 或 array否纯文本或 content parts
tool_call_idstring否tool 消息对应的工具调用 ID
tool_callsarray否assistant 消息中的工具调用

多模态内容

当 content 是数组时，支持：

文本：

{
  "type": "text",
  "text": "描述这张图片"
}

图片：

{
  "type": "image_url",
  "image_url": {
    "url": "/path/to/image.jpg"
  }
}

图片 URL 支持：

  • llamapi-server 本地图片路径。
  • png、jpeg、jpg、webp 的 base64 data URL。

不支持 http:// 或 https:// 远程图片 URL。

音频：

{
  "type": "input_audio",
  "input_audio": {
    "format": "wav",
    "data": "<base64>"
  }
}

协议层支持 wav 和 mp3，具体模型可能只支持其中一部分。

video、file 和未知类型会返回 unsupported_content_part_type。

工具定义

tools[] 使用 OpenAI function tool 结构：

字段类型必填
typestring是，建议为 function
function.namestring是
function.descriptionstring是
function.parametersJSON是

非流式请求

curl -s http://127.0.0.1:9265/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3",
    "messages": [
      { "role": "user", "content": "用一句话介绍 LlamaPi。" }
    ],
    "max_tokens": 128
  }'

非流式响应

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "Qwen3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "...",
        "tool_calls": []
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 14,
    "total_tokens": 27
  }
}

流式请求

curl -N http://127.0.0.1:9265/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3",
    "messages": [
      { "role": "user", "content": "你好" }
    ],
    "stream": true
  }'

流式响应

每个 SSE 事件的 data 是 chat.completion.chunk JSON。生成结束后，llamapi-server 发送独立的 usage chunk，再发送 [DONE]：

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"Qwen3","choices":[{"index":0,"delta":{"role":"assistant","content":"你"}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"Qwen3","choices":[{"index":0,"delta":{"content":"好"}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"Qwen3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"Qwen3","choices":[],"usage":{"prompt_tokens":13,"completion_tokens":14,"total_tokens":27}}

data: [DONE]

流式生成中途失败时，llamapi-server 发送：

event: error
data: {"error":{...}}

错误后终止流，不再发送 [DONE]。

Embeddings

POST /v1/embeddings

模型必须是 embedding 类型。

Embeddings 请求字段

字段类型必填说明
modelstring是已加载 Embedding 模型 ID
inputstring 或 string array是单条或批量文本
encoding_formatstring否float 或 base64；默认 float
dimensionsinteger否会被解析，但当前 llamapi-server 不裁剪向量
userstring否会被解析，但当前 llamapi-server 不使用

base64 表示 little-endian f32 原始字节的 base64 编码。

加载 Embedding 模型

可以使用 llamapi-cli：

llamapi load bge-m3
llamapi ps

也可以调用管理 API：

curl -s http://127.0.0.1:9265/v1/models/load \
  -H 'Content-Type: application/json' \
  -d '{
    "model_id": "bge-m3",
    "model_path": "/var/lib/llamapi/models/rknn2/rk3588/bge-m3"
  }'

Embeddings 请求示例

curl -s http://127.0.0.1:9265/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bge-m3",
    "input": ["hello", "LlamaPi"],
    "encoding_format": "float"
  }'

Embeddings 响应示例

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1, 0.2],
      "index": 0
    }
  ],
  "model": "bge-m3",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

查询模型

列出模型

GET /v1/models
curl -s http://127.0.0.1:9265/v1/models

响应：

{
  "object": "list",
  "data": [
    {
      "id": "Qwen3",
      "object": "model",
      "created": 0,
      "owned_by": "llamapi/rkllm",
      "platform": "rkllm",
      "instance_count": 1,
      "model_path": "/var/lib/llamapi/models/rkllm/rk3588/qwen3-4b",
      "model_kind": "chat"
    }
  ]
}

查询单个模型

GET /v1/models/{model_id}
curl -s http://127.0.0.1:9265/v1/models/Qwen3

响应对象字段与 /v1/models 的 data[] 相同。模型不存在时返回 404 model_not_found。

加载模型

POST /v1/models/load

加载模型请求字段

字段类型必填说明
model_idstring是对外暴露的模型 ID
model_pathstring是llamapi-server 文件系统中的模型目录
instance_countinteger否目标实例数，默认 1，必须大于等于 1
request_queue_sizeinteger否模型等待队列容量；缺省使用 llamapi-server 配置
default_paramsobject否模型默认生成参数

default_params 支持：

  • temperature
  • top_p
  • top_k
  • repeat_penalty
  • frequency_penalty
  • presence_penalty
  • max_tokens
  • max_context_len
  • stop
  • enable_thinking

加载模型请求示例

curl -s http://127.0.0.1:9265/v1/models/load \
  -H 'Content-Type: application/json' \
  -d '{
    "model_id": "Qwen3",
    "model_path": "/var/lib/llamapi/models/rkllm/rk3588/qwen3-4b",
    "instance_count": 2,
    "default_params": {
      "temperature": 0.7,
      "max_tokens": 512
    }
  }'

加载模型响应示例

{
  "success": true,
  "message": "model 'Qwen3' loaded",
  "requested_instance_count": 2,
  "actual_instance_count": 2
}

如果至少一个实例加载成功，接口返回 200 OK：

  • 全部成功时，message 为 model '<id>' loaded。
  • 部分成功时，message 为 model '<id>' partially loaded。
  • requested_instance_count 是目标数量。
  • actual_instance_count 是实际加载数量。

协处理器实例限制

在协处理器芯片上通过 /v1/models/load 或 /v1/models/resize 请求多个模型实例，可能导致加载失败、芯片通信失败和服务异常。当前应将协处理器模型的 instance_count 保持为 1。故障恢复步骤见协处理器加载多个模型实例后通信失败。

调整实例数

POST /v1/models/resize
字段类型必填说明
model_idstring是已加载模型 ID
instance_countinteger是目标实例数，必须大于等于 1
curl -s http://127.0.0.1:9265/v1/models/resize \
  -H 'Content-Type: application/json' \
  -d '{
    "model_id": "Qwen3",
    "instance_count": 1
  }'

响应：

{
  "success": true,
  "message": "model 'Qwen3' resized",
  "requested_instance_count": 1,
  "actual_instance_count": 1
}

扩容只成功创建部分实例时仍可能返回 200 OK，message 为 model '<id>' partially resized。

卸载模型

POST /v1/models/unload
字段类型必填说明
model_idstring是已加载模型 ID
curl -s http://127.0.0.1:9265/v1/models/unload \
  -H 'Content-Type: application/json' \
  -d '{ "model_id": "Qwen3" }'

响应：

{
  "success": true,
  "message": "model 'Qwen3' unloaded"
}

查询平台

GET /v1/platforms

返回已注册的对话与 Embedding 平台，以及当前主机检测到的芯片。

curl -s http://127.0.0.1:9265/v1/platforms

响应示例：

{
  "platforms": [
    {
      "id": "rknn3",
      "display_name": "RKNN3",
      "available": true,
      "detected_chips": [
        {
          "chip_type": "RK1828",
          "count": 2
        }
      ]
    }
  ]
}

detected_chips 按芯片型号汇总数量。没有检测到芯片时返回空数组。

健康检查

GET /health
curl -s http://127.0.0.1:9265/health

响应：

ok

健康接口只检查 HTTP 服务是否运行，不代表已经加载模型。模型可用性应通过 /v1/models 和实际推理请求确认。

服务配置与运维

上一页

本页目录

API 接口详解接口概览快速调用通用约定数据取值约定闭合集合已知但可扩展的响应值开放值接口列表错误响应Chat Completions请求字段消息字段多模态内容工具定义非流式请求非流式响应流式请求流式响应EmbeddingsEmbeddings 请求字段加载 Embedding 模型Embeddings 请求示例Embeddings 响应示例查询模型列出模型查询单个模型加载模型加载模型请求字段加载模型请求示例加载模型响应示例协处理器实例限制调整实例数卸载模型查询平台健康检查