密级	公开
版本	10D.2

AICP MT HTTP开发手册

1. 概述#

1.1 功能描述#

MT（机器翻译）能力服务主要用于将一种语言的文本翻译为另一种语言的文本，也可用于对一段文本进行分句。

MT 能力服务目前提供 HTTP 形式的接口，是“请求-响应”式的同步接口。对于每个HTTP请求，云端完成相应操作后一次性返回结果，多个HTTP请求之间逻辑上没有相关性。

1.2 模型特征串#

AICP-10 平台提供的 MT 能力接口中，模型特征串形式为：{from}2{to}_{domain}。 {from}表示源语言编码，{to}表示目标语言编码，{domain}表示领域编码。

模型特征串的概念和语言编码，请参见《AICP 10 开发通用规范》

领域是针对翻译任务的一种性能优化手段。不同的领域中，常用的句式结构、常用的词汇等都有所差别。在进行特定领域的翻译时，如果模型进行了针对性优化，就有可能得到更准确的结果。MT支持领域的概念。目前仅支持 common 领域。

目前支持的模型特征串如下：

模型特征串(property)	说明	模型特征串(property)	说明
cn2en_common	中译英	en2cn_common	英译中
cn2fr_common	中译法	fr2cn_common	法译中
cn2ru_common	中译俄	ru2cn_common	俄译中
cn2ja_common	中译日	ja2cn_common	日译中
cn2ko_common	中译韩	ko2cn_common	韩译中
cn2de_common	中译德	de2cn_common	德译中
cn2es_common	中译西	es2cn_common	西译中
cn2ar_common	中译阿	ar2cn_common	阿译中
cn2ug_common	汉译维	ug2cn_common	维译汉
cn2bo_common	汉译藏	bo2cn_common	藏译汉

1.3 访问认证#

访问接口所需的认证机制，请参见《AICP 10 开发通用规范》

2. 接口概览#

MT 接口提供如下两个接口：

翻译接口
http://ip:port/v10/mt/translate/{property}/translate?appkey={appkey}
分句接口
http://ip:port/v10/mt/translate/{property}/segment?appkey={appkey}

2.1 URL 参数#

URL 中携带的参数如下：

参数	类型	必选	说明
property	string	是	模型特征串，服务器端利用此值来调用不同的模型。
appkey	string	是	分配给开发者的 appkey

以下是一个具体示例（用于将一段中文文本翻译为英文，采用通用领域模型）：

http://ip:port/v10/mt/translate/cn2en_common/translate?appkey=xxx

2.2 HTTP 头域参数#

请求的 HTTP Header 参数如下：

参数	类型	必选	说明
Content-Type	string	是	application/json
X-Hci-Access-Token	string	是	从 get-access-token 接口获取的令牌

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

2.3 包体参数#

待处理的文本连同其它参数必须放在请求正文中，并以JSON格式编码。

2.4 响应格式#

在响应消息中，HTTP 状态码表示请求的总体执行情况，正文包含一个以JSON格式编码的字符串，用于携带进一步的信息。

正常响应：HTTP 状态码为 200，响应包体中不包含“error”字段，但通常会包含“result” 字段用于携带正常的结果数据。
失败响应：HTTP 状态码为 200 之外的值，响应包体中包含“error”字段，包含详细错误码和错误信息。

响应的格式统一为：

参数	类型	说明
traceToken	string	服务内部的 token 字符串，可用于日志追溯。在某些错误情况下可能没有此令牌字符串。
error	object	发生错误时可用，如果请求成功将没有此字段
result	object	调用成功表示识别结果，调用失败时将没有此字段

error 的结构如下：

参数	类型	说明
code	number	错误代码，请参见《AICP 10 开发通用规范》
message	string	详细的错误信息

result 的结构针对不同调用接口是不一样的，会在下面的每个接口描述中详细说明。

以下是一个失败响应的示例：

{
  "error": {
    "code": 1,
    "message": "The specified language is not supported."
  }
}

在后文中，我们将略过对错误响应的描述，而仅给出正常响应的 result 的格式和示例。

3. 标准翻译接口#

翻译一句话，翻译方向由 URL 中的 property 确定。

3.1 接口 URL#

POST http(s)://ip:port/v10/mt/translate/{property}/translate?appkey={appkey}

3.2 请求参数#

参数名	类型	必选	缺省	说明
config	object	否	null	识别配置信息
extraInfo	string	否	空串	客户端设置的信息串，服务器端只做记录，可将来作为定制版本的一些特殊信息
text	string	是	-	待翻译的文本。必须以UTF-8格式编码。

云端对待翻译文本的最大长度（字符数）有限制，限制由服务器端配置决定，通常 CPU 版本为 2K，GPU 版本为10K。如果超出此限制，云端直接返回错误响应，不会返回任何部分结果。

config 的结构如下：

参数名	类型	必选	缺省	说明
correct-input	bool	否	false	是否对待翻译文本进行自动纠错。
segment	bool	否	false	是否输出分句的翻译结果。当 `segment` 为 `true` 时，会按照子句进行输出，否则按照一整段进行输出。
segment	bool	否	false	是否输出分句的翻译结果。当 `segment` 为 `true` 时，会按照子句进行输出，否则按照一整段进行输出。

以下是一个翻译请求正文示例：

{
  "config": {
    "correct-input": true
  },
  "extraInfo": "abcdef",
  "text": "今天天气闷热，不适宜长时间进行户外活动。明天白天阴有小雨。",
}

3.3 响应参数#

正常响应中 result 结构如下：

参数	类型	说明
segments	array	如果 `segment` 为 `true`，有此字段，表示分句的翻译结果
translated	string	如果 `segment` 为 `false`，有此字段，表示完整的翻译结果。结果文本以UTF-8格式编码。
score	number	如果 `segment` 为 `false`，有此字段，表示结果文本的置信度。取值范围为[0.0,1.0]。置信度越高，结果越可信。
from	string	源语言编码。
to	string	目标语言编码。

segments 的每一项的结构如下：

参数	类型	说明
start	number	子句在原句中的起始位置（字节）
len	number	子句的长度（字节）
translated	string	此分句的翻译结果，结果文本以UTF-8格式编码
score	number	结果文本的置信度。取值范围为[0.0,1.0]。置信度越高，结果越可信。

注意：在标准翻译接口中，from 和 to 的值和请求URL中 property 里的对应值相同。

以下是一个正常响应的示例：

segment 是 false 时：

{
  "traceToken": "xxxxxx",
  "result":
  {
    "translated": "It’s very hot, not suitable for long-time outdoor \
      activities. Tomorrow it will be cloudy and light rain in the daytime. ",
    "score": 0.94,
    "from": "cn",
    "to": "en"
  }
}

segment 是 true 时：

{
  "traceToken": "xxxxxx",
  "result":
  {
    "segments": [
      {
        "start": 0,
        "len": 60,
        "translated": "It’s very hot, not suitable for long-time outdoor \
          activities. ",
        "score": 0.92,
      },
      {
        "start": 60,
        "len": 27,
        "translated": "Tomorrow it will be cloudy and light rain in \
          the daytime. ",
        "score": 0.95,
      }
    ],
    "from": "cn",
    "to": "en"
  }
}

4. 标准分句接口#

标准分句接口对一大段文本进行拆分，拆分为多段内容。要用于文本内容的长度超过标准翻译接口的文本长度限制时，可以先进行分句，然后顺序或者并发地对每一句内容调用翻译接口进行翻译。

4.1 接口 URL#

POST http(s)://ip:port/v10/mt/translate/{property}/segment?appkey={appkey}

4.2 请求参数#

参数	类型	必选	缺省	说明
config	object	否	null	识别配置信息
extraInfo	string	否	空串	客户端设置的信息串，服务器端只做记录，可以作为每次的会话id用于查询
text	string	是	-	待分句的文本。必须以UTF-8格式编码。

云端对待分句文本的最大长度只受请求包体最大长度限制。此限制由服务器端配置决定，缺省8M。如果超出此限制，云端直接返回错误响应，不会返回任何部分结果。

config 的结构如下：

参数	类型	必选	缺省	说明
detail	bool	否	false	返回格式，如果设置为false，只会返回子句在原句中的位置和长度信息，不返回子句的内容。如果设置为true, 则会返回子句的具体内容
detail	bool	否	false

以下是一个分句的请求示例（以下示例比较简单，通常应该是很大的文本）：

{
  "text": "这是第一句话。这是第二句话。",
  "config":
  {
   "detail": true
  }
}

4.3 响应参数#

正常响应中 result 结构如下表所示：

参数名	类型	说明
segments	array	分句得到的各个子句
lang	string	句子的语言编码

segments 中的每一项为如下对象：

参数名	类型	说明
start	number	子句在原句中的起始位置（字节）
len	number	子句的长度（字节）
text	string	句子的内容，以UTF-8格式编码。如果 `detail`为 `false`，将没有此项

在标准分句接口中，lang 的值和请求URL中 property 里的 from 相同。

以下是一个正常响应的示例（以下示例比较简单，通常结果中的每个分句也比较大）：

如果 detail 为 true

{
  "traceToken": "xxxxxx",
  "result":
  {
    "segments": [
      {
        "start": 0,
        "len": 21,
        "text": "这是第一句话。",
      },
      {
        "start": 21,
        "len": 21,
        "text": "这是第二句话。"
      }
    ],
    "lang": "cn"
  }
}

如果 detail 为 false

{
  "traceToken": "xxxxxx",
  "result":
  {
    "segments": [
      {
        "start": 0,
        "len": 21,
      },
      {
        "start": 21,
        "len": 21,
      }
    ],
    "lang": "cn"
  }
}

5. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.1.0	10C.0	aicp_mt 10.2.0	增加支持的语种对
10.0.0	10B.0	aicp_mt.10.0.0	初始版本