接入第三方应用

LlamaPi 可以通过 OpenAI 兼容 API 为第三方应用提供本地大模型能力。

本章以对话模型为例介绍通用接入方法。接口字段和完整能力范围见API 接口详解。

接入前提

接入第三方应用前，请按下列操作逐步确认 LlamaPi 的运行状态、网络连通性以及接口可用性。

确认服务和推理平台

llamapi platform

正常输出示例：

SoC:                    RK3588
Coprocessor:            null
Supported platforms:    rkllm, rknn2
Unsupported platforms:  rknn3
Service:                running  (http://127.0.0.1:9265/v1)

输出中显示已识别的 SoC、Supported platforms 至少列出一个推理平台，且 Service 为 running 时，表示 LlamaPi 服务和推理平台状态正常。

设备没有协处理器时，Coprocessor: null 属于正常输出。Unsupported platforms 中的内容不影响使用已支持的推理平台。

确认所需模型已加载

llamapi ps

正常输出示例：

ID                         MODEL       TYPE   PLATFORM       STATUS       INSTANCES    ENABLE
qwen3:4b@rkllm-rk3588      qwen3:4b    chat   rkllm/rk3588   ● active     1            no

在输出中找到准备接入的模型，并确认：

• MODEL 列与需要使用的模型名称一致。如果同名模型有多行记录，可通过 PLATFORM 列区分推理平台变体。
• TYPE 为 chat 的模型可以接收对话请求，TYPE 为 embedding 的模型可以接收词嵌入推理请求。
• STATUS 为 ● active 表示模型已加载，可以接收对应类型的请求。

确认后，将同一行 ID 列的完整值作为第三方应用中的模型名称，不要只填写 MODEL 列中的显示名称。

如果未找到目标模型，或其状态为 ○ inactive，请先加载模型：

llamapi load qwen3:4b

确认服务地址可达

本地访问 LlamaPi

如果第三方应用与 LlamaPi 运行在同一设备上，使用以下服务地址：

http://127.0.0.1:9265/v1

在该设备的 Linux 终端中执行：

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

如果使用 Windows，请在 PowerShell 或命令提示符中执行：

curl.exe -s http://127.0.0.1:9265/health

局域网内访问 LlamaPi

如果第三方应用位于同一局域网中的其他设备上，需要先在运行 LlamaPi 的设备上查看其 IP 地址：

hostname -I

将下方地址中的 <设备 IP> 替换为查询到的实际 IP 地址：

http://<设备 IP>:9265/v1

在第三方应用所在设备上测试连通性。如果该设备运行 Linux，请在终端执行：

curl -s http://<设备 IP>:9265/health

如果该设备运行 Windows，请在 PowerShell 或命令提示符中执行：

curl.exe -s http://<设备 IP>:9265/health

以上命令返回 ok 表示第三方应用所在设备可以访问 LlamaPi 服务。如果连接超时或被拒绝，请检查设备 IP、防火墙和端口 9265。

确认推理接口可用

建议先在能够访问 LlamaPi 服务的终端中，根据接入需求验证对话接口或词嵌入接口。以下命令中的 <设备 IP> 请按照上文说明替换为 127.0.0.1 或运行 LlamaPi 设备的实际 IP。

对话接口（对应 TYPE 为 chat 的模型）：

curl http://<设备 IP>:9265/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3:4b@rkllm-rk3588",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "stream": false
  }'

词嵌入接口（对应 TYPE 为 embedding 的模型）：

curl http://<设备 IP>:9265/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bge-m3@rknn2-rk3588",
    "input": "需要转换为向量的文本"
  }'

将 model 替换为 llamapi ps 显示的实际模型 ID。

配置第三方应用

不同应用的设置名称可能不同，但通用配置流程如下：

1. 在应用中选择 OpenAI 或 OpenAI-compatible 服务提供方。
2. 找到自定义 Base URL、API Endpoint 或服务地址的设置。
3. 填写前述步骤中确认的 Base URL 和模型 ID。如果应用要求填写 API Key，请填写任意非空内容。
4. 保存配置并发送一条测试消息。

配置项填写示例：

如果应用会自动查询模型列表，应确认它访问的是 /v1/models。如果应用不能自定义 Base URL，或者只接受特定云服务地址，则无法使用这种通用方式直接接入。

⚠️ 安全提醒：当前 LlamaPi 不提供 API 鉴权。

第三方应用中填写的 API Key 仅用于满足客户端的必填校验，不会被 LlamaPi 验证，也不能限制访问。

建议仅在本机或可信局域网中使用，不要直接将端口 9265 和 9266 暴露到公网。9266 为模型管理服务的监听端口，同样免认证，且提供删除本地模型的接口。

需要跨网络访问时，请配置防火墙、反向代理和访问认证。详细说明见服务配置与运维。

常见连接问题

更多问题见常见问题与故障排查。