为Luminoso客户端API提供的Python绑定

本软件包包含与Luminoso文本处理服务器通过其REST API交互的Python代码。

在此代码中，您不必单独验证每个请求，而是创建一个“会话”对象来跟踪您的登录信息，然后调用它上面的方法，这些方法将被正确验证。

安装

此客户端API旨在与Python 3一起使用。

您可以使用Python包管理器下载和安装它

pip install luminoso-api

或

easy_install luminoso-api

或者，您可以下载此存储库并以常规方式安装它

python setup.py install

如果您在Mac或Unix系统的主Python环境中安装，您可能需要在这些命令前加上sudo，并输入您的密码，例如sudo python setup.py install。

入门

您可以通过LuminosoClient对象与API交互，该对象向以给定路径开始的URL发送HTTP请求，并跟踪您的认证信息。

在您能够连接到API之前，您需要访问网页上的UI并获取一个长期有效的API令牌。（要获取令牌，请转到右上角下拉菜单中的“用户设置”选项，然后点击“API令牌”按钮。）一旦您有了它，您就可以用它来连接到API。

请注意，保存的令牌针对每个域名是特定的（针对daylight.luminoso.com的令牌在本地安装上不会工作，反之亦然）。

from luminoso_api import LuminosoClient
project = LuminosoClient.connect('/projects/my_project_id', token='my_token')

# And then, for instance:
docs = project.get('docs', limit=10)

除了在连接时指定令牌外，您还可以使用LuminosoClient将令牌保存到文件中，此时您无需指定令牌即可连接。（令牌的保存也可以在命令行中完成；请参阅下文“从命令行使用API”）。

from luminoso_api import LuminosoClient
LuminosoClient.save_token('my_token')
project = LuminosoClient.connect('/projects/my_project_id')
docs = project.get('docs', limit=10)

请注意，路径中的所有前导和尾随斜杠都是可选的，因为LuminosoClient确保斜杠被放置在正确的位置。例如，以下所有调用都将发送到端点https://daylight.luminoso.com/api/v5/projects/my_project_id/docs/。

LuminosoClient.connect('/projects/my_project_id').get('docs')
LuminosoClient.connect('projects/my_project_id/').get('/docs')
LuminosoClient.connect('/projects/my_project_id/').get('docs/')
LuminosoClient.connect('projects/my_project_id').get('/docs/')

connect方法还提供了一个可选的超时参数。这将设置底层请求中使用的连接和读取超时。如果设置了此参数，并且请求连接或读取响应超时，则会引发LuminosoTimeoutError异常。

HTTP方法

您可以与之通信的URL在https://daylight.luminoso.com/api/v5/上进行了文档记录。该文档是关于您可以使用API做什么的权威来源，而这段Python代码只是帮助您实现它。

LuminosoClient对象具有.get、.post和.put等方法，它们对应于API使用的相应HTTP方法。例如，.get用于检索信息而不进行更改，.post通常用于创建新事物或执行操作，而.put通常用于更新信息。

示例

大多数时候，您希望LuminosoClient引用特定的项目，但在最初获取项目列表的情况下并不需要。

from luminoso_api import LuminosoClient
client = LuminosoClient.connect()
project_info_list = client.get('/projects/')
print(project_info_list)

处理项目的示例，包括使用便利方法.wait_for_build。

from luminoso_api import LuminosoClient
client = LuminosoClient.connect()

# Create a new project by POSTing its name and language
project_id = client.post('/projects/', name='testproject', language='en')['project_id']

# use that project from here on
project = client.client_for_path('/projects/' + project_id)

docs = [{'title': 'First example', 'text': 'This is an example document.'},
        {'title': 'Second example', 'text': 'Examples are a great source of inspiration.'},
        {'title': 'Third example', 'text': 'Great things come in threes.'}]
project.post('upload', docs=docs)
project.post('build')
project.wait_for_build()

# When the previous call finishes:
response = project.get('concepts')
for concept in response['result']:
    print('%s - %f' % (concept['texts'][0], concept['relevance']))

向量

术语的语义由“向量”对象表示，该API将返回如下不可读的base64编码字符串：

'WAB6AJG6kL_6D_6yAHE__R9kSAE8BlgKMo_80y8cCOCCSN-9oAQcABP_TMAFhAmMCUA'

如果您想查看这些向量并比较它们，请下载我们的库pack64，可通过pip install pack64获取。它将这些转换为NumPy向量，因此需要NumPy。

>>> from pack64 import unpack64
>>> unpack64('WAB6AJG6kL_6D_6y')
array([ 0.00046539,  0.00222015, -0.08491898, -0.0014534 , -0.00127411], dtype=float32)

从命令行使用API

此库包括可以从命令行使用的实验性工具：lumi-save-token、lumi-api、lumi-upload和lumi-download。使用-h运行它们将提供有关可用参数的更详细文档。此外，以下示例可能提供了使用lumi-api访问API的一些指导。

# save a token obtained from the UI - note that you must run this first for the following commands to work!
# (also, this is not a real API token, but yours will look similar)
lumi-save-token gF1XgbExN30O4DfBXse95vCjm6V069Ko

# get a project list
lumi-api -b https://daylight.luminoso.com/api/v5/ get /projects

# get a project list in CSV format
lumi-api -b https://daylight.luminoso.com/api/v5/ get /projects -c

# create a project
lumi-api -b https://daylight.luminoso.com/api/v5/ post /projects/ -p 'name=project name' -p 'language=en'

# upload documents
# my_data.json format: {"docs":[{"text": "..", "title": "..", "metadata": [..]}, {"text": "..", "title": "..", "metadata": [..]}]}
lumi-api -b https://daylight.luminoso.com/api/v5/ post /projects/my_project_id/upload my_data.json

# build project
# this takes time, if you want to be notified via email when the build is done, add -j '{"notify": true}' parameter
lumi-api -b https://daylight.luminoso.com/api/v5/ post /projects/my_project_id/build

# get concepts from project
lumi-api -b https://daylight.luminoso.com/api/v5/ get /projects/my_project_id/concepts

# get project's match counts
lumi-api -b https://daylight.luminoso.com/api/v5/ get /projects/my_project_id/concepts/match_counts

# create a saved concept
lumi-api -b https://daylight.luminoso.com/api/v5/ post /projects/my_project_id/concepts/saved -j '{"concepts": [{"texts": ["My new concept text"]}]}'