IBM Cloud Docs
Integrating with Watson Knowledge Studio

Integrating with Watson Knowledge Studio

You can integrate one or more custom models from IBM Watson™ Knowledge Studio with Discovery to provide custom entity and relations enrichments.

This gives you the flexibility to apply Discovery's document-enhancing capabilities with information specific to areas of particular focus, such as industry or scientific discipline. You can use both public data and your own proprietary data in your enrichment model.

You can use the service API or the Discovery tooling to integrate a Knowledge Studio model with Discovery.

Before you begin

Before you can integrate a custom model from Knowledge Studio with Discovery, you must create and deploy the model by using Knowledge Studio. See the Knowledge Studio documentation for information on creating and deploying models. You need the unique ID of the deployed model to integrate it with Discovery.

Integrating your custom model with the API

  1. Get the ID of your Discovery environment as described at List environments. Note the environment ID.
  2. List the IDs of your current Discovery configuration or configurations as described at List configurations Note the ID of the configuration that you want to integrate with your IBM Watson™ Knowledge Studio custom model.
  3. Download a copy of your current Discovery configuration by running the following commands in a bash shell or equivalent, such as Cygwin for Windows. Substitute {environment_id} and {configuration_id} with the IDs you noted down in the previous two steps.

    curl -u "apikey":"{apikey_value}" "{url}/v1/environments/{environment_id}/configurations/{configuration_id}?version=2019-04-30" > my_config.json
    

    This command lists the contents of your collection file and puts them in a JSON file named my_config.json.

  4. Open the my_config.json file in a text editor and make the following changes:

    1. Change the value of the "name" field to something that indicates the purpose of the new configuration. You can optionally change the value of the "description" field as well.

      ...
      "name": "wks-config",
      "description": "This is a configuration to use with a WKS model",
      ...
      
    2. Update the enrichment fields with information for the Knowledge Studio model. Assuming that the enrichment fields originally read:

      "enrichments": [
      {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
              "features": {
                  "entities": {
                      "sentiment": true,
                      "emotion": false,
                      "limit": 50
                  },
                  "sentiment": {
                      "document": true
                  },
                  "categories": {},
                  "concepts": {
                      "limit": 8
                  },
                  "relations": {}
              }
          }
      }]
      
    3. Update the file as follows, substituting the unique ID of the Knowledge Studio model described in "Before you begin" for {watson_knowledge_studio_model_ID}.

      It is possible to apply more than one custom model to identical fields using the API. See the example in Integrating multiple custom models.

      "enrichments": [
      {
          "source_field": "text",
          "destination_field": "enriched_text",
          "enrichment": "natural_language_understanding",
          "options": {
              "features": {
                  "entities": {
                      "sentiment": true,
                      "emotion": false,
                      "limit": 50,
                      "model": "{watson_knowledge_studio_model_ID}"
                  },
                  "sentiment": {
                      "document": true
                  },
                  "categories": {},
                  "concepts": {
                      "limit": 8
                  },
                  "relations": {
                      "model": "{watson_knowledge_studio_model_ID}"
                  }
              }
          }
      }]
      
  5. Save the my_config.json file.

  6. Use a JSON validator, such as JSLint to validate and, if necessary, correct your edited JSON before you perform the next steps.
  7. Update the configuration as follows. You again need the {environment_id} and {configuration_id} IDs you collected at the start of this procedure.

    curl -X PUT -u "apikey":"{apikey_value}" -H "Content-Type: application/json" -d @my_config.json "{url}/v1/environments/{environment_id}/configurations/{configuration_id}?version=2019-04-30"
    

    If you are creating a configuration or modifying the default configuration, create another custom configuration instead of updating an existing configuration. Before you create the configuration, remove the "configuration_id": field from your my_config.json file, and then run the following command:

    curl -X POST -u "apikey":"{apikey_value}" -H "Content-Type: application/json" -d @my_config.json "{url}/v1/environments/{environment_id}/configurations?version=2019-04-30"
    

    Both commands return the contents of the updated configuration file.

    Replace {apikey} and {url} with your API key and URL.

Integrating multiple custom models

You can apply more than one custom model to identical fields using the API. Follow the steps in Integrating your custom model with the API and use the example here as a guide.

You cannot apply multiple custom models using the Discovery tooling. Only the entity and relations enrichments can be customized.

You must specify a different destination_field for each identical source_field. In addition, each source_field must be enriched by a unique model. For example, if you want to apply multiple custom models to the source_field of text and you apply the model {watson_knowledge_studio_model_ID} to the entities enrichment, you must not use that model again for the entities enrichment.

   "enrichments": [
   {
        "source_field": "text",
        "destination_field": "enriched_text",
        "enrichment": "natural_language_understanding",
        "options": {
            "features": {
                "entities": {
                    "model": "{watson_knowledge_studio_model_ID}"
                },
                "relations": {
                    "model": "{watson_knowledge_studio_model_ID}"
            }
        }
    }
},
   {
        "source_field": "text",
        "destination_field": "enriched_text_2",
        "enrichment": "natural_language_understanding",
        "options": {
            "features": {
                "entities": {
                    "model": "{watson_knowledge_studio_model_ID_b}"
            },
                "relations": {
                    "model": "{watson_knowledge_studio_model_ID_c}"
            }
        }
    }
}]

Integrating your custom model with the Discovery tooling

You can integrate a Knowledge Studio custom model into the Entity Extraction or Relation Extraction enrichments with the Discovery tooling.

You cannot apply multiple custom models to the same field using the Discovery tooling. It is possible to apply more than one custom model to identical fields using the API. See Integrating your custom model with the API.

  1. Get the Model ID of your Knowledge Studio model.
  2. In the Discovery tooling, click the Manage Data icon to open the Manage data screen, then create or open a collection.

If you choose an existing collection, it must be empty. If not, create a new collection and reingest the documents after you have followed these steps.

  1. Click Configure data. The Enrich fields tab opens.
  2. Click Add enrichments and select either the Entity Extraction or Relation Extraction enrichment.
  3. Enter the Model ID in the Custom Model ID box of the selected enrichment. The custom IBM Watson™ Knowledge Studio model overrides the default for that enrichment.
  4. Click Apply, then Done.

When documents are uploaded to a data collection, they are converted and enriched using the configuration file chosen for that collection. If you switch an existing collection to a new configuration file after documents are uploaded, those uploaded documents remain converted by the original configuration file. Any documents uploaded after switching the configuration file use the new configuration file. If you want the entire collection to use the new configuration, you must create a new collection, choose that new configuration file, and re-upload all the documents.

Next Steps

Use Discovery with your new configuration to ingest private data. Documents you ingest with the updated configuration are automatically enriched with the data from your custom model.