语义角色标注 API 文档

接口说明

自然语言处理，是以哈工大社会计算与信息检索研究中心研发的 “语言技术平台（LTP）” 为基础，为用户提供高效精准的 中文（简体） 自然语言处理服务。该自然语言基础处理服务包括：词法分析、依存句法分析、语义角色标注、语义依存 (依存树) 分析、语义依存 (依存图) 分析五类，其中词法分析又可以分为：中文分词、词性标注、命名实体识别。

模块简介：

中文分词(cws)

中文分词(Chinese Word Segmentation, CWS)指的是将汉字序列切分成词序列。因为在汉语中，词是承载语义的最基本的单元。分词是信息检索、文本分类、情感分析等多项中文自然语言处理任务的基础。
词性标注(pos)

词性标注(Part-of-speech Tagging, POS)是给句子中每个词一个词性类别的任务。这里的词性类别可能是名词、动词、形容词或其他。
命名实体识别(ner)

命名实体识别(Named Entity Recognition, NER)是在句子的词序列中定位并识别人名、地名、机构名等实体的任务。
依存句法分析(dp)

依存语法(Dependency Parsing, DP) 通过分析语言单位内成分之间的依存关系揭示其句法结构。直观来讲，依存句法分析识别句子中的“主谓宾”、“定状补”这些语法成分，并分析各成分之间的关系。
语义角色标注(srl)

语义角色标注(Semantic Role Labeling, SRL) 是一种浅层的语义分析技术，标注句子中某些短语为给定谓词的论元 (语义角色)，如施事、受事、时间和地点等。其能够对问答系统、信息抽取和机器翻译等应用产生推动作用。
语义依存 (依存树) 分析(sdp)

语义依存 (依存树) 分析(Semantic Dependency Parsing, SDP)，分析句子各个语言单位之间的语义关联，并将语义关联以依存结构呈现。使用语义依存刻画句子语义，好处在于不需要去抽象词汇本身，而是通过词汇所承受的语义框架来描述该词汇，而论元的数目相对词汇来说数量总是少了很多的。语义依存分析目标是跨越句子表层句法结构的束缚，直接获取深层的语义信息。
语义依存 (依存图) 分析(sdgp)

语义依存 (依存图) 分析(Semantic Dependency Graph Parsing, SDGP) 是在语义依存树基础上做了突破，使得对连动、兼语、概念转位等汉语中常见的现象的分析更全面深入。

以上能力是通过HTTP API的方式给开发者提供一个通用的接口，适用于一次性交互数据传输的AI服务场景。相较于SDK，API具有轻量、跨语言的特点，不过请注意该接口使用的HTTP API协议不支持跨域。

接口Demo

示例demo 请点击这里下载。
目前仅提供部分开发语言的demo，其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到讯飞开放平台社区分享你们的demo。

接口要求

集成自然语言处理API时，需按照以下要求。

内容	说明
请求协议	http[s] (为提高安全性，强烈推荐https)
请求地址	http[s]: //ltpapi.xfyun.cn/v1/{func} 不同的模块func不同，请参照接口说明注：服务器IP不固定，为保证您的接口稳定，请勿通过指定IP的方式调用接口，使用域名方式调用
请求方式	POST
接口鉴权	签名机制，见授权认证
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向讯飞云服务发起HTTP请求的均可
适用范围	任意操作系统，但因不支持跨域不适用于浏览器，请在后端调用接口
文本语种	中文简体
文本长度	不超过500字节

接口调用流程

注：若需配置IP白名单，请前往控制台。IP白名单规则请参照 IP白名单。

通过接口密钥基于MD5计算签名，将签名以及其他参数放在Http Request Header中，详见下方请求头。
将文本数据放在Http Request Body中，以POST表单的形式提交，详见下方请求体。
向服务器端发送Http请求后，接收服务器端的返回结果，返回结果详见各接口的详细说明。

接口地址示例：

	POST http[s]://ltpapi.xfyun.cn/v1/{func} HTTP/1.1
	Content-Type:application/x-www-form-urlencoded; charset=utf-8

说明: 接口地址中{func}需替换为相应的功能模块名称，目前开放的功能模块有：中文分词(cws)、词性标注(pos)、依存句法分析(dp)、命名实体识别(ner)、语义角色标注(srl)、语义依存 (依存树) 分析(sdp)、语义依存 (依存图) 分析(sdgp)

白名单

在调用该业务接口时

若关闭IP白名单，接口认为IP不限，不会校验IP。
若打开IP白名单，则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。

IP白名单规则

IP白名单，在控制台-我的应用-相应服务的应用管理卡片上编辑，保存后五分钟左右生效；
不同Appid的不同服务都需要分别设置IP白名单；
IP白名单需设置为外网IP，请勿设置局域网IP；
如果服务器返回结果如下所示(illegal client_ip)，则表示由于未配置IP白名单或配置有误，服务端拒绝服务。

{
    "code":"10105",
    "desc":"illegal access|illegal client_ip",
    "data":"",
    "sid":"xxxxxx"
}

接口请求参数

请求头

在 Http Request Header 中配置以下参数。

授权认证

以下参数用于授权认证：

参数	格式	说明	必须
X-Appid	string	讯飞开放平台注册申请应用的应用ID(appid)	是
X-CurTime	string	当前UTC时间戳从1970年1月1日0点0 分0 秒开始到现在的秒数	是
X-Param	string	相关参数JSON串经Base64编码后的字符串，详见业务参数	是
X-CheckSum	string	令牌，计算方法：MD5(APIKey + X-CurTime + X-Param)，三个值拼接的字符串，进行MD5哈希计算（32位小写）	是

注：

APIKey：接口密钥，在讯飞开放平台控制台添加相应服务后即可获取，调用方注意保管，如泄露，可到控制台提交工单联系技术人员重置；
X-CheckSum 有效期：出于安全性考虑，每个 X-CheckSum 的有效期为 5 分钟(用 X-CurTime 计算)，同时 X-CurTime 要与标准时间同步，否则时间相差太大，服务端会直接认为 X-CurTime 无效；
BASE64 编码采用 MIME 格式，字符包括大小写字母各26个，加上10个数字，和加号 + ，斜杠 / ，一共64个字符。

*X-CheckSum *生成示例：

String APIKey="abcd1234"; 
String X-CurTime="1502607694";
String X-Param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String X-CheckSum=MD5(apiKey + X-CurTime + X-Param);

业务参数

X-Param 为各配置参数组成的 JSON 串经 BASE64 编码之后的字符串，原始 JSON 串各字段说明如下：

参数	类型	必须	说明	示例
type	string	是	类型，可选值：dependent	dependent

X-Param生成示例：

	原始JSON串：
	{
	    "type": "dependent"
	}
	BASE64编码（即X-Param）：
	eyJ0eXBlIjoiZGVwZW5kZW50In0=

请求体

以POST表单的形式提交以下参数：

参数	类型	必须	说明	示例
text	string	是	待分析文本，长度限制为500字节(中文简体)	他叫汤姆去拿外衣。

注：
一般基础类库会默认进行urlencode处理，请注意不要重复处理。

接口返回参数

返回值为json串，各字段如下：

参数	类型	说明
code	string	结果码(具体见SDK&API错误码查询)
data	json对象	对应具体的文本分析结果，例如分词结果
desc	string	描述
sid	string	会话ID

其中sid字段主要用于追查问题，如果出现问题，可以提供sid给讯飞技术人员帮助确认问题。

data各字段说明如下：

参数	类型	说明
word	json数组	中文分词结果
pos	json数组	词性标注结果
dp	json数组	依存句法分析结果,对象中字段`parent,relate`分别是父节点，标注关系
ner	json数组	命名实体识别结果
srl	json数组	语义角色标注结果,对象中字段`beg,end,id,type`分别是语义角色开始位置，结束位置，谓词位置，角色标签名
sdp	json数组	语义依存 (依存树) 分析结果,对象中字段`parent,relate`分别是父节点，语义关系
sdgp	json数组	语义依存 (依存图) 分析结果,对象中字段`id,parent,relate`分别是弧指向节点词索引，弧父节点词索引，语义关系

结果示例如下：

失败结果：

	{
		"code": "10105",
		"desc": "illegal access|invalid X-Appid",
		"data": {},
		"sid": "ltp0000a744@ch78290eb1e128000100"
	}

成功结果：

中文分词(cws)

	{
	    "code": "0",
	    "data": {
	        "word": [
	            "他",
	            "叫",
	            "汤姆",
	            "去",
	            "拿",
	            "外衣",
	            "。"
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp00000006@ch7ea90e9a28b8000100"
	}

词性标注(pos)

	{
	    "code": "0",
	    "data": {
	        "pos": [
	            "r",
	            "v",
	            "nh",
	            "v",
	            "v",
	            "n",
	            "wp"
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp00000007@ch7ea90e9a28ef000100"
	}

"r", "v", "nh", "v", "v", "n", "wp" 分别对应cws返回结果中的"他", "叫", "汤姆", "去", "拿", "外衣", "。"

依存句法分析(dp)

	{
	    "code": "0",
	    "data": {
	        "dp": [
	            {
	                "parent": 1,
	                "relate": "SBV"
	            },
	            {
	                "parent": -1,
	                "relate": "HED"
	            },
	            {
	                "parent": 1,
	                "relate": "DBL"
	            },
	            {
	                "parent": 4,
	                "relate": "ADV"
	            },
	            {
	                "parent": 1,
	                "relate": "VOB"
	            },
	            {
	                "parent": 4,
	                "relate": "VOB"
	            },
	            {
	                "parent": 1,
	                "relate": "WP"
	            }
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp00000005@ch7ea90e9a2858000100"
	}

以dp[0]为例，"他"的父节点是"叫"，他们中间的关系为SBV，即主谓关系。

命名实体识别(ner)

	{
	    "code": "0",
	    "data": {
	        "ner": [
	            "O",
	            "O",
	            "S-Nh",
	            "O",
	            "O",
	            "O",
	            "O"
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp00000008@ch7ea90e9a2928000100"
	}

"O", "O", "S-Nh", "O", "O", "O", "O" 分别对应cws返回结果中的"他", "叫", "汤姆", "去", "拿", "外衣", "。"

语义角色标注(srl)

	{
	    "code": "0",
	    "data": {
	        "srl": [
	            {
	                "beg": 0,
	                "end": 0,
	                "id": 1,
	                "type": "A0"
	            },
	            {
	                "beg": 2,
	                "end": 2,
	                "id": 1,
	                "type": "A1"
	            },
	            {
	                "beg": 3,
	                "end": 5,
	                "id": 1,
	                "type": "A2"
	            },
	            {
	                "beg": 5,
	                "end": 5,
	                "id": 4,
	                "type": "A1"
	            }
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp0000a741@ch78290eb1df9e000100"
	}

语义依存 (依存树) 分析(sdp)

	{
	    "code": "0",
	    "data": {
	        "sdp": [
	            {
	                "parent": 2,
	                "relate": "Agt"
	            },
	            {
	                "parent": 0,
	                "relate": "Root"
	            },
	            {
	                "parent": 2,
	                "relate": "Datv"
	            },
	            {
	                "parent": 2,
	                "relate": "eSucc"
	            },
	            {
	                "parent": 4,
	                "relate": "ePurp"
	            },
	            {
	                "parent": 5,
	                "relate": "Pat"
	            },
	            {
	                "parent": 2,
	                "relate": "mPunc"
	            }
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp00000002@ch409d0e9a29ec000100"
	}

以sdp[0]为例，"他"的父节点是"叫"，他们中间的关系为Agt，即施事关系。

语义依存 (依存图) 分析(sdgp)

	{
	    "code": "0",
	    "data": {
	        "sdgp": [
	            {
	                "id": 0,
	                "parent": 1,
	                "relate": "Agt"
	            },
	            {
	                "id": 1,
	                "parent": -1,
	                "relate": "Root"
	            },
	            {
	                "id": 2,
	                "parent": 1,
	                "relate": "Datv"
	            },
	            {
	                "id": 2,
	                "parent": 3,
	                "relate": "Agt"
	            },
	            {
	                "id": 2,
	                "parent": 4,
	                "relate": "Agt"
	            },
	            {
	                "id": 3,
	                "parent": 1,
	                "relate": "eSucc"
	            },
	            {
	                "id": 4,
	                "parent": 3,
	                "relate": "ePurp"
	            },
	            {
	                "id": 5,
	                "parent": 4,
	                "relate": "Pat"
	            },
	            {
	                "id": 6,
	                "parent": 4,
	                "relate": "mPunc"
	            }
	        ]
	    },
	    "desc": "success",
	    "sid": "ltp0000000a@dx4f2f0f1f5931000100"
	}

以sdgp[0]为例，"他"的父节点是"叫"，他们中间的关系为Agt，即施事关系。

python脚本示例(python3)

说明：将脚本中TEXT, API_KEY, APPID,{func}, 换成相应的待分析文本，讯飞开放平台提供的apiKey，讯飞开放平台应用的appid以及功能模块名称即可，运行脚本可打印相应结果。

	#!/usr/bin/python
	## -*- coding: UTF-8 -*-
	import time
	import urllib.request
	import urllib.parse
	import json
	import hashlib
	import base64
	
	
	def main():
	    body = urllib.parse.urlencode({'text': 'TEXT'}).encode('utf-8')
	
	    url = 'http://ltpapi.xfyun.cn/v1/{func}'
	    api_key = 'API_KEY'
	    param = {"type": "dependent"}
	
	    x_appid = 'APPID'
	    x_param = base64.b64encode(json.dumps(param).replace(' ', '').encode('utf-8'))
	    x_time = int(int(round(time.time() * 1000)) / 1000)
	    x_checksum = hashlib.md5(api_key.encode('utf-8') + str(x_time).encode('utf-8') + x_param).hexdigest()
	    x_header = {'X-Appid': x_appid,
	                'X-CurTime': x_time,
	                'X-Param': x_param,
	                'X-CheckSum': x_checksum}
	    req = urllib.request.Request(url, body, x_header)
	    result = urllib.request.urlopen(req)
	    result = result.read()
	    print(result.decode('utf-8'))
	    return
	
	
	if __name__ == '__main__':
	    main()

附录

词性标记集

Tag	Description	含义描述	Example
r	pronoun	代词	我们
n	general noun	名词	苹果
ns	geographical name	地名	北京
wp	punctuation	标点	，。！
k	suffix	后缀	界, 率
h	prefix	前缀	阿, 伪
u	auxiliary	助词	的, 地
c	conjunction	连词	和, 虽然
v	verb	动词	跑, 学习
p	preposition	介词	在, 把
d	adverb	副词	很
q	quantity	量词	个
nh	person name	人名	杜甫, 汤姆
m	number	数词	一，第一
e	exclamation	语气词	哎
b	other noun-modifier	状态词	大型, 西式
a	adjective	形容词	美丽
nd	direction noun	方位词	右侧
nl	location noun	处所词	城郊
o	onomatopoeia	拟声词	哗啦
nt	temporal noun	时间词	近日, 明代
nz	other proper noun	其他专名	诺贝尔奖
nl	organization name	机构团体	保险公司
i	idiom	成语	百花齐放
j	abbreviation	缩写词	公检法
ws	foreign words	外来词	CPU
g	morpheme	词素	茨, 甥
x	non-lexeme	非词位	萄, 翱

依存句法分析标注关系

关系类型	Tag	Description	Example
主谓关系	SBV	subject-verb	我送她一束花 (我 <-- 送)
动宾关系	VOB	直接宾语，verb-object	我送她一束花 (送 --> 花)
间宾关系	IOB	间接宾语，indirect-object	我送她一束花 (送 --> 她)
前置宾语	FOB	前置宾语，fronting-object	他什么书都读 (书 <-- 读)
兼语	DBL	double	他请我吃饭 (请 --> 我)
定中关系	ATT	attribute	红苹果 (红 <-- 苹果)
状中结构	ADV	adverbial	非常美丽 (非常 <-- 美丽)
动补结构	CMP	complement	做完了作业 (做 --> 完)
并列关系	COO	coordinate	大山和大海 (大山 --> 大海)
介宾关系	POB	preposition-object	在贸易区内 (在 --> 内)
左附加关系	LAD	left adjunct	大山和大海 (和 <-- 大海)
右附加关系	RAD	right adjunct	孩子们 (孩子 --> 们)
独立结构	IS	independent structure	两个单句在结构上彼此独立
标点	WP	punctuation	。
核心关系	HED	head	指整个句子的核心

命名实体说明

标记	说明
Nh	人名
Ns	地名
Ni	机构名

前缀说明: 包含BIES四种前缀，分别表示开始、中间、结束、独立

语义角色列表

标记	说明
ADV	adverbial, default tag ( 附加的，默认标记 )
BNE	beneﬁciary ( 受益人 )
CND	condition ( 条件 )
DIR	direction ( 方向 )
DGR	degree ( 程度 )
EXT	extent ( 扩展 )
FRQ	frequency ( 频率 )
LOC	locative ( 地点 )
MNR	manner ( 方式 )
PRP	purpose or reason ( 目的或原因 )
TMP	temporal ( 时间 )
TPC	topic ( 主题 )
CRD	coordinated arguments ( 并列参数 )
PRD	predicate ( 谓语动词 )
PSR	possessor ( 持有者 )
PSE	possessee ( 被持有 )

备注: 核心的语义角色为A0-5六种，A0通常表示动作的施事，A1通常表示动作的影响等，A2-5根据谓语动词不同会有不同的语义含义。

语义依存关系说明

关系类型	Tag	Description	Example
施事关系	Agt	Agent	我送她一束花 (我 <-- 送)
当事关系	Exp	Experiencer	我跑得快 (跑 --> 我)
感事关系	Aft	Affection	我思念家乡 (思念 --> 我)
领事关系	Poss	Possessor	他有一本好读 (他 <-- 有)
受事关系	Pat	Patient	他打了小明 (打 --> 小明)
客事关系	Cont	Content	他听到鞭炮声 (听 --> 鞭炮声)
成事关系	Prod	Product	他写了本小说 (写 --> 小说)
源事关系	Orig	Origin	我军缴获敌人四辆坦克 (缴获 --> 坦克)
涉事关系	Datv	Dative	他告诉我个秘密 ( 告诉 --> 我 )
比较角色	Comp	Comitative	他成绩比我好 (他 --> 我)
属事角色	Belg	Belongings	老赵有俩女儿 (老赵 <-- 有)
类事角色	Clas	Classification	他是中学生 (是 --> 中学生)
依据角色	Accd	According	本庭依法宣判 (依法 <-- 宣判)
缘故角色	Reas	Reason	他在愁女儿婚事 (愁 --> 婚事)
意图角色	Int	Intention	为了金牌他拼命努力 (金牌 <-- 努力)
结局角色	Cons	Consequence	他跑了满头大汗 (跑 --> 满头大汗)
方式角色	Mann	Manner	球慢慢滚进空门 (慢慢 <-- 滚)
工具角色	Tool	Tool	她用砂锅熬粥 (砂锅 <-- 熬粥)
材料角色	Malt	Material	她用小米熬粥 (小米 <-- 熬粥)
时间角色	Time	Time	唐朝有个李白 (唐朝 <-- 有)
空间角色	Loc	Location	这房子朝南 (朝 --> 南)
历程角色	Proc	Process	火车正在过长江大桥 (过 --> 大桥)
趋向角色	Dir	Direction	部队奔向南方 (奔 --> 南)
范围角色	Sco	Scope	产品应该比质量 (比 --> 质量)
数量角色	Quan	Quantity	一年有365天 (有 --> 天)
数量数组	Qp	Quantity-phrase	三本书 (三 --> 本)
频率角色	Freq	Frequency	他每天看书 (每天 <-- 看)
顺序角色	Seq	Sequence	他跑第一 (跑 --> 第一)
描写角色	Desc(Feat)	Description	他长得胖 (长 --> 胖)
宿主角色	Host	Host	住房面积 (住房 <-- 面积)
名字修饰角色	Nmod	Name-modifier	果戈里大街 (果戈里 <-- 大街)
时间修饰角色	Tmod	Time-modifier	星期一上午 (星期一 <-- 上午)
反角色	r + main role		打篮球的小姑娘 (打篮球 <-- 姑娘)
嵌套角色	d + main role		爷爷看见孙子在跑 (看见 --> 跑)
并列关系	eCoo	event Coordination	我喜欢唱歌和跳舞 (唱歌 --> 跳舞)
选择关系	eSelt	event Selection	您是喝茶还是喝咖啡 (茶 --> 咖啡)
等同关系	eEqu	event Equivalent	他们三个人一起走 (他们 --> 三个人)
先行关系	ePrec	event Precedent	首先，先
顺承关系	eSucc	event Successor	随后，然后
递进关系	eProg	event Progression	况且，并且
转折关系	eAdvt	event adversative	却，然而
原因关系	eCau	event Cause	因为，既然
结果关系	eResu	event Result	因此，以致
推论关系	eInf	event Inference	才，则
条件关系	eCond	event Condition	只要，除非
假设关系	eSupp	event Supposition	如果，要是
让步关系	eConc	event Concession	纵使，哪怕
手段关系	eMetd	event Method
目的关系	ePurp	event Purpose	为了，以便
割舍关系	eAban	event Abandonment	与其，也不
选取关系	ePref	event Preference	不如，宁愿
总括关系	eSum	event Summary	总而言之
分叙关系	eRect	event Recount	例如，比方说
连词标记	mConj	Recount Marker	和，或
的字标记	mAux	Auxiliary	的，地，得
介词标记	mPrep	Preposition	把，被
语气标记	mTone	Tone	吗，呢
时间标记	mTime	Time	才，曾经
范围标记	mRang	Range	都，到处
程度标记	mDegr	Degree	很，稍微
频率标记	mFreq	Frequency Marker	再，常常
趋向标记	mDir	Direction Marker	上去，下来
插入语标记	mPars	Parenthesis Marker	总的来说，众所周知
否定标记	mNeg	Negation Marker	不，没，未
情态标记	mMod	Modal Marker	幸亏，会，能
标点标记	mPunc	Punctuation Marker	，。！
重复标记	mPept	Repetition Marker	走啊走 (走 --> 走)
多数标记	mMaj	Majority Marker	们，等
实词虚化标记	mVain	Vain Marker
离合标记	mSepa	Seperation Marker	吃了个饭 (吃 --> 饭) 洗了个澡 (洗 --> 澡)
根节点	Root	Root	全句核心节点

调用示例

注: demo只是一个简单的调用示例，不适合直接放在复杂多变的生产环境使用

自然语言基础处理demo go语言

自然语言基础处理demo php语言

自然语言基础处理demo java语言

自然语言基础处理demo python3语言

自然语言基础处理demo c#语言

常见问题

语义角色标注主要功能是什么？

答：语义角色标注是一种浅层的语义分析技术，标注句子中某些短语为给定谓词的论元 (语义角色) ，如施事者、受事者、经验者、时间和地点等。

语义角色标注支持什么应用平台？

答：目前语义角色标注支持Web API应用平台。

语义角色标注如何试用？

答：登录讯飞开放平台后，进入语义角色标注页面，点击“服务管理”，添加IP白名单，下载相应的demo，填写appid和apikey即可调用Web api接口。

在这篇文章中：

# 语义角色标注 API 文档

# 接口说明

# 接口Demo

# 接口要求

# 接口调用流程

# 白名单

# 接口请求参数

# 请求头

# 授权认证

# 业务参数

# 请求体

# 接口返回参数

# 附录

# 词性标记集

# 依存句法分析标注关系

# 命名实体说明

# 语义角色列表

# 语义依存关系说明

# 调用示例

# 常见问题

# 语义角色标注主要功能是什么？

# 语义角色标注支持什么应用平台？

# 语义角色标注如何试用？