En | 中

TexSmart HTTP API


TexSmart API共分三类,即文本理解API、文本匹配API以及文本图谱API,下面介绍文本理解API的使用方式。 该API支持通过HTTP-POST方式访问,API地址为 https://texsmart.qq.com/api
输入的post-data需要是JSON格式,输出也是JSON格式。 推荐使用Postman来查看API的结果。

下面是一个简单的JSON输入示例:
{"str":"他在看流浪地球。"}
调用API的示例代码: Python代码 | Java代码 | C++代码 | C#代码

调用API后返回的结果是如下的JSON格式:
{
	"header":{"time_cost_ms":1.517,"time_cost":0.001517,
                  "core_time_cost_ms":1.467,"ret_code":"succ"},
	"norm_str":"他在看流浪地球。",
	"word_list":[
		{"str":"他","hit":[0,1,0,1],"tag":"PN"},
		{"str":"在","hit":[1,1,1,1],"tag":"P"},
		{"str":"看","hit":[2,1,2,1],"tag":"VV"},
		{"str":"流浪","hit":[3,2,3,2],"tag":"JJ"},
		{"str":"地球","hit":[5,2,5,2],"tag":"NN"},
		{"str":"。","hit":[7,1,7,1],"tag":"PU"}
	],
	"phrase_list":[
		{"str":"他","hit":[0,1,0,1],"tag":"PN"},
		{"str":"在","hit":[1,1,1,1],"tag":"P"},
		{"str":"看","hit":[2,1,2,1],"tag":"VV"},
		{"str":"流浪地球","hit":[3,4,3,4],"tag":"NN"},
		{"str":"。","hit":[7,1,7,1],"tag":"PU"}
	],
	"entity_list":[
		{"str":"流浪地球","hit":[3,4,3,4],"type":{"name":"work.movie","i18n":"电影","flag":1},
		"meaning":{"related":["战狼二", "上海堡垒", "悲伤逆流成河", "新喜剧之王", "少年的你", 
		"烈火英雄", "我不是药神", "西虹市首富", "战狼2", "飞驰人生"]},
		"tag":"work.movie","tag_i18n":"电影"}
	],
	"fn_list":[
	],
	"syntactic_parsing_str":"",
	"srl_str":""
}
其中,header给出的是一些说明API调用的辅助信息(耗时、错误码等),norm_str给出的是文本正规化的结果, word_list包含基础粒度的分词及其词性标注结果,phrase_list是复合粒度的分词和词性标注, entity_list给出了所有识别出的实体及其类型,syntactic_parsing_str和srl_str分别表示成分句法树和语义角色标注结果。 在这个例子中syntactic_parsing_str和srl_str均为空字符串,因为syntactic_parsing和srl在缺省设置中是没有被激活的。

需要指出的是,复合粒度的分词和词性标注模块依赖实体识别的结果。因此当实体识别功能被激活或关闭时(在option选项中设置:"ner":{"enable":true/false}),复合粒度的分词和词性标注结果可能会有所不同。

完整的输入输出格式说明

输入JSON对象支持的字段说明如下:

字段名称 数据类型 字段说明
str string 输入的句子
options JSON Object 选项信息,主要用来指定要调用的功能以及完成每项功能所采用的算法等。详见后面"更多调用方式"一节的内容
echo_data JSON Object 作为这个字段值的JSON对象可以由用户自由定义,服务将在输出中以echo方式原封不动地返回此对象的内容。
用户可以用这个字段来记录当前request的标识信息

输出JSON对象的各个字段说明如下:

字段名称 数据类型 字段说明
header JSON Object 调用执行后返回的辅助信息
time_cost_ms字段:处理请求所花的时间,以毫秒(ms)计算。
time_cost字段:处理请求所花的时间,以秒来计算。
ret_code字段:返回码,"succ"表示成功,其它为错误码。常见错误码包括:
    error.invalid_request_format: 请求格式不合法(比如不是JSON格式)
    error.timeout: 超时
    error.busy: 服务忙(正在处理其它请求)
    error.too_long_text: 文本长度超过限额(长度限定8192个字符)
norm_str string 输入句子正则化的结果
word_list JSON Object 基础粒度分词和词性标注的结果
hit字段:值是一个JSON数组(JSON array),其中数组中第一个数表示本word在norm_str中的位置,第二个数表示word的长度。 请忽略第三和第四个数。 位置和长度都是按照字符(character)而不是按照字节(byte)来计算的。 比如一个汉字、数字、标点、空格等都是一个字符。
tag字段:本word的词性(POS tag)
phrase_list JSON Object 复合粒度分词和词性标注的结果
(各个字段的含义参见word_list)
entity_list JSON Object 识别出的实体信息
hit字段:参见word_list中的说明
type字段:值是一个JSON对象,包含实体类型的信息,如类型的标准名字、自然语言表达、flag等。 其中:
    name: 实体类型的标准名字;
    i18n: 类型名字的自然语言表达(中文或者英文);
    flag: 表示实体是以名字方式还是子类型方式出现的 (1表示名字,2表示子类型,0表示未知);当flag为0的时候,此字段可能省略(即不出现在结果JSON中);
    path: 此实体类型在TexSmart类型系统中的路径, 从根结点开始,一直到此类型的直接父类型。
    请通过下载页面 获取TexSmart所支持的所有实体类型的信息。
meaning字段:实体的语义信息,用一个JSON对象来表示,具体格式跟实体类型相关。
tag字段:【即将失效,请使用type字段】实体类型的标准名字。
tag_i18n字段:【即将失效,请使用type字段】实体类型的自然语言表达(中文或者英文)
syntactic_parsing_str string 成分句法分析的结果
srl_str string 语义角色标注的结果


更多调用方式

输入选项设置

更一般地,输入JSON还可以包括一些options,这些options包括分词、词性标注、命名实体识别、句法分析和语义角色标注等功能,以及调用什么算法来实现某个功能。 开头简单例子的输入JSON中没有options,表示采用缺省选项。下面例子的options各个字段都是缺省值:

{
  "str":"他在看流浪地球。",
  "options":
  {
    "input_spec":{"lang":"auto"},
    "word_seg":{"enable":true},
    "pos_tagging":{"enable":true,"alg":"log_linear"},
    "ner":{"enable":true,"alg":"fine.std"},
    "syntactic_parsing":{"enable":false},
    "srl":{"enable":false},
    "text_cat":{"enable":false},
  },
  "echo_data":{"request_id":12345}
}
其中,input_spec表示输入的语言种类,它有三个取值,分别是自动识别语言(“auto”),中文(“chs”)和英文(“en”)。 ”enable”可以取”true”或”false”,表示是否要激活对应的功能。 ”alg”表示对应的功能需要调用什么算法,”pos_tagging”中的”alg”有三种选择(“crf”, “dnn”, “log_linear”), ”ner“中的”alg”有五种选择("coarse.crf", "coarse.dnn", “coarse.lua”, "fine.std"和"fine.high_acc"), ”coarse\fine”表示返回的是粗粒度/细粒度NER的结果。 "syntactic_parsing", "srl", "text_cat"分别表示句法分析、语义角色标注和文本分类工具;它们默认为缺省值。 ”echo_data“的取值由用户自由定义,用户可以用它来记录当前request的标识信息,如request_id,它在异步调用等场合可能会有用。

批处理调用

Texsmart支持批处理调用API:通过一个JSON输入,处理多个(中文和英文)句子的分析。它的JSON输入实例如下:

{
  "str":[
         "上个月30号,南昌王先生在自己家里边看流浪地球边吃煲仔饭。",
         "2020年2月7日,经中央批准,国家监察委员会决定派出调查组赴湖北省武汉市,就群众反映的涉及李文亮医生的有关问题作全面调查。",
         "John Smith stayed in San Francisco last month."
        ]
}
请注意,批处理调用的输出格式跟普通调用的输出格式有一些区别,所有句子的分析结果构成一个JSON array,作为"res_list"字段的值。


示例代码

用Python调用API的示例代码

示例代码1(用http.client):
# -*- coding: utf8 -*-
import json
import http.client

obj = {"str": "他在看流浪地球。"}
req_str = json.dumps(obj)

conn = http.client.HTTPSConnection("texsmart.qq.com")
conn.request("POST", "/api", req_str)
response = conn.getresponse()
print(response.status, response.reason)
res_str = response.read().decode('utf-8')
print(res_str)
#print(json.loads(res_str))
示例代码2(需要安装requests包):
# -*- coding: utf8 -*-
import json
import requests

obj = {"str": "他在看流浪地球。"}
req_str = json.dumps(obj).encode()

url = "https://texsmart.qq.com/api"
r = requests.post(url, data=req_str)
r.encoding = "utf-8"
print(r.text)
#print(json.loads(r.text))

用Java调用API的示例代码

[TBD]

用C++调用API的示例代码

[TBD]

用C#调用API的示例代码

[TBD]

关于TexSmart

TexSmart是腾讯AI Lab自然语言处理团队所构建的一个自然语言文本理解系统,用以对中文和英文两种语言的文本进行词法、句法和语义分析。 除了支持分词、词性标注、命名实体识别(NER)、句法分析、语义角色标注等常见功能外,TexSmart还提供细粒度命名实体识别语义联想深度语义表达等特色功能。

体验Demo | 系统介绍