密级公开
版本10D.2

AICP 10 通用规范

1. 概述#

本文档描述 AICP-10 HTTP/WebSocket 接口的一些通用规范。

2. 语言编码#

在 AICP-10 平台的接口使用过程中，经常需要指明所涉及的语言种类。为了规范语种信息的表示，我们使用国际标准 ISO 639 及其衍生标准对语言进行编码。

但要注意的是：在标准中，中文的语言代码为 zh。CN 仅表示区域代码。为保证和之前全智能能力服务平台的一致性，在 AICP 中，我们还是沿用 cn表示中文的语言代码。但其它语言代码会符合 ISO 639-1 (2字母) 或者 ISO 639-2 / ISO 639-3 (3字母) 的标准。

在 AICP-10 中，常见语种的编码如下：

语言编码语言编码
中文、汉语cn英语en
维吾尔语ug法语fr
藏语bo德语de
彝语ii俄语ru
哈萨克语kk西班牙语es
蒙语mn葡萄牙语pt
壮语za意大利语it
粤语yue阿拉伯语ar
闽南语nan波斯语fa
吴语wuu日语ja
客家话hak朝鲜语、韩语ko

对于一些方言，或者在标准中没有定义，或者其定义不一定适合，因此在 AICP-10 中，会自定义一些语种编码，自定义的语种编码都会带 x- 前缀。例如：

语言编码
四川话x-sichuan

3. 模型特征串#

在 AICP-10 平台提供的能力接口 URL 中，通常都会包含模型特征串（简写为 property），用于标识在处理过程中不同的模型。网关服务会根据 URL 中的模型特征串，将请求转发到相应的支持此种模型的后端服务，后端服务也会使用正确的模型进行处理。

例如，在 ASR 接口中，模型特征串形式为：{lang}_{samplerate}_{domain}。{lang}表示语言编码， {samplarate} 可以是 8K 或者16K，表示识别模型的训练时所用的采样率，{domain}表示领域编码。则 cn_16k_common 就表示中文16K的通用领域模型。

每一种 AI 能力都有不同的模型特征串的形式，具体请参考不同能力的开发手册。

4. 开发者账号#

针对每个开发者，有一个开发者账号。每个开发者账号下，可以有多个应用，不同的应用以 appkey 区分。每个 appkey 都有一个对应的秘钥 secret，用于获取认证用的访问令牌。

目前在私有云环境下，只有一个开发者账号和一个 appkey，缺省的 appkey 和 secret 已经预置：

appkeysecret
aicp_appQWxhZGRpbjpvcGVuIHNlc2FtZQ

部署时可以更改 appkey 和 secret 配置，但需要注意在访问时也需要使用新的配置。

5. 能力URL#

AICP-10 平台提供的能力接口 URL 通常为下述方式：

http(s)://ip:port/v10/asr/freetalk/{property}/short_audio?appkey={appkey}

  • asr 一节表示使用的 AI 能力
  • freetalk 一节表示子能力，例如语音识别包括 freetalk（自由说），grammar（语法识别），trans（离线转写）等。
  • property 一节即前面描述的“模型特征串”
  • short_audio 是指具体功能，通常服务于一个特定的目的或场景。

WebSocket 接口基本类似，但多一个可选的 access-token 参数。

ws(s)://ip:port/v10/asr/freetalk/{property}/short_stream?appkey={appkey}[&access-token={token}]

6. 访问认证#

访问 AICP-10 平台提供的能力接口，都需要要客户端事先已通过云端的认证接口（get-access-token），给出分配好的 appkey 和 secret 参数，获取对应的访问令牌（access token)。

然后在访问能力URL时，客户端需要在 URL 中给出 appkey 参数，并设置 X-Hci-Access-Token HTTP 头，将获取的令牌传入。

在 HTML5 中，由于 Javascript 在创建 WebSocket 对象时，无法设置 HTTP 头域，此时可以通过 URL 中的 access-token 参数来传入。

访问令牌有过期时间，需要定期刷新。关于如何获取令牌和刷新令牌，请参阅 《系统服务 HTTP开发手册》。

7. 接口响应#

7.1 HTTP 接口响应#

AICP-10 平台中，HTTP 接口的响应通常遵循标准的 HTTP 状态码（HTTP Response Code）规范。

当接口调用成功时，HTTP 状态码为200 OK （也有可能是其它 2xx，比如 201 Created, 202 Accepted等）。此时包体里一般没有 error 字段。

当接口调用失败时，一般返回 4xx 或者 5xx 的状态码，同时响应消息体中一般是 JSON 格式的内容，并包含 error 字段，其下又包括具体的错误码 code 和错误信息 message。

在错误时，HTTP 状态码和 error 字段中的 code（错误码）也有一定的对应关系，具体参见下表。

HTTP 状态码错误码说明解决方案
400
Bad Request		3
INVALID_ARGUMENT		请求参数异常检查请求参数字段，修改正确后重试
400
Bad Request		11
OUT_OF_RANGE		请求参数超出范围检查请求参数字段，修改正确后重试
401
Unauthorized		16
UNAUTHENTICATED		认证失败，没有给出令牌或令牌无效、过期检查认证参数，修改正确后重试
403
Forbidden		7
PERMISSION_DENIED		无访问权限，就算通过身份验证也禁止访问。例如访问有白名单机制检查请求的资源是否有访问权限，或联系厂商
404
Not Found		5
NOT_FOUND		未找到访问资源, 例如URL错误检查发送的URL等是否正确，修改正确后重试
409
Conflict		9
FAILED_PRECONDITION		某些预置条件不满足, 例如被删除的某个资源还在被使用。用户先解决冲突问题，然后进行重试
429
Too Many Requests		8
RESOURCE_EXHAUSTED		某种资源耗尽，或者由于限流原因拒绝服务检查是否超过了并发连接数或者限流上限
501
Not Implemented		12
UNIMPLEMENTED		合理的请求，但当前尚未支持当前并不支持，不应该重试
500
Internal Server Error		13
INTERNAL		内部服务异常，主要是一些内部逻辑错误等过一段时间重试, 如果偶现可以忽略，否则请联系厂商
503
Service Unavailable		14
UNAVAILABLE		无法找到支持的服务, 用户可以过一段时间重试过一段时间重试, 如果偶现可以忽略，否则请联系厂商

下面一些错误当前的HTTP接口访问时可能不会发生，暂时列在这里：

HTTP状态码错误码说明
409
Conflict		6
ALREADY_EXISTS		客户端试图创建的资源已存在
499
Client Closed Request		1
CANCELLED		操作被用户取消
409
Conflict		10
ABORTED		操作中止，通常由于事务中断等
500
Internal Server Error		2
UNKNOWN		未知内部错误
500
Internal Server Error		15
DATA_LOSS		不可恢复的数据丢失或损坏
504
Gateway Timeout		4
DEADLINE_EXCEEDED		访问超时

7.2 WebSocket 接口响应#

WebSocket 接口的调用分为握手阶段和连接阶段两个部分。

7.2.1 握手阶段#

在握手阶段，实际上还是以 HTTP 形式发送握手信息，因此其响应也遵循标准的 HTTP 状态码规范。

当握手接口调用成功时，HTTP 状态码为 101 Switching Protocols，包体中无内容。

当握手失败时，HTTP 状态码为其它值，其消息体中一般都会包含错误码 errCode 和错误信息 errMessage，表示具体的错误。

HTTP状态码和错误码可能如下：

HTTP 状态码错误码说明解决方案
401
Unauthorized		16
UNAUTHENTICATED		认证失败，不是合法用户检查认证参数，修改正确后重试
403
Forbidden		7
PERMISSION_DENIED		无访问权限，就算通过身份验证也禁止访问。例如访问有白名单机制检查请求的资源是否有访问权限，或联系厂商
404
Not Found		5
NOT_FOUND		未找到访问资源, 例如URL错误检查发送的URL等是否正确，修改正确后重试

7.2.2 连接阶段#

在连接建立之后发生错误时，是通过响应的内容来返回的。除了正常的响应外，一般都会定义 错误响应 或者 严重错误响应。

  • 错误响应，一般是业务上的错误，通常会关闭当前会话，但不关闭连接。
  • 严重错误响应，是指流程无法继续的情况，一般此时服务器端会主动断连。

在错误响应或严重错误响应时，其消息体中一般都会包含错误码 errCode 和错误信息 errMessage，表示具体的错误。

此时可能的错误码如下：

错误码说明解决方案
3
INVALID_ARGUMENT		请求参数异常检查请求参数字段，修改正确后重试
11
OUT_OF_RANGE		请求参数超出范围检查请求参数字段，修改正确后重试
8
RESOURCE_EXHAUSTED		某种资源耗尽，或者由于限流原因拒绝服务检查是否超过了并发连接数或者限流上限
14
UNAVAILABLE		无法找到支持的服务, 用户可以过一段时间重试过一段时间重试, 如果偶现可以忽略，否则请联系厂商
10
ABORTED		出现严重错误，操作由服务器端中止重新连接并访问