You're reading an pre-release version of this documentation.
For the latest stable release version, please have a look at master.

server 接口说明

简介

下位机实现了一个基于 JSON-RPC 2.0 标准协议的轻量级服务端框架。 实现通过网口进行nb文件的上传、推理、删除、查询等功能。

编译和使用

  • 下载下位机源码。下位机源码路径工程下的examples/jsonrpc_server下

  • 编译工具和相关库请看jsonrpc_server的页面

  • 将板子ip设置为192.168.23.100，在电脑上添加192.168.23.132这个ip（与板子ip保持在同一网段）。

  • 将可执行文件为examples/jsonrpc_server下的server

  • 传输到板子，在命令行输入./server运行即可。

通信基础信息

  • 通信协议：WebSocket

  • 连接地址：ws://192.168.23.100:8000/websocket，与板卡保持一致

  • 数据格式：JSON-RPC（远程过程调用协议，请求/响应均为JSON格式）

JSON-RPC请求通用格式

所有请求需符合以下JSON结构，通过WebSocket发送文本帧（WEBSOCKET_OP_TEXT）：

{
  "jsonrpc": "2.0",    // JSON-RPC标准版本，固定为2.0
  "method": "方法名",   // 需调用的具体功能（如test、add_model）
  "params": [ ],      // 方法对应的参数列表（格式因方法而异）
  "id": 1               // 请求ID（自定义整数，用于匹配响应与请求）
}

核心功能API详情

1. 加载模型

加载Base64编码的模型文件（.nb格式），并为该模型注册一个专属的推理方法（后续可通过该方法调用模型推理）。

  • 请求参数

    • method：add_model

    • params：数组，包含2个元素： Base64编码的模型文件数据（.nb模型二进制内容）；字符串，为该模型注册的推理方法名（后续调用rpc_infer需使用此名称）。

  • 请求示例

{
  "jsonrpc": "2.0",
  "method": "add_model",
  "params": [
    "nbfile",
    "infer_method"
  ],
  "id": 1
}

  • 成功响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Method 'infer_method' added"
}

  • 失败响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 500,
    "message": "model_add_failed"
  }
}

  • 失败原因：模型文件解码失败、模型上下文创建失败（create_app_ctx返回NULL）。

2. 模型推理

  • 功能描述 调用通过add_model注册的模型，输入Base64编码的图像数据，执行推理并返回Base64编码的张量结果与推理耗时。

  • 请求参数

    • method：通过add_model注册的推理方法名（如infer_method）；

    • params：数组，元素数量等于模型输入节点数（ctx->input_count），每个元素为Base64编码的图像数据（对应模型单个输入的二进制内容）。

  • 请求示例

    {
  "jsonrpc": "2.0",
  "method": "infer_method",  // 已注册的推理方法名
  "params": [
    "image1",
    "image2",
    "..."
  ],
  "id": 1
}

  • 成功响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tensor": [
      "image1",
      "image2",
      "..."     // 数量等于模型输出节点数
    ],
    "infer_time": "12.345678 ms"  // 推理耗时（毫秒级，保留6位小数）
  }
}

  • 内存分配失败：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 500,
    "message": "malloc input_tensor failed"
  }
}

  • 推理执行失败：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 500,
    "message": "Inference failed"
 }
}

3. 删除模型

  • 功能描述 删除已通过add_model注册的模型，释放模型上下文资源与对应的推理方法，避免内存泄漏。

  • 请求参数

  • method：delete_model；

  • params：数组，仅1个元素，为通过add_model注册的推理方法名。

  • 请求示例

{
  "jsonrpc": "2.0",
  "method": "delete_model",
  "params": ["infer_method"],  // 需删除的推理方法名
  "id": 1
}

  • 成功响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Model 'infer_method' deleted"
}

  • 说明：若指定的方法名不存在，仍返回成功（内部会跳过不存在的方法，不报错）。

4. 查询已注册的RPC方法列表

  • 功能描述

返回当前系统中所有已注册的JSON-RPC方法（包括系统方法与用户通过add_model注册的推理方法）。

  • 请求参数

    • method：rpc.list；

    • params：无（空数组[]）。

  • 请求示例

{
  "jsonrpc": "2.0",
  "method": "rpc.list",
  "params": [],
  "id": 1
}

  • 成功响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "add_model",          // 系统加载模型方法
    "delete_model",       // 系统删除模型方法
    "infer_method"        // 用户注册的推理方法（若存在）
    "rpc.list",           // 系统方法列表查询方法
  ]
}

  • 说明：result为字符串数组，包含所有可用的RPC方法名。