Using the machine learning model

About this task

When you deploy the machine learning model, you select the version of it that you want to deploy.

Procedure

To deploy a machine learning model, complete the following steps:

1. Log in as a Knowledge Studio administrator or project manager, and select your workspace.

2. Select Machine Learning Model > Versions.

3. Choose the version of the model that you want to deploy.

   If there is only one working version of the model, create a snapshot of the current model. This versions the model, which enables you to deploy one version, while you continue to improve the current version. The option to deploy does not appear until you create at least one version.

   Each version can be deployed to any number of service instances. Each deployed instance of a model version is given a unique Model ID, but is identical in all other ways.

4. Click Deploy, choose to deploy it to Discovery, and then click Next.

5. Select the IBM Cloud space and instance. If necessary, select a different region.

6. Click Deploy.

7. The deployment process might take a few minutes. To check the status of the deployment, click Status on the Versions tab next to the version that you deployed.

   If the model is still being deployed, the status indicates "deploying". After deployment completes, the status changes to "available" or "deployed" if the deployment was successful, or "error" if problems occurred.

   Once available, make a note of the model ID (model_id).

What to do next

To use the model, you must export the model, and then import it into Discovery.

1. Select Machine Learning Model > Versions.

2. Click Export current model.

   If you have a Lite plan subscription, no export option is available.

   The model is saved as a ZIP file, and you are prompted to download the file.

3. Download the file to your local system.

4. From the Discovery service, follow the steps to create a Machine Learning enrichment, which include uploading the ZIP file. For more details, see Machine Learning models in the Discovery v2 documentation.

If you're using a Discovery v1 service instance, you must provide the model ID when it is requested during the Discovery service enrichment configuration process. For more information, see Integrating your custom model with the Discovery tooling in the Discovery v1 documentation.

Before you begin

You must have a Natural Language Understanding service to deploy to. And you must know the IBM Cloud space and instance names that are associated with the service. If you do not remember the space or instance names, find them by logging in to IBM Cloud. If you do not have an IBM Cloud account, sign up for one.

About this task

When you deploy the machine learning model, you select the version of it that you want to deploy.

Procedure

To deploy a machine learning model to the Natural Language Understanding service, complete the following steps:

1. Log in as a Knowledge Studio administrator or project manager, and select your workspace.

2. Select Machine Learning Model > Versions.

3. Choose the version of the model that you want to deploy.

   If there is only one working version of the model, create a snapshot of the current model. This versions the model, which enables you to deploy a version, while you continue to improve the current version. The option to deploy does not appear until you create at least one version.

   Each version can be deployed to any number of service instances. Each deployed instance of a model version is given a unique Model ID but is identical in all other ways.

4. Click Deploy, choose to deploy it to Natural Language Understanding, and then click Next.

5. Select the IBM Cloud space and instance. If necessary, select a different region.

6. Click Deploy.

7. The deployment process might take a few minutes. To check the status of the deployment, click Status on the Versions tab next to the version that you deployed. If the model is still being deployed, the status indicates "publishing". After deployment completes, the status changes to "available" if the deployment was successful, or "error" if problems occurred.

   Once available, make a note of the model ID (model_id). You will provide this ID to the Natural Language Understanding service to enable the service to use your custom model.

What to do next

You can list deployed model in the Natural Language Understanding service instance by calling the following API method.

curl --user "apikey:{apikey}" "{url}/v1/models?version=2018-11-16"

Any deployed models will be returned in an array similar to the following one:

{
  "models": [
    {
      "workspace_id": "{workspace_id}",
      "version_description": "{version_description}",
      "version": "{version}",
      "status": "available",
      "name": null,
      "model_id": "10:7abc4c2f-5846-3334-b8f7-af5a6fad3398",
      "language": "en",
      "description": null,
      "created": "2018-11-28T17:08:00.000000Z"
    }
  ]
}

The {workspace_id}, {version_description}, and {version} will all match the information listed on the Versions page of your Knowledge Studio service instance.

To use the deployed model, you must specify the model ID of your custom model in the entities.model parameter of an analyze call.

You can use the model with the Natural Language Understanding GET /analyze request to extract the following features:

• entities

  The following command finds the entities that are present in the sentence that is passed by using the text parameter:

  curl --user "apikey":"{apikey}" "{url}/v1/analyze?version=2018-09-21"
  --request POST
  --header "Content-Type: application/json"
  -d '{"text": "Vehicle 1, a 1995 Honda Civic was traveling north on a two lane
         undivided roadway, negotiating a curve to the left on an upgrade.",
          "features": {
            "entities": {
              "model": "your-model-id-here"
            }
          }
       }'
  

  The service returns a JSON object of instances that it finds of entity types that are defined in the custom model:

  {
    "language": "en",
    "entities": [
      {
        "type": "MANUFACTURER",
        "text": "Honda",
        "count": 1
      },
      {
        "type": "MODEL",
        "text": "Civic",
        "count": 1
      },
      {
        "type": "VEHICLE",
        "text": "Vehicle 1",
        "count": 1
      },
      {
        "type": "STRUCTURE",
        "text": "two lane undivided roadway",
        "count": 1
      },
      {
        "type": "STRUCTURE",
        "text": "curve",
        "count": 1
      },
      {
        "type": "MODEL_YEAR",
        "text": "1995",
        "count": 1
      },
      {
        "type": "CONDITION",
        "text": "negotiating",
        "count": 1
      }
    ],
    "language": "en"
  }
  

• relations

  The following command finds the relationships that are present in the sentence that is passed by using the text parameter:

  curl --user "apikey":"{apikey}" "{url}/v1/analyze?version=2018-09-21"
  --request POST
  --header "Content-Type: application/json"
  -d '{"text": "Vehicle 1, a 1995 Honda Civic was traveling north on a two lane
         undivided roadway, negotiating a curve to the left on an upgrade.",
          "features": {
            "relations": {
              "model": "your-model-id-here"
            }
          }
       }'
  

  The service returns a JSON object of instances that it finds of relation types that are defined in the custom model:

  {
    "relations": [
      {
        "type": "timeOf",
        "sentence": "Vehicle 1, a 1995 Honda Civic was traveling north
         on a two lane undivided roadway, negotiating a curve to
         the left on an upgrade.",
        "score": 0.954254,
        "arguments": [
          {
            "text": "1995",
            "entities": [
              {
                "type": "Date",
                "text": "1995"
              }
            ]
          },
          {
            "text": "Honda Civic",
            "entities": [
              {
                "type": "SportingEvent",
                "text": "Honda Civic"
              }
            ]
          }
        ]
      },
      {
        "type": "locatedAt",
        "sentence": "Vehicle 1, a 1995 Honda Civic was traveling north
         on a two lane undivided roadway, negotiating a curve to
         the left on an upgrade.",
        "score": 0.40592,
        "arguments": [
          {
            "text": "negotiating",
            "entities": [
              {
                "type": "EventMeeting",
                "text": "negotiating"
              }
            ]
          },
          {
            "text": "roadway",
            "entities": [
              {
                "type": "Facility",
                "text": "roadway"
              }
            ]
          }
        ]
      }
    ],
    "language": "en"
  }
  

For more information, see the Natural Language Understanding documentation.

Procedure

To undeploy models or find model IDs:

1. Launch Knowledge Studio.
2. From the Settings menu in the top right menu bar, select Manage deployed models.
3. From the list of deployed models, find the model you want to view or undeploy.
4. To undeploy the model, from the last column of that row, click Undeploy model.
5. To find the model ID, see the Model ID column.

Alternatively, you can undeploy models from the Versions pages for rule-based models and machine learning models.

Before you begin

If you choose to identify relation types and annotate them, then you must define at least two relation types, and annotate instances of the relationships in the ground truth before you export the model. Defining and annotating only one relation type can cause subsequent issues in IBM Watson Explorer, release 11.0.1.0.

About this task

Now that the machine learning model is trained to recognize entities and relationships for a specific domain, you can leverage it in IBM Watson Explorer.

Watch a brief video that illustrates how to export a model and use it in IBM Watson Explorer.

Procedure

To leverage a machine learning model in IBM Watson Explorer, complete the following steps.

1. Log in as a Knowledge Studio administrator or project manager, and select your workspace.

2. Select Machine Learning Model > Versions.

3. Click Export current model.

   If you have a Lite plan subscription, no export option is available.

   The model is saved as a ZIP file, and you are prompted to download the file.

4. Download the file to your local system.

5. From the IBM Watson Explorer application, import the model.

   You can then map the model to a machine learning model in Watson Explorer Content Analytics. After you perform the mapping step, when you crawl documents, the model finds instances of the entities and relations that your model understands. For more information about how to import and configure the model in IBM Watson Explorer, see the technical document that describes the integration: Using machine-learning annotators from Knowledge Studio in Watson Explorer.