Relations

At a glance

The relations model encapsulates algorithms for extracting relations between two entity mentions. For example, in the text:

John Smith drives for Uber.

a relation extraction model may decide that the entities John Smith and Uber are in a relationship with each other, and the relationship type is works for.

Class definitions
watson_nlp.workflows.relations.sire.SIRE
watson_nlp.workflows.relations.transformer.Transformer

SIRE models are feature-based Maximum Entropy models.

The Transformer model uses an IBM-trained multilingual Foundation Model as a base.

For language support, see Supported languages.

Pretrained models

Several pretrained models are available, for common relations types such as worksIn, bornIn from the generic relations type system.

Note that entity models are applicable on top of an Entity Mention extraction model, therefore the type system of the Entity Mention should be compatible. That is, a Relations model trained to identify when Person and Organization mentions are in a relationship will not work when the input does not contain entity mentions of type Person and Organization.

Model ID Container Image
SIRE models
relations_sire-workflow_lang_en_stock cp.icr.io/cp/ai/watson-nlp_relations_sire-workflow_lang_en_stock:1.4.1
Transformer models
relations_transformer-workflow_lang_en_stock cp.icr.io/cp/ai/watson-nlp_relations_transformer-workflow_lang_en_stock:1.4.1
relations_transformer-workflow_lang_multi_distilwatbert cp.icr.io/cp/ai/watson-nlp_relations_transformer-workflow_lang_multi_distilwatbert:1.4.1
relations_transformer-workflow_lang_multi_watbert cp.icr.io/cp/ai/watson-nlp_relations_transformer-workflow_lang_multi_watbert:1.4.1
relations_transformer-workflow_lang_multilingual_slate.153m.distilled cp.icr.io/cp/ai/watson-nlp_relations_transformer-workflow_lang_multilingual_slate.153m.distilled:1.4.1
relations_transformer-workflow_lang_multilingual_slate.270m cp.icr.io/cp/ai/watson-nlp_relations_transformer-workflow_lang_multilingual_slate.270m:1.4.1

The models have been trained and tested on labeled data from news reports.

The Relation models are compatible with the v2 relation type system. For details, see Understanding model type systems.

Running models

The Relations model request accepts the following fields:

Field Type Required
Optional
Repeated
Description
raw_document watson_core_data_model.nlp.RawDocument required The input document on which to perform Relations predictions

Example requests

REST API

curl -s \
  "http://localhost:8080/v1/watson.runtime.nlp.v1/NlpService/RelationsPredict" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "Grpc-Metadata-mm-model-id: relations_transformer-workflow_lang_en_stock" \
  -d '{ "raw_document": { "text": "Joe works at IBM. Arvind Krishna is CEO and President of IBM." } }'

Response

{"relations":[
    {"entity1":{
        "mentions":[
            {"span":{"begin":0, "end":3, "text":"Joe"}, "type":"Person", "producerId":null, "confidence":1, "mentionType":"MENTT_UNSET", "mentionClass":"MENTC_SPC", "role":"Person"}
            ],
        "text":"Joe",
        "type":"Person",
        "confidence":1,
        "relevance":0,
        "disambiguation":null},
     "entity2":{
        "mentions":[
            {"span":{"begin":13, "end":16, "text":"IBM"}, "type":"Organization", "producerId":null, "confidence":1, "mentionType":"MENTT_UNSET", "mentionClass":"MENTC_SPC", "role":"Organization"}, {"span":{"begin":57, "end":60, "text":"IBM"}, "type":"Organization", "producerId":null, "confidence":1, "mentionType":"MENTT_UNSET", "mentionClass":"MENTC_SPC", "role":"Organization"}
            ],
        "text":"IBM",
        "type":"Organization",
        "confidence":0.8826071,
        "relevance":0,
        "disambiguation":null},
 "relationMentions":[{
    "type":"employedBy",
      "mention1":
        {"span":{"begin":0, "end":3, "text":"Joe"}, "type":"Person", "producerId":null, "confidence":1, "mentionType":"MENTT_UNSET", "mentionClass":"MENTC_SPC", "role":"Person"},
      "mention2":
        {"span":{"begin":13, "end":16, "text":"IBM"}, "type":"Organization", "producerId":null, "confidence":1, "mentionType":"MENTT_UNSET", "mentionClass":"MENTC_SPC", "role":"Organization"},
    "confidence":0.9998783,
    "producerId":null,
    "subtype":"None",
    "text":"Joe works at IBM. Arvind Krishna is CEO and President of IBM."}],
    "type":"employedBy",
    "confidence":0.9998783}
    ],
 "producerId":{
   "name":"Transformer Relation Mentions Workflow", "version":"0.0.1"
 }
}

Python

import grpc

from watson_nlp_runtime_client import (
    common_service_pb2,
    common_service_pb2_grpc,
    syntax_types_pb2,
)

channel = grpc.insecure_channel("localhost:8085")

stub = common_service_pb2_grpc.NlpServiceStub(channel)

request = common_service_pb2.RelationsRequest(
    raw_document=syntax_types_pb2.RawDocument(text="Joe works at IBM. Arvind Krishna is CEO and President of IBM."),
)

  response = stub.RelationsPredict(
    request, metadata=[("mm-model-id", "relations_transformer-workflow_lang_en_stock")]
)

print(response)

Response

relations {
  entity1 {
    mentions {
      span {
        end: 3
        text: "Joe"
      }
      type: "Person"
      confidence: 1
      mention_class: MENTC_SPC
      role: "Person"
    }
    text: "Joe"
    type: "Person"
    confidence: 1
  }
  entity2 {
    mentions {
      span {
        begin: 13
        end: 16
        text: "IBM"
      }
      type: "Organization"
      confidence: 1
      mention_class: MENTC_SPC
      role: "Organization"
    }
    mentions {
      span {
        begin: 57
        end: 60
        text: "IBM"
      }
      type: "Organization"
      confidence: 1
      mention_class: MENTC_SPC
      role: "Organization"
    }
    text: "IBM"
    type: "Organization"
    confidence: 0.882607102
  }
  relation_mentions {
    type: "employedBy"
    mention1 {
      span {
        end: 3
        text: "Joe"
      }
      type: "Person"
      confidence: 1
      mention_class: MENTC_SPC
      role: "Person"
    }
    mention2 {
      span {
        begin: 13
        end: 16
        text: "IBM"
      }
      type: "Organization"
      confidence: 1
      mention_class: MENTC_SPC
      role: "Organization"
    }
    confidence: 0.999878287
    subtype: "None"
    text: "Joe works at IBM. Arvind Krishna is CEO and President of IBM."
  }
  type: "employedBy"
  confidence: 0.999878287
}
producer_id {
  name: "Transformer Relation Mentions Workflow"
  version: "0.0.1"
}