科大訊飛語音云使用說明

1、· API參數(shù)集用戶通過指定API參數(shù)來獲取對應(yīng)的結(jié)果，語言云服務(wù)的API參數(shù)集如下表所示：參數(shù)名含義說明api_key用戶注冊語音云服務(wù)后獲得的認(rèn)證標(biāo)識text待分析的文本請以UTF-8格式編碼，GET方式最大10K，POST方式最大20Kpattern用以指定分析模式，可選值包括ws(分詞)，pos(詞性標(biāo)注)，ner(命名實體識別)，dp(依存句法分析)，srl(語義角色標(biāo)注),all(全部任務(wù))plain格式中不允許指定全部任務(wù)format用以指定結(jié)果格式類型，可選值包括xml(XML格式)，json(JSON格式)，conll(CONLL格式)，plain(簡潔文本格式)x

2、ml_input用以指定輸入text是否是xml格式，可選值為false(默認(rèn)值),true僅限POST方式has_key用以指定json結(jié)果中是否含有鍵值，可選值包括true(含有鍵值，默認(rèn))，false(不含有鍵值)配合format=json使用only_ner用以指定plain格式中是否只需要ner列表，可選值包括false(默認(rèn)值)和true配合pattern=ner&format=plain使用callback用以指定JavaScript調(diào)用中所使用的回調(diào)函數(shù)名稱配合format=json使用*· 調(diào)用方式用戶可以用兩種方式來調(diào)用API，直接使用REST 

3、| 在JavaScript中使用RESTRESTREST,或者叫做Representational State Transfer，在語言云API中并不等同于傳統(tǒng)的REST。傳統(tǒng)的REST提供對于資源的訪問，而語言云REST API提供對于服務(wù)的訪問。因此，在語言云API中，一個單獨的URI就是一個服務(wù)端點。在語言云中，所有的API訪問都是通過HTTP請求的方式。并且需要從域進(jìn)行訪問。語言云只支持GET和POST方式的HTTP請求。用戶通過在HTTP請求中指定參數(shù)來獲取對應(yīng)的結(jié)果。舉個例子，對“我是中國人?！边@句話做依存句法分析，并且返回plain格式的結(jié)果。GET請求及返回結(jié)果示例：

4、$ curl -i "HTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 04:24:32 GMTContent-Type: text/plainTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encoding是_1 -1 HED中國_2 人_3 ATT人_3 是_1 VOBPOST請求及返回結(jié)果示例：$ curl -i -d "api_key=YourApiKey&te

5、xt=我是中國人。&pattern=dp&format=plain" "HTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 05:58:55 GMTContent-Type: text/plainTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encoding我_0 是_1 SBV是_1 -1 HED中國_2 人_3 ATT人_3 是_1 VOB使用Python語言以GET

6、方式調(diào)用REST API代碼示例如下：1. # -*- coding:utf8 -*- 2.import urllib2 3.if _name_ = '_main_': 4. url_get_base = "5. api_key = '' 6. text = '' 7. format = '' 8. pattern = ''&#

7、160;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方式調(diào)用REST API代碼示例以及注意事項請參考API編程調(diào)用示例。JavaScript調(diào)用RE

8、ST語言云支持用戶使用JavaScript以JSON-P回調(diào)的方式調(diào)用API，用戶需要以GET方式進(jìn)行調(diào)用并且只支持json的返回格式。在此方式中，需要用戶在uri中添加callback參數(shù)并且在js中指定相同名稱的回調(diào)函數(shù)進(jìn)行結(jié)果的捕捉，這通常用于跨域訪問使得結(jié)果嵌入到Web頁面中。$ curl -i "HTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 08:08:56 GMTContent-Type: application/javascriptTransfer-Encoding: chunkedConn

9、ection: keep-aliveVary: Accept-Encodingfoo(/json data)在JavaScript中捕捉調(diào)用結(jié)果代碼示例如下：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.

10、60;var base = "7. var api_key = "" 8. var text = "" 9. var pattern = "" 10. var format = "json" 11. var callback = "foo" 12. var url = base + "api_key

11、="+api_key+ "&text="+text+ "&pattern="+pattern+ "&format="+format+ "&callback="+callback; 13. var script = document.createElement( 'script'); 14. script.setAttribute( 'src',

12、 url); 15. document.getElementsByTagName( 'head')0.appendChild(script); 16.語言云也提供了使用Jquery調(diào)用API的示例，請參考JavaScript調(diào)用API示例。*· 結(jié)果表示· PLAIN· 分詞· 對文本進(jìn)行分詞的調(diào)用示例如下：· GET · 返回結(jié)果為：· 1. 我  是  中國  人  。

13、3; 在plain格式的分詞結(jié)果中，每句話占一行。詞與詞之間用空格分割，句與句之間用換行分割。段落與段落之間用兩個換行分割。· 詞性標(biāo)注· 對文本進(jìn)行詞性標(biāo)注的調(diào)用示例如下：· GET · 返回結(jié)果為：· 1. 我_r  是_v  中國_ns  人_n  。_wp· 在plain格式的詞性標(biāo)注結(jié)果中，每句話占一行。詞和詞的標(biāo)注信息之間用下劃線連接，項與項之間用空格分割，句與句之間用換行分割。段落與段落之間用兩個換行分割。· 命名實體識別

14、· 對文本進(jìn)行命名實體識別的調(diào)用示例如下：· GET · 返回結(jié)果為：· 1. 我  是  中國Ns  人  。· 在plain格式的命名實體識別結(jié)果中，每句話占一行。如果本句話含有實體，將會被包圍，并且在之后添加實體類型標(biāo)識。段落與段落之間有兩個換行符分割。· 如果您只想獲得文本中的所有的命名實體列表，請用參數(shù)only_ner=true來指定。· 其調(diào)用示例如下：· GET · 返回結(jié)果為：· 1.

15、60;中國  Ns· 在plain格式的命名實體識別列表形式的返回結(jié)果中，每個實體信息占一行。每一行有兩列，第一列為實體本身，第二列為實體類型。· 依存句法分析· 對文本進(jìn)行依存句法分析的調(diào)用示例如下：· GET · 返回結(jié)果為：· 1. 我_0   是_1  SBV 2. 是_1   -1  HED 3. 中國_2   人_3 

16、; ATT 4. 人_3   是_1  VOB 5. 。_4   是_1  WP· 在plain格式的依存句法分析返回結(jié)果中，文本中的每個詞的句法信息占一行。每一行獨占三列。第一列為依存句法分析的孩子結(jié)點信息，由結(jié)點名+下劃線+詞id組成；第二列為依存句法分析的父親節(jié)點信息，由結(jié)點名+下劃線+詞id組成，如果沒有父親結(jié)點，則由-1表示;第三列為具體的依存句法分析關(guān)系。文本句子級別的信息之間用兩個換行分割，文本段落級別的信息之間用三個換行

17、分割。· 語義角色標(biāo)注· 對文本進(jìn)行語義角色標(biāo)注的調(diào)用示例如下：· GET · 返回結(jié)果為：· 1. 我A0   是v   中國  人A1   。· XML· 對文本進(jìn)行全部任務(wù)的分析示例如下：· GET · 返回結(jié)果為：· 1. <? xml version= "1.0" encoding= &quo

18、t;utf-8" ?> 2. <xml4nlp> 3. <note sent="y" word="y" pos="y" ne="y" parser="y" wsd="y" srl="y" /> 4. <doc> 5. <para&#

19、160;id="0" > 6. <sent id="0" cont="我們都是中國人" > 7. <word id="0" cont="我們" pos="r" ne="O" parent="2" relate="SBV" /> 8

20、. <word id="1" cont="都" pos="d" ne="O" parent="2" relate="ADV" /> 9. <word id="2" cont="是" pos="v" ne="O" parent=&qu

21、ot;-1" relate="HED" > 10. <arg id="0" type="A0" beg="0" end="0" /> 11. <arg id="1" type="AM-ADV" beg="1" end="1" 

22、/> 12. </word> 13. <word id="3" cont="中國" pos="ns" ne="S-Ns" parent="4" relate="ATT" > 14. <word id="4" cont="人" pos="

23、;n" ne="O" parent="2" relate="VOB" > 15. </sent> 16. </para> 17. </doc> 18. </xml4nlp>· XML標(biāo)準(zhǔn)結(jié)果如下：結(jié)點標(biāo)簽分別為 xml4nlp, note, doc, para, sent, word,

24、 arg 共七種結(jié)點標(biāo)簽：· 1. xml4nlp 為根結(jié)點，無任何屬性值；· 2. note 為標(biāo)記結(jié)點，具有的屬性分別為：sent, word, pos, ne, parser, srl；分別代表分句，分詞，詞性標(biāo)注，命名實體識別，依存句法分析，詞義消歧，語義角色標(biāo)注；值為"n"，表明未做，值為"y"則表示完成，如pos="y"，表示已經(jīng)完成了詞性標(biāo)注；· 3. doc 為

25、篇章結(jié)點，以段落為單位包含文本內(nèi)容；無任何屬性值；· 4. para 為段落結(jié)點，需含id 屬性，其值從0 開始；· 5. sent 為句子結(jié)點，需含屬性為id，cont；id 為段落中句子序號，其值從0 開始；cont 為句子內(nèi)容；· 6. word 為分詞結(jié)點，需含屬性為id, cont；id 為句子中的詞的序號，其值從0 開始，cont為分詞內(nèi)容；可選屬性為 pos, ne, parent, relate；pos的內(nèi)容為詞性標(biāo)注內(nèi)容；ne 為命名實體

26、內(nèi)容；parent 與 relate 成對出現(xiàn)，parent 為依存句法分析的父親結(jié)點id 號，relate 為相對應(yīng)的關(guān)系；· 7. arg 為語義角色信息結(jié)點，任何一個謂詞都會帶有若干個該結(jié)點；其屬性為id, type, beg，end；id 為序號，從0 開始；type 代表角色名稱；beg 為開始的詞序號，end 為結(jié)束的序號；· 各結(jié)點及屬性的邏輯關(guān)系說明如下：· 1. 各結(jié)點層次關(guān)系可以從圖中清楚獲得，凡帶有id 屬性的結(jié)點

27、是可以包含多個；· 2. 如果sent="n"即未完成分句，則不應(yīng)包含sent 及其下結(jié)點；· 3. 如果sent="y" word="n"即完成分句，未完成分詞，則不應(yīng)包含word 及其下結(jié)點；· 4. 其它情況均是在sent="y" word="y"的情況下：· (1) 如果 pos="y" 則分詞結(jié)點中必須包含pos 屬性；· (2) 如果 ne="y" 則分詞

28、結(jié)點中必須包含ne 屬性；· (3) 如果 parser="y" 則分詞結(jié)點中必須包含parent 及relate 屬性；· (4) 如果 srl="y" 則凡是謂詞(predicate)的分詞會包含若干個arg 結(jié)點；· 在XML格式的分析中，用戶可以通過指定參數(shù)pattern=ws | pos | ner | dp | srl | all 來指名分析任務(wù)并獲取對應(yīng)的XML結(jié)果。· 注意！ 依存句法分析結(jié)果中并不具有ne信息。· JSON· 對文本進(jìn)行全

29、部任務(wù)的分析示例如下：· GET · 返回結(jié)果為：· "id": 0,"cont": "我", "pos": "r", "ne": "O", "parent": 1, "relate": "SBV", "arg": ,"id": 1,&qu

30、ot;cont": "是", "pos": "v", "ne": "O", "parent": -1, "relate": "HED", "arg": "id": 0, "type": "A0", "beg":

31、 0, "end": 0, "id": 1, "type": "A1", "beg": 2, "end": 3,"id": 2,"cont": "中國", "pos": "ns", "ne": "S-Ns", "

32、;parent": 3, "relate": "ATT", "arg": ,"id": 3,"cont": "人", "pos": "n", "ne": "O", "parent": 1, "relate": "VOB"

33、, "arg": ,· JSON (JavaScript Object Notation) 是一種常見的，與語言無關(guān)的數(shù)據(jù)格式，提供任意數(shù)據(jù)結(jié)構(gòu)的簡單表示。· 在json格式的返回結(jié)果中，采用段落級、句子級、單詞級的遞進(jìn)層次關(guān)系，且段落與句子并沒有進(jìn)行鍵值名標(biāo)識，因而須采用數(shù)組下標(biāo)方式獲取信息。· 比如說，p代表json結(jié)果，獲取第一段第二句第三個單詞的詞性信息，獲取方式類似于p012"pos"。· json格式是語言云重點推薦給用戶的語言分析結(jié)果格式，有關(guān)更多使用方法，請參考語言云提供的JSON格式的重

34、要說明。· 在json格式的單詞對象中，需含鍵值名為id, cont；id 為句子中的詞的序號，其值從0 開始，cont為分詞內(nèi)容；可選鍵值名為 pos, ne, parent, relate；pos 的內(nèi)容為詞性標(biāo)注內(nèi)容；ne 為命名實體內(nèi)容；parent 與 relate 成對出現(xiàn)，parent 為依存句法分析的父親結(jié)點id 號，relate 為相對應(yīng)的關(guān)系；· 如果用戶做了srl級別的分析，json結(jié)果中還會有鍵值名arg所標(biāo)識的數(shù)組。數(shù)組中的每個對象是一項語義角色，任何一個謂詞都會帶有若干個該對象；其鍵值名為id, type, beg，end；id 為序號，從0 開

35、始；type 代表角色名稱；beg 為開始的詞序號，end 為結(jié)束的序號；如果單詞沒有語義角色信息，arg所標(biāo)識的數(shù)組為空。· 用戶也可以通過指定參數(shù)has_key=false來去掉鍵值名，示例如下：· GET · 返回結(jié)果為：· 0, "我", "r", "O", 1, "SBV", , 1, "是", "v", "O", -1, &q

36、uot;HED", 0, "A0", 0, 0 , 1, "A1", 2, 3 , 2, "中國", "ns", "S-Ns", 3, "ATT", , 3, "人", "n", "O", 1, "VOB", · 在json格式的無鍵值名的返回結(jié)果中，數(shù)組信息排序與有鍵值名的情況

37、相同。即按照："id","cont","pos","ne","parent","relate","arg"的順序。· arg中信息的順序為"id","type","beg","end"。· CONLL· 對文本進(jìn)行全部任務(wù)的分析示例如下：· GET · 返回結(jié)果為：· 1. 0  

38、0;我  _  _  r  O  1  SBV  _  _  _   (A0*) 2. 1   是  _  _  v  O  -1  HED  _  _  _&

39、#160; 是  (v*) 3. 2   中國  _  _  ns  S-Ns  3  ATT  _  _  _   (A1* 4. 3   人  _  _  n  O 

40、 1  VOB  _  _  _   *)· conll是一種表示語言分析結(jié)果的通用格式。在語言云的conll格式中，分析結(jié)果的每一行代表句子中每個詞的信息，詞標(biāo)號從0開始。分析結(jié)果的基礎(chǔ)列有10列，之后的每一列代表文本中的語義信息，每列之間用Tab分割。此列值為空用"_"占位。conll每列的含義請見下表：列號含義1單詞在句子中的標(biāo)號，從0開始2單詞本身3空4空5單詞詞性標(biāo)注信息6依存句法關(guān)系中的父親節(jié)點標(biāo)號7依存句法關(guān)系類型8空9空10如果單

41、詞是語義角色標(biāo)注中的謂詞，則為單詞本身，否則為空11及以后每個謂詞占一列，每一列為該謂詞的語義角色標(biāo)注信息*· 錯誤響應(yīng)· 正常情況下，用戶將得到正確的結(jié)果，此時HTTP狀態(tài)為200 OK 。· $ curl -i "HTTP/1.1 200 OK.· 但如果用戶調(diào)用API的方式不當(dāng)，服務(wù)器將會返回對應(yīng)的錯誤，錯誤信息如下表所示:HTTP狀態(tài)碼錯誤信息說明400 Bad RequestURI PARAMETER ERRORAPI參數(shù)錯誤。請確保參數(shù)符合API參數(shù)集規(guī)范并且text中含有的特殊字符已經(jīng)進(jìn)行了調(diào)整。EMPTY SENTENCEtext參數(shù)不允許為空。ENCODING NOT IN UTF8text編碼錯誤。請確保使用UTF8編碼。BAD XML FORMAT輸入的XML格式不正確。請參考XML格式進(jìn)行調(diào)整。SENTENCE TOO LONG輸入某句子超過300字或分詞結(jié)果超過70詞。401 UnauthorizedUNAUTHORIZED USERAPI_KEY不合法，用戶認(rèn)證不被通過。403 ForbiddenACCOU