├── .DS_Store ├── images ├── ToneAnalyzerRequest.png └── ToneAnalyzerResponse.png ├── overriding-language-detection.md ├── relations.md ├── landing.json ├── activity-tracker-events.md ├── ha-dr.md ├── toc.yaml ├── detectable-languages.md ├── additional-resources.md ├── customizing.md ├── usage-limits.md ├── information-security.md ├── custom-ent-rel.md ├── troubleshooting.md ├── relations-v2.md ├── tone-analytics.md ├── versioning.md ├── analyzing-webpages.md ├── pricing.md ├── entity-types.md ├── getting-started.md ├── index.md ├── custom-categories.md ├── custom-class.md ├── sample-apps.md ├── relations-v1.md ├── language-support.md ├── entity-types-v2.md ├── entity-types-v1.md └── migrate-to-watson-nlp.md /.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ibm-cloud-docs/natural-language-understanding/HEAD/.DS_Store -------------------------------------------------------------------------------- /images/ToneAnalyzerRequest.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ibm-cloud-docs/natural-language-understanding/HEAD/images/ToneAnalyzerRequest.png -------------------------------------------------------------------------------- /images/ToneAnalyzerResponse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ibm-cloud-docs/natural-language-understanding/HEAD/images/ToneAnalyzerResponse.png -------------------------------------------------------------------------------- /overriding-language-detection.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-02-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:note: .note} 16 | {:codeblock: .codeblock} 17 | {:screen: .screen} 18 | {:javascript: .ph data-hd-programlang='javascript'} 19 | {:java: .ph data-hd-programlang='java'} 20 | {:python: .ph data-hd-programlang='python'} 21 | {:swift: .ph data-hd-programlang='swift'} 22 | 23 | # Overriding language detection 24 | {: #overriding-language-detection} 25 | 26 | To override automatic language detection in `/analyze` requests, specify a language code in the `language` attribute of the `parameters` JSON object. 27 | 28 | __Example _parameters.json_ file__ 29 | 30 | ```json 31 | { 32 | "text": "...X, Y, Z, now I know my A, B, Cs", 33 | "features": { 34 | "semantic_roles": {} 35 | }, 36 | "language": "en" 37 | } 38 | ``` 39 | {: codeblock} 40 | 41 | __Example curl request__ 42 | 43 | ```bash 44 | curl --user "apikey:{apikey}" \ 45 | "{url}/v1/analyze?version=2018-09-21" \ 46 | --request POST \ 47 | --header "Content-Type: application/json" \ 48 | --data @parameters.json 49 | 50 | ``` 51 | {: pre} 52 | -------------------------------------------------------------------------------- /relations.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-02-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Relation type systems 23 | {: #relation-type-systems} 24 | 25 | The relation type system that {{site.data.keyword.nlushort}} uses differs depending on which language you are using. This page describes which relation type system is used for each language. 26 | {: shortdesc} 27 | 28 | For example, analyzing relations in German text will use the [Version 2 relation type system][v2]. 29 | 30 | |Language|Relation type system| 31 | | --- | ---| 32 | | Arabic | [Version 1][v1] | 33 | | English | [Version 1][v1] | 34 | | French | [Version 2][v2] | 35 | | German | [Version 2][v2] | 36 | | Italian | [Version 2][v2] | 37 | | Japanese | [Version 2][v2] | 38 | | Korean | [Version 1][v1] | 39 | | Portuguese | [Version 2][v2] | 40 | | Spanish | [Version 1][v1] | 41 | 42 | 43 | [v1]: /docs/natural-language-understanding?topic=natural-language-understanding-relation-types-version-1 44 | [v2]: /docs/natural-language-understanding?topic=natural-language-understanding-relation-types-version-2 45 | -------------------------------------------------------------------------------- /landing.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 2, 3 | "title": "IBM Watson® Natural Language Understanding", 4 | "introduction": "This documentation describes the usage of Natural Languge Understanding for IBM Cloud as a Service.", 5 | "product_page": "https://www.ibm.com/products/natural-language-understanding", 6 | "console_page": "/catalog/services/natural-language-understanding", 7 | "section_topics": { 8 | "links": [ 9 | { 10 | "title": "Getting started with Natural Language Understanding", 11 | "href": "/docs/natural-language-understanding?topic=natural-language-understanding-getting-started" 12 | }, 13 | { 14 | "title": "Analyzing webpages", 15 | "href": "/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages" 16 | }, 17 | { 18 | "title": "Customizing models", 19 | "href": "/docs/natural-language-understanding?topic=natural-language-understanding-customizing" 20 | }, 21 | { 22 | "title": "Activity Tracker events for Natural Language Understanding", 23 | "href": "/docs/natural-language-understanding?topic=natural-language-understanding-at_events" 24 | }, 25 | { 26 | "title": "Language support", 27 | "href": "/docs/natural-language-understanding?topic=natural-language-understanding-language-support" 28 | } 29 | ] 30 | }, 31 | "section_highlights": [ 32 | { 33 | "title": "Stack Overflow", 34 | "description": "To discuss questions with developers", 35 | "href": "https://stackoverflow.com/questions/tagged/watson-nlu", 36 | "type": "blog" 37 | } 38 | ], 39 | "section_devtools": { 40 | "api": "/apidocs/natural-language-understanding" 41 | }, 42 | "section_updates": { 43 | "view_more": "/docs/natural-language-understanding?topic=natural-language-understanding-release-notes" 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /activity-tracker-events.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2016, 2020 5 | lastupdated: "2020-06-08" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:codeblock: .codeblock} 14 | {:pre: .pre} 15 | {:screen: .screen} 16 | {:note: .note} 17 | {:important: .important} 18 | {:tip: .tip} 19 | {:download: .download} 20 | {:table: .aria-labeledby="caption"} 21 | 22 | # Activity Tracker events for Natural Language Understanding 23 | {: #at_events} 24 | 25 | You can use the {{site.data.keyword.cloudaccesstrailfull}} service to track how users and applications interact with {{site.data.keyword.nlushort}} in {{site.data.keyword.cloud}}. 26 | {: shortdesc} 27 | 28 | {{site.data.keyword.at_full_notm}} records user-initiated activities that change the state of a service in {{site.data.keyword.cloud_notm}}. You can use this service to investigate abnormal activity and critical actions and to comply with regulatory audit requirements. In addition, you can be alerted about actions as they happen. The events that are collected comply with the Cloud Auditing Data Federation (CADF) standard. For more information, see the [getting started tutorial for {{site.data.keyword.at_full_notm}}](/docs/Activity-Tracker-with-LogDNA?topic=Activity-Tracker-with-LogDNA-getting-started#getting-started). 29 | 30 | ## List of events 31 | {: #list-of-events} 32 | 33 | | Action | Description | 34 | |:-----------------|:-----------------| 35 | | `natural-language-understanding.model.create` | Create a model | 36 | | `natural-language-understanding.model.delete` | Delete a model | 37 | {: caption="Actions that generate events" caption-side="top"} 38 | 39 | ## Viewing events 40 | {: #viewing-events} 41 | 42 | Events that are generated by an instance of the {{site.data.keyword.nlushort}} service are automatically forwarded to the {{site.data.keyword.at_full_notm}} service instance that is available in the same location. 43 | 44 | {{site.data.keyword.at_full_notm}} can have only one instance per location. To view events, you must access the web UI of the {{site.data.keyword.at_full_notm}} service in the same location where your service instance is available. For more information, see [Launching the web UI through the IBM Cloud UI](/docs/Activity-Tracker-with-LogDNA?topic=Activity-Tracker-with-LogDNA-launch#launch_step2). 45 | -------------------------------------------------------------------------------- /ha-dr.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2019, 2021 5 | lastupdated: "2021-09-30" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:new_window: target="_blank"} 12 | {:shortdesc: .shortdesc} 13 | {:screen: .screen} 14 | {:pre: .pre} 15 | {:table: .aria-labeledby="caption"} 16 | {:codeblock: .codeblock} 17 | {:tip: .tip} 18 | {:download: .download} 19 | 20 | # High availability and disaster recovery 21 | {: #ha-dr} 22 | 23 | {{site.data.keyword.nlufull}} is highly available within multiple {{site.data.keyword.cloud_notm}} locations (for example, Dallas and Washington, DC). However, recovering from potential disasters that affect an entire location requires planning and preparation. 24 | {: shortdesc} 25 | 26 | You are responsible for understanding your configuration, customization, and usage of the service. You are also responsible for being ready to re-create an instance of the service in a new location and to restore your data in any location. See [How do I ensure zero downtime? ![External link icon](../../icons/launch-glyph.svg "External link icon")](/docs/overview?topic=overview-zero-downtime#zero-downtime){: new_window} for more information. 27 | 28 | ## High availability 29 | {: #high-availability} 30 | 31 | {{site.data.keyword.nlushort}} supports high availability with no single point of failure. The service achieves high availability automatically and transparently by using the multi-zone region (MZR) feature provided by {{site.data.keyword.cloud_notm}}. 32 | 33 | {{site.data.keyword.cloud_notm}} enables multiple zones that do not share a single point of failure within a single location. It also provides automatic load balancing across the zones within a region. 34 | 35 | ## Disaster recovery 36 | {: #disaster-recovery} 37 | 38 | In the event of a catastrophic failure in a region, complete the following steps. 39 | 40 | - Create a new {{site.data.keyword.nlushort}} service instance. 41 | - Adjust your application software to use the new service instance URL and credentials. 42 | - If you use {{site.data.keyword.nlushort}} with {{site.data.keyword.knowledgestudioshort}} custom models, you will need to redeploy your custom models to the new service instance. See [Backing up and restoring data](/docs/watson-knowledge-studio?topic=watson-knowledge-studio-backup-restore#restoremodels) to learn how to backup and restore {{site.data.keyword.knowledgestudioshort}} data. 43 | -------------------------------------------------------------------------------- /toc.yaml: -------------------------------------------------------------------------------- 1 | toc: 2 | properties: 3 | subcollection: natural-language-understanding 4 | service-name: natural-language-understanding 5 | version: 2 6 | category: ai 7 | audience: service 8 | href: /docs/natural-language-understanding 9 | console-page: /catalog/services/natural-language-understanding 10 | product-page: https://www.ibm.com/cloud/watson-natural-language-understanding/ 11 | path: natural-language-understanding 12 | label: Natural Language Understanding 13 | entries: 14 | - navgroup: 15 | id: learn 16 | topics: 17 | - getting-started.md 18 | - index.md 19 | - additional-resources.md 20 | - topic: release-notes.md 21 | navtitle: Release notes 22 | - navgroup: 23 | id: howto 24 | topics: 25 | - analyzing-webpages.md 26 | - topicgroup: 27 | label: Customizing 28 | topics: 29 | - customizing.md 30 | - custom-ent-rel.md 31 | - custom-categories.md 32 | - custom-class.md 33 | - overriding-language-detection.md 34 | - include: /watson/watson-keyservice.md 35 | - include: /watson/watson-public-private-endpoints.md 36 | - include: migrate-to-watson-nlp.md 37 | - navgroup: 38 | id: reference 39 | topics: 40 | - link: 41 | label: API reference 42 | href: https://cloud.ibm.com/apidocs/natural-language-understanding 43 | - activity-tracker-events.md 44 | - topicgroup: 45 | label: Categories type system 46 | topics: 47 | - categories-v2.md 48 | - categories-v1.md 49 | - detectable-languages.md 50 | - topicgroup: 51 | label: Entity types 52 | topics: 53 | - entity-types.md 54 | - entity-types-v1.md 55 | - entity-types-v2.md 56 | - language-support.md 57 | - topicgroup: 58 | label: Relation types 59 | topics: 60 | - relations.md 61 | - relations-v1.md 62 | - relations-v2.md 63 | - tone-analytics.md 64 | - sample-apps.md 65 | - usage-limits.md 66 | - versioning.md 67 | - ha-dr.md 68 | - information-security.md 69 | - include: /watson/watson-using-sdks.md 70 | - link: 71 | label: Watson GitHub repos 72 | href: https://github.com/watson-developer-cloud/ 73 | - navgroup: 74 | id: help 75 | topics: 76 | - troubleshooting.md 77 | - pricing.md 78 | - topicgroup: 79 | label: Developer community 80 | links: 81 | - link: 82 | label: StackOverflow 83 | href: https://stackoverflow.com/questions/tagged/watson-nlu -------------------------------------------------------------------------------- /detectable-languages.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-02-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Detectable languages 23 | {: #detectable-languages} 24 | 25 | When you analyze text or a web page, Natural Language Understanding detects the source language automatically and returns the corresponding ISO 639-1 code in the response. For automatic language detection to work best, it is recommended that you use text with at least 100 characters. 26 | {: shortdesc} 27 | 28 | If automatic language detection isn't working well for your use case, you can [manually specify the language of your content](/docs/natural-language-understanding?topic=natural-language-understanding-overriding-language-detection) in each request. 29 | {: tip} 30 | 31 | The following table lists the detectable languages and corresponding ISO 639-1 codes. 32 | 33 | |Language |ISO 639-1 code| 34 | |------------|------| 35 | |Afrikaans|af| 36 | |Albanian|sq| 37 | |Amharic|am| 38 | |Arabic|ar| 39 | |Armenian|hy| 40 | |Azerbaijani|az| 41 | |Basque|eu| 42 | |Belarusian|be| 43 | |Bengali|bn| 44 | |Bihari|bh| 45 | |Bulgarian|bg| 46 | |Catalan|ca| 47 | |Chinese|zh| 48 | |Croatian|hr| 49 | |Czech|cs| 50 | |Danish|da| 51 | |Dhivehi|dv| 52 | |Dutch|nl| 53 | |English|en| 54 | |Estonian|et| 55 | |Fijian|fj| 56 | |Finnish|fi| 57 | |French|fr| 58 | |Galician|gl| 59 | |Ganda|lg| 60 | |Georgian|ka| 61 | |German|de| 62 | |Greek|el| 63 | |Gujarati|gu| 64 | |Haitian Creole|ht| 65 | |Hebrew|he| 66 | |Hindi|hi| 67 | |Hungarian|hu| 68 | |Icelandic|is| 69 | |Indonesian|id| 70 | |Inuktitut|iu| 71 | |Irish|ga| 72 | |Italian|it| 73 | |Javanese|jv| 74 | |Japanese|ja| 75 | |Kannada|kn| 76 | |Khmer|km| 77 | |Kinyarwanda|rw| 78 | |Kirghiz|ky| 79 | |Korean|ko| 80 | |Latin|la| 81 | |Laothian|lo| 82 | |Latvian|lv| 83 | |Lithuanian|lt| 84 | |Macedonian|mk| 85 | |Malay|ms| 86 | |Malayalam|ml| 87 | |Maltese|mt| 88 | |Maori|mi| 89 | |Marathi|mr| 90 | |Nepali|ne| 91 | |Norwegian|no| 92 | |Oriya|or| 93 | |Persian|fa| 94 | |Polish|pl| 95 | |Portuguese|pt| 96 | |Punjabi|pa| 97 | |Pashto|ps| 98 | |Romanian|ro| 99 | |Russian|ru| 100 | |Scots Gaelic|gd| 101 | |Serbian|sr| 102 | |Shona|sn| 103 | |Sinhalese|si| 104 | |Slovak|sk| 105 | |Slovenian|sl| 106 | |Spanish|es| 107 | |Swahili|sw| 108 | |Swedish|sv| 109 | |Tagalog|tl| 110 | |Tamil|ta| 111 | |Telugu|te| 112 | |Thai|th| 113 | |Turkish|tr| 114 | |Ukrainian|uk| 115 | |Urdu|ur| 116 | |Vietnamese|vi| 117 | |Welsh|cy| 118 | |Wolof|wo| 119 | |Xhosa|xh| 120 | |Yiddish|Yi| 121 | -------------------------------------------------------------------------------- /additional-resources.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-02-28" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Additional resources 23 | {: #additional-resources} 24 | 25 | ## Features at-a-glance 26 | {: at-a-glance} 27 | 28 | - [Custom categories (Beta)](https://github.com/watson-developer-cloud/doc-tutorial-downloads/blob/master/natural-language-understanding/Explainers/Custom%20Categories%20One%20Pager-2023.pdf): Learn how the custom categories feature works, and best practices for training your model. 29 | 30 | ## Case studies 31 | {: #case-studies} 32 | 33 | | | | | 34 | |--- |--- |--- | 35 | | Content Recommendation | Course Hero | Understand user preferences and recommend videos based on their interests | 36 | | Advertising Optimization | [BuzzRadar](https://www.ibm.com/case-studies/buzz-radar-cloud-marketing-performance-optimization) | Optimizing campaigns for clients through instant insight into consumers, influencers, brand health and more | 37 | | | [Equals3](https://www.ibm.com/watson/stories/equals-3/?cm_mmc=OSocial_Twitter-_-Watson+Core_Watson+Core+-+Platform-_-WW_WW-_-Watson+Equals+3+Twitter+May+2018&cm_mmca1=000000OF&cm_mmca2=10000408&) | Understanding natural language queries and building profiles according to user specifications, inputs, and other data | 38 | | | [Influential](https://www.ibm.com/case-studies/influential) | Amplifying marketing messages by influencers throughout social media campaigns | 39 | | Voice-of-Customer Analysis | [Guardio](https://www.ibm.com/case-studies/guardio-cloud-bullying-detection-application) | Helping parents protect children from cyberbullying by flagging and detecting certain messages across social media accounts | 40 | | Data Mining | [Bradesco](https://www.ibm.com/watson/stories/bradesco/) | Addressing and resolving customer conversations at scale through a trained virtual assistant | 41 | | | [Legalmation](https://www.ibm.com/case-studies/legalmation) | Detecting citizens' civic concerns with 97% accuracy using IBM Watson | 42 | | | Accrete | Delivering highly accurate insight into financial markets with artificial intelligence | 43 | 44 | ## Blogs 45 | {: #blogs} 46 | 47 | - [How to find new football stars with AI technology](https://www.ibm.com/blogs/client-voices/how-find-new-football-stars-ai/) 48 | - [Buzz Radar Cognitive Command Center makes insights actionable with IBM Watson](https://www.ibm.com/blogs/cloud-computing/2018/05/31/cognitive-command-center-buzz-radar-ibm-watson/) 49 | - [Train Better with NLU Classifications](https://medium.com/ibm-data-ai/train-better-with-nlu-classifications-bd4070173e4) 50 | -------------------------------------------------------------------------------- /customizing.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-08-02" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:tip: .tip} 14 | {:note: .note} 15 | {:beta: .beta} 16 | {:pre: .pre} 17 | {:important: .important} 18 | {:codeblock: .codeblock} 19 | {:screen: .screen} 20 | {:javascript: .ph data-hd-programlang='javascript'} 21 | {:java: .ph data-hd-programlang='java'} 22 | {:python: .ph data-hd-programlang='python'} 23 | {:swift: .ph data-hd-programlang='swift'} 24 | 25 | # Overview - Customizing models 26 | {: #customizing} 27 | 28 | You can extend {{site.data.keyword.nlushort}} with custom models for supported feature and language combinations. 29 | {: shortdesc} 30 | 31 | ## Before you begin 32 | {: #customizing-before-you-begin} 33 | 34 | 1. If you haven't done so already, [get started](/docs/natural-language-understanding?topic=natural-language-understanding-getting-started) with {{site.data.keyword.nlushort}}. 35 | 1. Check [Language support for custom models](#language-support-for-custom-models) to make sure that the custom model you want to create is supported. 36 | 1. Follow the customization instructions for one of the following features. 37 | - [Entities and relations](/docs/natural-language-understanding?topic=natural-language-understanding-entities-and-relations) 38 | - [Categories (Beta)](/docs/natural-language-understanding?topic=natural-language-understanding-categories) 39 | - [Classifications](/docs/natural-language-understanding?topic=natural-language-understanding-classifications) 40 | 41 | ## Language support for custom models 42 | {: #language-support-for-custom-models} 43 | 44 | Check the *Custom model support* columns in the tables on the [Language support](/docs/natural-language-understanding?topic=natural-language-understanding-language-support) page to see the features that support custom models for each language. 45 | 46 | ## Specifying training parameters for custom models 47 | {: #training-for-custom-models} 48 | 49 | As part of the request to create or update a custom model, you may optionally include a training parameters object that specifies attributes of the model. For details, see feature-specific [Classifications training parameters](/docs/natural-language-understanding?topic=natural-language-understanding-classifications#classification-training-parameters). 50 | 51 | ## Targeted sentiment for custom model entities 52 | {: #targeted-sentiment-for-custom-entities} 53 | 54 | For English only, you can get sentiment scores for each custom model entity that is detected by the service by setting the `sentiment: true` option in the entities object. No other languages support targeted sentiment for custom model entities. 55 | 56 | ## Usage restrictions for custom models 57 | {: #usage-restrictions-for-custom-models} 58 | 59 | The maximum number of models that can be trained via the {{site.data.keyword.nlushort}} customization API in parallel is 3. 60 | -------------------------------------------------------------------------------- /usage-limits.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-08-05" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Usage limits 23 | {: #usage-limits} 24 | 25 | The following usage limits and restrictions apply to {{site.data.keyword.nlushort}} service instances. 26 | {: shortdesc} 27 | 28 | ## Analyzed text limit 29 | {: #analyzed-text} 30 | 31 | {{site.data.keyword.nlushort}} truncates analyzed text that contains more than 50,000 single-byte or multibyte characters. To view the text that counts toward this limit in your requests, set the `return_analyzed_text` parameter to `true`. 32 | 33 | You can set a smaller character limit with the `limit_text_characters` parameter. If you are interested in analyzing only a small portion of your content, this can help you avoid excessive costs. 34 | 35 | Example parameters object: 36 | ```json 37 | { 38 | "url": "ibm.com", 39 | "limit_text_characters": 10000, 40 | "return_analyzed_text": true, 41 | "features": { 42 | "concepts": {} 43 | } 44 | } 45 | ``` 46 | 47 | ## Request limit 48 | {: #concurrent-requests} 49 | 50 | Each {{site.data.keyword.nlushort}} service instance is limited, based on the number of analyze requests being processed. For the Lite plan, the limit is 5 analyze requests per second; for the Standard plan, the limit is 150 analyze requests per second. Analyze requests exceeding these limits may receive a `429: Too Many Requests` error. 51 | 52 | The limit for the Standard plan can be increased by [opening a support ticket](https://ibm.biz/ibmcloudsupport). 53 | 54 | All other requests are rate-limited at 5 requests per second. 55 | 56 | ## Custom model training limit 57 | {: custom-model-training-limit} 58 | 59 | The maximum number of models that can be trained via the {{site.data.keyword.nlushort}} customization API in parallel is 3. 60 | 61 | ## Custom model size limit for Lite pricing plans 62 | {: #custom-models} 63 | 64 | There is a size limit for {{site.data.keyword.knowledgestudioshort}} custom models that are deployed to {{site.data.keyword.nlushort}} service instances on Lite pricing plans. To remove the custom model size limit, upgrade your {{site.data.keyword.nlushort}} service instance to a paid pricing plan. You can find your service instances on the {{site.data.keyword.cloud_notm}} [resources page](https://{DomainName}/resources). 65 | 66 | ## Language support 67 | {: #usage-language-support} 68 | 69 | Different language restrictions apply depending on how you use the service. For details, see the [Language support](/docs/natural-language-understanding?topic=natural-language-understanding-language-support) page. 70 | 71 | 72 | -------------------------------------------------------------------------------- /information-security.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-04-19" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | {:note: .note} 22 | 23 | # Information security 24 | {: #information-security} 25 | 26 | IBM is committed to providing our clients and partners with innovative data privacy, security and governance solutions. 27 | {: shortdesc} 28 | 29 | **Notice:** 30 | Clients are responsible for ensuring their own compliance with various laws and regulations, including the European Union General Data Protection Regulation. Clients are solely responsible for obtaining advice of competent legal counsel as to the identification and interpretation of any relevant laws and regulations that may affect the clients’ business and any actions the clients may need to take to comply with such laws and regulations. 31 | 32 | The products, services, and other capabilities described herein are not suitable for all client situations and may have restricted availability. IBM does not provide legal, accounting or auditing advice or represent or warrant that its services or products will ensure that clients are in compliance with any law or regulation. 33 | 34 | If you need to request GDPR support for {{site.data.keyword.cloud}} {{site.data.keyword.watson}} resources that are created 35 | 36 | - In the European Union (EU), see [Requesting support for IBM Cloud Watson resources created in the European Union](/docs/watson?topic=watson-gdpr-sar#request-EU). 37 | - Outside of the EU, see [Requesting support for resources outside the European Union](/docs/watson/?topic=watson-gdpr-sar#request-non-EU). 38 | 39 | ## European Union General Data Protection Regulation (GDPR) 40 | {: #gdpr} 41 | 42 | IBM is committed to providing our clients and partners with innovative data privacy, security and governance solutions to assist them on their journey to GDPR compliance. 43 | 44 | Learn more about IBM's own GDPR readiness journey and our GDPR capabilities and offerings to support your compliance journey [here ![External link icon](../../icons/launch-glyph.svg "External link icon")](../../icons/launch-glyph.svg "External link icon")](http://www.ibm.com/gdpr){: new_window}. 45 | 46 | ## Labeling and deleting data in Natural Language Understanding 47 | {: #gdpr-in-service} 48 | 49 | Users should not input any sensitive or personal information when using customization features. Beta releases may not be compatible with legislation such as GDPR. 50 | {: note} 51 | 52 | The {{site.data.keyword.nlushort}} service processes but does not store users’ data. Users of the {{site.data.keyword.nlushort}} service do not need to take any action to identify, protect, or delete their data. 53 | -------------------------------------------------------------------------------- /custom-ent-rel.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2021 5 | lastupdated: "2021-02-12" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:tip: .tip} 14 | {:note: .note} 15 | {:beta: .beta} 16 | {:pre: .pre} 17 | {:important: .important} 18 | {:codeblock: .codeblock} 19 | {:screen: .screen} 20 | {:javascript: .ph data-hd-programlang='javascript'} 21 | {:java: .ph data-hd-programlang='java'} 22 | {:python: .ph data-hd-programlang='python'} 23 | {:swift: .ph data-hd-programlang='swift'} 24 | 25 | # Creating custom entities and relations models 26 | {: #entities-and-relations} 27 | 28 | The {{site.data.keyword.nlushort}} Free plan limits the size and performance of your custom model. To test a custom model to its full extent, use it with the {{site.data.keyword.nlushort}} Standard plan. 29 | {: shortdesc} 30 | 31 | 1. [Get started with {{site.data.keyword.knowledgestudioshort}}](/docs/watson-knowledge-studio?topic=watson-knowledge-studio-wks_tutintro#wks_tutintro). 32 | 1. Create a custom model. 33 | 1. To create a custom entities and relations model, see [Creating a machine learning model](/docs/watson-knowledge-studio?topic=watson-knowledge-studio-wks_tutml_intro) 34 | 1. You can also create a custom entities model with a rule-based model. See [Creating a rule-based model](/docs/watson-knowledge-studio?topic=watson-knowledge-studio-wks_tutrule_intro) for details. 35 | 1. [Deploy your model to {{site.data.keyword.nlushort}}](/docs/watson-knowledge-studio?topic=watson-knowledge-studio-publish-ml#wks_manlu) 36 | 1. To use your model, specify the `model` that you deployed in the [entities](https://{DomainName}/apidocs/natural-language-understanding#entities){: external} or [relations](https://{DomainName}/apidocs/natural-language-understanding#relations){: external} options of your API request: 37 | 38 | - Example *parameters.json* file: 39 | 40 | ```json 41 | { 42 | "url": "www.url.example", 43 | "features": { 44 | "entities": { 45 | "model": "your-model-id-here" 46 | }, 47 | "relations": { 48 | "model": "your-model-id-here" 49 | } 50 | } 51 | } 52 | ``` 53 | 54 | - Example curl request: 55 | 56 | ```bash 57 | curl --user "apikey":"{apikey}" \ 58 | "{url}/v1/analyze?version={date}" \ 59 | --request POST \ 60 | --header "Content-Type: application/json" \ 61 | --data @parameters.json 62 | ``` 63 | 64 | ## Deleting custom entities and relations models 65 | {: #deleting-a-custom-model} 66 | 67 | To delete an entities or relations model from your service instance, use the **Delete model** method. Replace `{url}` and `{apikey}` with your service URL and API key, and replace `{model_id}` with the model ID of the model you want to delete. 68 | 69 | - The following example undeploys an entities or relations model. 70 | 71 | ```bash 72 | curl --user "apikey":"{apikey}" "{url}/v1/models/{model_id}?version={date}" 73 | --request DELETE 74 | ``` 75 | -------------------------------------------------------------------------------- /troubleshooting.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2023 5 | lastupdated: "2023-03-10" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | content-type: troubleshoot 10 | 11 | --- 12 | 13 | {:tsSymptoms: .tsSymptoms} 14 | {:tsCauses: .tsCauses} 15 | {:tsResolve: .tsResolve} 16 | {:shortdesc: .shortdesc} 17 | {:new_window: target="_blank"} 18 | {:tip: .tip} 19 | {:pre: .pre} 20 | {:codeblock: .codeblock} 21 | {:screen: .screen} 22 | {:javascript: .ph data-hd-programlang='javascript'} 23 | {:java: .ph data-hd-programlang='java'} 24 | {:python: .ph data-hd-programlang='python'} 25 | {:swift: .ph data-hd-programlang='swift'} 26 | {:download: .download} 27 | {:troubleshoot: data-hd-content-type='troubleshoot'} 28 | 29 | # Troubleshooting 30 | {: #troubleshoot} 31 | 32 | If you have problems with {{site.data.keyword.nlushort}}, the following troubleshooting tips might help. 33 | {: shortdesc} 34 | 35 | ## Entities and relations entity types are not consistent 36 | {: #inconsistent-entity-types} 37 | {: troubleshoot} 38 | 39 | The entity type systems for the entities and relations features are not always consistent. For some languages and version dates, relations results will contain entity types that are different from the entity types that appear in entities results. See [Entity types and subtypes](/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems) and [Relation types](/docs/natural-language-understanding?topic=natural-language-understanding-relation-type-systems) for more details. 40 | 41 | ## Incorrect language detection 42 | {: #incorrect-language-detection} 43 | {: troubleshoot} 44 | 45 | The automatic language detection might not be accurate for text that contains fewer than 100 characters. If the service doesn't detect the correct language of your text, you can [override automatic language detection](/docs/natural-language-understanding?topic=natural-language-understanding-overriding-language-detection). 46 | 47 | ## Too many requests 48 | {: #too-many-requests} 49 | {: troubleshoot} 50 | 51 | If you are seeing a "429: Too many requests" error, your service instance is likely hitting the concurrent requests limit. View the [Usage limits](/docs/natural-language-understanding?topic=natural-language-understanding-usage-limits#concurrent-requests) page for more information. 52 | 53 | ## Unable to analyze more than one URL 54 | {: #multiple-webpages} 55 | {: troubleshoot} 56 | 57 | You can specify only one publicly accessible URL in your API request, therefore you cannot extract sentiment scoring from several URLs. You could, however, compile the text from multiple web pages and then pass that entire compiled text for sentiment analysis. 58 | 59 | ## Unexpected results from webpage analysis 60 | {: #unexpected-webpage-results} 61 | {: troubleshoot} 62 | 63 | Analyzing a webpage might return unexpected results in some cases. To investigate, try setting the **return_analyzed_text** parameter to `true` to inspect the actual text that is being analyzed in your request. In cases where [webpage cleaning](/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#webpage-cleaning) does not remove enough unwanted text, consider using the [**xpath**](/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#xpath) parameter to focus the analysis on specific elements of the page. 64 | 65 | ## Explanations for particular results 66 | {: #explanations-for-results} 67 | {: troubleshoot} 68 | 69 | {{site.data.keyword.nlushort}} does not provide any diagnostic tools to explain why a particular request returns a particular result. The service is designed to provide accurate results for as many text samples as possible, but due to the nature of the machine learning models we use, there is no guarantee that any particular result will look correct from a human perspective. 70 | 71 | ## Unexpected changes in response and confidence scores 72 | {: #continuous-model-improvement} 73 | {: troubleshoot} 74 | NLU continuously updates pretrained models and the training algorithms powering custom models to give customers better results. These updates may include differences in overall response and confidence scores. NLU is agnostic to individual use cases and makes these updates to models for the sole purpose of better accuracy and better performance for all customers. 75 | 76 | See Section 5.1.2 regarding continuous model updates in our [Terms of Service](https://www.ibm.com/support/customer/csol/terms/?id=i128-0025&lc=en#detail-document). 77 | -------------------------------------------------------------------------------- /relations-v2.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-02-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Relation types (Version 2) 23 | {: #relation-types-version-2} 24 | 25 | The following table lists the relation types returned by the _Version 2_ relation type system. The relation type system that {{site.data.keyword.nlushort}} uses differs based on which language you are using. For more details, see the [Relation type systems](/docs/natural-language-understanding?topic=natural-language-understanding-relation-type-systems) page. 26 | {: shortdesc} 27 | 28 | The entity types used by this relation type system are listed on the [Entity types (Version 2)](/docs/natural-language-understanding?topic=natural-language-understanding-entity-types-version-2) page. 29 | 30 | | Relation | Description | 31 | |-----------------|----------------| 32 | | affiliatedWith | Exists between two entities that have an affiliation or are similarly connected. | 33 | | basedIn | Exists between an Organization and the place where it is mainly, only, or intrinsically located. | 34 | | bornAt | Exists between a Person and the place where they were born. | 35 | | bornOn | Exists between a Person and the Date or Time when they were born. | 36 | | clientOf | Exists between two entities when one is a direct business client of the other (that is, pays for certain services or products). | 37 | | colleague | Exists between two Persons who are part of the same Organization. | 38 | | competitor | Exists between two Organizations that are engaged in economic competition. | 39 | | contactOf | Relates contact information with an entity. | 40 | | diedAt | Exists between a Person and the place at which he, she, or it died. | 41 | | diedOn | Exists between a Person and the Date or Time on which he, she, or it died. | 42 | | dissolvedOn | Exists between an Organization or URL and the Date or Time when it was dissolved. | 43 | | educatedAt | Exists between a Person and the Organization at which he or she is or was educated.| 44 | | employedBy | Exists between two entities when one pays the other for certain work or services; monetary reward must be involved. In many circumstances, marking this relation requires world knowledge. | 45 | | foundedOn | Exists between an Organization or URL and the Date or Time on which it was founded. | 46 | | founderOf | Exists between a Person and a Facility, Organization, or URL that they founded. | 47 | | locatedAt | Exists between an entity and its location. | 48 | | managerOf | Exists between a Person and another entity such as a Person or Organization that he or she manages as his or her job. | 49 | | memberOf | Exists between an entity, such as a Person or Organization, and another entity to which he, she, or it belongs. | 50 | | ownerOf | Exists between an entity, such as a Person or Organization, and an entity that he, she, or it owns. The owner does not need to have permanent ownership of the entity for the relation to exist. | 51 | | parentOf | Exists between a Person and their children or stepchildren. | 52 | | partner | Exists between two Organizations that are engaged in economic cooperation. | 53 | | partOf | Exists between a smaller and a larger entity of the same type or related types in which the second entity subsumes the first. If the entities are both events, the first must occur within the time span of the second for the relation to be recognized. | 54 | | partOfMany | Exists between smaller and larger entities of the same type or related types in which the second entity, which must be plural, includes the first, which can be singular or plural. | 55 | | populationOf | Exists between a place and the number of people located there, or an organization and the number of members or employees it has. | 56 | | measureOf | This relation indicates the quantity of an entity or measure (height, weight, etc) of an entity. | 57 | | relative | Exists between two Persons who are relatives. To identify parents, children, siblings, and spouses, use the `parentOf`, `siblingOf`, and `spouseOf` relations. | 58 | | residesIn | Exists between a Person and a place where they live or previously lived. | 59 | | shareholdersOf | Exists between a Person or Organization, and an Organization of which the first entity is a shareholder. | 60 | | siblingOf | Exists between a Person and their sibling or stepsibling. | 61 | | spokespersonFor | Exists between a Person and an Facility, Organization, or Person that he or she represents. | 62 | | spouseOf | Exists between two Persons that are spouses. | 63 | | subsidiaryOf | Exists between two Organizations when the first is a subsidiary of the second. | 64 | -------------------------------------------------------------------------------- /tone-analytics.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2021 5 | lastupdated: "2021-12-09" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:tip: .tip} 14 | {:note: .note} 15 | {:beta: .beta} 16 | {:pre: .pre} 17 | {:important: .important} 18 | {:codeblock: .codeblock} 19 | {:screen: .screen} 20 | {:javascript: .ph data-hd-programlang='javascript'} 21 | {:java: .ph data-hd-programlang='java'} 22 | {:python: .ph data-hd-programlang='python'} 23 | {:swift: .ph data-hd-programlang='swift'} 24 | 25 | # Tone analytics (Classifications) 26 | {: #tone_analytics} 27 | 28 | Tone analytics is currently available for English and French languages only, as indicated in the [language support](/docs/natural-language-understanding?topic=natural-language-understanding-language-support) topic. 29 | {: important} 30 | 31 | Tone analysis is done by using a pre-built classifications model, which provides an easy way to detect language tones in written text. It detects seven tones: `sad`, `frustrated`, `satisfied`, `excited`, `polite`, `impolite`, and `sympathetic`. 32 | 33 | ## Analyzing tone 34 | {: #analyzing-tone} 35 | 36 | To detect tone, use the language-specific classifications model ID in your API request. 37 | 38 | The language-specific tone model ID is formatted as `tone-classifications-xx-v1`, where `xx` is a two-character language code. Languages available include: 39 | 40 | | Language | Code | 41 | | --- | --- | 42 | | English | `en` | 43 | | French | `fr` | 44 | 45 | - Example *parameters.json* file: 46 | 47 | ```json 48 | { 49 | "language": "en", 50 | "text": "This is example text in English.", 51 | "features": { 52 | "classifications": { 53 | "model": "tone-classifications-en-v1" 54 | } 55 | } 56 | } 57 | ``` 58 | 59 | - Example cURL request: 60 | 61 | ```bash 62 | curl --request POST \ 63 | --header "Content-Type: application/json" \ 64 | --user "apikey":"{apikey}" \ 65 | "{url}/v1/analyze?version=2021-08-01" \ 66 | --data @parameters.json 67 | ``` 68 | 69 | ### Understanding tone analytics 70 | {: #understanding-tone-analytics} 71 | 72 | The model returns scores for the following tones: 73 | 74 | | Tone | Description | 75 | | --- | --- | 76 | | `excited` | Showing personal enthusiasm and interest | 77 | | `frustrated` | Feeling annoyed and irritable | 78 | | `impolite` | Being disrespectful and rude | 79 | | `polite` | Displaying rational, goal-oriented behavior | 80 | | `sad` | An unpleasant passive emotion | 81 | | `satisfied` | An affective response to perceived service quality | 82 | | `sympathetic` | An affective mode of understanding that involves emotional resonance | 83 | 84 | - Example response: 85 | 86 | ```json 87 | { 88 | "usage": { 89 | "text_units": 1, 90 | "text_characters": 60, 91 | "features": 1 92 | }, 93 | "language": "en", 94 | "classifications": [ 95 | { 96 | "confidence": 0.564849, 97 | "class_name": "excited" 98 | }, 99 | { 100 | "confidence": 0.355816, 101 | "class_name": "satisfied" 102 | }, 103 | { 104 | "confidence": 0.126127, 105 | "class_name": "polite" 106 | }, 107 | { 108 | "confidence": 0.026995, 109 | "class_name": "sympathetic" 110 | }, 111 | { 112 | "confidence": 0.012211, 113 | "class_name": "frustrated" 114 | }, 115 | { 116 | "confidence": 0.011065, 117 | "class_name": "sad" 118 | }, 119 | { 120 | "confidence": 0.000872, 121 | "class_name": "impolite" 122 | } 123 | ] 124 | } 125 | ``` 126 | 127 | ## Migrating from Watson Tone Analyzer Customer Engagement endpoint to {{site.data.keyword.nlushort}} 128 | {: #migrating-watson-tone-analyzer} 129 | 130 | You can migrate your [Watson Tone Analyzer customer-engagement](/docs/tone-analyzer?topic=tone-analyzer-utco) analysis requests to {{site.data.keyword.nlushort}}. This can help you better understand your interactions with customers and improve your communications generally, or for specific customers. 131 | 132 | ### Reformatting your input data 133 | 134 | In Watson Tone Analyzer, you pass the `/v3/tone_chat` method a JSON `ToneChatInput` object consisting of `utterances`, `text`, and an optional `user` string fields. For {{site.data.keyword.nlushort}}, you pass a JSON object that contains `text` to be analyzed, and a language-specific `model` classification ID, to the `/v1/analyze` method. 135 | 136 | ![Tone Analyzer request mapping to NLU](images/ToneAnalyzerRequest.png). 137 | 138 | ### Understanding your response content 139 | 140 | In Watson Tone Analyzer, the service returns a JSON `UtteranceAnalyses` object that contains a single field, `utterances_tone`, which contains an array of `UtteranceAnalysis` objects, including `score` and `tone_id`. For {{site.data.keyword.nlushort}}, a `classifications` field is returned, containing `confidence` and `class_name` objects that correspond to the Watson Tone Analyzer `score` and `tone_id` objects. 141 | 142 | ![Tone Analyzer response mapping to NLU](images/ToneAnalyzerResponse.png). 143 | -------------------------------------------------------------------------------- /versioning.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2019, 2022 5 | lastupdated: "2022-08-10" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Versioning 23 | {: #versioning} 24 | 25 | **Current API version**: 2022-08-10 26 | 27 | API requests require a version parameter that takes the date in the format `version=YYYY-MM-DD`. Send the version parameter with every API request. 28 | 29 | When we change the API in a backwards-incompatible way, we release a new minor version. To take advantage of the changes in a new version, change the value of the version parameter to the new date. If you're not ready to update to that version, don't change your version date. 30 | 31 | ## Deprecation schedule for version dates 32 | {: #deprecation-schedule-for-version-dates} 33 | 34 | When a new version date is released, the previous version date will enter a deprecation period lasting one year. You will have one year to migrate your code to support a version that is not deprecated before API requests that use the retired version are automatically switched over to the latest version available. 35 | 36 | The following timeline provides examples of what might happen during the deprecation schedule for the `2019-06-04` version. 37 | 38 | - The `2019-07-12` version date is released. This begins a deprecation period for the previous `2019-06-04` version date that lasts one year. 39 | - The deprecated version date is still available to use during the deprecation period. 40 | - A new version date is released during the deprecation period, such as `2020-05-10`. 41 | - On July 12, 2020, the deprecation period for the `2019-06-04` version date ends and the version date is retired. 42 | - API requests that still use the `2019-06-04` version date after July 12, 2020 are automatically changed to use the behavior of the latest version date available. For this example, the latest version available is `2020-05-10`. 43 | 44 | ## Version dates 45 | {: #version-dates} 46 | 47 | The following table shows the service behavior changes for each version date. Switching to a later version date will activate all changes introduced in earlier versions. 48 | 49 | |Version date|Changes summary|Retirement date| 50 | |---|---|---| 51 | |[`2022-08-10`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-aug1022)|
  • Language expansion of entities with a new model for improved accuracy and confidence scores.
  • Version 2 Russian entity type system.
  • Version 2 Swedish entity type system.
    • | 52 | |[`2022-04-07`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-apr0722)|
  • Bug fix for Version 2 Categories type system.
    • | 53 | |[`2020-12-09`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-dec0920)|
  • Version 2 English entity type system.
    • | 54 | |[`2020-12-02`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-dec0220)|
  • Version 2 Korean entity type system.
  • Version 2 Spanish entity type system.
    • | 55 | |[`2020-08-01`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-aug0120)|
  • Taxonomy changes aimed towards standardization of the label names in the default taxonomy.
    • | 56 | |[`2019-07-12`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-jul1219)
    Deprecated|
  • New English entities model with improved accuracy and confidence scores.
    • |August 1, 2021| 57 | |[`2019-06-04`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-jun0419)
    Deprecated|
  • Fixed a bug that caused entities requests with custom models to ignore the `limit` option.
  • The default `limit` value for all entities requests is now 50 for all models.
  • The maximum `limit` value of 250 entities has been removed.
    • |July 12, 2020| 58 | |[`2018-11-16`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-nov1618)
    Deprecated|
  • Version 2 Italian entity type system.
    • |July 12, 2020| 59 | |[`2018-09-21`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-sep2118)
    Deprecated|
  • Version 2 Portuguese entity type system.
    • |July 12, 2020| 60 | |[`2018-03-16`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-mar1618)
    Deprecated|
  • Version 2 French entity type system.
  • Version 2 German entity type system.
    • |July 12, 2020| 61 | |[`2017-02-27`](/docs/natural-language-understanding?topic=natural-language-understanding-release-notes#natural-language-understanding-feb2717)
    Deprecated| Base version.|July 12, 2020| 62 | -------------------------------------------------------------------------------- /analyzing-webpages.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-06-20" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:deprecated: .deprecated} 14 | {:important: .important} 15 | {:note: .note} 16 | {:tip: .tip} 17 | {:preview: .preview} 18 | {:beta: .beta} 19 | {:pre: .pre} 20 | {:codeblock: .codeblock} 21 | {:screen: .screen} 22 | {:shortdesc: .shortdesc} 23 | {:javascript: .ph data-hd-programlang='javascript'} 24 | {:java: .ph data-hd-programlang='java'} 25 | {:python: .ph data-hd-programlang='python'} 26 | {:swift: .ph data-hd-programlang='swift'} 27 | {:download: .download} 28 | 29 | 30 | # Analyzing webpages 31 | {: #analyzing-webpages} 32 | 33 | {{site.data.keyword.nlushort}} enables you to analyze text from webpages programmatically. When you provide raw HTML or a publicly accessible URL in your API request, the service attempts to focus the analysis on the main content of the page, such as the text from a news article or blog post. 34 | 35 | **How it works:** 36 | 37 | 1. Specify a publicly accessible URL with the **url** parameter, or send raw HTML in the **html** parameter. 38 | 2. By default, the service [cleans](#webpage-cleaning) the webpage to remove generally unwanted text such as advertisements. 39 | 3. If you specify an [XPath query](#xpath) with the **xpath** parameter, the service uses the query to select specific elements of the page to include in the analysis. If **clean** is set to `false` when you use **xpath**, only the result of the XPath query will be analyzed. 40 | 41 | ## Webpage cleaning 42 | {: #webpage-cleaning} 43 | 44 | By default, the service "cleans" webpages before they are analyzed. Webpage cleaning attempts to remove generally unwanted content such as advertisements and other text that might interfere with analyzing the main content of the page. 45 | 46 | To disable webpage cleaning, set the **clean** parameter to `false`. The following example disables webpage cleaning. 47 | 48 | ```sh 49 | curl -X POST -u "apikey:{apikey}" \ 50 | --header "Content-Type: application/json" \ 51 | --data "{ 52 | \"url\": \"http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver\", 53 | \"features\": { 54 | \"concepts\": {} 55 | }, 56 | \"return_analyzed_text\": true, 57 | \"clean\": false 58 | }" \ 59 | "{url}/v1/analyze?version=2018-09-21" 60 | ``` 61 | {: pre} 62 | 63 | ## Analyzing specific elements of a webpage with XPath 64 | {: #xpath} 65 | 66 | The **xpath** parameter enables you to use an XPath query to analyze specific parts of a webpage. To learn more about XPath, check out the following resources. 67 | 68 | - [W3Schools XPath tutorial](https://www.w3schools.com/xml/xpath_intro.asp){: external} 69 | - [XPath on Wikipedia](https://wikipedia.org/wiki/XPath){: external} 70 | 71 | The behavior of the **xpath** parameter depends on the value of the **clean** parameter: 72 | 73 | - **clean** = `true` (default): Results of the XPath query will be appended to the cleaned webpage text before the combined text is analyzed. 74 | - **clean** = `false`: Only the results of the XPath query will be analyzed. 75 | 76 | ### Including text from specific elements in the analysis 77 | {: #analyze-cleaned-and-xpath} 78 | 79 | By default, the **clean** parameter is set to `true`, and results of an XPath query are appended to the cleaned webpage text after a newline character before the combined text is analyzed. This can be useful if you want to include elements in the analysis that would otherwise be removed by webpage cleaning. The following example uses the **xpath** parameter to include the title and subtitle of the example webpage in the analysis. 80 | 81 | **Example `parameters.json` file** 82 | 83 | ```json 84 | { 85 | "url": "http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver", 86 | "features": { 87 | "concepts": {} 88 | }, 89 | "return_analyzed_text": true, 90 | "xpath": "//div[@class='wd_title wd_language_left' or @class='wd_subtitle wd_language_left']" 91 | } 92 | ``` 93 | {: codeblock} 94 | 95 | **Example request** 96 | 97 | ```sh 98 | curl -X POST -u "apikey:{apikey}" \ 99 | --header "Content-Type: application/json" \ 100 | --data @parameters.json \ 101 | "{url}/v1/analyze?version=2018-09-21" 102 | ``` 103 | {: pre} 104 | 105 | ### Analyzing text from specific elements only 106 | {: #analyze-xpath-results-only} 107 | 108 | To analyze only the result of an XPath query, use the **xpath** parameter and set the **clean** parameter to `false`. The following example analyzes only the title and subtitle of the example webpage. 109 | 110 | **Example `parameters.json` file** 111 | 112 | ```json 113 | { 114 | "url": "http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver", 115 | "features": { 116 | "concepts": {} 117 | }, 118 | "return_analyzed_text": true, 119 | "xpath": "//div[@class='wd_title wd_language_left' or @class='wd_subtitle wd_language_left']", 120 | "clean": false 121 | } 122 | ``` 123 | {: codeblock} 124 | 125 | **Example request** 126 | 127 | ```sh 128 | curl -X POST -u "apikey:{apikey}" \ 129 | --header "Content-Type: application/json" \ 130 | --data @parameters.json \ 131 | "{url}/v1/analyze?version=2018-09-21" 132 | ``` 133 | {: pre} 134 | -------------------------------------------------------------------------------- /pricing.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2021 5 | lastupdated: "2021-07-28" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Pricing 23 | {: #pricing} 24 | 25 | {{site.data.keyword.nlushort}} has two pricing plans: Lite and Standard. 26 | 27 | This page contains pricing information in USD. To view pricing information in your local currency, see the [{{site.data.keyword.nlushort}}](https://{DomainName}/catalog/natural-language-understanding) page in the {{site.data.keyword.cloud}} catalog. 28 | {: tip} 29 | 30 | ## Lite 31 | {: #lite} 32 | 33 | The Lite plan is free for users who are looking to try out Natural Language Understanding or build a proof-of-concept. 34 | 35 | **Pricing** 36 | - Free 30,000 NLU items/month 37 | 38 | **Custom Model** 39 | - 1 free custom model 40 | 41 | ## Standard 42 | {: #standard} 43 | 44 | A "pay-as-you-go" plan that is recommended once you are ready to move your application from proof-of-concept to production. 45 | 46 | **Pricing** (billed monthly) 47 | - Tier 1: $0.003/NLU item for the first 1-250,000 NLU items 48 | - Tier 2: $0.001/NLU item for 250,001 to 5,000,000 NLU items 49 | - Tier 3: $0.0002/NLU item for additional NLU items past 5,000,000 50 | 51 | **Custom Entities and Relations Models** ($/custom model/month) 52 | - $800 for all tiers 53 | 54 | **Custom Classification Model** ($/custom classification model/month) 55 | - $25 for all tiers 56 | 57 | ## What is an NLU item? 58 | {: #nlu-items} 59 | 60 | API usage is measured in **NLU items**. One NLU item is one **text unit** (up to 10,000 characters of text) that is analyzed for one **feature**, such as sentiment. 61 | 62 | To keep track of the number of NLU items in your request, you can examine the `usage` object in the response. For example, analyzing 15,000 characters of text for sentiment, emotion, and keywords will return the following usage information. 63 | 64 | ```json 65 | "usage": { 66 | "text_units": 2, 67 | "text_characters": 15000, 68 | "features": 3 69 | } 70 | ``` 71 | {: code} 72 | 73 | There are **2** text units and **3** features in the request, so there are **2 × 3 = 6** NLU items. 74 | 75 | Text units are counted seperately for each request. If one request analyzes 15,000 characters and another request analyzes 3,000 characters, that counts as 3 text units total. The first request has 2 text units and the second request has 1 text unit. 76 | 77 | ## FAQ 78 | {: #faq} 79 | 80 | ### I want to understand sentiment across 20,000 tweets. How can I estimate what I will pay on the Standard plan? 81 | 82 | - Step 1: Calculate the number of text units per request
    83 | As of November 2018, the maximum number of characters allowed in a tweet are 280.
    84 | That translates to one text unit per request. 85 | 86 | - Step 2: Calculate the number of features per request
    87 | One feature, sentiment, is enabled in each request. 88 | 89 | - Step 3: Calculate the number of NLU items per request
    90 | NLU items = (Number of text units) × (Number of features)
    91 | NLU items = 1 text unit × 1 feature = 1 NLU item 92 | 93 | - Step 4: Calculate total number of NLU items
    94 | Total number of NLU items = (Number of requests) × (Number of NLU items per request)
    95 | Total number of NLU items = 20,000 requests × 1 NLU item per request = 20,000 total NLU items 96 | 97 | - Step 5: Estimate the price for total number of NLU items
    98 | For the Standard pricing plan, the first 250,000 NLU items are charged at $0.003 per item
    99 | Estimated price = (Number of NLU items) × (Price per NLU item)
    100 | Estimated price = 20,000 NLU items × $0.003 = $60 101 | 102 | **Total cost = $60** 103 | 104 | ### I want to extract Entities, Keywords and Categories for 50,000 documents with an average of 12,000 characters per document. What will be my estimated price on the Standard plan? 105 | - Step 1: Calculate number of text units per request
    106 | Text units = Number of groups of 10,000 characters or less
    107 | 12,000 characters per request = 2 text units per request 108 | 109 | - Step 2: Calculate the number of features per request
    110 | Entities, Keywords, Categories = 3 features 111 | 112 | - Step 3: Calculate number of NLU items per request
    113 | NLU items = (Number of text unit) × (Number of features)
    114 | NLU items = 2 data units × 3 enrichments = 6 NLU items 115 | 116 | - Step 4: Calculate total number of NLU items
    117 | Total number of NLU items = (Number of requests or documents) × (Number of NLU items)
    118 | Total number of NLU items = 50,000 requests × 6 NLU items = 300,000 NLU items 119 | 120 | - Step 5: Estimate the price for the total number of NLU items
    121 | The first 250,000 NLU items are charged at $0.003 per item
    122 | Additional NLU items until the 5,000,000th NLU item are charged at $0.001 per item
    123 | Estimated price = (250,000 NLU items × $0.003) + (50,000 NLU items × $0.001)
    124 | Estimated price = $750 + $50 125 | 126 | 127 | **Total cost = $800** 128 | 129 | ### How do I calculate the Standard Plan price for 15,000 NLU items? 130 | - Since the first 250,000 NLU items are priced at $0.003/item - your 15,000 NLU items are charged at $0.003 per item (Tier 1). Your estimated price would be $45. 131 | 132 | ### How do I calculate the Standard Plan price for 6,000,000 NLU items? 133 | - Since you have more than 5,000,000 NLU items, your first 250,000 NLU items are charged at $0.003 per item (Tier 1), your next 4,750,000 NLU items are charged at $0.001 per item (Tier 2), and your remaining 1,000,000 NLU items are charged at $0.0002 per item (Tier 3). Your estimated price would be $5,700. 134 | 135 | 136 | 137 | -------------------------------------------------------------------------------- /entity-types.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-11-22" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:deprecated: .deprecated} 15 | {:pre: .pre} 16 | {:codeblock: .codeblock} 17 | {:screen: .screen} 18 | {:javascript: .ph data-hd-programlang='javascript'} 19 | {:java: .ph data-hd-programlang='java'} 20 | {:python: .ph data-hd-programlang='python'} 21 | {:swift: .ph data-hd-programlang='swift'} 22 | 23 | # Entity type systems 24 | {: #entity-type-systems} 25 | 26 | The entity type system that {{site.data.keyword.nlushort}} uses differs depending on which version date and which language you are using. This page describes, for each version date, which type system is used for each language. 27 | {: shortdesc} 28 | 29 | The _Version 1_ entity type system is deprecated. As of 11 July 2023, the v1 Entities type system will no longer be available. To understand which _Version 1_ entity types have been added to or removed in _Version 2_, see [Version 1 deprecation notes](/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems#version-1-deprecation-notes). 30 | {: deprecated} 31 | 32 | For example, analyzing entities in French text with version date set to `2018-09-21` uses the [Version 2 entity type system][v2]. Analyzing entities in French text with a `2017-02-27` version date uses the [Version 1 entity type system][v1]. 33 | 34 | | Language | | | | Version date | | | | 35 | | --- | --- | --- | --- | --- | --- | -- | -- | 36 | | | **2017-07-27** | **2018-03-16** | **2018-09-21** | **2018-11-16** | **2020-12-02** | **2020-12-09** | **2022-08-10** | 37 | | Arabic | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 38 | | Chinese | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 39 | | Czech | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 40 | | Danish | [Version 2][v2] |[Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 41 | | Dutch | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 42 | | English | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | 43 | | Finnish | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 44 | | French | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 45 | | German | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 46 | | Hebrew | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 47 | | Hindi | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 48 | | Italian | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 49 | | Japanese | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 50 | | Korean | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 51 | | Norwegian (Bokmal) | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 52 | | Norwegian (Nyorsk) | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 53 | | Polish | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 54 | | Portuguese | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 55 | | Romanian | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 56 | | Russian | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | 57 | | Slovak | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 58 | | Spanish | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 59 | | Swedish | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 1][v1] | [Version 2][v2] | 60 | | Turkish | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | [Version 2][v2] | 61 | 62 | ## Version 1 deprecation notes 63 | {: #version-1-deprecation-notes} 64 | 65 | This table shows which deprecated _Version 1_ entity types have been added to, or removed in, the _Version 2_ entity type system: 66 | 67 | | New types in v2 | Removed types in v2 | 68 | |:---|:---| 69 | | Date | Anatomy | 70 | | Duration | Award | 71 | | Measure | Broadcaster | 72 | | Money | Company | 73 | | Number¹ | Crime | 74 | | Ordinal | Drug | 75 | | Percent¹ | HealthCondition | 76 | | PhoneNumber¹ | Movie | 77 | | Time | MusicGroup | 78 | | URL¹ | NaturalEvent | 79 | | | PrintMedia | 80 | | | Quantity² | 81 | | | Sport | 82 | | | SportingEvent | 83 | | | TelevisionShow | 84 | | | Vehicle | 85 | 86 | ¹This entity type is not yet detectable in French or Japanese text. 87 | 88 | ²This entity type is now an entity _subtype_ in the v2 type system. 89 | 90 | 91 | [v1]: /docs/natural-language-understanding/?topic=natural-language-understanding-entity-types-version-1 92 | [v2]: /docs/natural-language-understanding/?topic=natural-language-understanding-entity-types-version-2 93 | -------------------------------------------------------------------------------- /getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-03-30" 6 | 7 | keywords: natural language understanding,getting started,analyze content,analyze text,text analysis 8 | 9 | subcollection: natural-language-understanding 10 | 11 | --- 12 | 13 | {:shortdesc: .shortdesc} 14 | {:external: target="_blank" .external} 15 | {:tip: .tip} 16 | {:important: .important} 17 | {:note: .note} 18 | {:deprecated: .deprecated} 19 | {:pre: .pre} 20 | {:codeblock: .codeblock} 21 | {:screen: .screen} 22 | {:video: .video} 23 | {:javascript: .ph data-hd-programlang='javascript'} 24 | {:go: .ph data-hd-programlang='go'} 25 | {:java: .ph data-hd-programlang='java'} 26 | {:python: .ph data-hd-programlang='python'} 27 | {:swift: .ph data-hd-programlang='swift'} 28 | {:hide-dashboard: .hide-dashboard} 29 | {:hide-in-docs: .hide-in-docs} 30 | 31 | # Getting started with {{site.data.keyword.nlushort}} 32 | {: #getting-started} 33 | 34 | This short tutorial introduces the {{site.data.keyword.nlushort}} API with example requests and links to additional resources. 35 | {: shortdesc} 36 | 37 | Watch the following video for a visual summary of getting started with the {{site.data.keyword.nlushort}} service. 38 | 39 | ![Get started with Watson Natural Language Understanding](https://video.ibm.com/embed/channel/23952663/video/NLU-get-started){: video output="iframe" data-script="none" id="watsonmediaplayer" width="560" height="315" scrolling="no" allowfullscreen webkitallowfullscreen mozAllowFullScreen frameborder="0" style="border: 0 none transparent;"} 40 | 41 | ## Before you begin 42 | {: #before-you-begin} 43 | 44 | - Create an instance of the service: 45 | 1. Go to the [{{site.data.keyword.nlushort}}](https://cloud.ibm.com/catalog/services/natural-language-understanding){: external} page in the {{site.data.keyword.cloud_notm}} catalog. 46 | 1. Sign up for a free {{site.data.keyword.cloud_notm}} account or log in. 47 | 1. Click **Create**. 48 | - Copy the credentials to authenticate to your service instance: 49 | 1. On the **Manage** page, click **Show Credentials**. 50 | 1. Copy the `API Key` and `URL` values. 51 | - Make sure that you have the `curl` command. 52 | - Test whether `curl` is installed. Run the following command on the command line. If the output lists the `curl` version with SSL support, you are set for the tutorial. 53 | 54 | ```sh 55 | curl -V 56 | ``` 57 | {: pre} 58 | 59 | - If necessary, install a version with SSL enabled from [curl.haxx.se](https://curl.haxx.se/){: external}. Add the location of the file to your PATH environment variables if you want to run `curl` from any command-line location. 60 | 61 | This tutorial shows you how to use the {{site.data.keyword.nlushort}} API from a command-line interface. To download client libraries for various programming languages, check out the [Watson SDKs](/docs/natural-language-understanding?topic=watson-using-sdks#using-sdks). 62 | {: tip} 63 | 64 | ## Step 1: Analyze a webpage 65 | {: #analyze-sample} 66 | 67 | Run the following command to analyze a webpage to get sentiment, concepts, categories, entities, and keywords. Replace `{apikey}` and `{url}` with your service credentials. 68 | 69 | ```sh 70 | curl -X POST -u "apikey:{apikey}" \ 71 | --header "Content-Type: application/json" \ 72 | --data '{ 73 | "url": "http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver", 74 | "features": { 75 | "sentiment": {}, 76 | "categories": {}, 77 | "concepts": {}, 78 | "entities": {}, 79 | "keywords": {} 80 | } 81 | }' \ 82 | "{url}/v1/analyze?version=2019-07-12" 83 | ``` 84 | {: pre} 85 | 86 | Windows users: This command might not run on Windows. Run the following command instead: 87 | 88 | ```sh 89 | curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"url\":\"http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver\",\"features\":{\"sentiment\":{},\"categories\":{},\"concepts\":{},\"entities\":{},\"keywords\":{}}}" "{url}/v1/analyze?version=2019-07-12" 90 | ``` 91 | {: pre} 92 | 93 | The next step demonstrates how to specify options that customize the analysis for each feature. 94 | 95 | ## Step 2: Analyze target phrases and keywords 96 | {: #analyze-phrase} 97 | 98 | {{site.data.keyword.nlushort}} can analyze target phrases in context of the surrounding text for focused sentiment and emotion results. The **targets** option for sentiment in the following example tells the service to search for the targets "apples", "oranges", and "broccoli". Since "apples" and "oranges" are located in the text, sentiment scores are returned for those targets. 99 | 100 | You can also get sentiment and emotion results for entities and keywords that are detected in your text. In the example, the **emotion** option for keywords tells the service to analyze each detected keyword for emotion results. 101 | 102 | ```sh 103 | curl -X POST -u "apikey:{apikey}" \ 104 | --header "Content-Type: application/json" \ 105 | --data '{ 106 | "text": "I love apples! I do not like oranges.", 107 | "features": { 108 | "sentiment": { 109 | "targets": [ 110 | "apples", 111 | "oranges", 112 | "broccoli" 113 | ] 114 | }, 115 | "keywords": { 116 | "emotion": true 117 | } 118 | } 119 | }' \ 120 | "{url}/v1/analyze?version=2019-07-12" 121 | ``` 122 | {: pre} 123 | 124 | Runnable command for Windows users: 125 | 126 | ```sh 127 | curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"text\":\"I love apples! I do not like oranges.\",\"features\":{\"sentiment\":{\"targets\":[\"apples\",\"oranges\",\"broccoli\"]},\"keywords\":{\"emotion\":true}}}" "{url}/v1/analyze?version=2019-07-12" 128 | ``` 129 | {: pre} 130 | 131 | ## Next steps 132 | {: #next-steps} 133 | 134 | - View the [API reference](https://cloud.ibm.com/apidocs/natural-language-understanding){: external}. 135 | - Learn how to identify [custom entities and relations](/docs/natural-language-understanding?topic=natural-language-understanding-customizing). 136 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2024 5 | lastupdated: "2024-10-17" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:deprecated: .deprecated} 14 | {:important: .important} 15 | {:note: .note} 16 | {:tip: .tip} 17 | {:preview: .preview} 18 | {:beta: .beta} 19 | {:pre: .pre} 20 | {:codeblock: .codeblock} 21 | {:screen: .screen} 22 | {:shortdesc: .shortdesc} 23 | {:javascript: .ph data-hd-programlang='javascript'} 24 | {:java: .ph data-hd-programlang='java'} 25 | {:python: .ph data-hd-programlang='python'} 26 | {:swift: .ph data-hd-programlang='swift'} 27 | {:download: .download} 28 | 29 | # About 30 | {: #about} 31 | 32 | With {{site.data.keyword.nlufull}}, developers can analyze semantic features of text input, including categories, concepts, emotion, entities, keywords, metadata, relations, semantic roles, and sentiment. 33 | {: shortdesc} 34 | 35 | ## Features 36 | {: #features} 37 | 38 | Send requests to the API with text, HTML, or a public URL, and specify one or more of the following features to analyze: 39 | 40 | ### Categories 41 | {: #categories} 42 | 43 | Categorize your content using a five-level classification hierarchy. View the complete list of categories [here](/docs/natural-language-understanding?topic=natural-language-understanding-categories-hierarchy). For example: 44 | 45 | **Input** 46 | > url: "www.cnn.com" 47 | 48 | **Response** 49 | > /news
    50 | > /art and entertainment
    51 | > /movies and tv/television
    52 | > /news
    53 | > /international news 54 | 55 | ### Concepts 56 | {: #concepts} 57 | 58 | Identify high-level concepts that aren't necessarily directly referenced in the text. For example: 59 | 60 | **Input** 61 | > text: "Natural Language Understanding uses natural language processing to analyze text." 62 | 63 | **Response** 64 | > Linguistics
    65 | > Natural language processing
    66 | > Natural language understanding 67 | 68 | ### Emotion 69 | {: #emotion} 70 | 71 | Analyze emotion conveyed by specific target phrases or by the document as a whole. You can also enable emotion analysis for entities and keywords that are automatically detected by the service. For example: 72 | 73 | **Input** 74 | > text: "I love apples, but I hate oranges."
    75 | > targets: "apples", and "oranges" 76 | 77 | **Response** 78 | > "apples": joy
    79 | > "oranges": anger 80 | 81 | ### Entities 82 | {: #entities} 83 | 84 | Find people, places, events, and other types of entities mentioned in your content. View the complete list of entity types and subtypes [here](/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems). For example: 85 | 86 | **Input** 87 | > text: "IBM is an American multinational technology company headquartered in Armonk, New York, United States, with operations in over 170 countries." 88 | 89 | **Response** 90 | > IBM: Company
    91 | > Armonk: Location
    92 | > New York: Location
    93 | > United States: Location 94 | 95 | ### Keywords 96 | {: #keywords} 97 | 98 | Search your content for relevant keywords. For example: 99 | 100 | **Input** 101 | >url: "[http://www-03.ibm.com/press/us/en/pressrelease/51493.wss](http://www-03.ibm.com/press/us/en/pressrelease/51493.wss)" 102 | 103 | **Response** 104 | >Australian Open
    105 | >Tennis Australia
    106 | >IBM SlamTracker analytics 107 | 108 | ### Metadata 109 | {: #metadata} 110 | 111 | For HTML and URL input, get the author of the webpage, the page title, and the publication date. For example: 112 | 113 | **Input** 114 | >url: "https://www.ibm.com/blogs/think/2017/01/cognitive-grid/" 115 | 116 | **Response** 117 | >Author: Stephen Callahan
    118 | >Title: Girding the Grid with Cognitive Computing - THINK Blog
    119 | >Publication date: January 31, 2017 120 | 121 | ### Relations 122 | {: #relations} 123 | 124 | Recognize when two entities are related, and identify the type of relation. For example: 125 | 126 | **Input** 127 | >text: "The Nobel Prize in Physics 1921 was awarded to Albert Einstein." 128 | 129 | **Response** 130 | >"awardedTo" relation between "Noble Prize in Physics" and "Albert Einstein"
    131 | >"timeOf" relation between "1921" and "awarded" 132 | 133 | ### Semantic Roles 134 | {: #semantic-roles} 135 | 136 | Parse sentences into subject-action-object form, and identify entities and keywords that are subjects or objects of an action. For example: 137 | 138 | **Input** 139 | >text: "In 2011, Watson competed on Jeopardy!" 140 | 141 | **Response** 142 | >Subject: Watson
    143 | >Action: competed
    144 | >Object: on Jeopardy 145 | 146 | ### Sentiment 147 | {: #sentiment} 148 | 149 | Analyze the sentiment toward specific target phrases and the sentiment of the document as a whole. You can also get sentiment information for detected entities and keywords by enabling the sentiment option for those features. For example: 150 | 151 | **Input** 152 | >text: "Thank you and have a nice day!" 153 | 154 | **Response** 155 | >Positive sentiment (score: 0.91) 156 | 157 | ### Syntax 158 | {: #syntax} 159 | 160 | Identify the sentences and tokens in your text. For example: 161 | 162 | **Input** 163 | >text: "I love apples! I do not like oranges." 164 | 165 | **Response** 166 | 167 | 168 | | Sentence | Location | 169 | | --- | --- | 170 | | "I love apples!" | `[0, 14]` | 171 | | "I do not like oranges." | `[15,37]` | 172 | 173 |
    174 | 175 | | Token | Lemma | Part of Speech | Location | 176 | |-----------|----------|----------------|------------| 177 | | "I" | "I" | `PRON` | `[0, 1]` | 178 | | "love" | "love" | `VERB` | `[2, 6]` | 179 | | "apples" | "apple" | `NOUN` | `[7, 13]` | 180 | | "!" | | `PUNCT` | `[13, 14]` | 181 | | "I" | "I" | `PRON` | `[15, 16]` | 182 | | "do" | "do" | `AUX` | `[17, 19]` | 183 | | "not" | "not" | `PART` | `[20, 23]` | 184 | | "like" | "like" | `VERB` | `[24, 28]` | 185 | | "oranges" | "orange" | `NOUN` | `[29, 36]` | 186 | | "." | | `NOUN` | `[36, 37]` | 187 | 188 | ## Supported languages 189 | {: #supported-languages} 190 | 191 | See the [Language support documentation](/docs/natural-language-understanding?topic=natural-language-understanding-language-support) for details about supported languages in {{site.data.keyword.nlushort}}. 192 | -------------------------------------------------------------------------------- /custom-categories.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-06-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:tip: .tip} 14 | {:note: .note} 15 | {:beta: .beta} 16 | {:pre: .pre} 17 | {:important: .important} 18 | {:codeblock: .codeblock} 19 | {:screen: .screen} 20 | {:javascript: .ph data-hd-programlang='javascript'} 21 | {:java: .ph data-hd-programlang='java'} 22 | {:python: .ph data-hd-programlang='python'} 23 | {:swift: .ph data-hd-programlang='swift'} 24 | 25 | # Creating custom categories models (Beta) 26 | {: #categories} 27 | 28 | The custom categories feature is Beta. It is in a trial stage of development and is not recommended for production use. 29 | {: beta} 30 | 31 | Do not input any sensitive or personal information when you use the custom categories feature. The Beta release might not be compatible with legislation such as GDPR. For more information, see [Information security](/docs/natural-language-understanding?topic=natural-language-understanding-information-security). 32 | {: important} 33 | 34 | [Learn at-a-glance](https://github.com/watson-developer-cloud/doc-tutorial-downloads/blob/master/natural-language-understanding/Explainers/Custom%20Categories%20One%20Pager-2023.pdf) how the custom categories feature works, and best practices for training your model. 35 | {: note} 36 | 37 | The custom categories feature allows you to train custom English categories models with service instances deployed in the Dallas location. A custom categories model can be trained when no data is available; the only fields required for training categories models are `labels` and `key_phrases`. 38 | 39 | ## Creating categories training data 40 | {: #create-categories-training-data} 41 | 42 | ### Categories training data requirements 43 | {: #categories-training-data-requirements} 44 | 45 | Create and train a custom categories model using the {{site.data.keyword.nlushort}} training API. You can also view an example [Python notebook](https://github.com/watson-developer-cloud/doc-tutorial-downloads/blob/master/natural-language-understanding/custom_categories_example.ipynb) that shows how to create and train a custom categories model. 46 | 47 | 1. Training data must be JSON format, with `application/json` content type. Each training data file needs to contain a list of JSON objects, and each of these objects needs to have `labels` and `key_phrases` defined: 48 | 49 | - `labels`: These are the lists of category labels, in the order of their hierarchy. For example, if you want to add labels with a hierarchy where `B` is a child of `A`, the list of labels here would be: 50 | 51 | ```bash 52 | "labels": ["A", "B"] 53 | ``` 54 | 55 | - `key_phrases`: These are lists of phrases that can uniquely identify the corresponding labels, for example: 56 | 57 | ```bash 58 | "key_phrases": ["films", "action movies"] 59 | ``` 60 | 61 | 1. Up to 5 levels of hierarchy are accepted in `labels`. Following is an example training data format: 62 | 63 | ```bash 64 | [ 65 | { 66 | "labels": [ 67 | "level1" 68 | ], 69 | "key_phrases": [ 70 | "key phrase", 71 | "key phrase 2" 72 | ] 73 | }, 74 | { 75 | "labels": [ 76 | "level1", 77 | "level2" 78 | ], 79 | "key_phrases": [ 80 | "key phrase 3", 81 | "key phrase 4" 82 | ] 83 | } 84 | ] 85 | ``` 86 | 87 | If you do use a `label` hierarchy, you **must** define `key_phrases` for each label level. 88 | {: important} 89 | 90 | ## Training a custom categories model 91 | {: #training-a-custom-categories-model} 92 | 93 | When your training data is ready, use the **Create categories model** method to create your custom model. Make sure to substitute your credentials for `{apikey}` and `{url}`, and use the path to your training data file in the `training_data` parameter. 94 | 95 | ```bash 96 | curl -X POST -u "apikey:{apikey}" \ 97 | -H "Content-Type: multipart/form-data" \ 98 | -F "name=MyCategoriesModel" \ 99 | -F "language=en" \ 100 | -F "model_version=1.0.1" \ 101 | -F "training_data=@categories_data.json;type=application/json" \ 102 | "{url}/v1/models/categories?version=2021-02-16" 103 | ``` 104 | 105 | Use the `model_id` in the response to check the status of your model. 106 | 107 | ## Checking the status of categories models 108 | {: #checking-status-of-categories-models} 109 | 110 | The following sample request for the **Get categories model** method checks the status for the model with ID `714a50d1-36c7-4a57-a790-99f13cc9301c`. 111 | 112 | ```bash 113 | curl -X GET -u "apikey:{apikey}" \ 114 | "{url}/v1/models/categories/714a50d1-36c7-4a57-a790-99f13cc9301c?version=2021-02-16" 115 | ``` 116 | 117 | To get information for all categories models deployed to your instance, use the **List categories models** method. 118 | 119 | ```bash 120 | curl -X GET -u "apikey:{apikey}" \ 121 | "{url}/v1/models/categories?version=2021-02-16" 122 | ``` 123 | 124 | When the status is `available`, the model is ready to use. 125 | 126 | ## Analyzing text with custom categories models 127 | {: #analyzing-text-with-custom-categories-models} 128 | 129 | To use your model, specify the `model` that you deployed in the [categories](https://{DomainName}/apidocs/natural-language-understanding#categories){: external} options of your API request: 130 | 131 | - Example *parameters.json* file: 132 | 133 | ```json 134 | { 135 | "url": "www.url.example", 136 | "features": { 137 | "categories": { 138 | "model": "your-model-id-here" 139 | } 140 | } 141 | } 142 | ``` 143 | 144 | - Example cURL request: 145 | 146 | ```bash 147 | curl --request POST \ 148 | --header "Content-Type: application/json" \ 149 | --user "apikey":"{apikey}" \ 150 | "{url}/v1/analyze?version=2021-02-16" \ 151 | --data @parameters.json 152 | ``` 153 | 154 | ## Deleting a custom categories model 155 | {: #deleting-a-custom-categories-model} 156 | 157 | To delete a categories model from your service instance, use the **Delete categories model** method. Replace {url} and {apikey} with your service URL and API key, and replace {model_id} with the model ID of the model you want to delete. 158 | 159 | - The following example undeploys a categories model. 160 | 161 | ```bash 162 | curl --user "apikey":"{apikey}" \ 163 | "{url}/v1/models/categories/{model_id}?version=2021-02-16" \ 164 | --request DELETE 165 | ``` 166 | -------------------------------------------------------------------------------- /custom-class.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2022 5 | lastupdated: "2022-09-06" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {{site.data.keyword.attribute-definition-list}} 12 | 13 | # Creating custom classification models 14 | {: #classifications} 15 | 16 | The custom classifications feature allows you to train a multi-label text classifier using your own labeled data. Once trained, the model will be automatically deployed in {{site.data.keyword.nlufull}} and available for analyze calls. 17 | 18 | ## Creating classifications model training data 19 | {: #create-classification-training-data} 20 | 21 | Create and train a custom classifications model using the Natural Language Understanding training API. You can use [this example Python notebook](https://github.com/watson-developer-cloud/doc-tutorial-downloads/blob/master/natural-language-understanding/custom_classifications_introduction.ipynb) that shows how to create a classifications model, or the [more advanced notebook](https://github.com/watson-developer-cloud/doc-tutorial-downloads/blob/master/natural-language-understanding/custom_classifications_training_and_tuning_advice.ipynb) that shows how to train and fine-tune your classifications model. 22 | 23 | ### Training data in JSON format 24 | 25 | Classifications accepts training data in the following JSON format: 26 | 27 | ```json 28 | [ 29 | { 30 | "text": "Example 1", 31 | "labels": ["label1"] 32 | }, 33 | { 34 | "text": "Example 2", 35 | "labels": ["label1", "label2"] 36 | } 37 | ] 38 | ``` 39 | {: codeblock} 40 | 41 | ### Training data in CSV format 42 | 43 | You can also provide training data in comma-separated value (CSV) format. 44 | 45 | ```bash 46 | Example 1,label1 47 | Example 2,label1,label2 48 | ``` 49 | 50 | In CSV format, a row in the file represents an example record. Each record has two or more columns. The first column is the representative text to classify. The additional columns are classes that apply to that text. 51 | 52 | Headers are not expected for the CSV file. 53 | {: note} 54 | 55 | ### Classifications training data requirements 56 | {: #classification-training-data-requirements} 57 | 58 | - Classifications training data consists of an array containing multiple JSON objects. 59 | - Each of these JSON objects, needs to contain, 1 `text` and 1 `labels` field. 60 | - `text` consists of the training examples and `labels` consists of 1 or more labels associated with an example. 61 | - `labels` are case-sensitive 62 | - Minimum number of unique labels required: `2` 63 | - Maximum number of unique labels allowed: `3000` 64 | - Minimum number of examples required per label: `5` 65 | - Maximum size of each example (training and predict): `2000` [codepoints](https://en.wikipedia.org/wiki/Code_point) 66 | - Maximum number of examples: `20000` 67 | 68 | ### Classifications training parameters 69 | {: #classification-training-parameters} 70 | 71 | Passing in the optional `training_parameters` object allows you to specify characteristics of your classifier. Not passing in the object or an empty object into the request will train the model using default values. 72 | 73 | Supported training parameters: 74 | 75 | | Keys | Default Value | Optional Values | 76 | | --- | --- | --- | 77 | | `model_type` | `multi_label` | `single_label` | 78 | 79 | Description: 80 | 81 | - `model_type`: Passing the `single_label` value will result in a single-label classifier, capable of handling training datasets with only one label per example. The single-label classifier will output normalized confidence scores so that the scores sum up to one. Passing the `multi_label` value will result in a multi-label classifier, capable of handling training datasets with multiple labels per example. The multi-label classifier will not output normalized confidence scores, in order to account for the added flexibility of associating multiple labels with examples. 82 | 83 | ## Training a custom classifications model 84 | {: #training-a-custom-classification} 85 | 86 | When your training data is ready, use the **Create classifications model** method to create your custom classifications model. Make sure to substitute your credentials for `{apikey}` and `{url}`, and use the path to your training data file in the `training_data` parameter. Optionally, you can also specify characteristics of your classifier using `training_parameters`. 87 | 88 | ```bash 89 | curl -X POST -u "apikey:{apikey}" \ 90 | -H "Content-Type: multipart/form-data" \ 91 | -F "name=MyClassificationsModel" \ 92 | -F "language=en" \ 93 | -F "model_version=1.0.1" \ 94 | -F 'training_parameters={"model_type": "multi_label"}' \ 95 | -F "training_data=@classifications_data.json;type=application/json" \ 96 | "{url}/v1/models/classifications?version=2021-03-23" 97 | ``` 98 | {: pre} 99 | 100 | Use the `model_id` in the response to check the status of your model. 101 | 102 | ## Checking the status of a classifications model 103 | {: #checking-status-of-classifications} 104 | 105 | The following sample request for the **Get classifications model** method checks the status for the classifications model with ID `cb3755ad-d226-4587-b956-43a4a7202202`. 106 | 107 | ```bash 108 | curl -X GET -u "apikey:{apikey}" \ 109 | "{url}/v1/models/classifications/cb3755ad-d226-4587-b956-43a4a7202202?version=2021-03-23" 110 | ``` 111 | {: pre} 112 | 113 | To get information for all classifications models deployed to your instance, use the **List classifications models** method. 114 | 115 | ```bash 116 | curl -X GET -u "apikey:{apikey}" \ 117 | "{url}/v1/models/classifications?version=2021-03-23" 118 | ``` 119 | {: pre} 120 | 121 | When the status is `available`, the classification is ready to use. 122 | 123 | ## Analyzing text with a custom classifications model 124 | {: #analyzing-text-with-custom-classifications-models} 125 | 126 | To use your classifications model, specify the `model` that you deployed in the [classifications](https://{DomainName}/apidocs/natural-language-understanding#classifications){: external} options of your API request: 127 | 128 | - Example *parameters.json* file: 129 | 130 | ```json 131 | { 132 | "url": "www.url.example", 133 | "features": { 134 | "classifications": { 135 | "model": "your-model-id-here" 136 | } 137 | } 138 | } 139 | ``` 140 | 141 | - Example cURL request: 142 | 143 | ```bash 144 | curl --request POST \ 145 | --header "Content-Type: application/json" \ 146 | --user "apikey":"{apikey}" \ 147 | "{url}/v1/analyze?version=2021-03-23" \ 148 | --data @parameters.json 149 | ``` 150 | {: pre} 151 | 152 | ## Deleting a custom classifications model 153 | {: #deleting-a-custom-classifications-model} 154 | 155 | To delete a classifications model from your service instance, use the **Delete classifications model** method. Replace `{url}` and `{apikey}` with your service URL and API key, and replace `{model_id}` with the model ID of the classifications model you want to delete. 156 | 157 | - The following example deletes a classification model. 158 | 159 | ```bash 160 | curl --user "apikey":"{apikey}" \ 161 | "{url}/v1/models/classifications/{model_id}?version=2021-03-23" \ 162 | --request DELETE 163 | ``` 164 | {: pre} 165 | 166 | ## Migrating from {{site.data.keyword.nlclassifiershort}} to {{site.data.keyword.nlushort}} 167 | {: #migrating-natural-language-classifier} 168 | 169 | On 9 August 2021, IBM announced the deprecation of the {{site.data.keyword.nlclassifierfull}} service. The service will no longer be available from 8 August 2022. As of 9 September 2021, you can't create new instances, and access to free instances will be removed. Existing premium plan instances are supported until 8 August 2022. Any instance that still exists on that date will be deleted. As an alternative, we encourage {{site.data.keyword.nlclassifiershort}} users to consider migrating to the {{site.data.keyword.nlushort}} service. 170 | 171 | ### When training data is available 172 | 173 | You can directly use the available training data to train `classifications` in {{site.data.keyword.nlushort}}. {{site.data.keyword.nlushort}} accepts the same CSV file format. 174 | 175 | ### When training data is not available 176 | 177 | You can fetch the data you used to train {{site.data.keyword.nlclassifiershort}} from the service. Refer to [this tutorial](https://github.com/watson-developer-cloud/doc-tutorial-downloads/blob/master/natural-language-understanding/custom_classifications_introduction.ipynb){: external}. 178 | -------------------------------------------------------------------------------- /sample-apps.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2021 5 | lastupdated: "2021-08-31" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | {:swift: .ph data-hd-programlang='swift'} 21 | 22 | # Sample apps 23 | {: #sample-apps} 24 | 25 | Learn more about IBM Watson™ Natural Language Understanding from these sample applications and labs. 26 | {: shortdesc} 27 | 28 | ## Build a cognitive moderator microservice 29 | {: #cognitive-moderator} 30 | 31 | Process messages and images exchanged in a chat channel using Watson services to moderate the discussions 32 | 33 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/build-a-cognitive-moderator-microservice/) 34 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/cognitive-moderator-service){: new_window} 35 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=z91RYXgU9CI){: new_window} 36 | - [Watch the Video ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=9c7NuamK8JA){: new_window} 37 | 38 | ## Get recommendations by linking structured and unstructured data 39 | {: #recommendations} 40 | 41 | Establish a relation with data stored in the structured format 42 | 43 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/generate-insights-from-multiple-data-formats-using-watson-services/) 44 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/generate-insights-from-data-formats-with-watson){: new_window} 45 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=wj39DepBVBg){: new_window} 46 | 47 | ## Provide automated customer support for emails 48 | {: #automated-customer-support-for-emails} 49 | 50 | Develop an intelligent customer support system using Watson natural language capabilities 51 | 52 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/email-support-automation-for-telco/) 53 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/smart-email-support){: new_window} 54 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=AT477px19gQ){: new_window} 55 | 56 | ## Query a knowledge base for documents 57 | {: #query-knowledge-base-for-documents} 58 | 59 | Use Watson NLU, Python NLTK, and IBM Watson Studio to query a knowledge base and get answers to questions related to a domain-specific document 60 | 61 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/algorithm-that-gives-you-answer-to-any-particular-question-based-on-mining-documents/) 62 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/query-knowledge-base-with-domain-specific-documents/){: new_window} 63 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=qMUDB7k8x3I){: new_window} 64 | 65 | ## Build a knowledge graph from documents 66 | {: #build-knowledge-graph-from-documents} 67 | 68 | Use IBM Cloud, Watson services, Watson Studio, and open source technologies to derive insights from unstructured text content generated in various business domains 69 | 70 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/build-a-domain-specific-knowledge-graph-from-given-set-of-documents/) 71 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/build-knowledge-base-with-domain-specific-documents/){: new_window} 72 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=qMUDB7k8x3I){: new_window} 73 | 74 | ## Snap and translate text in images 75 | {: #translate-text-in-images} 76 | 77 | Capture an image, extract, and translate text using Tesseract OCR and Watson Language Translator 78 | 79 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/snap-translate-using-tesseract-ocr-watson-language-translator/) 80 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/snap-and-translate){: new_window} 81 | 82 | ## Analyze product reviews and generate a shopping guide 83 | {: #analyze-product-reviews} 84 | 85 | Create a Node.js app to make cognitive decisions using product reviews evaluated by Watson Natural Language Understanding. 86 | 87 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/analyze-product-reviews-and-generate-a-shopping-guide/) 88 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/watson-second-opinion?cm_sp=Developer-_-slug-_-Get-the-Code){: new_window} 89 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=wwNAEvbxd54){: new_window} 90 | 91 | ## Create a Banking Chatbot 92 | {: #banking-chatbot} 93 | 94 | Use Node.js and Watson to detect emotion, identify entities, and discover answers. 95 | 96 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/create-cognitive-banking-chatbot/) 97 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/watson-banking-chatbot?cm_sp=IBMCode-_-create-cognitive-banking-chatbot-_-Get-the-Code){: new_window} 98 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=Jxi7U7VOMYg&cm_sp=IBMCode-_-create-cognitive-banking-chatbot-_-View-the-Demo){: new_window} 99 | - [Build from a Starter Kit ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://console.bluemix.net/developer/watson/create-project?starterKit=a5819b41-0f6f-34cb-9067-47fd16835d04&cm_sp=dw-bluemix-_-code-_-devcenter){: new_window} 100 | 101 | ## Enrich multimedia files using Watson services 102 | {: #enrich-multimedia-files} 103 | 104 | Build an app that enriches audio and visual files using IBM Watson services. 105 | 106 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/enrich-multi-media-files-using-ibm-watson/) 107 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/watson-multimedia-analyzer?cm_sp=Developper-_-enrich-multi-media-files-using-ibm-watson-_-Get-the-Code){: new_window} 108 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=nTzrA56zLTE&cm_sp=Developper-_-enrich-multi-media-files-using-ibm-watson-_-View-the-Video){: new_window} 109 | 110 | ## Analyze SMS messages with Watson Knowledge Studio 111 | {: #analyze-sms-messages} 112 | 113 | Build a custom model to better categorize SMS message content using Watson Knowledge Studio and Watson Natural Language Understanding. 114 | 115 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/analyze-sms-messages-with-watson-knowledge-studio/) 116 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/sms-analysis-with-wks?cm_sp=Developer-_-analyze-sms-messages-with-watson-knowledge-studio-_-Get-the-code){: new_window} 117 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://youtu.be/lwW97UQj0RM?cm_sp=Developer-_-analyze-sms-messages-with-watson-knowledge-studio-_-Watch-the-Video){: new_window} 118 | 119 | ## Correlate documents from different sources 120 | {: #correlate-content-across-documents} 121 | 122 | Correlate content across documents by using the Python NLTK and IBM Data Science Experience. 123 | 124 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/watson-document-correlation/) 125 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/watson-document-co-relation?cm_sp=Developer-_-watson-document-correlation-_-Get-the-Code){: new_window} 126 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://youtu.be/vDCaBPhAr64?cm_sp=Developer-_-watson-document-correlation-_-View-the-Demo){: new_window} 127 | 128 | ## Discover hidden Facebook usage insights 129 | {: #facebook-insights} 130 | 131 | Harness the power of cognitive data analysis in a Jupyter Notebook with PixieDust. 132 | 133 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/discover-hidden-facebook-usage-insights/) 134 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/pixiedust-facebook-analysis?cm_sp=IBMCode-_-discover-hidden-facebook-usage-insights-_-Get-the-Code){: new_window} 135 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=UIkjFo9o3vI&cm_sp=IBMCode-_-discover-hidden-facebook-usage-insights-_-View-the-Demo){: new_window} 136 | 137 | ## Extend Watson text classification 138 | {: #extend-text-classification} 139 | 140 | Use the Python NLTK toolkit and IBM DSX to achieve the desired text classification results. 141 | 142 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/extend-watson-text-classification/) 143 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/watson-document-classifier?cm_sp=Developer-_-extend-watson-text-classification-_-Get-the-code){: new_window} 144 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://youtu.be/kp8dcM9AKrA?cm_sp=Developer-_-extend-watson-text-classification-_-Watch-the-video){: new_window} 145 | 146 | ## Fingerprinting personal data from unstructured text 147 | {: #fingerprint-personal-data} 148 | 149 | Build a custom model using Watson Natural Language Understanding and Watson Knowledge Studio. 150 | 151 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/fingerprinting-personal-data-from-unstructured-text/) 152 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/gdpr-fingerprint-pii){: new_window} 153 | - [Blog Post ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://youtu.be/NiBCa3EtCr0){: new_window} 154 | 155 | ## Use Swift to interpret unstructured data from Hacker News 156 | {: #analyze-hacker-news} 157 | 158 | Use cognitive APIs to gain insight into tech trends on Hacker News with a twist. 159 | 160 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/use-swift-interpret-unstructured-data-hacker-news/) 161 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/Hackernews-NLU?cm_sp=IBMCode-_-use-swift-interpret-unstructured-data-hacker-news-_-Get-the-Code){: new_window} 162 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://youtu.be/sFbI6nu31ss?cm_sp=IBMCode-_-use-swift-interpret-unstructured-data-hacker-news-_-View-the-Demo){: new_window} 163 | 164 | ## Accelerate training of machine learning algorithms 165 | {: #accelerate-ml-training} 166 | 167 | Achieve faster training of machine learning algorithms using Google TensorFlow on IBM PowerAI. 168 | 169 | - [Learn more](https://developer.ibm.com/patterns/accelerate-training-of-machine-learning-algorithms/) 170 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/powerai-notebook?cm_sp=IBMCode-_-accelerate-training-of-machine-learning-algorithms-_-Get-the-Code){: new_window} 171 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://www.youtube.com/watch?v=1nnWj6W7QJI&cm_sp=IBMCode-_-accelerate-training-of-machine-learning-algorithms-_-View-the-Demo){: new_window} 172 | 173 | ## Build a cognitive recommendation app with Swift 174 | {: #cognitive-recommendation-app} 175 | 176 | Build a Swift-based mobile chatbot to provide recommendations, reservations, and event planning. 177 | - [Learn more ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://developer.ibm.com/patterns/build-a-cognitive-recommendation-app-with-swift/) 178 | - [Get the Code ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://github.com/IBM/CognitiveConcierge?cm_sp=IBMCode-_-build-a-cognitive-recommendation-app-with-swift-_-Get-the-Code){: new_window} 179 | - [View the Demo ![External link icon](../../icons/launch-glyph.svg "External link icon")](https://vimeo.com/222564546?cm_mc_uid=56476701007714999647300&cm_mc_sid_50200000=1500411355&cm_mc_sid_52640000=&cm_sp=IBMCode-_-build-a-cognitive-recommendation-app-with-swift-_-View-the-Demo){: new_window} 180 | -------------------------------------------------------------------------------- /relations-v1.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-02-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:note: .note} 16 | {:codeblock: .codeblock} 17 | {:screen: .screen} 18 | {:javascript: .ph data-hd-programlang='javascript'} 19 | {:java: .ph data-hd-programlang='java'} 20 | {:python: .ph data-hd-programlang='python'} 21 | {:swift: .ph data-hd-programlang='swift'} 22 | 23 | # Relation types (Version 1) 24 | {: #relation-types-version-1} 25 | 26 | The following table lists the relation types returned by the _Version 1_ relation type system. The relation type system that {{site.data.keyword.nlushort}} uses differs based on which language you are using. For more details, see the [Relation type systems](/docs/natural-language-understanding?topic=natural-language-understanding-relation-type-systems) page. 27 | {: shortdesc} 28 | 29 | In the _Version 1_ type system, the entity types in relations results are different than the entity types returned in entities results. To see the list of entity types used in _Version 1_ relations, see the [Entity types (Version 1)](/docs/natural-language-understanding?topic=natural-language-understanding-entity-types-version-1#relations-entity-types) page. 30 | {: note} 31 | 32 | | Relation | Description | 33 | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 34 | | affectedBy | Exists between an entity and an event that has clear directionality and affects the entity. | 35 | | affiliatedWith | Exists between two entities that have an affiliation or are similarly connected. | 36 | | ageOf | Relates an age to an entity. | 37 | | agentOf | Exists between an entity and an event in which the entity plays the most active role according to the text. No background knowledge should be required. | 38 | | authorOf | Exists between a person and a TitleWork that he or she created. | 39 | | awardedBy | Exists between an Award or Degree and the person or organization by which it was awarded or conferred. | 40 | | awardedTo | Exists between an Award or Degree and the person or organization to which it was awarded or conferred. | 41 | | basedIn | Exists between an Organization and the place where it is mainly, only, or intrinsically located. | 42 | | before | Signifies the temporal relation "before" between two Times or Events. Marked only when the text clearly specifies the relation. | 43 | | bornAt | Exists between a Person or Animal and the place where she, he, or it was born. | 44 | | bornOn | Exists between a Person or Animal and the Date or Time on which she, he, or it was born. | 45 | | capitalOf | Exists between a capital and its country, state, or province. Marked only when the text explicitly states the relation, not based on world knowledge. | 46 | | citizenOf | Exists between a person and the GeopoliticalEntity of which he or she is a citizen. | 47 | | clientOf | Exists between two entities when one is a direct business client of the other (that is, pays for certain services or products). | 48 | | colleague | Exists between two People who are part of the same Organization. | 49 | | competitor | Exists between two GeopoliticalEntities or Organizations that are engaged in economic competition. | 50 | | contactOf | Relates contact information with an entity. | 51 | | diedAt | Exists between a Person or Animal and the place at which he, she, or it died. | 52 | | diedOf | Exists between a Person or Animal and the cause of his, her, or its death. | 53 | | diedOn | Exists between a Person or Animal and the Date or Time on which he, she, or it died. | 54 | | dissolvedOn | Exists between an entity such as an Organization and the Date or Time on which it was dissolved. | 55 | | educatedAt | Exists between a Person and the Organization at which he or she is or was educated. | 56 | | employedBy | Exists between two entities when one pays the other for certain work or services; monetary reward must be involved. In many circumstances, marking this relation requires world knowledge. | 57 | | foundedOn | Exists between an entity such as an Organization and the Date or Time on which it was founded. | 58 | | founderOf | Exists between a Person or GeopoliticalEntity and an entity such as an Organization that it founded. | 59 | | hasDisease | Indicates that a Person or Animal has or had a Disease. | 60 | | hasMoney | Indicates that an entity such as a person has or had Money. | 61 | | instrumentOf | Exists between an entity such as a Weapon and an Event that the entity is or was used to bring about. | 62 | | locatedAt | Exists between an entity and its physical location. | 63 | | managerOf | Exists between a Person and another entity such as a Person or Organization that he or she manages as his or her job. | 64 | | measureOf | Indicates a particular Measure such as the height or weight of an entity. | 65 | | memberOf | Exists between an entity such as a Person, Organization, or GeopoliticalEntity and another entity to which he, she, or it belongs. | 66 | | near | Exists between two entities that are located close to each other physically. | 67 | | overlaps | Indicates that two Times or Events overlap temporally. Marked only when the text clearly specifies the relation. | 68 | | ownerOf | Exists between an entity such as a Person, Organization, or GeopoliticalEntity and an entity that he, she, or it owns, either permanently or temporarily. | 69 | | parentOf | Exists between a Person or Animal and his, her, or its child or stepchild. | 70 | | participantIn | Exists between a participant such as a Person, Animal, Organization, or GeopoliticalEntity and an Event in which he, she, or it is participating or has participated. | 71 | | partner | Exists between two GeopoliticalEntities or Organizations that are engaged in economic cooperation. | 72 | | partOf | Exists between a smaller and a larger entity of the same type or related types in which the second entity subsumes the first. If the entities are Events, the first must occur within the time span of the second. | 73 | | partOfMany | Exists between smaller and larger entities of the same type or related types in which the second entity, which must be plural, subsumes the first, which can consist of one or more entities. | 74 | | playsRoleOf | Exists between a Person and a specific character that he or she plays or played in a performance. | 75 | | populationOf | Exists between a Cardinal and an entity such as an organization or country for which the number represents the entire population. | 76 | | productOf | Exists between a Product or TitleWork and the Organization that produced it. | 77 | | quantityOf | Indicates a Cardinal that is the quantity or amount of a second entity. | 78 | | rateOf | Exists between a Rate and an event whose frequency of occurrence it specifies. | 79 | | relative | Exists between a Person or Animal and another Person or Animal of which he, she, or it is a relative when a more specific relation is inappropriate. | 80 | | residesIn | Exists between a living entity and the location at which he, she, or it permanently resides. | 81 | | shareholdersOf | Exists between a person, Organization, or GeopoliticalEntity and an Organization of which the first entity is a shareholder. | 82 | | siblingOf | Exists between a Person or Animal and his, her, or its sibling or stepsibling. | 83 | | spokespersonFor | Exists between a Person and an entity that he or she represents. Marked only when the text explicitly states the relation, not based on world knowledge. | 84 | | spouseOf | Exists between two People that are formal spouses. | 85 | | subsidiaryOf | Exists between two Organizations when the first is a subsidiary of the second, meaning the first entity has a fair amount of autonomy despite being under the control of the second. | 86 | | timeOf | Indicates the Date, Time, or Duration at or for which an event occurred; a TitleWork was published, performed, or broadcast; or a Law was first drafted, created, passed, or abolished. | 87 | -------------------------------------------------------------------------------- /language-support.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2023 5 | lastupdated: "2023-03-09" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:note: .note} 14 | {:tip: .tip} 15 | {:pre: .pre} 16 | {:codeblock: .codeblock} 17 | {:screen: .screen} 18 | {:javascript: .ph data-hd-programlang='javascript'} 19 | {:java: .ph data-hd-programlang='java'} 20 | {:python: .ph data-hd-programlang='python'} 21 | {:swift: .ph data-hd-programlang='swift'} 22 | 23 | # Language support 24 | {: #language-support} 25 | 26 | {{site.data.keyword.nlushort}} supports a variety of languages depending on which features you analyze. Currently, English is the only language that is supported across all features. The rest of the languages have limited support. To jump to the list of features that are compatible with a language, click the language in the following list. 27 | 28 | - [Arabic](#arabic) 29 | - [Chinese (Simplified)](#chinese-simplified) 30 | - [Czech](#czech) 31 | - [Danish](#danish) 32 | - [Dutch](#dutch) 33 | - [English](#english) 34 | - [Finnish](#finnish) 35 | - [French](#french) 36 | - [German](#german) 37 | - [Hebrew](#hebrew) 38 | - [Hindi](#hindi) 39 | - [Italian](#italian) 40 | - [Japanese](#japanese) 41 | - [Korean](#korean) 42 | - [Norwegian](#norwegian) 43 | - [Norwegian (Bokmal)](#norwegian-bokmal) 44 | - [Norwegian (Nyorsk)](#norwegian-nyorsk) 45 | - [Polish](#polish) 46 | - [Portuguese](#portuguese) 47 | - [Romanian](#romanian) 48 | - [Russian](#russian) 49 | - [Slovak](#slovak) 50 | - [Spanish](#spanish) 51 | - [Swedish](#swedish) 52 | - [Turkish](#turkish) 53 | 54 | Language support might be different if you are a {{site.data.keyword.Bluemix_dedicated}} customer. If you are using {{site.data.keyword.Bluemix_dedicated}}, check with your IBM salesperson to confirm which languages are supported in your environment. 55 | {: tip} 56 | 57 | ## Arabic 58 | {: #arabic} 59 | 60 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 61 | | --- | --- | --- | 62 | | Categories | X | | 63 | | Classifications | | X | 64 | | Concepts | | | 65 | | Emotion | | | 66 | | Entities | X* | X | 67 | | Keywords | X | | 68 | | Metadata | X | | 69 | | Relations | X | X | 70 | | Semantic roles | | | 71 | | Sentiment | X | | 72 | | Syntax | X | | 73 | 74 | \* Relevance ranking is not supported. 75 | 76 | ## Chinese (Simplified) 77 | {: #chinese-simplified} 78 | 79 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 80 | | --- | --- | --- | 81 | | Categories | X | | 82 | | Classifications | | | 83 | | Concepts | | | 84 | | Emotion | | | 85 | | Entities | X* | X | 86 | | Keywords | X | | 87 | | Metadata | | | 88 | | Relations | | X | 89 | | Semantic roles | | | 90 | | Sentiment | X | | 91 | | Syntax | X | | 92 | 93 | \* Relevance ranking is not supported. 94 | 95 | ## Czech 96 | {: #czech} 97 | 98 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 99 | | --- | --- | --- | 100 | | Categories | | | 101 | | Classifications | | | 102 | | Concepts | | | 103 | | Emotion | | | 104 | | Entities | X* | | 105 | | Keywords | X | | 106 | | Metadata | | | 107 | | Relations | | | 108 | | Semantic roles | | | 109 | | Sentiment | X | | 110 | | Syntax | X | | 111 | 112 | \* Relevance ranking is not supported. 113 | 114 | ## Danish 115 | {: #danish} 116 | 117 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 118 | | --- | --- | --- | 119 | | Categories | | | 120 | | Classifications | | | 121 | | Concepts | | | 122 | | Emotion | | | 123 | | Entities | X* | | 124 | | Keywords | X | | 125 | | Metadata | | | 126 | | Relations | | | 127 | | Semantic roles | | | 128 | | Sentiment | X | | 129 | | Syntax | X | | 130 | 131 | \* Relevance ranking is not supported. 132 | 133 | ## Dutch 134 | {: #dutch} 135 | 136 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 137 | | --- | --- | --- | 138 | | Categories | X | | 139 | | Classifications | | | 140 | | Concepts | | | 141 | | Emotion | | | 142 | | Entities | X* | X | 143 | | Keywords | X | | 144 | | Metadata | | | 145 | | Relations | | X | 146 | | Semantic roles | | | 147 | | Sentiment | X | | 148 | | Syntax | X | | 149 | 150 | \* Relevance ranking is not supported. 151 | 152 | ## English 153 | {: #english} 154 | 155 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 156 | | --- | --- | --- | 157 | | Categories | X | X (Beta) | 158 | | Classifications | X* | X | 159 | | Concepts | X | | 160 | | Emotion | X | | 161 | | Entities | X | X | 162 | | Keywords | X | | 163 | | Metadata | X | | 164 | | Relations | X | X | 165 | | Semantic roles | X | | 166 | | Sentiment | X | | 167 | | Syntax | X | | 168 | 169 | \* Indicates support for tone analysis; see [Tone analytics (Classifications)](/docs/natural-language-understanding?topic=natural-language-understanding-tone_analytics) for more information. 170 | 171 | ## Finnish 172 | {: #finnish} 173 | 174 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 175 | | --- | --- | --- | 176 | | Categories | | | 177 | | Classifications | | | 178 | | Concepts | | | 179 | | Emotion | | | 180 | | Entities | X* | | 181 | | Keywords | X | | 182 | | Metadata | | | 183 | | Relations | | | 184 | | Semantic roles | | | 185 | | Sentiment | X | | 186 | | Syntax | X | | 187 | 188 | \* Relevance ranking is not supported. 189 | 190 | ## French 191 | {: #french} 192 | 193 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 194 | | --- | --- | --- | 195 | | Categories | X | | 196 | | Classifications | X* | X | 197 | | Concepts | X | | 198 | | Emotion | X | | 199 | | Entities | X | X | 200 | | Keywords | X | | 201 | | Metadata | X | | 202 | | Relations | X | X | 203 | | Semantic roles | | | 204 | | Sentiment | X | | 205 | | Syntax | X | | 206 | 207 | \* Indicates support for tone analysis; see [Tone analytics (Classifications)](/docs/natural-language-understanding?topic=natural-language-understanding-tone_analytics) for more information. 208 | 209 | ## German 210 | {: #german} 211 | 212 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 213 | | --- | --- | --- | 214 | | Categories | X | | 215 | | Classifications | | X | 216 | | Concepts | X | | 217 | | Emotion | | | 218 | | Entities | X | X | 219 | | Keywords | X | | 220 | | Metadata | X | | 221 | | Relations | X | X | 222 | | Semantic roles | X | | 223 | | Sentiment | X | | 224 | | Syntax | X | | 225 | 226 | ## Hebrew 227 | {: #hebrew} 228 | 229 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 230 | | --- | --- | --- | 231 | | Categories | | | 232 | | Classifications | | | 233 | | Concepts | | | 234 | | Emotion | | | 235 | | Entities | X* | | 236 | | Keywords | X | | 237 | | Metadata | | | 238 | | Relations | | | 239 | | Semantic roles | | | 240 | | Sentiment | X | | 241 | | Syntax | X | | 242 | 243 | \* Relevance ranking is not supported. 244 | 245 | ## Hindi 246 | {: #hindi} 247 | 248 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 249 | | --- | --- | --- | 250 | | Categories | | | 251 | | Classifications | | | 252 | | Concepts | | | 253 | | Emotion | | | 254 | | Entities | X* | | 255 | | Keywords | X | | 256 | | Metadata | | | 257 | | Relations | | | 258 | | Semantic roles | | | 259 | | Sentiment | X | | 260 | | Syntax | X | | 261 | 262 | \* Relevance ranking is not supported. 263 | 264 | ## Italian 265 | {: #italian} 266 | 267 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 268 | | --- | --- | --- | 269 | | Categories | X | | 270 | | Classifications | | X | 271 | | Concepts | X | | 272 | | Emotion | | | 273 | | Entities | X | X | 274 | | Keywords | X | | 275 | | Metadata | X | | 276 | | Relations | X | X | 277 | | Semantic roles | | | 278 | | Sentiment | X | | 279 | | Syntax | X | | 280 | 281 | ## Japanese 282 | {: #japanese} 283 | 284 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 285 | | --- | --- | --- | 286 | | Categories | X | | 287 | | Classifications | | X | 288 | | Concepts | X | | 289 | | Emotion | | | 290 | | Entities | X | X | 291 | | Keywords | X | | 292 | | Metadata | X | | 293 | | Relations | X | X | 294 | | Semantic roles | X | | 295 | | Sentiment | X | | 296 | | Syntax | X | | 297 | 298 | ## Korean 299 | {: #korean} 300 | 301 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 302 | | --- | --- | --- | 303 | | Categories | X | | 304 | | Classifications | | X | 305 | | Concepts | X | | 306 | | Emotion | | | 307 | | Entities | X | X | 308 | | Keywords | X | | 309 | | Metadata | X | | 310 | | Relations | X | X | 311 | | Semantic roles | X | | 312 | | Sentiment | X | | 313 | | Syntax | X | | 314 | 315 | ## Norwegian 316 | {: #norwegian} 317 | 318 | Please note that {{site.data.keyword.nlushort}} considers Norwegian (standard language code `no`) as equivalent to Norwegian-Bokmal (standard language code `nb`), and uses the same Norwegian-Bokmal model for both language codes. 319 | {: note} 320 | 321 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 322 | | --- | --- | --- | 323 | | Categories | | | 324 | | Classifications | | | 325 | | Concepts | | | 326 | | Emotion | | | 327 | | Entities | X* | | 328 | | Keywords | X | | 329 | | Metadata | | | 330 | | Relations | | | 331 | | Semantic roles | | | 332 | | Sentiment | X | | 333 | | Syntax | X | | 334 | 335 | \* Relevance ranking is not supported. 336 | 337 | ## Norwegian (Bokmal) 338 | {: #norwegian-bokmal} 339 | 340 | Please note that {{site.data.keyword.nlushort}} considers Norwegian (standard language code `no`) as equivalent to Norwegian-Bokmal (standard language code `nb`), and uses the same Norwegian-Bokmal model for both language codes. 341 | {: note} 342 | 343 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 344 | | --- | --- | --- | 345 | | Categories | | | 346 | | Classifications | | | 347 | | Concepts | | | 348 | | Emotion | | | 349 | | Entities | X* | | 350 | | Keywords | X | | 351 | | Metadata | | | 352 | | Relations | | | 353 | | Semantic roles | | | 354 | | Sentiment | X | | 355 | | Syntax | X | | 356 | 357 | \* Relevance ranking is not supported. 358 | 359 | ## Norwegian (Nyorsk) 360 | {: #norwegian-nyorsk} 361 | 362 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 363 | | --- | --- | --- | 364 | | Categories | | | 365 | | Classifications | | | 366 | | Concepts | | | 367 | | Emotion | | | 368 | | Entities | X* | | 369 | | Keywords | X | | 370 | | Metadata | | | 371 | | Relations | | | 372 | | Semantic roles | | | 373 | | Sentiment | X | | 374 | | Syntax | X | | 375 | 376 | \* Relevance ranking is not supported. 377 | 378 | ## Polish 379 | {: #polish} 380 | 381 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 382 | | --- | --- | --- | 383 | | Categories | | | 384 | | Classifications | | | 385 | | Concepts | | | 386 | | Emotion | | | 387 | | Entities | X* | | 388 | | Keywords | X | | 389 | | Metadata | | | 390 | | Relations | | | 391 | | Semantic roles | | | 392 | | Sentiment | X | | 393 | | Syntax | X | | 394 | 395 | \* Relevance ranking is not supported. 396 | 397 | ## Portuguese 398 | {: #portuguese} 399 | 400 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 401 | | --- | --- | --- | 402 | | Categories | X | | 403 | | Classifications | | X | 404 | | Concepts | X | | 405 | | Emotion | | | 406 | | Entities | X | X | 407 | | Keywords | X | | 408 | | Metadata | X | | 409 | | Relations | X | X | 410 | | Semantic roles | | | 411 | | Sentiment | X | | 412 | | Syntax | X | | 413 | 414 | ## Romanian 415 | {: #romanian} 416 | 417 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 418 | | --- | --- | --- | 419 | | Categories | | | 420 | | Classifications | | | 421 | | Concepts | | | 422 | | Emotion | | | 423 | | Entities | X* | | 424 | | Keywords | X | | 425 | | Metadata | | | 426 | | Relations | | | 427 | | Semantic roles | | | 428 | | Sentiment | X | | 429 | | Syntax | X | | 430 | 431 | \* Relevance ranking is not supported. 432 | 433 | ## Russian 434 | {: #russian} 435 | 436 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 437 | | --- | --- | --- | 438 | | Categories | | | 439 | | Classifications | | | 440 | | Concepts | | | 441 | | Emotion | | | 442 | | Entities | X* | | 443 | | Keywords | X | | 444 | | Metadata | X | | 445 | | Relations | | | 446 | | Semantic roles | | | 447 | | Sentiment | X | | 448 | | Syntax | X | | 449 | 450 | \* Relevance ranking is not supported. 451 | 452 | ## Slovak 453 | {: #slovak} 454 | 455 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 456 | | --- | --- | --- | 457 | | Categories | | | 458 | | Classifications | | | 459 | | Concepts | | | 460 | | Emotion | | | 461 | | Entities | X* | | 462 | | Keywords | X | | 463 | | Metadata | | | 464 | | Relations | | | 465 | | Semantic roles | | | 466 | | Sentiment | X | | 467 | | Syntax | X | | 468 | 469 | \* Relevance ranking is not supported. 470 | 471 | ## Spanish 472 | {: #spanish} 473 | 474 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 475 | | --- | --- | --- | 476 | | Categories | X | | 477 | | Classifications | | X | 478 | | Concepts | X | | 479 | | Emotion | | | 480 | | Entities | X | X | 481 | | Keywords | X | | 482 | | Metadata | X | | 483 | | Relations | X | X | 484 | | Semantic roles | X | | 485 | | Sentiment | X | | 486 | | Syntax | X | | 487 | 488 | ## Swedish 489 | {: #swedish} 490 | 491 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 492 | | --- | --- | --- | 493 | | Categories | | | 494 | | Classifications | | | 495 | | Concepts | | | 496 | | Emotion | | | 497 | | Entities | X* | | 498 | | Keywords | X | | 499 | | Metadata | X | | 500 | | Relations | | | 501 | | Semantic roles | | | 502 | | Sentiment | X | | 503 | | Syntax | X | | 504 | 505 | \* Relevance ranking is not supported. 506 | 507 | ## Turkish 508 | {: #turkish} 509 | 510 | | Feature | Standard Support | [Custom model](/docs/natural-language-understanding?topic=natural-language-understanding-customizing) support | 511 | | --- | --- | --- | 512 | | Categories | | | 513 | | Classifications | | | 514 | | Concepts | | | 515 | | Emotion | | | 516 | | Entities | X* | | 517 | | Keywords | X | | 518 | | Metadata | | | 519 | | Relations | | | 520 | | Semantic roles | | | 521 | | Sentiment | X | | 522 | | Syntax | X | | 523 | 524 | \* Relevance ranking is not supported. 525 | -------------------------------------------------------------------------------- /entity-types-v2.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-11-22" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:note: .note} 15 | {:pre: .pre} 16 | {:codeblock: .codeblock} 17 | {:screen: .screen} 18 | {:javascript: .ph data-hd-programlang='javascript'} 19 | {:java: .ph data-hd-programlang='java'} 20 | {:python: .ph data-hd-programlang='python'} 21 | {:swift: .ph data-hd-programlang='swift'} 22 | 23 | # Entity types (Version 2) 24 | {: #entity-types-version-2} 25 | 26 | The following tables list the entity types and subtypes that are used in the _Version 2_ entity type system. 27 | {: shortdesc} 28 | 29 | The entity type system that {{site.data.keyword.nlushort}} uses differs based on which version date and which language you are using. 30 | 31 | ## Entity types 32 | {: #types-version-2} 33 | 34 | | Entity type | 35 | | ----------------- | 36 | | Date | 37 | | Duration | 38 | | EmailAddress | 39 | | Facility | 40 | | GeographicFeature | 41 | | Hashtag | 42 | | IPAddress† | 43 | | JobTitle | 44 | | Location | 45 | | Measure | 46 | | Money | 47 | | Number* | 48 | | Ordinal | 49 | | Organization | 50 | | Percent* | 51 | | Person | 52 | | PhoneNumber* | 53 | | Time | 54 | | TwitterHandle | 55 | | URL* | 56 | 57 | * This entity type is not yet detectable in French or Japanese text. 58 | 59 | † IPv6 addresses are not yet detectable in Japanese text. 60 | 61 | ## Entity subtypes 62 | {: #subtypes-version-2} 63 | 64 | Subtypes are determined by the disambiguated entity, not the entity type. There is no strict relationship between entity types and entity subtypes. 65 | {: note} 66 | 67 | | Entity subtype | 68 | | ----------------------------------- | 69 | | AbusedSubstance | 70 | | Academic | 71 | | AcademicInstitution | 72 | | AcademicPostTitle | 73 | | AccidentType | 74 | | Accommodation | 75 | | Actor | 76 | | AdministrativeDivision | 77 | | AircraftDesigner | 78 | | AircraftManufacturer | 79 | | Airline | 80 | | AirlinerAccident | 81 | | Airport | 82 | | AirportOperator | 83 | | AmericanIndianGroup | 84 | | AminoAcid | 85 | | Animal | 86 | | AnimalBreed | 87 | | API | 88 | | Appellation | 89 | | AppointedRole | 90 | | Appointer | 91 | | Architect | 92 | | ArchitecturalContractor | 93 | | ArchitectureFirm | 94 | | ArmedForce | 95 | | Artery | 96 | | ArtSeries | 97 | | Artwork | 98 | | Asteroid | 99 | | Astronaut | 100 | | AstronomicalDiscovery | 101 | | AstronomicalObservatory | 102 | | Athlete | 103 | | AutomobileCompany | 104 | | AutomobileGeneration | 105 | | AutomobileModel | 106 | | Award | 107 | | AwardCeremony | 108 | | AwardDiscipline | 109 | | AwardJudge | 110 | | AwardNominee | 111 | | AwardPresentingOrganization | 112 | | AwardWinner | 113 | | BasketballConference | 114 | | BasketballDivision | 115 | | BasketballPlayer | 116 | | BasketballTeam | 117 | | Bassist | 118 | | Beer | 119 | | Belief | 120 | | Beverage | 121 | | BicycleManufacturer | 122 | | BipropellantRocketEngine | 123 | | Blog | 124 | | Blogger | 125 | | BoardMember | 126 | | BoardMemberTitle | 127 | | BodyOfWater | 128 | | Bone | 129 | | Book | 130 | | BookEdition | 131 | | BoxingWeightDivision | 132 | | Brand | 133 | | Bridge | 134 | | BritishRoyalty | 135 | | Broadcast | 136 | | BroadcastArtist | 137 | | BroadcastContent | 138 | | BroadcastDistributor | 139 | | Building | 140 | | BuildingComplex | 141 | | BuildingFunction | 142 | | CameraFormat | 143 | | CanadianAboriginalGroup | 144 | | CandyBar | 145 | | CandyBarManufacturer | 146 | | Cardinal | 147 | | CauseOfDeath | 148 | | Cave | 149 | | Celebrity | 150 | | CelestialObject | 151 | | Chancellor | 152 | | CharacterOccupation | 153 | | CharacterRank | 154 | | CharacterSpecies | 155 | | Cheese | 156 | | Chef | 157 | | ChemicalCompound | 158 | | ChemicalElement | 159 | | ChineseEthnicGroup | 160 | | ChristianBishop | 161 | | CityTown | 162 | | Club | 163 | | Collector | 164 | | College | 165 | | CollegeCoach | 166 | | CollegeUniversity | 167 | | Comedian | 168 | | ComicBookCreator | 169 | | ComicBookIssue | 170 | | ComicBookPublisher | 171 | | ComicBookSeries | 172 | | ComicBookStory | 173 | | ComicBookStoryArc | 174 | | ComicStripArtist | 175 | | ComicStripSyndicate | 176 | | Company | 177 | | CompanyFounder | 178 | | CompanyShareholder | 179 | | Competition | 180 | | CompetitiveSpace | 181 | | Composer | 182 | | Composition | 183 | | CompositionalForm | 184 | | ComputerPeripheral | 185 | | ComputingPlatform | 186 | | ConcertFilm | 187 | | ConcertTour | 188 | | ConductedEnsemble | 189 | | Conductor | 190 | | Conference | 191 | | ConferenceSeries | 192 | | ConsumerProduct | 193 | | ContentLicense | 194 | | Continent | 195 | | Country | 196 | | CranialNerve | 197 | | CreativeWork | 198 | | CricketAdministrativeBody | 199 | | CricketTournamentEvent | 200 | | Criminal | 201 | | CriminalOffense | 202 | | Cuisine | 203 | | CulinaryMeasure | 204 | | CulinaryTool | 205 | | DedicatedWork | 206 | | Dedicatee | 207 | | Dedicator | 208 | | Degree | 209 | | Deity | 210 | | DietFollower | 211 | | DigitalCamera | 212 | | DisasterSurvivor | 213 | | Disease | 214 | | DiseaseCause | 215 | | DiseaseOrMedicalCondition | 216 | | Dish | 217 | | DomesticatedAnimal | 218 | | DrinkingEstablishment | 219 | | Drug | 220 | | Election | 221 | | ElectionCampaign | 222 | | EndorsedProduct | 223 | | Engine | 224 | | Facility | 225 | | Family | 226 | | FamilyName | 227 | | FashionLabel | 228 | | FictionalCreature | 229 | | FictionalJobTitle | 230 | | FictionalUniverse | 231 | | FictionalUniverseCreator | 232 | | FieldOfStudy | 233 | | FileFormat | 234 | | Film | 235 | | FilmActor | 236 | | FilmCharacter | 237 | | FilmCinematographer | 238 | | FilmCompany | 239 | | FilmCritic | 240 | | FilmDirector | 241 | | FilmDistributor | 242 | | FilmEditor | 243 | | FilmFestival | 244 | | FilmFestivalEvent | 245 | | FilmFestivalFocus | 246 | | FilmJob | 247 | | FilmMusicContributor | 248 | | FilmProducer | 249 | | FilmSeries | 250 | | FilmWriter | 251 | | FootballCompetition | 252 | | FootballDivision | 253 | | FootballLeague | 254 | | FootballManager | 255 | | FootballMatch | 256 | | FootballOrganization | 257 | | FootballPlayer | 258 | | FootballPosition | 259 | | FootballTeam | 260 | | FootballWorldCup | 261 | | Galaxy | 262 | | Game | 263 | | GameDesigner | 264 | | GameExpansion | 265 | | GamePublisher | 266 | | GeneralElection | 267 | | GeographicFeature | 268 | | GovernmentAgency | 269 | | GovernmentalBody | 270 | | GovernmentOfficeOrTitle | 271 | | Governor | 272 | | Guitar | 273 | | Guitarist | 274 | | HallOfFame | 275 | | HallOfFameInductee | 276 | | HistoricPlace | 277 | | Hobby | 278 | | HockeyCoach | 279 | | HockeyConference | 280 | | HockeyDivision | 281 | | HockeyPlayer | 282 | | HockeyTeam | 283 | | Holiday | 284 | | Hormone | 285 | | Hospital | 286 | | House | 287 | | HumanLanguage | 288 | | Illustrator | 289 | | Industry | 290 | | InfectiousDisease | 291 | | Interest | 292 | | InternetProtocol | 293 | | Invention | 294 | | Inventor | 295 | | Island | 296 | | JobTitle | 297 | | Journal | 298 | | Journalist | 299 | | Judge | 300 | | Kingdom | 301 | | Lake | 302 | | LanguageDialect | 303 | | LanguageFamily | 304 | | LanguageWritingSystem | 305 | | LaunchSite | 306 | | LegislativeCommittee | 307 | | Legislature | 308 | | Ligament | 309 | | Lighthouse | 310 | | LiterarySchoolOrMovement | 311 | | Location | 312 | | Magazine | 313 | | ManufacturingPlant | 314 | | MartialArt | 315 | | MartialArtsOrganization | 316 | | Mascot | 317 | | Material | 318 | | Mayor | 319 | | MeansOfPropulsion | 320 | | MedicalSpecialty | 321 | | MedicalTreatment | 322 | | MemberOfParliament | 323 | | MeteorologicalService | 324 | | MeteorShower | 325 | | MilitaryConflict | 326 | | MilitaryPerson | 327 | | MilitaryPost | 328 | | MilitaryUnit | 329 | | Model | 330 | | Monarch | 331 | | Mountain | 332 | | MultipartTVEpisode | 333 | | Muscle | 334 | | Museum | 335 | | MusicalAlbum | 336 | | MusicalArtist | 337 | | MusicalGameSong | 338 | | MusicalGroup | 339 | | MusicalGroupMember | 340 | | MusicalInstrumentCompany | 341 | | MusicalPerformanceRole | 342 | | MusicalRelease | 343 | | MusicalTrack | 344 | | MusicFestival | 345 | | NaturalOrCulturalPreservationAgency | 346 | | Nerve | 347 | | Newspaper | 348 | | NobleRank | 349 | | NobleTitle | 350 | | Non-ProfitOrganisation | 351 | | Nutrient | 352 | | OfficeHolder | 353 | | OilField | 354 | | OlympicAthlete | 355 | | OlympicDemonstrationCompetition | 356 | | OlympicEvent | 357 | | OlympicEventCompetition | 358 | | OlympicGames | 359 | | Opera | 360 | | OperaCharacter | 361 | | OperaCompany | 362 | | OperaHouse | 363 | | OperaLibretto | 364 | | OperatingSystem | 365 | | OperatingSystemDeveloper | 366 | | OrganismClassification | 367 | | Organization | 368 | | OrganizationCommittee | 369 | | OrganizationSector | 370 | | Park | 371 | | ParliamentaryElection | 372 | | PeriodicalPublisher | 373 | | Person | 374 | | PersonalAppearanceRole | 375 | | Philosopher | 376 | | Physician | 377 | | Play | 378 | | Poem | 379 | | PoeticVerseForm | 380 | | PoliticalDistrict | 381 | | PoliticalIdeology | 382 | | PoliticalParty | 383 | | Politician | 384 | | Prayer | 385 | | ProductionCompany | 386 | | Profession | 387 | | ProfessionalField | 388 | | ProgrammingLanguage | 389 | | ProgrammingLanguageDesigner | 390 | | ProjectParticipant | 391 | | ProtectedArea | 392 | | Protein | 393 | | Protocol | 394 | | ProtocolProvider | 395 | | PublicLibrary | 396 | | PublicSpeakingEvent | 397 | | PublishedWork | 398 | | Quantity | 399 | | RadioFormat | 400 | | RadioNetwork | 401 | | RadioStation | 402 | | Rank | 403 | | RecordLabel | 404 | | RecordProducer | 405 | | RecurringEvent | 406 | | Religion | 407 | | ReligiousLeadershipRole | 408 | | ReligiousOrganization | 409 | | ReligiousPractice | 410 | | ReligiousText | 411 | | ReportIssuingInstitution | 412 | | RiskFactor | 413 | | River | 414 | | Road | 415 | | Rocket | 416 | | RocketEngine | 417 | | RocketEngineFuel | 418 | | RocketFuel | 419 | | RocketFunction | 420 | | RocketManufacturer | 421 | | Saint | 422 | | Satellite | 423 | | School | 424 | | SchoolDistrict | 425 | | SchoolMascot | 426 | | SchoolNewspaper | 427 | | SchoolSportsTeam | 428 | | Scientist | 429 | | ShipBuilder | 430 | | ShoppingCenter | 431 | | ShortStory | 432 | | SkiArea | 433 | | Skyscraper | 434 | | SoccerClub | 435 | | Software | 436 | | SoftwareDeveloper | 437 | | SoftwareLicense | 438 | | Soundtrack | 439 | | SpaceAgency | 440 | | Spacecraft | 441 | | SpaceMission | 442 | | Spaceport | 443 | | Sport | 444 | | SportsAssociation | 445 | | SportsEquipment | 446 | | SportsLeagueChampionship | 447 | | SportsLeagueChampionshipEvent | 448 | | SportsLeagueDraft | 449 | | SportsOfficial | 450 | | SportsTeam | 451 | | Stadium | 452 | | Star | 453 | | StarSystem | 454 | | StarSystemBody | 455 | | Station | 456 | | Supercouple | 457 | | Symptom | 458 | | Synthesizer | 459 | | Telescope | 460 | | TelescopePlatform | 461 | | TelevisionShow | 462 | | TennisPlayer | 463 | | TennisTournament | 464 | | Theater | 465 | | TheaterCharacter | 466 | | TheaterProduction | 467 | | TopLevelDomainRegistry | 468 | | TouristAttraction | 469 | | Tower | 470 | | TradeUnion | 471 | | TransitLine | 472 | | TransportOperator | 473 | | TransportTerminus | 474 | | TropicalCyclone | 475 | | TVActor | 476 | | TVCharacter | 477 | | TVCrewRole | 478 | | TVEpisode | 479 | | TVNetwork | 480 | | TVPersonality | 481 | | TVProducer | 482 | | TVSeason | 483 | | TVWriter | 484 | | TypeOfPlaceOfWorship | 485 | | UnfinishedWork | 486 | | UnitOfMass | 487 | | UnitOfVolume | 488 | | University | 489 | | U.S.Congressperson | 490 | | Vein | 491 | | VideoGame | 492 | | VideoGameDesigner | 493 | | VideoGameDeveloper | 494 | | VideoGameEngine | 495 | | VideoGamePlatform | 496 | | VideoGamePublisher | 497 | | VisualArtist | 498 | | WebBrowserExtension | 499 | | Website | 500 | | WineProducer | 501 | | WineRegion | 502 | | WorkOfFiction | 503 | | Writer | 504 | -------------------------------------------------------------------------------- /entity-types-v1.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2015, 2020 5 | lastupdated: "2020-02-24" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:new_window: target="_blank"} 13 | {:tip: .tip} 14 | {:note: .note} 15 | {:deprecated: .deprecated} 16 | {:pre: .pre} 17 | {:codeblock: .codeblock} 18 | {:screen: .screen} 19 | {:javascript: .ph data-hd-programlang='javascript'} 20 | {:java: .ph data-hd-programlang='java'} 21 | {:python: .ph data-hd-programlang='python'} 22 | {:swift: .ph data-hd-programlang='swift'} 23 | 24 | # Entity types (Version 1) 25 | {: #entity-types-version-1} 26 | 27 | The _Version 1_ entity type system is deprecated. As of 11 July 2023, the v1 Entities type system will no longer be available. To understand which _Version 1_ entity types have been added to or removed in _Version 2_, see [Version 1 deprecation notes](/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems#version-1-deprecation-notes). 28 | {: deprecated} 29 | 30 | The following tables list the entity types and subtypes that are used in the _Version 1_ entity type system. 31 | {: shortdesc} 32 | 33 | The entity type system that {{site.data.keyword.nlushort}} uses differs based on which version date and which language you are using. For more details, see the [Entity type systems](/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems) page. 34 | 35 | ## Entity types 36 | {: #entity-types} 37 | 38 | | Entity type | 39 | |-------------------| 40 | | Anatomy | 41 | | Award | 42 | | Broadcaster | 43 | | Company | 44 | | Crime | 45 | | Drug | 46 | | EmailAddress | 47 | | Facility | 48 | | GeographicFeature | 49 | | HealthCondition | 50 | | Hashtag | 51 | | IPAddress | 52 | | JobTitle | 53 | | Location | 54 | | Movie | 55 | | MusicGroup | 56 | | NaturalEvent | 57 | | Organization | 58 | | Person | 59 | | PrintMedia | 60 | | Quantity | 61 | | Sport | 62 | | SportingEvent | 63 | | TelevisionShow | 64 | | TwitterHandle | 65 | | Vehicle | 66 | 67 | ## Entity subtypes 68 | {: #entity-subtypes} 69 | 70 | Subtypes are determined by the disambiguated entity, not the entity type. There is no strict relationship between entity types and entity subtypes. 71 | {: note} 72 | 73 | | Entity subtype | 74 | |-------------------------------------| 75 | | AbusedSubstance | 76 | | Academic | 77 | | AcademicInstitution | 78 | | AcademicPostTitle | 79 | | AccidentType | 80 | | Accommodation | 81 | | Actor | 82 | | AdministrativeDivision | 83 | | AircraftDesigner | 84 | | AircraftManufacturer | 85 | | Airline | 86 | | AirlinerAccident | 87 | | Airport | 88 | | AirportOperator | 89 | | AmericanIndianGroup | 90 | | AminoAcid | 91 | | Animal | 92 | | AnimalBreed | 93 | | API | 94 | | Appellation | 95 | | AppointedRole | 96 | | Appointer | 97 | | Architect | 98 | | ArchitecturalContractor | 99 | | ArchitectureFirm | 100 | | ArmedForce | 101 | | Artery | 102 | | ArtSeries | 103 | | Artwork | 104 | | Asteroid | 105 | | Astronaut | 106 | | AstronomicalDiscovery | 107 | | AstronomicalObservatory | 108 | | Athlete | 109 | | AutomobileCompany | 110 | | AutomobileGeneration | 111 | | AutomobileModel | 112 | | Award | 113 | | AwardCeremony | 114 | | AwardDiscipline | 115 | | AwardJudge | 116 | | AwardNominee | 117 | | AwardPresentingOrganization | 118 | | AwardWinner | 119 | | BasketballConference | 120 | | BasketballDivision | 121 | | BasketballPlayer | 122 | | BasketballTeam | 123 | | Bassist | 124 | | Beer | 125 | | Belief | 126 | | Beverage | 127 | | BicycleManufacturer | 128 | | BipropellantRocketEngine | 129 | | Blog | 130 | | Blogger | 131 | | BoardMember | 132 | | BoardMemberTitle | 133 | | BodyOfWater | 134 | | Bone | 135 | | Book | 136 | | BookEdition | 137 | | BoxingWeightDivision | 138 | | Brand | 139 | | Bridge | 140 | | BritishRoyalty | 141 | | Broadcast | 142 | | BroadcastArtist | 143 | | BroadcastContent | 144 | | BroadcastDistributor | 145 | | Building | 146 | | BuildingComplex | 147 | | BuildingFunction | 148 | | CameraFormat | 149 | | CanadianAboriginalGroup | 150 | | CandyBar | 151 | | CandyBarManufacturer | 152 | | Cardinal | 153 | | CauseOfDeath | 154 | | Cave | 155 | | Celebrity | 156 | | CelestialObject | 157 | | Chancellor | 158 | | CharacterOccupation | 159 | | CharacterRank | 160 | | CharacterSpecies | 161 | | Cheese | 162 | | Chef | 163 | | ChemicalCompound | 164 | | ChemicalElement | 165 | | ChineseEthnicGroup | 166 | | ChristianBishop | 167 | | CityTown | 168 | | Club | 169 | | Collector | 170 | | College | 171 | | CollegeCoach | 172 | | CollegeUniversity | 173 | | Comedian | 174 | | ComicBookCreator | 175 | | ComicBookIssue | 176 | | ComicBookPublisher | 177 | | ComicBookSeries | 178 | | ComicBookStory | 179 | | ComicBookStoryArc | 180 | | ComicStripArtist | 181 | | ComicStripSyndicate | 182 | | Company | 183 | | CompanyFounder | 184 | | CompanyShareholder | 185 | | Competition | 186 | | CompetitiveSpace | 187 | | Composer | 188 | | Composition | 189 | | CompositionalForm | 190 | | ComputerPeripheral | 191 | | ComputingPlatform | 192 | | ConcertFilm | 193 | | ConcertTour | 194 | | ConductedEnsemble | 195 | | Conductor | 196 | | Conference | 197 | | ConferenceSeries | 198 | | ConsumerProduct | 199 | | ContentLicense | 200 | | Continent | 201 | | Country | 202 | | CranialNerve | 203 | | CreativeWork | 204 | | CricketAdministrativeBody | 205 | | CricketTournamentEvent | 206 | | Criminal | 207 | | CriminalOffense | 208 | | Cuisine | 209 | | CulinaryMeasure | 210 | | CulinaryTool | 211 | | DedicatedWork | 212 | | Dedicatee | 213 | | Dedicator | 214 | | Degree | 215 | | Deity | 216 | | DietFollower | 217 | | DigitalCamera | 218 | | DisasterSurvivor | 219 | | Disease | 220 | | DiseaseCause | 221 | | DiseaseOrMedicalCondition | 222 | | Dish | 223 | | DomesticatedAnimal | 224 | | DrinkingEstablishment | 225 | | Drug | 226 | | Election | 227 | | ElectionCampaign | 228 | | EndorsedProduct | 229 | | Engine | 230 | | Facility | 231 | | Family | 232 | | FamilyName | 233 | | FashionLabel | 234 | | FictionalCreature | 235 | | FictionalJobTitle | 236 | | FictionalUniverse | 237 | | FictionalUniverseCreator | 238 | | FieldOfStudy | 239 | | FileFormat | 240 | | Film | 241 | | FilmActor | 242 | | FilmCharacter | 243 | | FilmCinematographer | 244 | | FilmCompany | 245 | | FilmCritic | 246 | | FilmDirector | 247 | | FilmDistributor | 248 | | FilmEditor | 249 | | FilmFestival | 250 | | FilmFestivalEvent | 251 | | FilmFestivalFocus | 252 | | FilmJob | 253 | | FilmMusicContributor | 254 | | FilmProducer | 255 | | FilmSeries | 256 | | FilmWriter | 257 | | FootballCompetition | 258 | | FootballDivision | 259 | | FootballLeague | 260 | | FootballManager | 261 | | FootballMatch | 262 | | FootballOrganization | 263 | | FootballPlayer | 264 | | FootballPosition | 265 | | FootballTeam | 266 | | FootballWorldCup | 267 | | Galaxy | 268 | | Game | 269 | | GameDesigner | 270 | | GameExpansion | 271 | | GamePublisher | 272 | | GeneralElection | 273 | | GeographicFeature | 274 | | GovernmentAgency | 275 | | GovernmentalBody | 276 | | GovernmentOfficeOrTitle | 277 | | Governor | 278 | | Guitar | 279 | | Guitarist | 280 | | HallOfFame | 281 | | HallOfFameInductee | 282 | | HistoricPlace | 283 | | Hobby | 284 | | HockeyCoach | 285 | | HockeyConference | 286 | | HockeyDivision | 287 | | HockeyPlayer | 288 | | HockeyTeam | 289 | | Holiday | 290 | | Hormone | 291 | | Hospital | 292 | | House | 293 | | HumanLanguage | 294 | | Illustrator | 295 | | Industry | 296 | | InfectiousDisease | 297 | | Interest | 298 | | InternetProtocol | 299 | | Invention | 300 | | Inventor | 301 | | Island | 302 | | JobTitle | 303 | | Journal | 304 | | Journalist | 305 | | Judge | 306 | | Kingdom | 307 | | Lake | 308 | | LanguageDialect | 309 | | LanguageFamily | 310 | | LanguageWritingSystem | 311 | | LaunchSite | 312 | | LegislativeCommittee | 313 | | Legislature | 314 | | Ligament | 315 | | Lighthouse | 316 | | LiterarySchoolOrMovement | 317 | | Location | 318 | | Magazine | 319 | | ManufacturingPlant | 320 | | MartialArt | 321 | | MartialArtsOrganization | 322 | | Mascot | 323 | | Material | 324 | | Mayor | 325 | | MeansOfPropulsion | 326 | | MedicalSpecialty | 327 | | MedicalTreatment | 328 | | MemberOfParliament | 329 | | MeteorologicalService | 330 | | MeteorShower | 331 | | MilitaryConflict | 332 | | MilitaryPerson | 333 | | MilitaryPost | 334 | | MilitaryUnit | 335 | | Model | 336 | | Monarch | 337 | | Mountain | 338 | | MultipartTVEpisode | 339 | | Muscle | 340 | | Museum | 341 | | MusicalAlbum | 342 | | MusicalArtist | 343 | | MusicalGameSong | 344 | | MusicalGroup | 345 | | MusicalGroupMember | 346 | | MusicalInstrumentCompany | 347 | | MusicalPerformanceRole | 348 | | MusicalRelease | 349 | | MusicalTrack | 350 | | MusicFestival | 351 | | NaturalOrCulturalPreservationAgency | 352 | | Nerve | 353 | | Newspaper | 354 | | NobleRank | 355 | | NobleTitle | 356 | | Non-ProfitOrganisation | 357 | | Nutrient | 358 | | OfficeHolder | 359 | | OilField | 360 | | OlympicAthlete | 361 | | OlympicDemonstrationCompetition | 362 | | OlympicEvent | 363 | | OlympicEventCompetition | 364 | | OlympicGames | 365 | | Opera | 366 | | OperaCharacter | 367 | | OperaCompany | 368 | | OperaHouse | 369 | | OperaLibretto | 370 | | OperatingSystem | 371 | | OperatingSystemDeveloper | 372 | | OrganismClassification | 373 | | Organization | 374 | | OrganizationCommittee | 375 | | OrganizationSector | 376 | | Park | 377 | | ParliamentaryElection | 378 | | PeriodicalPublisher | 379 | | Person | 380 | | PersonalAppearanceRole | 381 | | Philosopher | 382 | | Physician | 383 | | Play | 384 | | Poem | 385 | | PoeticVerseForm | 386 | | PoliticalDistrict | 387 | | PoliticalIdeology | 388 | | PoliticalParty | 389 | | Politician | 390 | | Prayer | 391 | | ProductionCompany | 392 | | Profession | 393 | | ProfessionalField | 394 | | ProgrammingLanguage | 395 | | ProgrammingLanguageDesigner | 396 | | ProjectParticipant | 397 | | ProtectedArea | 398 | | Protein | 399 | | Protocol | 400 | | ProtocolProvider | 401 | | PublicLibrary | 402 | | PublicSpeakingEvent | 403 | | PublishedWork | 404 | | RadioFormat | 405 | | RadioNetwork | 406 | | RadioStation | 407 | | Rank | 408 | | RecordLabel | 409 | | RecordProducer | 410 | | RecurringEvent | 411 | | Religion | 412 | | ReligiousLeadershipRole | 413 | | ReligiousOrganization | 414 | | ReligiousPractice | 415 | | ReligiousText | 416 | | ReportIssuingInstitution | 417 | | RiskFactor | 418 | | River | 419 | | Road | 420 | | Rocket | 421 | | RocketEngine | 422 | | RocketEngineFuel | 423 | | RocketFuel | 424 | | RocketFunction | 425 | | RocketManufacturer | 426 | | Saint | 427 | | Satellite | 428 | | School | 429 | | SchoolDistrict | 430 | | SchoolMascot | 431 | | SchoolNewspaper | 432 | | SchoolSportsTeam | 433 | | Scientist | 434 | | ShipBuilder | 435 | | ShoppingCenter | 436 | | ShortStory | 437 | | SkiArea | 438 | | Skyscraper | 439 | | SoccerClub | 440 | | Software | 441 | | SoftwareDeveloper | 442 | | SoftwareLicense | 443 | | Soundtrack | 444 | | SpaceAgency | 445 | | Spacecraft | 446 | | SpaceMission | 447 | | Spaceport | 448 | | Sport | 449 | | SportsAssociation | 450 | | SportsEquipment | 451 | | SportsLeagueChampionship | 452 | | SportsLeagueChampionshipEvent | 453 | | SportsLeagueDraft | 454 | | SportsOfficial | 455 | | SportsTeam | 456 | | Stadium | 457 | | Star | 458 | | StarSystem | 459 | | StarSystemBody | 460 | | Station | 461 | | Supercouple | 462 | | Symptom | 463 | | Synthesizer | 464 | | Telescope | 465 | | TelescopePlatform | 466 | | TelevisionShow | 467 | | TennisPlayer | 468 | | TennisTournament | 469 | | Theater | 470 | | TheaterCharacter | 471 | | TheaterProduction | 472 | | TopLevelDomainRegistry | 473 | | TouristAttraction | 474 | | Tower | 475 | | TradeUnion | 476 | | TransitLine | 477 | | TransportOperator | 478 | | TransportTerminus | 479 | | TropicalCyclone | 480 | | TVActor | 481 | | TVCharacter | 482 | | TVCrewRole | 483 | | TVEpisode | 484 | | TVNetwork | 485 | | TVPersonality | 486 | | TVProducer | 487 | | TVSeason | 488 | | TVWriter | 489 | | TypeOfPlaceOfWorship | 490 | | UnfinishedWork | 491 | | UnitOfMass | 492 | | UnitOfVolume | 493 | | University | 494 | | U.S.Congressperson | 495 | | Vein | 496 | | VideoGame | 497 | | VideoGameDesigner | 498 | | VideoGameDeveloper | 499 | | VideoGameEngine | 500 | | VideoGamePlatform | 501 | | VideoGamePublisher | 502 | | VisualArtist | 503 | | WebBrowserExtension | 504 | | Website | 505 | | WineProducer | 506 | | WineRegion | 507 | | WorkOfFiction | 508 | | Writer | 509 | 510 | ## Relations entity types 511 | {: #relations-entity-types} 512 | 513 | For languages that use the _Version 1_ entity type system that also support relations, relations results contain entity types that are different from the entity types returned in entities results. To return the relations entity types in your entities results, you can specify one of the following public entity models in the `model` option for the `entities` feature to override the default entity detection model. 514 | 515 | |Model ID|Description| 516 | |--------|-----------| 517 | |ar-news|Arabic news| 518 | |en-news|English news| 519 | |es-news|Spanish news| 520 | 521 | The following entity types can be identified with the relations entity models: 522 | 523 | |Entity type| 524 | |---| 525 | |Age| 526 | |Anatomy| 527 | |Animal| 528 | |Award| 529 | |Cardinal| 530 | |Crime| 531 | |Date| 532 | |Degree| 533 | |Duration| 534 | |EmailAddress| 535 | |Event| 536 | |EventBusiness| 537 | |EventCommunication| 538 | |EventCustody| 539 | |EventDemonstration| 540 | |EventEducation| 541 | |EventElection| 542 | |EventGathering| 543 | |EventLegal| 544 | |EventLegislation| 545 | |EventMeeting| 546 | |EventPerformance| 547 | |EventPersonnel| 548 | |EventViolence| 549 | |Facility| 550 | |Food| 551 | |GeographicFeature| 552 | |GeopoliticalEntity| 553 | |HealthCondition| 554 | |Law| 555 | |Location| 556 | |Money| 557 | |Measure| 558 | |NaturalEvent| 559 | |Organization| 560 | |Ordinal| 561 | |Percent| 562 | |Person| 563 | |Phone| 564 | |Plant| 565 | |Product| 566 | |SportingEvent| 567 | |Substance| 568 | |Ticker| 569 | |Time| 570 | |TitleWork| 571 | |Vehicle| 572 | |Weapon| 573 | |Weather| 574 | |Web| 575 | 576 | -------------------------------------------------------------------------------- /migrate-to-watson-nlp.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | copyright: 4 | years: 2025 5 | lastupdated: "2025-08-22" 6 | 7 | subcollection: natural-language-understanding 8 | 9 | --- 10 | 11 | {:shortdesc: .shortdesc} 12 | {:external: target="_blank" .external} 13 | {:tip: .tip} 14 | {:pre: .pre} 15 | {:codeblock: .codeblock} 16 | {:screen: .screen} 17 | {:javascript: .ph data-hd-programlang='javascript'} 18 | {:java: .ph data-hd-programlang='java'} 19 | {:python: .ph data-hd-programlang='python'} 20 | 21 | # Migrating to Watson Natural Language Processing in watsonx.ai Studio 22 | {: #migrating-to-watson-nlp} 23 | 24 | ## Useful links 25 | {: #useful-links} 26 | 27 | - [Watson NLU API documentation](https://cloud.ibm.com/apidocs/natural-language-understanding) 28 | - [Watson NLP in watsonx.ai Studio in IBM Cloud documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp.html?context=wx&audience=wdp) 29 | - [Watson NLP in watsonx.ai Studio in CloudPak for Data docs](https://www.ibm.com/docs/en/cloud-paks/cp-data/5.2.x?topic=scripts-watson-natural-language-processing) 30 | 31 | ## Overview 32 | {: #overview} 33 | 34 | Watson Natural Language Understanding (NLU) consists of a set of APIs to analyze various features of text content at scale. You can submit plain text, raw HTML, or a public URL and receive results for the features you request through NLU. To analyze text, Watson NLU uses Watson NLP as its underlying processing framework. 35 | 36 | In watsonx.ai Studio, all Watson NLP models are available as a Python library. You can access these models from notebooks or deploy them as Python functions or scripts. Both online and batch deployment options are available for use. 37 | 38 | ## Migration process 39 | {: #migration-process} 40 | 41 | To migrate from Watson NLU to watsonx.ai Studio with Watson NLP, see the following process. 42 | 43 | ### 1. Install the prerequisites 44 | 45 | Prepare your instance of watsonx.ai Studio. You can migrate to watsonx.ai Studio with Watson NLP in SaaS IBM Cloud environment, or using your own on-prem environment. 46 | 47 | #### For watsonx.ai Studio SaaS in IBM Cloud: 48 | 1. Create an instance of [watsonx.ai Studio](https://cloud.ibm.com/catalog/services/watsonxai-studio). 49 | 1. Create an instance of the [Watson Machine Learning (WML) service](https://cloud.ibm.com/catalog/services/watson-machine-learning). 50 | 51 | #### For watsonx.ai Studio on-prem in CPD: 52 | 2. Configure using [IBM Sales Configurator](https://app.ibmsalesconfigurator.com/#/watsonxCPD/home) and ensure you have the following services selected (note these services are selected by default): Watson Studio and Watson Machine Learning 53 | 3. Install the NLP models that you need for your application. For instructions, see [Installing pre-trained NLP models for Python-based notebook runtimes](https://www.ibm.com/docs/en/software-hub/5.1.x?topic=studio-post-installation-setup#nlp). 54 | 55 | ### 2. Identify the corresponding model in watsonx.ai Studio 56 | To identify the corresponding model in watsonx.ai Studio with Watson NLP, see the section titled [Model mapping](#model-mapping). 57 | 58 | ### 3. Write a Python function 59 | Write a Python function that takes a string as input and returns the output of the NLP model applied to that text. See [Model mapping](#model-mapping) on how to identify the code snippet to use in the Python function. Watson NLU and watsonx.ai Studio may not produce the same output schema. 60 | 61 | ### 4. Deploy the Python function 62 | {: #4-deploy-the-python-function} 63 | Deploy the Python function as an online deployment. Use the following documentation for deploying NLP models: 64 | 65 | #### In watsonx.ai Studio SaaS in IBM Cloud 66 | 67 | - [Documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-NLP-model.html?context=wx&audience=wdp) 68 | - [Sample notebook](https://www.ibm.com/docs/en/cloud-paks/cp-data/5.2.x?topic=assets-deploying-nlp-models#nlp-model-deployment-examples) 69 | 70 | #### In watsonx.ai Studio on-prem in CPD 71 | 72 | - [Documentation](https://www.ibm.com/docs/en/cloud-paks/cp-data/5.2.x?topic=assets-deploying-nlp-models) 73 | - [Sample notebook](https://www.ibm.com/docs/en/cloud-paks/cp-data/5.2.x?topic=assets-deploying-nlp-models#nlp-model-deployment-examples) 74 | 75 | ### 5. Sizing and pricing 76 | 77 | Every Watson NLP model has its own runtime performance characteristics. Therefore, every API call may take more or less compute, depending on the actual model that is executed. For example, syntax is much faster than a transformer-based entity extractor. 78 | 79 | To estimate the necessary scale-out of deployed Python functions to meet a specific application workload using Watson NLP in watsonx.ai Studio, see the following guidance: 80 | 81 | 1. Measure the runtime performance (throughput) of the model in their environment 82 | 2. Use the results from step 1 to estimate the scale-up required to meet your application’s throughput needs. 83 | 84 | Pricing in watsonx.ai Studio: 85 | 1. In SaaS IBM Cloud, the pricing is based on CUH (Compute unit Hours). Once you estimate the scale out needed, you can estimate your price in CUH accordingly. To find the pricing for your specific plan, see [watsonx.ai Studio plan](https://cloud.ibm.com/catalog/services/watsonxai-studio). As of January 10, 2025, pricing is defined by the compute hours for the base environment based on the vCPU/RAM chosen plus an up-charge of 5 CUH for the NLP environment. For example, running a Notebook NLP environment with 16 vCPU/64 GB costs 13 (8+5) capacity unit per hour and price for one capacity unit is $1.02 in the professional plan. 86 | 2. In on-prem in CPD, pricing is per VPC. Your throughput measurements can be used to estimate the number of VPCs needed. 87 | 88 | For additional assistance with calculating costs, please contact IBM Sales. 89 | 90 | ## Example for Tone Classification 91 | {: #example-for-tone-classification} 92 | 93 | This section exemplifies Steps 2 and 3 for the Tone Classification model. 94 | 95 | ### Step 2: Identify the model in watsonx.ai Studio 96 | Using Watson NLU [Tone Classification](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-tone_analytics) involves calling this API: 97 | ```sh 98 | curl \ 99 | -X POST \ 100 | -u "apikey:" \ 101 | -H "Content-Type: application/json" \ 102 | -d '{ 103 | "text": "Yummy affordable bread that is great for parties! I would describe like a sweeter tiny pandesal bread. They heat up the bread post transaction so it always comes up nice and fresh. Expect about a 10 minute wait for that. The wait can be unpredictable though. I came on a Sunday, no line, but after I paid. There was a line out the door. Place is very tiny so expect to be a little cramped if it gets busy. So happy I dont have to drive all the way to Chula Vista to try starbread!", 104 | "features": { 105 | "classifications": { 106 | "model": "tone-classifications-en-v1" 107 | } 108 | }, 109 | "return_analyzed_text": false 110 | }' \ 111 | "https://api.us-south.natural-language-understanding.watson.cloud.ibm.com/v1/analyze?version=2025-04-07" 112 | ``` 113 | Which produces this response: 114 | ```json 115 | { 116 | "usage": 117 | { 118 | "text_units": 1, 119 | "text_characters": 480, 120 | "features": 1 121 | }, 122 | "language": "en", 123 | "classifications": [ 124 | { 125 | "confidence": 0.167542, 126 | "class_name": "frustrated" 127 | }, 128 | { 129 | "confidence": 0.157899, 130 | "class_name": "sad" 131 | }, 132 | { 133 | "confidence": 0.154908, 134 | "class_name": "excited" 135 | }, 136 | { 137 | "confidence": 0.141476, 138 | "class_name": "polite" 139 | }, 140 | { 141 | "confidence": 0.053681, 142 | "class_name": "satisfied" 143 | }, 144 | { 145 | "confidence": 0.0419, 146 | "class_name": "sympathetic" 147 | }, 148 | { 149 | "confidence": 0.013666, 150 | "class_name": "impolite" 151 | } 152 | ] 153 | } 154 | ``` 155 | 156 | The corresponding Tone Classification models in watsonx.ai Studio models are documented [here](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-tone.html?context=cpdaas&audience=wdp): 157 | - ensemble_classification-workflow_en_tone-stock 158 | - ensemble_classification-workflow_fr_tone-stock 159 | 160 | The Python code snippet to invoke the model in a notebook is also documented in the same page: 161 | ```py 162 | import watson_nlp 163 | # Load Tone Classification model for English 164 | tone_workflow=watson_nlp.download_and_load("ensemble_classification-wf_v2-3-1_lang_en_tone-stock_2022-02-01-100000") 165 | # Run the tone classification model on the input text 166 | tone_workflow.run(breadReview) 167 | 168 | # Print the classified tone 169 | print(tone_ workflow) 170 | ``` 171 | And produces this response: 172 | 173 | ```json 174 | { 175 | "classes": [ 176 | { 177 | "class_name": "frustrated", 178 | "confidence": 0.1675415905898042 179 | }, 180 | { 181 | "class_name": "sad", 182 | "confidence": 0.15789897138055303 183 | }, 184 | { 185 | "class_name": "excited", 186 | "confidence": 0.15490848593639606 187 | }, 188 | { 189 | "class_name": "polite", 190 | "confidence": 0.14147561901446545 191 | }, 192 | { 193 | "class_name": "satisfied", 194 | "confidence": 0.053680803683219536 195 | }, 196 | { 197 | "class_name": "sympathetic", 198 | "confidence": 0.04189955103069996 199 | }, 200 | { 201 | "class_name": "impolite", 202 | "confidence": 0.013665584500951369 203 | } 204 | ], 205 | "producer_id": { 206 | "name": "Voting based Ensemble", 207 | "version": "0.0.1" 208 | } 209 | } 210 | ``` 211 | ### Step 3: Write a Python function 212 | Wrap the code snippet below in a Python function that takes a string as input and outputs the response of the model. Here is an example from the [Sample Notebook](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/4fbabbab-c553-4554-bab8-3b3b8f1c33e6?context=cpdaas?context=wx&audience=wdp): 213 | ```py 214 | def detect_tone(): 215 | import watson_nlp 216 | 217 | tone_model = tone_classification_model = watson_nlp.load(' ensemble_classification-workflow_en_tone-stock ') 218 | 219 | def score(input): 220 | scoring_prediction_out = [] 221 | for input_data_row in input["input_data"][0]["values"]: 222 | scoring_prediction_row = [] 223 | for input_data in input_data_row: 224 | tone_classification = tone_classification_model.run(input_data) 225 | scoring_prediction_row.append(tone_classification.to_dict()) 226 | 227 | scoring_prediction_out.append(scoring_prediction_row) 228 | 229 | # Score using the pre-defined model 230 | scoring_response = { 231 | 'predictions': [{'fields': ['nlp_prediction'], 232 | 'values': scoring_prediction_out 233 | }] 234 | } 235 | 236 | return scoring_response 237 | 238 | return score 239 | ``` 240 | 241 | Follow the documentation to [Deploy a Watson NLP model as a Python function](#4-deploy-the-python-function). 242 | 243 | ## Model mapping 244 | {: #model-mapping} 245 | 246 | This section describes the correspondence between Watson NLU features, and the corresponding models in watsonx.ai Studio with Watson NLP, as well as pointers to the code snippet necessary to implement the Python function necessary to expose NLP model as an online deployment in watsonx.ai. 247 | 248 | ### Categories 249 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#categories) 250 | Note: The Categories feature in Watson NLP is only available in the English language. 251 | 252 | Watsonx.ai Studio models: 253 | - categories_esa_en_stock 254 | 255 | [Watsonx.ai Studio code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-hierarchical-cat.html) 256 | 257 | #### Transforming Watson NLP response 258 | ```py 259 | def transform_categories(wnlp_response): 260 | transformed_categories = [] 261 | 262 | for prediction in wnlp_response['predictions']: 263 | categories = prediction['values'][0][0]['categories'] 264 | for category in categories: 265 | labels = category['labels'] 266 | score = category['score'] 267 | explanation = category['explanation'] 268 | 269 | # Construct NLU response format 270 | nlu_category = { 271 | "score": score, 272 | "label": '/'.join(f'/{label}' if i == 0 else f'{label}' for i, label in enumerate(labels)), 273 | "explanation": { 274 | "relevant_text":[ 275 | { "text": explanation[0]['text'] } 276 | ] 277 | } 278 | } 279 | transformed_categories.append(nlu_category) 280 | 281 | 282 | return transformed_categories 283 | ``` 284 | 285 | ### Tone Classification 286 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#classifications) 287 | 288 | Watsonx.ai Studio models: 289 | - ensemble_classification-workflow__tone-stock 290 | 291 | [Watsonx.ai Studio code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-tone.html) 292 | 293 | #### Transforming Watson NLP response 294 | ```py 295 | def transform_tone_classification(wnlp_response): 296 | transformed_predictions = [] 297 | 298 | for prediction in wnlp_response['predictions']: 299 | classes = prediction['values'][0][0]['classes'] 300 | for classification in classes: 301 | class_name = classification['class_name'] 302 | confidence = classification['confidence'] 303 | 304 | # Construct NLU response format 305 | nlu_classifications = { 306 | "confidence": round(confidence, 6), 307 | "class_name": class_name, 308 | 309 | } 310 | transformed_predictions.append(nlu_classifications) 311 | 312 | # Construct the final NLU response 313 | nlu_response = { 314 | "classifications": transformed_predictions 315 | } 316 | 317 | return nlu_response 318 | ``` 319 | 320 | ### Concepts 321 | [Watson NLU documentation](https://www.ibm.com/docs/en/watson-libraries?topic=catalog-concepts) 322 | 323 | Watsonx.ai Studio models: 324 | - concepts_alchemy__stock 325 | 326 | [Watsonx.ai Studio code snippet](https://cloud.ibm.com/apidocs/natural-language-understanding#concepts) 327 | 328 | #### Transforming Watson NLP response 329 | No transformation of Watson NLP response is required - the responses are equivalent. 330 | 331 | ### Emotion 332 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#emotion) 333 | 334 | Watsonx.ai Studio models: 335 | - emotion_aggregated-workflow__stock 336 | 337 | [Watsonx.ai Studio code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-emotion.html) 338 | 339 | #### Transforming Watson NLP response 340 | ```py 341 | def transform_emotion(wnlp_response): 342 | transformed_predictions = {} 343 | 344 | # Transform @wnlp_response.json to @nlu_response.json 345 | for prediction in wnlp_response['predictions']: 346 | predictions = prediction['values'][0][0]['emotion_predictions'] 347 | for emotion_pred in predictions: 348 | target = emotion_pred['target'] 349 | emotion_dict = emotion_pred['emotion'] 350 | 351 | target_emotion = { 352 | "text": target, 353 | "emotion": {} 354 | } 355 | # Add target-level emotion prediction (only if target is not empty) 356 | if target: 357 | target_emotion["emotion"] = sort_emotions(emotion_dict) 358 | # create "targets" if none 359 | if 'targets' in transformed_predictions: 360 | transformed_predictions["targets"].append(target_emotion) 361 | else: 362 | transformed_predictions['targets'] = [target_emotion] 363 | 364 | # Add document-level emotion prediction (only if target is empty) 365 | if not target: 366 | document_emotion = sort_emotions(emotion_dict) 367 | if "document" in transformed_predictions: 368 | transformed_predictions["document"]["emotion"] = document_emotion 369 | else: 370 | transformed_predictions["document"] = {"emotion": document_emotion} 371 | 372 | # Construct the final NLU response 373 | nlu_response = { 374 | "emotion": transformed_predictions 375 | } 376 | 377 | return nlu_response 378 | 379 | def sort_emotions(emotion_dict): 380 | emotion_list = list(emotion_dict.items()) 381 | emotion_list.sort(key=lambda x: x[0], reverse=True) 382 | return {emotion: round(probability, 6) for emotion, probability in emotion_list} 383 | ``` 384 | 385 | ### Entities 386 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#entities) 387 | Note: Disambiguation is not available in Watson NLP in Watsonx.ai Studio. 388 | 389 | | Watsonx.ai Studio models | Code Snippet Link| 390 | | --- | --- | 391 | | entity-mentions_transformer-workflow_multilingual_slate.153m.distilled
    entity-mentions_transformer-workflow_multilingual_slate.153m.distilled-cpu) | [Code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-entity-enhanced.html) | 392 | | entity-mentions_rbr__stock | [Code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-entity-enhanced.html) 393 | | entity-mentions_rbr_multi_pii | [Code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-entity-enhanced.html?context=cpdaas&audience=wdp#rule-based-pii)| 394 | 395 | #### Transforming Watson NLP response 396 | ```py 397 | def transform_entities(wnlp_response): 398 | transform_entities = {'entities':[]} 399 | 400 | for entities in wnlp_response['predictions'][0]['values'][0]['entities']: 401 | entity_type = entities['type'] 402 | text = entities['text'] 403 | relevance = entities['relevance'] 404 | count = len(entities['mentions']) 405 | confidence = entities['confidence'] 406 | disambiguation = entities['disambiguation'] 407 | 408 | transform_entities['entities'].append({ 409 | "type": entity_type, 410 | "text": text, 411 | "relevance": relevance, 412 | "count": count, 413 | "confidence": confidence 414 | } 415 | ) 416 | 417 | if disambiguation: 418 | transform_entities['entities'][-1]["disambiguation"]=disambiguation 419 | 420 | 421 | return transform_entities 422 | ``` 423 | 424 | ### Keywords 425 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#keywords) 426 | 427 | Watsonx.ai Studio models: 428 | - keywords_embed-rank_multi_stock 429 | 430 | [Watsonx.ai Studio code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-keyword.html) 431 | 432 | #### Transforming Watson NLP response 433 | ```py 434 | def transform_keywords(wnlp_response): 435 | transform_keywords = {'keywords':[]} 436 | 437 | for keywords in wnlp_response['predictions'][0]['values'][0]['keywords']: 438 | text = keywords['text'] 439 | relevance = keywords['relevance'] 440 | count = len(keywords['mentions']) 441 | 442 | # Construct NLU response format 443 | nlu_syntax = { 444 | "text": text, 445 | "relevance": relevance, 446 | "count": count, 447 | } 448 | transform_keywords['keywords'].append(nlu_syntax) 449 | 450 | 451 | return transform_keywords 452 | 453 | ``` 454 | 455 | ### Metadata 456 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#metadata) 457 | 458 | Watsonx.ai Studio models: there is no corresponding feature in watsonx.ai Studio. 459 | 460 | ### Relations 461 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#relations) 462 | 463 | Watsonx.ai Studio models: 464 | - relations_transformer-workflow_multilingual_slate.153m.distilled 465 | 466 | [Watsonx.ai Studio code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-relation-extraction.html) 467 | 468 | #### Transforming Watson NLP response 469 | ```py 470 | def transform_relations(wnlp_response): 471 | transform_relations = {'relations':[]} 472 | 473 | for relations in wnlp_response['predictions'][0]['values'][0]['relations']: 474 | relation_mentions = relations['relation_mentions'] 475 | for mention in relation_mentions: 476 | relation_type = mention['type'] 477 | sentence = mention['text'] 478 | score = mention['confidence'] 479 | arguments = [] 480 | arguments.append( 481 | { 482 | "text": mention['mention1']['span']['text'], 483 | "location": [mention['mention1']['span']['begin'], mention['mention1']['span']['end']], 484 | "entities": [{"type": relations['entity1']['type'], 485 | "text": relations['entity1']['text'], 486 | "disambiguation": relations['entity1']['disambiguation']}] 487 | 488 | } 489 | ) 490 | arguments.append( 491 | { 492 | "text": mention['mention2']['span']['text'], 493 | "location": [mention['mention2']['span']['begin'], mention['mention2']['span']['end']], 494 | "entities": [{"type":relations['entity2']['type'], 495 | "text":relations['entity2']['text'], 496 | "disambiguation":relations['entity2']['disambiguation']}] 497 | 498 | } 499 | ) 500 | 501 | transform_relations['relations'].append({ 502 | "type": relation_type, 503 | "sentence": sentence, 504 | "score": score, 505 | "arguments": arguments 506 | } 507 | ) 508 | 509 | return transform_relations 510 | ``` 511 | 512 | ### Semantic Roles 513 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#semantic-roles) 514 | 515 | Watsonx.ai Studio models: there is no corresponding feature in watsonx.ai Studio. 516 | 517 | ### Sentiment 518 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#sentiment) 519 | 520 | #### Watsonx.ai Studio models (aggregated): 521 | - sentiment-aggregated_transformer-workflow_multilingual_slate.153m.distilled 522 | - sentiment-aggregated_transformer-workflow_multilingual_slate.153m.distilled-cpu 523 | #### Watsonx.ai Studio models (targeted): 524 | - targets-sentiment_transformer-workflow_multilingual_slate.153m.distilled 525 | - targets-sentiment_transformer-workflow_multilingual_slate.153m.distilled-cpu 526 | 527 | 528 | [Watsonx.ai Studio code snippet (aggregated)](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-sentiment.html) 529 | 530 | [Watsonx.ai Studio code snippet (targeted)](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-sentiment.html?context=cpdaas&audience=wdp#targets-sentiment-workflows) 531 | #### Transforming Watson NLP response 532 | ##### Document Sentiment 533 | ```py 534 | def transform_sentiment_document(wnlp_response): 535 | transformed_syntax = {'sentiment':{'document':{}}} 536 | sentiment_mapping = {'SENT_NEGATIVE':'negatve','SENT_POSITIVE':'positive', 'SENT_NEUTRAL':'neutral'} 537 | 538 | sentiment_pred = wnlp_response['predictions'][0]['values'][0]['document_sentiment'] 539 | label = sentiment_mapping[sentiment_pred['label']] 540 | mixed = int(sentiment_pred['mixed']) 541 | score = sentiment_pred['score'] 542 | 543 | # Construct NLU response format 544 | nlu_syntax = { 545 | "score": score, 546 | "mixed": mixed, 547 | "label": label, 548 | } 549 | transformed_syntax['sentiment']['document']=nlu_syntax 550 | 551 | 552 | return transformed_syntax 553 | ``` 554 | ##### Targeted Sentiment 555 | ```py 556 | def transform_sentiment_target(wnlp_response): 557 | transformed_syntax = {'sentiment':{'document':{},'targets': []}} 558 | sentiment_mapping = {'SENT_NEGATIVE':'negatve','SENT_POSITIVE':'positive', 'SENT_NEUTRAL':'neutral'} 559 | 560 | sentiment_pred = wnlp_response['predictions'][0]['values'][0]['document_sentiment'] 561 | label = sentiment_mapping[sentiment_pred['label']] 562 | mixed = int(sentiment_pred['mixed']) 563 | score = sentiment_pred['score'] 564 | 565 | # Construct NLU response format 566 | nlu_syntax = { 567 | "score": score, 568 | "mixed": mixed, 569 | "label": label, 570 | } 571 | transformed_syntax['sentiment']['document']=nlu_syntax 572 | 573 | for k, v in wnlp_response['predictions'][0]['values'][0]['targeted_sentiments']['targeted_sentiments'].items(): 574 | text = k 575 | score = v['score'] 576 | label = sentiment_mapping[v['label']] 577 | 578 | nlu_syntax = { 579 | "text": text, 580 | "score": score, 581 | "label": label, 582 | } 583 | transformed_syntax['sentiment']['targets'].append(nlu_syntax) 584 | 585 | 586 | return transformed_syntax 587 | ``` 588 | 589 | ### Syntax 590 | [Watson NLU documentation](https://cloud.ibm.com/apidocs/natural-language-understanding#syntax) 591 | 592 | Watsonx.ai Studio models: 593 | - syntax_izumo__stock if you do not need dependency parsing features, OR 594 | - syntax_izumo__stock-dp if you need dependency parsing features 595 | 596 | [Watsonx.ai Studio code snippet](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/watson-nlp-block-syntax.html) 597 | 598 | #### Transforming Watson NLP response 599 | ##### Syntax Token 600 | ```py 601 | def transform_syntax_token(wnlp_response): 602 | transformed_syntax = {'syntax':{'tokens':[]}} 603 | 604 | for syntax in wnlp_response['predictions'][0]['values'][0]['tokens']: 605 | lemma = syntax['lemma'] 606 | part_of_speech = syntax['part_of_speech'][4:] 607 | location = [syntax['span']['begin'],syntax['span']['end']] 608 | text = syntax['span']['text'] 609 | 610 | # Construct NLU response format 611 | nlu_syntax = { 612 | "text": text, 613 | "part_of_speech": part_of_speech, 614 | "location": location, 615 | "lemma": lemma 616 | } 617 | transformed_syntax['syntax']['tokens'].append(nlu_syntax) 618 | 619 | 620 | return transformed_syntax 621 | ``` 622 | ##### Syntax Sentence 623 | ```py 624 | def transform_syntax_sentences(wnlp_response): 625 | transformed_syntax = {'syntax':{'sentences':[]}} 626 | 627 | for syntax in wnlp_response['predictions'][0]['values'][0]['sentences']: 628 | 629 | location = [syntax['span']['begin'],syntax['span']['end']] 630 | text = syntax['span']['text'] 631 | 632 | # Construct NLU response format 633 | nlu_syntax = { 634 | "text": text, 635 | "location": location, 636 | } 637 | transformed_syntax['syntax']['sentences'].append(nlu_syntax) 638 | 639 | 640 | return transformed_syntax 641 | 642 | ``` 643 | 644 | ## Customization 645 | This section describes customization features and corresponding functionality in watsonx.ai Studio with Watson NLP. 646 | 647 | - [Convert sentiment prediction from Watson NLP to NLU](https://dataplatform.cloud.ibm.com/analytics/notebooks/v2/5a950803-c4b1-4f1f-ba87-e8500f0064f3/view?access_token=d075c474244bc48131d72164feacd81ac4c88bdedfe06700aef09efd4df949b4&context=cpdaas) 648 | - [Convert categories predictions from Watson NLP to NLU](https://dataplatform.cloud.ibm.com/analytics/notebooks/v2/384274b3-ba61-472e-a534-697bc84f14d6/view?access_token=78d5b1bba89f0b25756a53d116fd35dba3bb9a6c6acc1e4f4248b38cd0f1355c&context=cpdaas) 649 | - [Convert emotions predictions from Watson NLP to NLU](https://dataplatform.cloud.ibm.com/analytics/notebooks/v2/0c7a3371-f876-4d7b-8577-06f8666ceb57/view?access_token=a972522bb28dd7c3edb92e19dfa9a6bad4f97f26efab2e6c5f2fd70d130ef59e&context=cpdaas) 650 | - [Deploy custom classification model from Watson NLP](https://dataplatform.cloud.ibm.com/analytics/notebooks/v2/c7ec3d45-5431-42da-a776-c1b252f4abcc/view?access_token=e2cab1c7e744dc2ab4f4cfae3c72fde9b410521a44300a9dd6f7c266fb3b1f5a&context=cpdaas) --------------------------------------------------------------------------------