개체 연결(NE Linking) API 란?
개체 연결(entity linking) API는 문장 내에서 인식된 개체 멘션(entity mention)을 지식베이스의 개체(entity)와 연결하는 기술입니다. 즉,
멘션이 있는 문장의 컨텍스트 정보에 기반하여 지식베이스 내의 다양한 개체후보들 중,
의미적으로 부합하는 개체를 찾아서 연결하는 개체 의미 분석 기술로 볼 수 있습니다. 멘션 인식과 개체 모호성 해소를 위해서 KorBERT 언어모델을 이용한 토큰분류(token classification) 모델과 이진분류(binary classification) 모델을 개발하였습니다. 또한, 개체 후보의 인기 정보를 이용하여 성능개선을 하였습니다.
API 호출 1일 허용량
| 기술명 | API명 | 1일 허용량 |
|---|---|---|
| 어휘관계 분석 기술 | 개체 연결 API | 5,000건/일 |
알림 사항
1) 개체연결 API는 한글만 처리합니다.
2) 입력된 문장(문단)은 5000 byte 이하로 제한됩니다.
3) 지식베이스는 2021년 07월 한글 위키피디아로 구성되어 있습니다
개체 연결 API 사용하기
개체 연결 API는 REST API는 REST API이며, 다의어 조회의 대상 어휘 데이터를 HTTP 통신으로 ETRI Open API 서버에 전달하면 됩니다. 서버가 제공하는 REST API의 URI는 다음과 같으며 POST 방식으로 호출해야 합니다.
http://epretx.etri.re.kr:8000/api/NELinking
[HTTP Request Header]
"Authorization" : "YOUR_ACCESS_KEY"
[HTTP Request Body]
{
"request_id": "reserved field",
"argument": {
“contents”: "YOUR_PARAGRAPH"
}
위와 같은 HTTP 요청을 e-PreTX 서버로 전달하면 서버는 JSON 형태의
Text 데이터를 HTTP 응답 메시지로 반환합니다. 다음은 HTTP 응답 예제 입니다.
[HTTP Response Header]
Access-Control-Allow-Origin:*
Connection:close
Content-Length:0
Content-Type:application/json; charset=UTF-8
[HTTP Response Body]
{
"request_id": "reserved field",
"result": 0,
"return_type": "com.google.gson.internal.LinkedTreeMap",
"return_object": {개체연결 분석 결과 JSON}
}구현 예제(Python)
python 3.0을 기준으로 작성되었습니다.
HTTP 통신을 위해 urllib3 라이브러리를 사용하여 제공하고 있습니다. Python 3.0 이하의 버전에서
예제를 실행하기 위해서는 별도로 urllib3의 설치가 필요합니다.
설치에 대한 설명은 https://pypi.python.org/pypi/urllib3 를 참고하시기 바랍니다.
설치에 대한 설명은 https://pypi.python.org/pypi/urllib3 를 참고하시기 바랍니다.
urllib3 라이브러리에 대한 자세한 설명은 https://urllib3.readthedocs.io/en/latest/
에서 확인 하실 수 있습니다.
#-*- coding:utf-8 -*-
import urllib3
import json
openApiURL = "http://epretx.etri.re.kr:8000/api/NELinking"
accessKey = "YOUR_ACCESS_KEY"
word = "YOUR_WORD"
requestJson = {
"argument": {
"contents ": contents
}
}
http = urllib3.PoolManager()
response = http.request(
"POST",
openApiURL,
headers={"Content-Type": "application/json; charset=UTF-8","Authorization" : accessKey},
body=json.dumps(requestJson)
)
print("[responseCode]" + str(response.status))
print("[responBody]")
print(str(response.data,"utf-8"))
개체 연결 API 레퍼런스
다음은
파라미터에 대한 설명입니다.
| Field 명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| access_key | String | ○ | API 사용을 위해 ETRI에서 발급한 사용자 API Key |
| argument | Object | ○ | API사용 요청 시 분석을 위해 전달할 내용 |
| contents | String | ○ | 분석할 문단 |
분석된 결과는 다음과 같은 내용이 포함되어 있습니다.
| 구분 | JSON Key 이름 | 설명 |
|---|---|---|
| sent_id | 문장 번호 | |
| sentence | 문장 | |
| t_sentence | 개체연결 ID가 부착된 문장 | |
| mentions | 개체 연결 정보 배열 | |
| mentions | mention | 인식된 멘션 |
| type | 인식된 개체 태그 | |
| article_id | 연결된 위키피디아 타이틀 ID | |
| prediction | 이진분류에서의 예측결과(true이면, 개체연결이 올바른 분류라는 의미) | |
| score | 개체연결에 대한 점수 | |
| url | 위키피디아 연결 URL | |
| definition | 연결 개체의 정의문(위키피디아 첫 문장(단락)) | |
| s_pos | 전체 입력에서 인식된 멘션의 시작 위치 | |
개체 연결 API의 오류 코드 목록은 다음과 같습니다.
| http status code | result | reason | 설명 |
|---|---|---|---|
| 403 | -1 | Empty Auth Header | Authorization 헤더가 없는 경우 |
| 403 | -1 | Invalid Key | KEY
API 키가 없는 경우 |
| 403 |
-1 | Blocked KEY | API
키가 관리자에 의해서 차단된 경우 |
| 403 |
-1 | Daily Limit Exceeded | 일간 호출 제한에 걸린 경우 |
| 403 |
-1 | Monthly
Limit Exceeded |
월간 호출 제한에 걸린 경우 |
| 403 |
-1 | Yearly
Limit Exceeded |
연간 호출 제한에 걸린 경우 |
| 403 |
-1 | Too Many Keys | 같은 IP에서 여러 API 키가 사용된 경우 |
| 403 |
-1 | Too Many IPs | 하나의 API 키를 여러 IP 에서 사용한 경우 |
| 403 |
-1 | Not Allowed IP | API
호출 가능한 IP 가 아닌경우 (API 설정에서 허용된 IP가 아닌경우) |
| 403 |
-1 | Not Allowed Subpath | 하위경로 접근 제한이 되어 있는 경우 |
| 403 | -1 | Invalid
API |
등록되지
않은 API를 요청한 경우 |
| 408 | -1 |
Request
Timeout |
서버의
요청 대기가 시간을 초과한 경우 |
| 413 |
-1 | Body
Size Limit Exceeded |
요청
바디가 설정된 값보다 큰 경우 |
| 429 |
-1 | Concurrent
Limit Exceeded |
연속호출
허용 범위를 넘어서 호출한 경우 |
| 500 | -1 | Internal Server Error | 내부 오류 발생한 경우 |