bosonnlp.py

BosonNLP HTTP API 封装库(SDK)。

安装

bosonnlp 代码托管在 GitHub,并且已经发布到 PyPI,可以直接通过 pip 安装:

$ pip install bosonnlp

bosonnlp 以 MIT 协议发布。

使用教程

>>> from bosonnlp import BosonNLP
>>> nlp = BosonNLP('YOUR_API_TOKEN')
>>> nlp.sentiment('这家味道还不错')
[[0.8758192096636473, 0.12418079033635264]]

可以在 BosonNLP 文档站点阅读详细的 BosonNLP HTTP API 文档。

API

class bosonnlp.BosonNLP(token, bosonnlp_url='https://api.bosonnlp.com', compress=True, session=None, timeout=60)[source]

BosonNLP HTTP API 访问的封装类。

Parameters:
  • token (string) – 用于 API 鉴权的 API Token。
  • bosonnlp_url (string) – BosonNLP HTTP API 的 URL,默认为 https://api.bosonnlp.com
  • compress (bool) – 是否压缩大于 10K 的请求体,默认为 True。
  • timeout (int) – HTTP 请求超时时间,默认为 60 秒。
sentiment(contents, model='general')[source]

BosonNLP 情感分析接口 封装。

Parameters:
  • contents (string or sequence of string) – 需要做情感分析的文本或者文本序列。
  • model (string) – 使用不同语料训练的模型,默认使用通用模型。
Returns:

接口返回的结果列表。

Raises:

HTTPError 如果 API 请求发生错误。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.sentiment('这家味道还不错', model='food')
[[0.9991737012037423, 0.0008262987962577828]]
>>> nlp.sentiment(['这家味道还不错', '菜品太少了而且还不新鲜'], model='food')
[[0.9991737012037423, 0.0008262987962577828],
 [9.940036427291687e-08, 0.9999999005996357]]
convert_time(content, basetime=None)[source]

BosonNLP 时间描述转换接口 封装

Parameters:
  • content (string) – 中文时间描述字符串
  • basetime (int or datetime.datetime) – 时间描述的基准时间,传入一个时间戳或datetime
Raises:

HTTPError 如果 API 请求发生错误。

Returns:

接口返回的结果

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> _json_dumps(nlp.convert_time("2013年二月二十八日下午四点三十分二十九秒"))
'{"timestamp": "2013-02-28 16:30:29", "type": "timestamp"}'
>>> import datetime
>>> _json_dumps(nlp.convert_time("今天晚上8点到明天下午3点", datetime.datetime(2015, 9, 1)))
'{"timespan": ["2015-09-02 20:00:00", "2015-09-03 15:00:00"], "type": "timespan_0"}'
classify(contents)[source]

BosonNLP 新闻分类接口 封装。

Parameters:contents (string or sequence of string) – 需要做分类的新闻文本或者文本序列。
Returns:接口返回的结果列表。
Raises:HTTPError 如果 API 请求发生错误。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.classify('俄否决安理会谴责叙军战机空袭阿勒颇平民')
[5]
>>> nlp.classify(['俄否决安理会谴责叙军战机空袭阿勒颇平民',
...               '邓紫棋谈男友林宥嘉:我觉得我比他唱得好',
...               'Facebook收购印度初创公司'])
[5, 4, 8]
suggest(word, top_k=None)[source]

BosonNLP 语义联想接口 封装。

Parameters:
  • word (string) – 需要做语义联想的词。
  • top_k (int) – 默认为 10,最大值可设定为 100。返回的结果条数。
Returns:

接口返回的结果列表。

Raises:

HTTPError 如果 API 请求发生错误。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.suggest('北京', top_k=2)
[[1.0, '北京/ns'], [0.7493540460397998, '上海/ns']]
extract_keywords(text, top_k=None, segmented=False)[source]

BosonNLP 关键词提取接口 封装。

Parameters:
  • text (string) – 需要做关键词提取的文本。
  • top_k (int) – 默认为 100,返回的结果条数。
  • segmented (bool) – 默认为 Falsetext 是否已进行了分词,如果为 True,则不会再对内容进行分词处理。
Returns:

接口返回的结果列表。

Raises:

HTTPError 如果 API 请求发生错误。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.extract_keywords('病毒式媒体网站:让新闻迅速蔓延', top_k=2)
[[0.8391345017584958, '病毒式'], [0.3802418301341705, '蔓延']]
depparser(contents)[source]

BosonNLP 依存文法分析接口 封装。

Parameters:contents (string or sequence of string) – 需要做依存文法分析的文本或者文本序列。
Returns:接口返回的结果列表。
Raises:HTTPError 如果 API 请求发生错误。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.depparser('今天天气好')
[{'head': [2, 2, -1],
  'role': ['TMP', 'SBJ', 'ROOT'],
  'tag': ['NT', 'NN', 'VA'],
  'word': ['今天', '天气', '好']}]
>>> nlp.depparser(['今天天气好', '美好的世界'])
[{'head': [2, 2, -1],
  'role': ['TMP', 'SBJ', 'ROOT'],
  'tag': ['NT', 'NN', 'VA'],
  'word': ['今天', '天气', '好']},
 {'head': [1, 2, -1],
  'role': ['DEC', 'NMOD', 'ROOT'],
  'tag': ['VA', 'DEC', 'NN'],
  'word': ['美好', '的', '世界']}]
ner(contents, sensitivity=None, segmented=False, space_mode='3')[source]

BosonNLP 命名实体识别接口 封装。

Parameters:
  • contents (string or sequence of string) – 需要做命名实体识别的文本或者文本序列。
  • sensitivity (int 默认为 3) – 准确率与召回率之间的平衡, 设置成 1 能找到更多的实体,设置成 5 能以更高的精度寻找实体。
  • segmented (boolean 默认为 False) – 输入是否为分词结果
  • space_mode (int(整型), 0-3有效,默认为 3) – 分词空格保留选项
Returns:

接口返回的结果列表。

Raises:

HTTPError 如果 API 请求发生错误。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.ner('成都商报记者 姚永忠', sensitivity=2)
[{'entity': [[0, 2, 'product_name'],
             [2, 3, 'job_title'],
             [3, 4, 'person_name']],
  'tag': ['ns', 'n', 'n', 'nr'],
  'word': ['成都', '商报', '记者', '姚永忠']}]
>>> nlp.ner(['成都商报记者 姚永忠', '微软XP操作系统今日正式退休'])
[{'entity': [[0, 2, 'product_name'],
             [2, 3, 'job_title'],
             [3, 4, 'person_name']],
  'tag': ['ns', 'n', 'n', 'nr'],
  'word': ['成都', '商报', '记者', '姚永忠']},
 {'entity': [[0, 2, 'product_name'],
             [3, 4, 'time']],
  'tag': ['nz', 'nx', 'nl', 't', 'ad', 'v'],
  'word': ['微软', 'XP', '操作系统', '今日', '正式', '退休']}]
tag(contents, space_mode=0, oov_level=3, t2s=0, special_char_conv=0)[source]

BosonNLP 分词与词性标注 封装。

Parameters:
  • contents (string or sequence of string) – 需要做分词与词性标注的文本或者文本序列。
  • space_mode (int(整型), 0-3有效) – 空格保留选项
  • oov_level (int(整型), 0-4有效) – 枚举强度选项
  • t2s (int(整型), 0-1有效) – 繁简转换选项,繁转简或不转换
  • special_char_conv (int(整型), 0-1有效) – 特殊字符转化选项,针对回车、Tab等特殊字符转化或者不转化
Returns:

接口返回的结果列表。

Raises:

HTTPError 如果 API 请求发生错误。

调用参数及返回值详细说明见:http://docs.bosonnlp.com/tag.html

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> result = nlp.tag('成都商报记者 姚永忠')
>>> _json_dumps(result)
'[{"tag": ["ns", "n", "n", "nr"], "word": ["成都", "商报", "记者", "姚永忠"]}]'
>>> format_tag_result = lambda tagged: ' '.join('%s/%s' % x for x in zip(tagged['word'], tagged['tag']))
>>> result = nlp.tag("成都商报记者 姚永忠")
>>> format_tag_result(result[0])
'成都/ns 商报/n 记者/n 姚永忠/nr'
>>> result = nlp.tag("成都商报记者 姚永忠", space_mode=2)
>>> format_tag_result(result[0])
'成都/ns 商报/n 记者/n  /w 姚永忠/nr'
>>> result = nlp.tag(['亚投行意向创始成员国确定为57个', '“流量贵”频被吐槽'], oov_level=0)
>>> format_tag_result(result[0])
'亚/ns 投/v 行/n 意向/n 创始/vi 成员国/n 确定/v 为/v 57/m 个/q'
>>> format_tag_result(result[1])
'“/wyz 流量/n 贵/a ”/wyy 频/d 被/pbei 吐槽/v'
summary(title, content, word_limit=0.3, not_exceed=False)[source]

BosonNLP 新闻摘要 封装。

Parameters:
  • title (unicode) – 需要做摘要的新闻标题。如果没有标题,请传空字符串。
  • content (unicode) – 需要做摘要的新闻正文。
  • word_limit (float or int) –

    摘要字数限制。 当为 float 时,表示字数为原本的百分比,0.0-1.0有效; 当为 int 时,表示摘要字数。

    Note

    传 1 默认为百分比。

  • not_exceed (bool,默认为 False) – 是否严格限制字数。
Returns:

摘要。

Raises:

HTTPError 当API请求发生错误。

调用参数及返回值详细说明见: http://docs.bosonnlp.com/summary.html

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> content = (
        '腾讯科技讯(刘亚澜)10月22日消息,前优酷土豆技术副总裁'
        '黄冬已于日前正式加盟芒果TV,出任CTO一职。'
        '资料显示,黄冬历任土豆网技术副总裁、优酷土豆集团产品'
        '技术副总裁等职务,曾主持设计、运营过优酷土豆多个'
        '大型高容量产品和系统。'
        '此番加入芒果TV或与芒果TV计划自主研发智能硬件OS有关。')
>>> title = '前优酷土豆技术副总裁黄冬加盟芒果TV任CTO'
>>> nlp.summary(title, content, 0.1)
腾讯科技讯(刘亚澜)10月22日消息,前优酷土豆技术副总裁黄冬已于日前正式加盟芒果TV,出任CTO一职。
cluster(contents, task_id=None, alpha=None, beta=None, timeout=1800)[source]

BosonNLP 文本聚类接口 封装。

Parameters:
  • contents (sequence of string or sequence of (_id, text) or sequence of {'_id': _id, 'text': text}) – 需要做文本聚类的文本序列或者 (_id, text) 序列或者 {‘_id’: _id, ‘text’: text} 序列。如果没有指定 _id,则自动 生成唯一的 _id。
  • task_id (string) – 唯一的 task_id,话题聚类任务的名字,可由字母和数字组成。
  • alpha (float) – 默认为 0.8,聚类最大 cluster 大小
  • beta (float) – 默认为 0.45,聚类平均 cluster 大小
  • timeout (float) – 默认为 1800 秒(30 分钟),等待文本聚类任务完成的秒数。
Returns:

接口返回的结果列表。

Raises:

HTTPError - 如果 API 请求发生错误

TaskError - 任务出错。

TimeoutError - 如果文本聚类任务未能在 timeout 时间内完成。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.cluster(['今天天气好', '今天天气好', '今天天气不错', '点点楼头细雨',
...              '重重江外平湖', '当年戏马会东徐', '今日凄凉南浦'])
[{'_id': 0, 'list': [0, 1], 'num': 2}]
create_cluster_task(contents=None, task_id=None)[source]

创建 ClusterTask 对象。

Parameters:
  • contents (None or sequence of string or sequence of (_id, text) or sequence of {‘_id’: _id, ‘text’: text}) – 需要做典型意见的文本序列或者 (_id, text) 序列或者 {‘_id’: _id, ‘text’: text} 序列。如果没有指定 _id,则自动 生成唯一的 _id。默认为 None
  • task_id (string) – 默认为 None,表示自动生成一个 唯一的 task_id,典型意见任务的名字,可由字母和数字组成。
Raises:
HTTPError - 如果 API 请求发生错误

如果 contents 不为 None,则可能会调用 push 上传文本。

Returns:

ClusterTask 实例。

comments(contents, task_id=None, alpha=None, beta=None, timeout=1800)[source]

BosonNLP 典型意见接口 封装。

Parameters:
  • contents (sequence of string or sequence of (_id, text) or sequence of {'_id': _id, 'text': text}) – 需要做典型意见的文本序列或者 (_id, text) 序列或者 {‘_id’: _id, ‘text’: text} 序列。如果没有指定 _id,则自动 生成唯一的 _id。
  • task_id (string) – 默认为 None,表示自动生成一个 唯一的 task_id,典型意见任务的名字,可由字母和数字组成。
  • alpha (float) – 默认为 0.8,聚类最大 cluster 大小
  • beta (float) – 默认为 0.45,聚类平均 cluster 大小
  • timeout (float) – 默认为 1800 秒(30 分钟),等待典型意见任务完成的秒数。
Returns:

接口返回的结果列表。

Raises:

HTTPError - 如果 API 请求发生错误

TaskError - 任务出错。

TimeoutError - 如果典型意见任务未能在 timeout 时间内完成。

调用示例:

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> nlp.comments(['今天天气好', '今天天气好', '今天天气不错', '点点楼头细雨',
...               '重重江外平湖', '当年戏马会东徐', '今日凄凉南浦'] * 2)
[{'_id': 0, 'list': [['点点楼头', 3], ['点点楼头', 10]],
  'num': 2, 'opinion': '点点楼头'},
 {'_id': 1, 'list': [['重重江外', 4], ['重重江外', 11]],
  'num': 2, 'opinion': '重重江外'},
 {'_id': 2, 'list': [['当年戏马', 5], ['当年戏马', 12]],
  'num': 2, 'opinion': '当年戏马'},
 {'_id': 3, 'list': [['今日凄凉', 6], ['今日凄凉', 13]],
  'num': 2, 'opinion': '今日凄凉'}]
create_comments_task(contents=None, task_id=None)[source]

创建 CommentsTask 对象。

Parameters:
  • contents (None or sequence of string or sequence of (_id, text) or sequence of {‘_id’: _id, ‘text’: text}) – 需要做典型意见的文本序列或者 (_id, text) 序列或者 {‘_id’: _id, ‘text’: text} 序列。如果没有指定 _id,则自动 生成唯一的 _id。默认为 None
  • task_id (string) – 默认为 None,表示自动生成一个 唯一的 task_id,典型意见任务的名字,可由字母和数字组成。
Raises:
HTTPError - 如果 API 请求发生错误

如果 contents 不为 None,则可能会调用 push 上传文本。

Returns:

CommentsTask 实例。

class bosonnlp.ClusterTask(nlp, contents=None, task_id=None)[source]

文本聚类任务封装类。

一般通过 create_cluster_task 创建实例。

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> cluster = nlp.create_cluster_task()

之后可以多次调用 push 上传文本。

>>> cluster.push(['今天天气好', '今天天气好', '今天天气不错', '点点楼头细雨'])
>>> cluster.push(['重重江外平湖'])
>>> cluster.push(['当年戏马会东徐', '今日凄凉南浦'])

然后调用 analysis 启动文本聚类任务。

>>> cluster.analysis()

一般文本聚类任务都用于处理大量的文本,需要比较长的处理时间。可以调用 wait_until_complete 等待任务完成。

>>> cluster.wait_until_complete(2 * 60)  # 最多等待 2 分钟

也可以调用 status 查看任务状态。

>>> cluster.status()
'done'

如果任务成功完成,可以通过 result 获取结果。

>>> cluster.result()
[{'_id': '9e90c56e-f1bb-4605-b995-304af733207a',
  'list': ['9e90c56e-f1bb-4605-b995-304af733207a',
           'a3feff6b-6d1b-4f46-a2d8-0eea25c7f17f'],
  'num': 2}]

获取结果后,可以通过 clear 清空服务器端缓存的文本和结果。

>>> cluster.clear()
True
Parameters:nlpBosonNLP 类实例。 其他参数和 cluster 一致。
analysis(alpha=None, beta=None)

启动分析任务

Parameters:
  • alpha (float) – 默认为 0.8,最大 cluster 大小
  • beta (float) – 默认为 0.45,平均 cluster 大小
Raises:

HTTPError - 如果 API 请求发生错误

clear()

清空服务器端缓存的文本和结果。

Returns:是否成功。
Raises:HTTPError - 如果 API 请求发生错误
push(contents)

批量上传需要进行处理的文本。

Parameters:contents (sequence of string or sequence of (_id, text) or sequence of {'_id': _id, 'text': text}) – 需要处理的的文本序列或者 (_id, text) 序列或者 {‘_id’: _id, ‘text’: text} 序列。如果没有指定 _id,则自动 生成唯一的 _id。
Raises:HTTPError - 如果 API 请求发生错误
result()

返回任务的结果。

Returns:接口返回的结果。
Raises:HTTPError - 如果 API 请求发生错误
status()

获取任务状态。

Returns:

任务状态。

状态 说明
received 成功接收到分析请求
running 数据分析正在进行中
done 分析已完成

Raises:

HTTPError - 如果 API 请求发生错误

TaskNotFoundError - 任务不存在。

TaskError - 任务出错。

wait_until_complete(timeout=None)

等待任务完成。

Parameters:

timeout (float) – 等待任务完成的秒数,默认为 None, 表示不会超时。

Raises:

HTTPError - 如果 API 请求发生错误

TaskNotFoundError - 任务不存在。

TaskError - 任务出错。

TimeoutError - 如果任务未能在 timeout 时间内完成。

class bosonnlp.CommentsTask(nlp, contents=None, task_id=None)[source]

典型意见任务封装类。

一般通过 create_comments_task 创建实例。

>>> import os
>>> nlp = BosonNLP(os.environ['BOSON_API_TOKEN'])
>>> comments = nlp.create_comments_task()

之后可以多次调用 push 上传文本。

>>> comments.push(['今天天气好', '今天天气好', '今天天气不错', '点点楼头细雨'] * 2)
>>> comments.push(['重重江外平湖'] * 2)
>>> comments.push(['当年戏马会东徐', '今日凄凉南浦'] * 2)

然后调用 analysis 启动典型意见任务。

>>> comments.analysis()

一般典型意见任务都用于处理大量的文本,需要比较长的处理时间。可以调用 wait_until_complete 等待任务完成。

>>> comments.wait_until_complete(2 * 60)  # 最多等待 2 分钟

也可以调用 status 查看任务状态。

>>> comments.status()
'done'

如果任务成功完成,可以通过 result 获取结果。

>>> comments.result()
[{'_id': 0,
  'list': [['点点楼头', '19c248e3-605b-4785-8785-ccd2d1b034cc'],
           ['点点楼头', '576d1d08-ff02-4bc5-9edf-fbc7a6915e44']],
  'num': 2,
  'opinion': '点点楼头'},
 {'_id': 2,
  'list': [['重重江外', 'a75e24bd-8597-4865-8254-2e9cab229770'],
           ['重重江外', '47db4d92-6328-45cd-98f8-099691e82c07']],
  'num': 2,
  'opinion': '重重江外'},
 {'_id': 4,
  'list': [['当年戏马', 'da0cd13f-4f13-4476-a541-6214df3b4dd9'],
           ['当年戏马', '89aecf45-4b78-4522-9ed2-ea76ed552f24']],
  'num': 2,
  'opinion': '当年戏马'},
 {'_id': 5,
  'list': [['今日凄凉', 'a5c1f6a9-b6a6-4877-b073-0b59bc67fa48'],
           ['今日凄凉', '9d38ecab-5860-44e9-9e3c-9ad4d4ed3547']],
  'num': 2,
  'opinion': '今日凄凉'}]

获取结果后,可以通过 clear 清空服务器端缓存的文本和结果。

>>> comments.clear()
True
Parameters:nlpBosonNLP 类实例。 其他参数和 comments 一致。
analysis(alpha=None, beta=None)

启动分析任务

Parameters:
  • alpha (float) – 默认为 0.8,最大 cluster 大小
  • beta (float) – 默认为 0.45,平均 cluster 大小
Raises:

HTTPError - 如果 API 请求发生错误

clear()

清空服务器端缓存的文本和结果。

Returns:是否成功。
Raises:HTTPError - 如果 API 请求发生错误
push(contents)

批量上传需要进行处理的文本。

Parameters:contents (sequence of string or sequence of (_id, text) or sequence of {'_id': _id, 'text': text}) – 需要处理的的文本序列或者 (_id, text) 序列或者 {‘_id’: _id, ‘text’: text} 序列。如果没有指定 _id,则自动 生成唯一的 _id。
Raises:HTTPError - 如果 API 请求发生错误
result()

返回任务的结果。

Returns:接口返回的结果。
Raises:HTTPError - 如果 API 请求发生错误
status()

获取任务状态。

Returns:

任务状态。

状态 说明
received 成功接收到分析请求
running 数据分析正在进行中
done 分析已完成

Raises:

HTTPError - 如果 API 请求发生错误

TaskNotFoundError - 任务不存在。

TaskError - 任务出错。

wait_until_complete(timeout=None)

等待任务完成。

Parameters:

timeout (float) – 等待任务完成的秒数,默认为 None, 表示不会超时。

Raises:

HTTPError - 如果 API 请求发生错误

TaskNotFoundError - 任务不存在。

TaskError - 任务出错。

TimeoutError - 如果任务未能在 timeout 时间内完成。

Exceptions

exception bosonnlp.HTTPError(*args, **kwargs)[source]

An HTTP error occurred.

exception bosonnlp.TaskNotFoundError(*args, **kwargs)[source]

任务不存在。

exception bosonnlp.TaskError(*args, **kwargs)[source]

分析任务出错。

exception bosonnlp.TimeoutError[source]

分析任务超时。