WAT

WAT是一個實體連結器，即一種工具，它可以在非結構化英文文字中標識有意義的子字串（稱為“點”），並將每個子字串連結到明確的實體（知識庫中的一項）。 實體是Wikipedia / Wikidata項。 這可用於一系列NLP / NLU問題，例如問題解答，知識庫填充，文字分類等。您可以通過向本頁中記錄的RESTful API發出查詢來註釋文字。 您可以通過查詢此頁面中記錄的API來註釋文字。

WAT不贊成TagME：儘管它目前只能處理英文文件，但它具有類似的執行時效能，但結果更準確（請參閱本文以瞭解詳細資訊）。

引數可以作為URL編碼的引數或作為多部分請求的欄位傳遞到API端點。 所有端點僅處理HTTP GET請求。

Registering to the service

該服務由D4Science基礎架構託管。 要獲得訪問許可權，您需要註冊到TagMe VRE並通過單擊左側皮膚中的“顯示”按鈕來獲取授權令牌。 現在，您已具備向WAT Api發出查詢的所有條件。 例如，您可以將瀏覽器指向：

https://wat.d4science.org/wat/tag/tag?lang=en&gcube-token=XXXX&text=Obama+visited+U.K.+in+March

How to annotate

註釋文字是WAT提供的主要服務。 這就是所謂的Sa2KB問題。 註釋是一對（點，實體），其中“點”是輸入文字的子字串，“實體”是對Wikipedia項的引用，表示該點在該上下文中的含義。

響應包括在輸入文字中找到的所有註釋。 WAT為每個註釋關聯一個稱為ρ（rho）的屬性，該屬性估計註釋中的置信度。 （請注意，ρ並不表示輸入文字中實體的相關性）。 您可以使用ρ值來丟棄低於給定閾值的註釋。 閾值應在間隔[0,1]中選擇。 合理的閾值在0.1到0.3之間。

Parameters

• text - required - the text to be annotated
• gcube-token - required - the D4Science Service Authorization Token.
• lang - optional - The language of the text to be annotated. Currently only en for English is accepted as value.
• tokenizer - 可選-要使用的Tokenizer。 接受的值：opennlp（預設，用於格式正確的文字），lucene（用於非格式正確的文字）。

Advanced optional parameters

• debug-可選-包括除錯資訊。 該值被解釋為多個值的按位或。 每個值都提供特定的除錯資訊：1（文件處理），2（發現的提及），4（管道），8（解歧義模組的解釋）。 例如。 要獲取有關文件處理和管道的除錯資訊，請提供debug = 5。

Python Running Example

這裡有一個用Python寫的玩具示例，用於使用本文中介紹的最佳配置設定來查詢WAT。 只需將這些示例複製並貼上到程式碼中，即可檢視其工作原理！

import json
import requests

MY_GCUBE_TOKEN = 'copy your gcube-token here!'

class WATAnnotation:
    # An entity annotated by WAT

    def __init__(self, d):

        # char offset (included)
        self.start = d['start']
        # char offset (not included)
        self.end = d['end']

        # annotation accuracy
        self.rho = d['rho']
        # spot-entity probability
        self.prior_prob = d['explanation']['prior_explanation']['entity_mention_probability']

        # annotated text
        self.spot = d['spot']

        # Wikpedia entity info
        self.wiki_id = d['id']
        self.wiki_title = d['title']


    def json_dict(self):
        # Simple dictionary representation
        return {'wiki_title': self.wiki_title,
                'wiki_id': self.wiki_id,
                'start': self.start,
                'end': self.end,
                'rho': self.rho,
                'prior_prob': self.prior_prob
                }


def wat_entity_linking(text):
    # Main method, text annotation with WAT entity linking system
    wat_url = 'https://wat.d4science.org/wat/tag/tag'
    payload = [("gcube-token", MY_GCUBE_TOKEN),
               ("text", text),
               ("lang", 'en'),
               ("tokenizer", "nlp4j"),
               ('debug', 9),
               ("method",
                "spotter:includeUserHint=true:includeNamedEntity=true:includeNounPhrase=true,prior:k=50,filter-valid,centroid:rescore=true,topk:k=5,voting:relatedness=lm,ranker:model=0046.model,confidence:model=pruner-wiki.linear")]

    response = requests.get(wat_url, params=payload)
    return [WATAnnotation(a) for a in response.json()['annotations']]


def print_wat_annotations(wat_annotations):
    json_list = [w.json_dict() for w in wat_annotations]
    print json.dumps(json_list, indent=4)


wat_annotations = wat_entity_linking('Barack Obama was in Pisa for a flying visit.')
print_wat_annotations(wat_annotations)

URL Get-Example

• gcube-token=
• text=Schumacher won the race in Indianapolis
• lang=en

https://wat.d4science.org/wat/tag/tag?lang=en&gcube-token=<your Service Authorization Token>&text=Schumacher won the race in Indianapolis

How to compute entity relatedness

該服務通過返回範圍為[0,1]的值來計算兩個實體之間的相關性，該值表示兩個實體在語義上彼此相關的程度，其中0 =不相關，1 =相關。

我們指出，可以通過首先使用TagMe對其進行註釋，然後估計其所有帶註釋實體對之間的成對相關性，來將該服務用於關聯兩個文字。 所有這些值可以某種方式組合（例如avg，max等），以便得出表示兩個輸入文字之間相關性的值。

該端點接受Wikipedia頁面ID的列表，並將返回所有提供的對之間的相關性值。 這意味著它將返回N2個值，其中N是提供的實體數，因此請小心！

Endpoint URL

https://wat.d4science.org/wat/relatedness/graph

Parameters

• lang-可選-要註釋的文字語言。 當前，僅英語的en被接受為值。
• ids-必需，重複-實體的Wikipedia ID（數字識別符號）。
• relatedness -可選-相關性函式進行計算。 接受的值包括：mw（Milne-Witten），jaccard（頁面出站的Jaccard度量），lm（語言模型），w2v（Word2Vect），條件概率（條件概率），barabasialbert（維基百科圖上的Barabasi-Albert），pmi（ 點向互惠資訊）。

Example

計算兩個實體巴拉克·奧巴馬（Wikipedia ID 534366）和巴拉克·奧巴馬（Barack Obama）總統職位（Wikipedia ID 20082093）之間的相關性：

• gcube-token=
• ids=534366
• ids=20082093

這對應於GET請求：

https://wat.d4science.org/wat/tag/tag?gcube-token=<your Service Authorization Token>&ids=534366&ids=20082093

如何獲取表面形式資訊

表面形式是可能提及實體的文字部分。 WAT提供了兩個端點來檢索表面形式的資訊，例如它可能引用的實體，在Wikipedia中被檢視過多少次，作為連結出現過多少次等等。這兩個端點具有相同的引數。 第一個端點提供有關表面形式頻率的資訊，而第二個端點也提供有關其可能引用的實體的資訊。

Endpoint URL - frequency information

https://wat.d4science.org/wat/sf/frequency

Endpoint URL - full information

https://wat.d4science.org/wat/sf/sf

Parameters

• lang - optional - The language of the text to be annotated. Currently only en for English is accepted as value.
• text - required - The surface form.

Example

Get information about the surface form obama:

• gcube-token=
• text=obama

This corresponds to the GET request:

https://wat.d4science.org/wat/sf/sf?gcube-token=<your Service Authorization Token>&text=obama

對響應中最重要欄位的簡要說明：

• link_probability：該表面形式在Wikipedia頁面中作為連結相對於普通文字出現的次數的比率。
• term_frequency：此表面形式在所有Wikipedia頁面中出現的次數。
• term_probability：此表面形式在所有Wikipedia頁面中相對於所有其他表面形式的出現率。
• document_frequency：不同的Wikipedia頁數包含此表面形式。
• entities：對於每個實體，此表面形式在Wikipedia中指向Wikipedia的頁面：
• wiki_id：維基百科頁面ID
• num_links：此表面形式指向此Wikipedia頁面的次數
• probability：此表面形式指向此Wikipedia頁面（相對於其他頁面）的次數的比率。

Wikipedia Title resolution

為了將Wikipedia頁面標題解析為其ID，WAT提供了以下API。

API Endpoint

https://wat.d4science.org/wat/title

Parameters

• lang - optional - The language of the text to be annotated. Currently only en for English is accepted as value.
• title - required - The Wikipedia page title.

Example

Get the ID of page Barack Obama:

• gcube-token=
• title=Barack_Obama

This corresponds to the GET request:

https://wat.d4science.org/wat/title?title=Barack_Obama

進階使用：部分填入資料的註解

本文件中描述的第一個API端點負責解析文字，搜尋文字以查詢可能的提及以及最終將它們連結到它們所引用的實體的整個流程。 WAT還提供了一個API端點來跳過某些步驟，方法是讓使用者提供已解析的文字或指出提到實體的表面形式（D2KB問題）。 在這種情況下，文件必須作為Json物件傳遞。

API Endpoint

https://wat.d4science.org/wat/tag/json

Parameters

• document-必需-表示要註釋文字的JSON物件。 該物件具有以下鍵值對：
  • “text”-必需-要處理的文件
  • “sentences”-可選-一個由Stanford CoreNLP解析器返回的格式的陣列。
  • “ spans”-可選-要註釋的跨度（D2KB問題），以及具有“開始”和“結束”欄位的物件陣列，即跨度的第一個（包括）和最後一個（不包括）字元的索引
    -gcube-token-必需-D4Science服務授權令牌。
    -lang-可選-要註釋的文字語言。 當前，僅英語的en被接受為值。
    -tokenizer-可選-使用的Tokenizer。 接受的值：opennlp（預設，用於格式正確的文字），lucene（用於非格式正確的文字）。

示例：提供解析的句子

手動建立對此端點的請求並不方便，主要是因為JSON必須經過URL編碼。 這是一個Python指令碼，該指令碼發出一個提供已解析文字的呼叫：

import json
import requests

document_json = json.loads("""{
  "text": "Barack Obama was in Pisa.",
  "sentences": [{
      "tokens": [
        { "position": { "start": 0, "end": 6 },
          "ner": { "type": "PERSON", "label": "Inside" },
          "id": 0,
          "word": { "word": "Barack" }
        }, {
          "position": { "start": 7, "end": 12 },
          "ner": { "type": "PERSON", "label": "Inside" },
          "id": 1,
          "word": { "word": "Obama" }
        }, {
          "position": { "start": 13, "end": 16 },
          "ner": { "type": "O", "label": "Outside" },
          "id": 2,
          "word": { "word": "was" }
        }, {
          "position": {"start": 17, "end": 19},
          "ner": {"type": "O", "label": "Outside"},
          "id": 3,
          "word": { "word": "in" }
        }, {
          "position": { "start": 20, "end": 24 },
          "ner": { "type": "LOCATION", "label": "Inside" },
          "id": 4,
          "word": { "word": "Pisa" }
        }, {
          "position": { "start": 24,  "end": 25 },
          "ner": { "type": "O",  "label": "Outside" },
          "id": 5,
          "word": { "word": "." }
        }
      ],
      "position": { "start": 0,  "end": 25 },
      "id": 0
    }]
}""")

r = requests.get('https://wat.d4science.org/wat/tag/json', params={"document": json.dumps(document_json)})

print r.text

示例：提供提及以消除歧義（D2KB問題）

您可以通過新增“ suggested_spans”鍵來請求WAT註釋特定範圍。

import json
import requests

document_json = json.loads("""{

  "text": "Barack Obama was in Pisa.",
  "suggested_spans": [
    { "start":0, "end":6 },
    { "start":20, "end":24 }
  ]
}""")

r = requests.get('https://wat.d4science.org/wat/tag/json', params={"document": json.dumps(document_json)})

print r.text

學分和參考

要了解有關WAT功能的更多資訊，請檢視這篇論文發表在ERD 2014和Francesco Piccinno的博士學位論文中。

SWAT API Documentation

特警是一種實體顯著性系統，可實時識別由文件的顯著維基百科實體表達的文件的語義焦點。 該技術的核心是基於廣泛的句法和語義特徵，這些語義和特徵從輸入文件中提取，然後饋送到分類器中，該分類器以前接受過從《紐約時報帶註釋的語料庫》中提取的數百萬個訓練示例的訓練。 可通過https://swat.d4science.org/獲得該系統的實驗GUI。

註冊服務

該服務由D4Science基礎架構託管。 要獲得訪問許可權，您需要註冊到TagMe VRE並通過單擊左側皮膚中的“顯示”按鈕來獲取授權令牌。 在對API的每次請求中，您都必須將此身份驗證令牌作為gcube-token URL引數發出。

如何在文件中獲得實體顯著性

您可以通過以下網址通過HTTP POST請求呼叫Swat的API來使用它：

https://swat.d4science.org/salience

該端點接受一個JSON物件作為輸入（將其放入POST請求的有效負載中）並返回一個JSON物件。 輸入物件必須/可以具有以下鍵值對

Key	Description	Type
content	The textual content of the input document (required)	string
title	The document’s title (optional)	string

A Python example

這是查詢SWAT的Python程式碼的一部分：

import json
import requests

MY_GCUBE_TOKEN = 'copy your gcube-token here!'

document = {
    "title": "Obama travels.",
    "content": 'Barack Obama was in Pisa for a flying visit.'
}

url = 'https://swat.d4science.org/salience'
response = requests.post(url,
                         data=json.dumps(document),
                         params={'gcube-token': MY_GCUBE_TOKEN})

print(json.dumps(response.json(), indent=4))

回應格式

響應將是具有以下結構的JSON物件：

{
    'status'                        # str

    'annotations':
       {
           'wiki_id'                # int
           'wiki_title'             # str
           'salience_class'         # int
           'salience_score'         # float
           'spans':                 # (where the entity is mentioned in content)
                [
                    {
                        'start'     # int (character-offset, included)
                        'end'       # int (character-offset, not included)
                    }
                ]
       }

    'title'                         # str
    'content'                       # str
}

學分和參考

要了解有關SWAT功能的更多資訊，請查閱Marco Ponza，Paolo Ferragina和Francesco Piccinno撰寫的論文SWAT：一種用於檢測文字中顯著的維基百科實體的系統。