科大讯飞语音云使用说明

?
API 参数集
用户通过指定 API 参数来获取对应的结果，语言云服务的 API 参数集如下表所示： 参数名 含义 说明
api_key
用户注册语音云服务后获得的认证标识
请以 UTF-8 格式编码， GET 方式最大 10K， POST 方式 text 待分析的文本 最大 20K
用以指定分析模式，可选值包括 ws(分词)，pos(词性标注)，ner(命名实体识别)，dp(依存句法分析)，srl(语义角 pattern 色标注),all(全部任务) plain 格式中不允许指定全部任务
用以指定结果格式类型，可选值包括 xml(XML 格式)，json(JSON 格式)，conll(CONLL 格式)，plain(简洁文本 format 格式)
xml_inp 用以指定输入 text 是否是 xml 格式，可选值为 false(默认值),true ut 仅限 POST 方式
has_key 用以指定 json 结果中是否含有键值，可选值包括 true(含有键值，默认)，false(不含有键值)
配合 format=json 使用
only_ne 用以指定 plain 格式中是否只需要 ner 列表，可选值包括 false(默认值)和 true r 配合 pattern=ner&format=plain 使用

参数名
含义
说明
callback 用以指定 JavaScript 调用中所使用的回调函数名称
配合 format=json 使用
******************************************************************************
?
调用方式
用户可以用两种方式来调用 API，直接使用 REST | 在 JavaScript 中使用 REST
REST
REST,或者叫做 Representational State Transfer，在语言云 API 中并不等同于传统的 REST。传统的 REST 提供对于资源的访问，而语言云 REST API 提供对于服务的访问。因此，在语言云 API 中，一个单独的 URI 就是一个服 务端点。 在语言云中，所有的 API 访问都是通过 HTTP 请求的方式。并且需要从 https://www.360docs.net/doc/dc7878503.html, 域进行访问。语言云只支持 GET 和 POST 方式的 HTTP 请求。用户通过在 HTTP 请求中指定参数来获取对应的结果。 举个例子，对“我是中国人。”这句话做依存句法分析，并且返回 plain 格式的结果。 GET 请求及返回结果示例：
$ curl -i "https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=dp&format=plain" HTTP/1.1 200 OK Server: nginx/1.1.19 Date: Fri, 03 Jan 2014 04:24:32 GMT Content-Type: text/plain Transfer-Encoding: chunked Connection: keep-alive

Vary: Accept-Encoding
是_1 -1 HED 中国_2 人_3 ATT 人_3 是_1 VOB
POST 请求及返回结果示例：
$ curl -i -d "api_key=YourApiKey&text=我是中国人。&pattern=dp&format=plain" "https://www.360docs.net/doc/dc7878503.html,/analysis/" HTTP/1.1 200 OK Server: nginx/1.1.19 Date: Fri, 03 Jan 2014 05:58:55 GMT Content-Type: text/plain Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding
我_0 是_1 SBV 是_1 -1 HED 中国_2 人_3 ATT 人_3 是_1 VOB
使用 Python 语言以 GET 方式调用 REST API 代码示例如下：

1. # -*- coding:utf8 -*2.import urllib2 3.if __name__ == '__main__': 4. url_get_base = "https://www.360docs.net/doc/dc7878503.html,/analysis/?" 5. api_key = '' 6. text = '' 7. format = '' 8. pattern = '' 9. result = urllib2.urlopen( "%sapi_key=%s&text=%s&format=%s&pattern=%s" % (url_get_base,api_key,text,format,pattern)) 10. content = result.read().strip() 11. print content
更多使用其他编程语言以 GET 和 POST 方式调用 REST API 代码示例以及注意事项请参考 API 编程调用示例。
JavaScript 调用 REST
语言云支持用户使用 JavaScript 以 JSON-P 回调的方式调用 API，用户需要以 GET 方式进行调用并且只支持 json 的返回格式。 在此方式中，需要用户在 uri 中添加 callback 参数并且在 js 中指定相同名称的回调函数进行结果的捕捉，这通常用于跨域访问使得结果嵌入到 Web 页面中。
$ curl -i "https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=dp&format=json&callback=foo" HTTP/1.1 200 OK Server: nginx/1.1.19 Date: Fri, 03 Jan 2014 08:08:56 GMT Content-Type: application/javascript

Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding
foo( //json data )
在 JavaScript 中捕捉调用结果代码示例如下：
1. var foo = function(data){ 2. json_str = JSON.stringify(data); 3. document.getElementsByTagName( "body")[0].innerHTML += json_str; 4.}; 5.window.onload=function(){ 6. var base = "https://www.360docs.net/doc/dc7878503.html,/analysis/?"; 7. var api_key = ""; 8. var text = ""; 9. var pattern = ""; 10. var format = "json"; 11. var callback = "foo"; 12. var url = base + "api_key="+api_key+ "&text="+text+ "&pattern="+pattern+ "&format="+format+ "&callback="+callback; 13. var script = document.createElement( 'script');

14. script.setAttribute( 'src', url); 15. document.getElementsByTagName( 'head')[0].appendChild(script); 16.}
语言云也提供了使用 Jquery 调用 API 的示例，请参考 JavaScript 调用 API 示例。
****************************************************************
?
结果表示
?
PLAIN 分词
对文本进行分词的调用示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=ws&format=plain
?
?
?
?
返回结果为：
1. 我 是 中国 人 。
?
?
在 plain 格式的分词结果中，每句话占一行。词与词之间用空格分割，句与句之间用换行分割。段落与段落之间用两个换行分割。
?
词性标注
对文本进行词性标注的调用示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=pos&format=plain
?
?

?
返回结果为：
1. 我_r 是_v 中国_ns 人_n 。_wp
?
?
在 plain 格式的词性标注结果中，每句话占一行。词和词的标注信息之间用下划线连接，项与项之间用空格分割，句与句之间用换行分割。段落与段落之间用两个换行分割。
?
命名实体识别
对文本进行命名实体识别的调用示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=ner&format=plain
?
?
?
返回结果为：
1. 我 是 [中国]Ns 人 。
?
?
在 plain 格式的命名实体识别结果中，每句话占一行。如果本句话含有实体，将会被[]包围，并且在之后添加实体类型标识。段落与段落之间有两个换行符分割。 如果您只想获得文本中的所有的命名实体列表，请用参数 only_ner=true 来指定。 其调用示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=ner&format=plain&only_ner=true
?
?
?
?
返回结果为：
1. 中国 Ns
?
?
在 plain 格式的命名实体识别列表形式的返回结果中，每个实体信息占一行。每一行有两列，第一列为实体本身，第二列为实体类型。
?
依存句法分析

?
对文本进行依存句法分析的调用示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=dp&format=plain
?
?
返回结果为：
1. 我_0 是_1 SBV 2. 是_1 -1 HED 3. 中国_2 人_3 ATT 4. 人_3 是_1 VOB 5. 。_4 是_1 WP
?
?
在 plain 格式的依存句法分析返回结果中，文本中的每个词的句法信息占一行。每一行独占三列。第一列为依存句法分析的孩子结点信息，由结点名+下划线+词 id 组成；第二列为依存句法分析的父亲节点信息，由结点名 +下划线+词 id 组成，如果没有父亲结点，则由-1 表示;第三列为具体的依存句法分析关系。文本句子级别的信息之间用两个换行分割，文本段落级别的信息之间用三个换行分割。
?
语义角色标注
对文本进行语义角色标注的调用示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=srl&format=plain
?
?
?
返回结果为：
1. [我]A0 [是]v [中国 人]A1 。
?
?
XML
对文本进行全部任务的分析示例如下：
?

?
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我们都是中国人。&pattern=all&format=xml
?
返回结果为：
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18.
?

? ?
XML 标准结果如下：结点标签分别为 xml4nlp, note, doc, para, sent, word, arg 共七种结点标签： 1. xml4nlp 为根结点，无任何属性值；
?
2. note 为标记结点，具有的属性分别为：sent, word, pos, ne, parser, srl；分别代表分句，分词，词性标注，命名实体识别，依存句法分析，词义消歧，语义角色标注；值为"n"，表明未做，值为"y"则表示完成，如 po s="y"，表示已经完成了词性标注；
?
3. doc 为篇章结点，以段落为单位包含文本内容；无任何属性值；
?
4. para 为段落结点，需含 id 属性，其值从 0 开始；
?
5. sent 为句子结点，需含属性为 id，cont；id 为段落中句子序号，其值从 0 开始；cont 为句子内容；
?
6. word 为分词结点，需含属性为 id, cont；id 为句子中的词的序号，其值从 0 开始，cont 为分词内容；可选属性为 pos, ne, parent, relate；pos 的内容为词性标注内容；ne 为命名实体内容；parent 与 relate 成对 出现，parent 为依存句法分析的父亲结点 id 号，relate 为相对应的关系；
?
7. arg 为语义角色信息结点，任何一个谓词都会带有若干个该结点；其属性为 id, type, beg，end；id 为序号，从 0 开始；type 代表角色名称；beg 为开始的词序号，end 为结束的序号；
?
各结点及属性的逻辑关系说明如下： 1. 各结点层次关系可以从图中清楚获得，凡带有 id 属性的结点是可以包含多个；
?
?
2. 如果 sent="n"即未完成分句，则不应包含 sent 及其下结点；
?
3. 如果 sent="y" word="n"即完成分句，未完成分词，则不应包含 word 及其下结点；
?
4. 其它情况均是在 sent="y" word="y"的情况下：
?
(1) 如果 pos="y" 则分词结点中必须包含 pos 属性；

?
(2) 如果 ne="y" 则分词结点中必须包含 ne 属性；
?
(3) 如果 parser="y" 则分词结点中必须包含 parent 及 relate 属性；
?
(4) 如果 srl="y" 则凡是谓词(predicate)的分词会包含若干个 arg 结点；
?
在 XML 格式的分析中，用户可以通过指定参数 pattern=ws | pos | ner | dp | srl | all 来指名分析任务并获取对应的 XML 结果。
?
注意！ 依存句法分析结果中并不具有 ne 信息。
?
JSON
对文本进行全部任务的分析示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=all&format=json
?
?
?
返回结果为：
[ [ [ { "id": 0, "cont": "我", "pos": "r", "ne": "O", "parent": 1,
?

"relate": "SBV", "arg": [] }, { "id": 1, "cont": "是", "pos": "v", "ne": "O", "parent": -1, "relate": "HED", "arg": [ { "id": 0, "type": "A0", "beg": 0, "end": 0 }, { "id": 1, "type": "A1", "beg": 2,

"end": 3 } ] }, { "id": 2, "cont": "中国", "pos": "ns", "ne": "S-Ns", "parent": 3, "relate": "ATT", "arg": [] }, { "id": 3, "cont": "人", "pos": "n", "ne": "O", "parent": 1, "relate": "VOB", "arg": []

}, ] ] ]
?
JSON (JavaScript Object Notation) 是一种常见的，与语言无关的数据格式，提供任意数据结构的简单表示。 在 json 格式的返回结果中，采用段落级、句子级、单词级的递进层次关系，且段落与句子并没有进行键值名标识，因而须采用数组下标方式获取信息。 比如说，p 代表 json 结果，获取第一段第二句第三个单词的词性信息，获取方式类似于 p[0][1][2]["pos"]。 json 格式是语言云重点推荐给用户的语言分析结果格式，有关更多使用方法，请参考语言云提供的 JSON 格式的重要说明。 在 json 格式的单词对象{}中，需含键值名为 id, cont；id 为句子中的词的序号，其值从 0 开始，cont 为分词内容；可选键值名为 pos, ne, parent, relate；pos 的内容为词性标注内容；ne 为命名实体内容；parent 与 relate 成对出现，parent 为依存句法分析的父亲结点 id 号，relate 为相对应的关系； 如果用户做了 srl 级别的分析，json 结果中还会有键值名 arg 所标识的数组。数组中的每个对象是一项语义角色，任何一个谓词都会带有若干个该对象；其键值名为 id, type, beg，end；id 为序号，从 0 开始；type 代表角色名称；beg 为开始的词序号，end 为结束的序号；如果单词没有语义角色信息，arg 所标识的数组为空。 用户也可以通过指定参数 has_key=false 来去掉键值名，示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=all&format=json&has_key=false
?
?
?
?
?
?
?
?
返回结果为：
[ [ [ [ 0, "我", "r", "O", 1, "SBV", [ ] ], [ 1, "是", "v", "O", -1, "HED", [ [ 0, "A0", 0, 0 ], [ 1, "A1", 2, 3 ] ] ], [ 2, "中国", "ns", "S-Ns", 3, "ATT", [ ] ], [ 3, "人", "n", "O", 1, "VOB", [ ] ] ] ] ]
?
?
在 json 格式的无键值名的返回结果中，数组信息排序与有键值名的情况相同。即按照："id","cont","pos","ne","parent","relate","arg"的顺序。

?
arg 中信息的顺序为"id","type","beg","end"。
?
CONLL
对文本进行全部任务的分析示例如下：
GET https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=YourApiKey&text=我是中国人。&pattern=all&format=conll
?
?
?
返回结果为：
1. 0 我 _ _ r O 1 SBV _ _ _ (A0*) 2. 1 是 _ _ v O -1 HED _ _ _ 是 (v*) 3. 2 中国 _ _ ns S-Ns 3 ATT _ _ _ (A1* 4. 3 人 _ _ n O 1 VOB _ _ _ *)
?
?
conll 是一种表示语言分析结果的通用格式。在语言云的 conll 格式中，分析结果的每一行代表句子中每个词的信息，词标号从 0 开始。分析结果的基础列有 10 列，之后的每一列代表文本中的语义信息，每列之间用 Tab 分割。此列值为空用"_"占位。conll 每列的含义请见下表：
列号
含义
1
单词在句子中的标号，从 0 开始
2
单词本身
3
空
4
空

列号
含义
5
单词词性标注信息
6
依存句法关系中的父亲节点标号
7
依存句法关系类型
8
空
9
空
10
如果单词是语义角色标注中的谓词，则为单词本身，否则为空
11 及以后
每个谓词占一列，每一列为该谓词的语义角色标注信息
*************************************************************
? ? ?
错误响应
正常情况下，用户将得到正确的结果，此时 HTTP 状态为 200 OK 。
$ curl -i "https://www.360docs.net/doc/dc7878503.html,/analysis/?{ValidParameters}" HTTP/1.1 200 OK ...
?
但如果用户调用 API 的方式不当，服务器将会返回对应的错误，错误信息如下表所示:

HTTP 状态码
错误信息
说明
URI PARAMETER ERROR
API 参数错误。请确保参数符合 API 参数集规范并且 text 中含有的特殊字符已经进行了调整。
EMPTY SENTENCE
text 参数不允许为空。
400 Bad Request
ENCODING NOT IN UTF8
text 编码错误。请确保使用 UTF8 编码。
BAD XML FORMAT
输入的 XML 格式不正确。请参考 XML 格式进行调整。
SENTENCE TOO LONG
输入某句子超过 300 字或分词结果超过 70 词。
401 Unauthorized
UNAUTHORIZED USER
API_KEY 不合法，用户认证不被通过。
403 Forbidden
ACCOUNT OUT OF QUOTA
本月流量使用超过该帐号配额，请联系管理员进行扩充。
405 Method Not Allowed
HTTP METHOD ERROR
该 HTTP 动作不被允许，系统只允许 GET 和 POST 方式的 HTTP 请求。
414 Request-URI Too Long
TEXT TOO LARGE ERROR
文本大小超过服务器限制，GET 方式最大 10K，POST 方式最大 20K。
500 Internal Server Error
SERVER ERROR
服务器内部错误。若稍候尝试仍然有此错误，请将 URI 用例报告给管理员。
503 Service Unavailable
API RATE LIMIT EXCEEDED
API 请求频率超过了语言云的限制。请参考频率限制。
? ?
举个例子，401 Unauthorized 错误的返回示例如下：
$ curl -i "https://www.360docs.net/doc/dc7878503.html,/analysis/?api_key=InvalidApiKey" HTTP/1.1 401 UNAUTHORIZED

Content-Type: application/json ... {"error_message": "UNAUTHORIZED USER"}
************************************************
? ? ?
频率限制
为保障系统稳定，语言云 API 的使用频率默认限制为每个 IP 200 次/秒。 超过此限制，将会被返回 503 Service Unavailable 错误。
********************************************************************
?
重要更新
?
1.关于如何自定义分词
语言云允许用户自定义分词，并在此基础上进行更深层次的语言分析。用户需指定参数 xml_input=true，分词结果需要以 XML 的表示方式指定在 text 参数中。用户必须使用 POST 方式开展此项功能。
?
?
2.关于如何一次性分析大量文本以及文本中含有特殊字符的处理
语言云支持一次性分析较大规模的文本。但也做了一些限制。GET 方式每次最多携带 10K 大小文本，POST 方式每次最多携带 20K 大小文本，且只支持 UTF-8 格式。超出限制，系统将会向您返回错误信息并提示您进行 缩减。
?
?
同样，请尽量不要在 GET 方式的参数 text 中携带其他特殊字符。如果必须携带且该字符可进行 url encode，请使用%加字符的 ASCII 码替代或者直接进行 url encode。譬如：'&'字符使用'%26'替代。否则，请删除该特 殊字符以获得正确结果。
?
3.关于使用 JSON 格式进行二次开发的重要说明

?
Json 格式是语言云着重推荐使用的返回格式。如果以上结果表示依然不能满足您的需要，您需要从中提取出对自己有用的分析信息，json 无疑是您的首选。在各编程语言中，几乎都有提供 json 格式的解析库。
?
在语言云返回的 json 格式中，是以段落级、句子级、单词级的递进层次关系标识的，段落级别和句子级别并没有进行键值名标识，因而须采用数组下标方式获取信息。 比如说，p 代表 json 结果，在 python 中，获取第 一段第二句第三个单词的词性信息，获取方式类似于 p[0][1][2]["pos"]。如果您的文本中没有明显的划分段落的标志，默认只有一个段落，句子依靠标点符号进行划分。