使用 Analyze API 按需分析数据
使用 Analyze API 通过 Discovery 服务的扩充管道处理文本文档，而不存储来自源文档的任何数据。
分析 API 仅受企业套餐部署和已安装的部署支持。
此方法是用于业务自动化目的的理想方法。 例如，如果要对电子邮件进行分类，那么可以使用 Analyze API 以同步调用 Discovery 来获取电子邮件的分类。 然后，可以在业务逻辑中使用该分类的输出。
“分析”API 仅支持 JSON 文档。
使用 API 分析文档时，通过指定要与分析关联的集合来指示如何处理文档。 文档未存储在集合中。 而是将集合的配置设置应用于文档。 例如，如果要在文档中查找实体引用，请针对应用了 Entities 扩充项的集合运行 Analyze API。 生成的文档分析可识别文档中的任何实体提及项。
仅针对一个配置了要用于按需分析文档的扩充项的集合提交分析请求。 请记住，集合中的文档并不重要。 它是为重要集合定义的扩充项。 如果向多个集合提交请求，那么将同时启动多个模型，这可能会导致请求失败。
“分析”API 支持以下扩充项：
- 高级规则模型
- 合约
- 定制实体
- 字典
- 文档分类器
- 实体(NLP)
- 关键字(NLP)
- 机器学习和 Watson Explorer Content Analytics Studio 模型
- 正则表达式
- 模式 (仅限企业套餐)
- 文档观点
- 表理解[1]
- 文本分类器
如需查看每种语言支持的丰富内容的完整列表，请参阅 语言支持。
有关更多信息，请参阅 Discovery API 参考。
分析示例
您提交用于分析的数据必须采用 JSON 格式。 文本必须指定为字符串; 不能指定为数组。 例如，以下 JSON 文件在要分析以在文本中查找任何关键字提及项的 Quote 字段中包含引号。
{
"Author": "Jane Austen",
"Book": "Pride and Prejudice",
"Quote": "From this day you must be a stranger to one of your parents. Your mother will never see you again if you do not marry Mr. Collins, and I will never see you again if you do.",
"Year": "1813/01/01",
"Subject":"Parental love",
"Speaker": "Mr. Bennett",
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0020"
}
您知道项目中集合的名称，其中 关键字 扩充项配置为应用于集合中的文档。 您可以使用 API 列出集合 来查找与您按名称查找的集合相关联的标识。
获取集合标识后，请将其包含在您提交的 POST 请求中，以将集合中的配置设置应用于 JSON 文件。 例如，以下请求在名为 favorites2.json 的文件中提交 JSON 片段以进行关键字分析。
curl --location --request POST \
'https://my-cloud-pak-for-data-cluster/discovery/zen-wd/instances/{instance-id}/api/v2/ \
projects/{project-id}/collections/{collection-id}/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file=@"/quotations/favorites2.json"'
结果包含在引号中识别的关键字列表。
{
"result": {
"enriched_Quote": [
{
"keywords": [
{
"text": "day",
"mentions": [
{
"text": "day",
"location": {
"begin": 10,
"end": 13
}
}
],
"relevance": 0.673739
},
{
"text": "stranger",
"mentions": [
{
"text": "stranger",
"location": {
"begin": 28,
"end": 36
}
}
],
"relevance": 0.596757
},
{
"text": "parents",
"mentions": [
{
"text": "parents",
"location": {
"begin": 52,
"end": 59
}
}
],
"relevance": 0.568336
},
{
"text": "mother",
"mentions": [
{
"text": "mother",
"location": {
"begin": 66,
"end": 72
}
}
],
"relevance": 0.755562
},
{
"text": "Mr. Collins",
"mentions": [
{
"text": "Mr. Collins",
"location": {
"begin": 118,
"end": 129
}
}
],
"relevance": 0.945891
}
]
}
],
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0020",
"Subject": "Parental love",
"Year": "1813/01/01",
"Book": "Pride and Prejudice",
"Author": "Jane Austen",
"Quote": [
"From this day you must be a stranger to one of your parents. Your mother will never see you again if you do not marry Mr. Collins, and I will never see you again if you do."
],
"metadata": {
"name": "favorites2.json"
},
"Speaker": "Mr. Bennett"
},
"notices": []
}
不能将对象数组作为输入提交。 例如，您可能想要分析多个报价，因此源可能如下所示:
{
"quotations":[
{
"Author": "Jane Austen",
"Book": "Sense and Sensibility",
"Quote": "Is there a felicity in the world superior to this?",
"Year": "1811/01/01",
"Subject": "Nature",
"Speaker": "Marianne Dashwood",
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0059"
},
{
"Author": "Jane Austen",
"Book": "Persuasion",
"Quote": "A man does not recover from such a devotion of the heart to such a woman. He ought not; he does not.",
"Subject": "Romantic love",
"Year": "1818/01/01",
"Speaker": "Captain Wentworth",
"url": "https://www.gutenberg.org/files/105/105-h/105-h.htm#chap20"
}
]
}
如果是这样，请将每个对象拆分为单独的文件，并单独分析每个文件。
分析文本片段
使用如下语法指定 JSON 格式的文本时，可以提交文本以进行分析:
{
"text":"The text that you want to analyze."
}
以下示例请求显示如何分析您在请求中指定的文本，而不是您在物理文件中传递的文本。
curl --location --request POST \
'https://my-cloud-pak-for-data-cluster/discovery/zen-wd/instances/{instance-id}/api/v2/ \
projects/{project-id}/collections/{collection-id}/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file={"text": "ISO 9000 is a standard."}'
响应可能如下所示。
{
"result" : {
"enriched_text" : [ {
"entities" : [ {
"text" : "ISO 9000",
"type" : "my_iso_pattern",
"mentions" : [ {
"text" : "ISO 9000",
"confidence" : 1.0,
"location" : {
"begin" : 0,
"end" : 8
}
} ],
"model_name" : "My ISO Pattern"
}, {
"text" : "9000",
"type" : "Number",
"mentions" : [ {
"text" : "9000",
"confidence" : 0.8,
"location" : {
"begin" : 4,
"end" : 8
}
} ],
"model_name" : "natural_language_understanding"
} ]
} ],
"metadata" : { },
"text" : [ "ISO 9000 is a standard." ]
},
"notices" : [ ]
}
分析 HTML 内容
当您使用如下语法以 JSON 格式提交 HTML 时，可以分析 HTML:
{
"html":"<p>My html content.</p>"
}
以下示例请求显示如何分析您在请求中指定的文本，而不是您在物理文件中传递的文本。
向其发出请求的集合使用以下扩充项，这意味着这些扩充项将应用于您使用 API 请求提交的内容:
- 实体
- 关键字
- 表理解
请求示例
请求主体包含名称为 file 的 form-data。 该值是要分析的 JSON 内容。
curl --location --request POST \
'https://cpd-abc.example.com/discovery/abc-wd/instances/1671204318684041/api/v2/projects/d457fcd9-a4ce-4637-a340-33123b5cbe2c/collections/2d47dbcc-64c7-84e9-0000-01851bb9d998/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file={
"html":"<html><head>This is my html file</head><body><p>My file contains a table.</p><table><tbody><tr><th>Holiday</th><th>Popular greeting</th></tr><tr><td>Christmas</td><td>Merry Christma!s</td></tr></tbody></table></body></html>",
"text":"This is a sentence that contains key words, such as George Washington and Boston, MA."
}'
结果
结果显示已提交的 text 和 html 字段上的“实体”，“关键字”和“表理解”扩充项的输出。
{
"result": {
"text": [
"This is a sentence that contains key words, such as George Washington and Boston, MA."
],
"enriched_text": [
{
"keywords": [
{
"text": "George Washington",
"mentions": [
{
"text": "George Washington",
"location": {
"begin": 52,
"end": 69
}
}
],
"relevance": 0.952591
},
{
"text": "Boston",
"mentions": [
{
"text": "Boston",
"location": {
"begin": 74,
"end": 80
}
}
],
"relevance": 0.578079
},
{
"text": "MA",
"mentions": [
{
"text": "MA",
"location": {
"begin": 82,
"end": 84
}
}
],
"relevance": 0.146905
}
],
"entities": [
{
"text": "George Washington",
"type": "Location",
"mentions": [
{
"text": "George Washington",
"confidence": 0.54922265,
"location": {
"begin": 52,
"end": 69
}
}
],
"model_name": "natural_language_understanding"
},
{
"text": "Boston, MA",
"type": "Location",
"mentions": [
{
"text": "Boston, MA",
"confidence": 0.66049105,
"location": {
"begin": 74,
"end": 84
}
}
],
"model_name": "natural_language_understanding"
}
]
}
],
"metadata": {},
"enriched_html": [
{
"tables": [
{
"body_cells": [
{}
],
"location": {
"begin": 99,
"end": 183
},
"row_headers": [],
"key_value_pairs": [],
"section_title": {},
"contexts": [],
"text": "Holiday Popular greeting Christmas Merry Christmas!",
"table_headers": [],
"title": {},
"column_headers": []
}
]
}
],
"html": [
"<html><head>This is my html file</head><body><p>My file contains a table.</p><table><tbody><tr><th>Holiday</th><th>Popular greeting</th></tr><tr><td>Christmas</td><td>Merry Christmas!</td></tr></tbody></table></body></html>"
]
},
"notices": []
}
分析 API 限制
下表显示了 Analyze API 的文件大小和使用限制。
| 部署类型 | 文件大小限制 | 并发收集限制 | 每个集合的并发查询数限制 |
|---|---|---|---|
| Cloud Pak for Data 已安装部署 | 无限制 | 无限制 | 无限制 |
| 企业计划受管部署 | 50 KB | 5 | 5 |
使用 Discovery Cartridge for IBM Cloud Pak for Data 中的 Analyze API 会影响许可证使用情况。 有关更多信息，请参阅 许可证信息。
监控使用情况 IBM Cloud Pak for DataIBM Software Hub
您可以从“API 使用情况”页面监视 Analyze API 的使用情况。
API 使用情况 页面仅可用于已安装的部署。 对于企业套餐，分析方法调用信息与查询方法调用信息相结合，并作为查询度量值的一部分进行报告。
要访问 API使用页面，请打开项目页面，选择数据使用，然后选择 API使用。
- 开始日期
- API 调用监视时间段的开始日期。
- 结束日期
- API 调用监视时间段的结束日期。
- 30 天呼叫总数
- 在 开始日期 和 结束日期指示的 30 天时间间隔内对 Analyze API 的调用次数。 时间间隔是通过计算API调用次数最多的连续时间段来确定的。 30天窗口更新为API调用次数变化最大的时间间隔。
API使用情况在API使用情况监控开始一段时间后才显示。 显示 30 天呼叫总数 的最终总数时可能会发生延迟，即使列出的 30 天时间段包含当前日期也是如此。
-
要使表了解扩充项以生成任何结果，输入必须包含要分析的
<table>HTML 元素。 ↩︎