科大訊飛語音云使用說明

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(簡潔文本格式)xml_inp

2、ut用以指定輸入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|在JavaScript中使用RESTRES

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

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

5、03 Jan 2014 05:58:55 GMTContent-Type: text/plainTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encoding我_0是_1 SBV是_1-1HED中國_2人_3 ATT人_3是_1 VOB使用Python語言以GET方式調(diào)用REST API代碼示例如下：1.# -*- coding:utf8 -*-2.import urllib23.if _name_ =_main_:4.url_get_base =5.api_key =6.text =7.format =8.patte

6、rn =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)用REST語言云支持用戶使用JavaScript以JSON-P回調(diào)的方式調(diào)用API，用戶需要以GET方式進行調(diào)用并且只支持json的返回格

7、式。在此方式中，需要用戶在uri中添加callback參數(shù)并且在js中指定相同名稱的回調(diào)函數(shù)進行結(jié)果的捕捉，這通常用于跨域訪問使得結(jié)果嵌入到Web頁面中。$ curl -iHTTP/1.1 200 OKServer: nginx/1.1.19Date: Fri, 03 Jan 2014 08:08:56 GMTContent-Type: application/javascriptTransfer-Encoding: chunkedConnection: keep-aliveVary: Accept-Encodingfoo(/json data)在JavaScript中捕捉調(diào)用結(jié)果代碼示例如下

8、：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 =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+&pa

9、ttern=+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調(diào)用API的示例，請參考JavaScript調(diào)用API示例。* 結(jié)果表示 PLAIN 分詞 對文本進行分詞的調(diào)用示例如下： GET 返回結(jié)果為： 1.我是中國人。 在plain格式的

10、分詞結(jié)果中，每句話占一行。詞與詞之間用空格分割，句與句之間用換行分割。段落與段落之間用兩個換行分割。 詞性標(biāo)注 對文本進行詞性標(biāo)注的調(diào)用示例如下： GET 返回結(jié)果為： 1.我_r是_v中國_ns人_n。_wp 在plain格式的詞性標(biāo)注結(jié)果中，每句話占一行。詞和詞的標(biāo)注信息之間用下劃線連接，項與項之間用空格分割，句與句之間用換行分割。段落與段落之間用兩個換行分割。 命名實體識別 對文本進行命名實體識別的調(diào)用示例如下： GET 返回結(jié)果為： 1.我是中國Ns人。 在plain格式的命名實體識別結(jié)果中，每句話占一行。如果本句話含有實體，將會被包圍，并且在之后添加實體類型標(biāo)識。段落與段落之間有兩個

11、換行符分割。 如果您只想獲得文本中的所有的命名實體列表，請用參數(shù)only_ner=true來指定。 其調(diào)用示例如下： GET 返回結(jié)果為： 1.中國Ns 在plain格式的命名實體識別列表形式的返回結(jié)果中，每個實體信息占一行。每一行有兩列，第一列為實體本身，第二列為實體類型。 依存句法分析 對文本進行依存句法分析的調(diào)用示例如下： GET 返回結(jié)果為： 1.我_0是_1SBV2.是_1-1HED3.中國_2人_3ATT4.人_3是_1VOB5.。_4是_1WP 在plain格式的依存句法分析返回結(jié)果中，文本中的每個詞的句法信息占一行。每一行獨占三列。第一列為依存句法分析的孩子結(jié)點信息，由結(jié)點名+

12、下劃線+詞id組成；第二列為依存句法分析的父親節(jié)點信息，由結(jié)點名+下劃線+詞id組成，如果沒有父親結(jié)點，則由-1表示;第三列為具體的依存句法分析關(guān)系。文本句子級別的信息之間用兩個換行分割，文本段落級別的信息之間用三個換行分割。 語義角色標(biāo)注 對文本進行語義角色標(biāo)注的調(diào)用示例如下： GET 返回結(jié)果為： 1.我A0是v中國人A1。 XML 對文本進行全部任務(wù)的分析示例如下： GET 返回結(jié)果為： ..8. XML標(biāo)準(zhǔn)結(jié)果如下：結(jié)點標(biāo)簽分別為xml4nlp,note,doc,para,sent,word,arg共七種

13、結(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為篇章結(jié)點，以段落為單位包含文本內(nèi)容；無任何屬性值； 4.para為段落結(jié)點，需含id 屬性，其值從0 開始； 5.sent為句子結(jié)點，需含屬性為id，cont；id 為段落中句子序號，其值從0 開始；cont 為句子內(nèi)容； 6.word為分詞結(jié)點，需含屬性為id, cont；

14、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)系； 7.arg為語義角色信息結(jié)點，任何一個謂詞都會帶有若干個該結(jié)點；其屬性為id,type,beg，end；id為序號，從0 開始；type代表角色名稱；beg為開始的詞序號，end為結(jié)束的序號； 各結(jié)點及屬性的邏輯關(guān)系說明如下： 1. 各結(jié)點層次關(guān)系可以從圖中清楚獲得，凡帶有id 屬性的結(jié)點是可以包含多個； 2. 如果sent

15、=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則分詞結(jié)點中必須包含ne 屬性； (3) 如果parser=y則分詞結(jié)點中必須包含parent 及relate 屬性； (4) 如果srl=y則凡是謂詞(predicate)的分詞會包含若干個arg 結(jié)點； 在XML格式的分析中，用戶可以通過指定參數(shù)pattern=ws | pos | ner | dp | srl

16、| all 來指名分析任務(wù)并獲取對應(yīng)的XML結(jié)果。 注意！ 依存句法分析結(jié)果中并不具有ne信息。 JSON 對文本進行全部任務(wù)的分析示例如下： GET 返回結(jié)果為： 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:

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

18、單詞對象中，需含鍵值名為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 開始；type 代表角色名稱；beg 為開始的詞序號

19、，end 為結(jié)束的序號；如果單詞沒有語義角色信息，arg所標(biāo)識的數(shù)組為空。 用戶也可以通過指定參數(shù)has_key=false來去掉鍵值名，示例如下： GET 返回結(jié)果為： 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格式的無鍵值名的返回結(jié)果中，數(shù)組信息排序與有鍵值名的情況相同。即按照：id,cont,pos,ne,parent,relate,arg的順序。 arg中信息的順序為id,type,beg,end。 CONLL 對文本進

20、行全部任務(wù)的分析示例如下： GET 返回結(jié)果為： 1.0我_rO1SBV_(A0*)2.1是_vO-1HED_是(v*)3.2中國_nsS-Ns3ATT_(A1*4.3人_nO1VOB_*) 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如果單詞是語義

21、角色標(biāo)注中的謂詞，則為單詞本身，否則為空11及以后每個謂詞占一列，每一列為該謂詞的語義角色標(biāo)注信息* 錯誤響應(yīng) 正常情況下，用戶將得到正確的結(jié)果，此時HTTP狀態(tài)為200 OK。 $ curl -iHTTP/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)進行了調(diào)整。EMPTY SENTENCEtext參數(shù)不允許為空。ENCODING NOT IN UTF8text編碼錯

22、誤。請確保使用UTF8編碼。BAD XML FORMAT輸入的XML格式不正確。請參考XML格式進行調(diào)整。SENTENCE TOO LONG輸入某句子超過300字或分詞結(jié)果超過70詞。401 UnauthorizedUNAUTHORIZED USERAPI_KEY不合法，用戶認(rèn)證不被通過。403 ForbiddenACCOUNT OUT OF QUOTA本月流量使用超過該帳號配額，請聯(lián)系管理員進行擴充。405 Method Not AllowedHTTP METHOD ERROR該HTTP動作不被允許，系統(tǒng)只允許GET和POST方式的HTTP請求。414 Request-URI Too Lon

23、gTEXT TOO LARGE ERROR文本大小超過服務(wù)器限制，GET方式最大10K，POST方式最大20K。500 Internal Server ErrorSERVER ERROR服務(wù)器內(nèi)部錯誤。若稍候嘗試仍然有此錯誤，請將URI用例報告給管理員。503 Service UnavailableAPI RATE LIMIT EXCEEDEDAPI請求頻率超過了語言云的限制。請參考頻率限制。 舉個例子，401 Unauthorized錯誤的返回示例如下： $ curl -iHTTP/1.1 401UNAUTHORIZEDContent-Type: application/json.error_message:UN