跳到主要内容
版本：最新版本(unreleased)

标准协议

ASE API协议​

1. 整体体说明​

本协议面向AthenaServing 进行了面向应用者开发、内部业务协议进行了约束和定义

2 面向应用开发者协议​

协议采用json进行描述，

2.1 元数据​

由于AI的服务请求一般是用于数据计算与处理，在交互的往来协议中，需要携带一些基础数据。本协议将数据进行抽象约束。为提高适配性，本协议对元数据进行了枚举定义。元数据结构中定义了对应数据类型基本的描述进行了定义，也允许增加K-V单层结构的的描述。用户在定义数据时，选择数据类型后，系统会主动提供结构字段。

2.1.1 文本描述​

结构举例：

{
    "encoding":"utf8", 
    "status":0,
    "seq": 1，
    "compress":"gzip",
    "custom1":"zz",
    "text":"hello word"
}
字段含义类型说明
encoding文本编码string取值范围可枚举
status数据状态int取值范围为0（开始）、1（继续）、2（结束）、3（一次传完）
text文本数据string为文本数据，base64
seq数据序号int标明数据为第几块，可选
custom1用户自定义参数string或 int用户自定义，一级参数
2.1.2 音频描述​
{
    "status":0，
    "sample_rate":16000,
    "channels":1,
    "bit_depth":16,
    "encoding":"opus",
    "seq": 1,
    "custom1":"zz",
    "audio":"xxxxxxxxxxxxxxxxxxxxxxxxxx" # 音频数据
}
字段含义类型说明
encoding音频编码string取值范围可枚举
status数据状态int取值范围为0（开始）、1（继续）、2（结束）、3（一次传完）
audio音频数据string为文本数据，base64
sample_rate采样率int音频采样率，可枚举
channels声道数int声道数，可枚举
bit_depth位深int单位bit，可枚举
seq数据序号int标明数据为第几块，可选
custom1用户自定义参数string或 int用户自定义，一级参数
2.1.2 待完善​

1 图像 2 音频 3 其他二进制数据等

2.2 请求协议说明​

分为三部分：平台参数、能力参数、传输数据。请求协议举模板如下：

{
     "header":{},
     "parameter":{
         "service_iat":{
              "accept_1":{
            }
         }
     }, 
     "payload":{
        "service_iat":{
        }
     }
}

字段说明：

字段含义类型说明
header平台参数Object用于控制平台特性的参数，如appid等，此结构只有一个层级，开发者不可修改。
parameter能力参数Object用于控制AI引擎特性开关的。该段将会被直接透传至引擎,多层级结构,结构确定,未枚举结构为一级结构
payload输入数据Object用于携带请求的数据，多层级结构,结构确定
accept_1输入数据Object用户自定义,用于描述返回结果的编码\数据格式的参数,此结构由元数据中定义的属性中定义的
service_iat输入数据Object用户自定义, 可默认与accept_1一致。 用于携带请求的数据，多层级结构,结构确定
2.2.1 单能力单数据举例如​
{
    "header":{
    "appid":"1234",
    "uid":"d233"
    },
    "parameter":{
        "service_iat":{
           "language": "zh_cn",
           "domain":"iat",
           "accent": "mandarin"
           }
    }, 
    "payload":{
        "service_iat":{
        "status":0,
        "format":"audio/L16;rate=16000",
        "encoding":"raw",
        "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
        }
     }
 }
2.2.2 单能力单多数据举例​
    {
    "header":{
        "appid":"1234",
        "uid":"1234"
    },

    "parameter":{
      "service_iat":{
           "language": "zh_cn",
           "domain":"iat",
           "accent": "mandarin"
           }
    },

    "payload":{
        "data_1":{
            "status":0,
            "format":"audio/L16;rate=16000",
            "encoding":"raw",
              "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
         },
         "data_2":{
            "status":0,
            "format":"audio/L16;rate=16000",
            "encoding":"raw",
               "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
     }
}
}

结构说明：

  1. 此时payload为多级结构
  2. 多数据情况想，payload通过不同的数据ID作为key来描述，如示例中的data_1、data_2
  3. 数据ID为用户自定义
2.2.3 多数据范围特性时的描述​

针对存在多个数据流返回的，需要在输入参数（parameter段）中指定多个数据特性的描述。

"parameter":{
      "service_iat":{
           "language": "zh_cn",
           "domain":"iat",
           "accent": "mandarin",
           "accept_1":{
            "format":"audio/L16;rate=16000",
            "encoding":"raw"
            },
           "accept_2":{
            "format":"audio/L16;rate=16000",
            "encoding":"raw"
           }
       ｝

    }

结构说明：

  1. 此时parameter为多级结构
  2. 多数据情况下，parameter通过不同的ID作为key来对不同的结果进行描述，如示例中的accept_1、accept_2
  3. Accept ID为用户自定义
2.2.4 多能力多数据描述​
    {
        "header":{
            "appid":"1234",
            "uid":"1234"
        },
        "parameter":{
            "service_1":{

                   "language": "zh_cn",
                   "domain":"iat",
                   "accent": "mandarin"
            },
            "service_2":{

                   "language": "zh_cn",
                   "domain":"iat",
                   "accent": "mandarin"
            }
        },

        "payload":{
            "service_1_data_1":{
                "status":0,
                "format":"audio/L16;rate=16000",
                "encoding":"raw",
                 "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
                  },

             "service_2_data_1":{
                "status":0,
                "format":"audio/L16;rate=16000",
                "encoding":"raw",
                 "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
              },
             "service_2_data_2":{
                "status":0,
                "format":"audio/L16;rate=16000",
                "encoding":"raw",
                "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
                 }
        }
    }

结构说明：

  1. 此时parameter为多级结构，此时payload为多级结构
  2. 多数据情况下，parameter通过不同的能力ID作为key来分别描述不同能力的特性描述，service_1、service_2
  3. 能力ID为用户自定义
  4. 多数据情况想，payload通过不同的数据ID作为key来描述，如示例中的service_1_data_1、service_2_data_1、service_2_data_2
  5. 此场景下数据ID为编排平台的借口生成
2.2.5 流式场景下，后续数据包描述​

header、parameter为可选，一般情况不携带。以多数据为例：

 {
    "header":{
         "sid":"iat000704fa@dx16ade44e4d87a1c802", #可选  
        },
    
    "payload":{
        "data_1":{
            "status":1,
            "format":"audio/L16;rate=16000",
            "encoding":"raw",
                    "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
         },

        "data_2":{
            "status":1,
            "format":"audio/L16;rate=16000",
            "encoding":"raw",
                    "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
         }
 }

字段说明：

字段含义类型说明
sid平台返回会话句柄Object返回消息中携带的会话句柄，可选

2.3 返回协议说明​

返回协议定义了会话的计算状态，以及数据段

2.3.1 单输出描述​
{
  "header":{
     "code": 0, 
     "message": "success", 
     "sid": "iat000704fa@dx16ade44e4d87a1c802"

},
 # 此结构为元数据结构（data），描述返回结果。
 "payload": {
     “result_1”：{
        "status":0, #数据状态
        "format":"audio/L16;rate=16000",
        "encoding":"raw",
           "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
        }
   }
}
字段含义类型说明
code错误码int可枚举
message错误描述string错误信息描述
sid平台返回会话句柄Object返回消息中携带的会话句柄，可选
payload输入数据Object用于携带返回的数据，元数据结构见 [2.1 元数据 的定义](”2.1 元数据 的定义“)
2.3.2 多输出描述​
{
    "header":{
        "code": 0,
         "message": "success",
         "sid": "iat000704fa@dx16ade44e4d87a1c802",
         "status":0     
        },
 
"payload":{
     "result_1":{
        "status":0,
        "format":"audio/L16;rate=16000",
        "encoding":"raw",
        "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
         },

     "result_2":{
        "status":0,
        "format":"audio/L16;rate=16000",
        "encoding":"raw",
        "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
         }
}
}

字段说明： 同 [2.3.1 单输出描述]("2.3.1 单输出描述") 结构说明：

  1. 此时payload为多级结构
  2. 多数据情况下，payload通过不同的结果ID作为key来分别描述不同的结果特性描述，如：result_1、result_2
  3. 结果ID为用户自定义

2.4 系统参数的约束​

2.4.1 header字段​
字段含义类型说明
app_id应用idstring必选
ath_id三方用户IDstring可选

3.1 路由信息​

新增session状态（SessState），用于描述流式与否

message GlobalRoute {
    string session_id = 1; //session id
    string trace_id = 2; //trace id
    string up_router_id = 3; //上行数据路由标识
    string guider_id = 4; //调度中心标识
    string down_router_id = 5; //下行数据路由标识
    string appid = 6; //应用标识
    string uid = 7; //用户标识
    string did = 8; //设备标识
    string client_ip = 9; //客户端ip
    
    SessState  session_state = 10; //新增：会话状态，流式、非流式,STATE为枚举

}

3.1 元数据调整​

去除原format、encoding字段，描述归入：desc_args字段，且将原来的byte类型调整为string类型

message GeneralData {
    string data_id = 1; //数据编号
    uint32 frame_id = 2; //数据序号

    //区分数据类型
    enum DataType {
    TEXT = 0; // 文本
    AUDIO = 1; // 音频
    IMAGE = 2; // 图像
    VIDEO = 3; // 视频
    }

    DataType data_type = 3; //数据类型

    //区分数据状态
   enum DataStatus {
    BEGIN = 0; //开始
    CONTINUE = 1; //跟流
    END = 2; //结束
    ONCE = 3; //一次调用结束
    }

    DataStatus status = 4; //数据状态

    map<string, string> desc_args = 5; //数据描述参数

    bytes data = 8; //数据内容
}