분석 API로 온디맨드 데이터 분석하기
분석 API를 사용하면 소스 문서의 데이터를 저장하지 않고도 Discovery 서비스의 보강 파이프라인을 통해 텍스트 문서를 처리할 수 있습니다.
분석 API는 Enterprise 플랜 배포 및 설치형 배포에서만 지원됩니다.
이 접근 방식은 비즈니스 자동화 목적에 이상적입니다. 예를 들어 이메일을 분류하려면 분석 API를 사용하여 Discovery를 동기적으로 호출하여 이메일의 분류를 가져올 수 있습니다. 그런 다음 비즈니스 로직에서 해당 분류의 출력을 사용할 수 있습니다.
분석 API는 JSON 문서만 지원합니다.
API로 문서를 분석할 때는 분석과 연결할 컬렉션을 지정하여 문서 처리 방식을 지정합니다. 문서가 컬렉션에 저장되지 않습니다. 대신 컬렉션의 구성 설정이 문서에 적용됩니다. 예를 들어, 문서에서 엔티티 참조를 찾으려면 Entities 강화 기능이 적용된 컬렉션에 대해 분석 API를 실행하세요. 결과 문서 분석은 문서에 언급된 모든 엔티티를 식별합니다.
필요에 따라 문서를 분석하는 데 사용하려는 강화 기능이 구성된 하나의 컬렉션에 대해서만 분석 요청을 제출하세요. 컬렉션에 있는 문서는 중요하지 않다는 점을 기억하세요. 중요한 것은 컬렉션에 대해 정의된 인텐시티입니다. 여러 컬렉션에 요청을 제출하는 경우 여러 모델이 동시에 시작되어 요청이 실패할 수 있습니다.
분석 API에서는 다음 강화가 지원됩니다.
- 고급 규칙 모델
- 계약
- 사용자 지정 엔티티
- 사전
- 문서 분류기
- 엔티티(NLP)
- 키워드(NLP)
- 기계 학습 및 Watson Explorer Content Analytics Studio 모델
- 정규식
- 패턴(Enterprise 요금제만 해당)
- 문서의 감성
- 표 이해[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를 사용하여 컬렉션 목록에 이름별로 찾고자 하는 컬렉션과 연결된 ID를 찾을 수 있습니다.
컬렉션 ID를 받은 후에는 컬렉션의 구성 설정을 JSON 파일에 적용하기 위해 제출하는 POST 요청에 컬렉션 ID를 포함하세요. 예를 들어, 다음 요청은 키워드 분석을 위해 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 요청과 함께 제출하는 콘텐츠에 적용됩니다:
- 엔티티
- 키워드
- 테이블 이해
요청 예제
요청 본문에는 form-data 이라는 이름의 file 가 포함됩니다. 값은 분석할 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 제한 분석
다음 표는 분석 API의 파일 크기 및 사용량 제한을 보여줍니다.
| 배치 유형 | 파일 크기 제한 | 동시 수집 한도 | 수집 한도당 동시 쿼리 수 |
|---|---|---|---|
| Cloud Pak for Data 설치 배포 | 무제한 | 무제한 | 무제한 |
| 엔터프라이즈 플랜 관리형 배포 | 50 KB | 5 | 5 |
Discovery 카트리지에서 IBM Cloud Pak for Data용 분석 API를 사용하면 라이선스 사용에 영향을 미칩니다. 자세한 내용은 라이센스 정보를 참조하세요.
사용량 모니터링 IBM Cloud Pak for DataIBM Software Hub
API 사용량 페이지에서 애널리틱스 API 사용량을 모니터링할 수 있습니다.
API 사용량 페이지는 설치된 배포에서만 사용할 수 있습니다. Enterprise 요금제의 경우, 분석 메서드 호출 정보는 쿼리 메서드 호출 정보와 결합되어 쿼리 메트릭의 일부로 보고됩니다.
API 사용 페이지 에 액세스하려면 프로젝트 페이지를 열고 데이터 사용량, 그리고 API 사용량을 선택합니다.
- 시작 날짜
- API 호출 모니터링 기간의 시작일입니다.
- 종료 날짜
- API 호출 모니터링 기간의 종료일입니다.
- 30일 통화 총량
- 시작 날짜 및 종료 날짜로 표시된 30일 시간 간격 동안 분석 API를 호출한 횟수입니다. 시간 간격은 API 호출 수가 가장 많은 연속 기간을 계산하여 결정됩니다. 30일 기간은 API 호출 수가 가장 많은 시간 간격으로 업데이트됩니다.
API 사용량은 API 사용량 모니터링이 시작된 후 얼마 동안은 표시되지 않습니다. 표시되는 30일 기간에 현재 날짜가 포함되어 있어도 30일 통화 총계의 최종 총 통화 수가 표시되는 데 지연이 발생할 수 있습니다.
-
테이블 이해도 보강이 결과를 생성하려면 입력에 분석할
<table>HTML 요소가 포함되어 있어야 합니다. ↩︎