Tutorial: Natural language processing (NLP)

This guide focuses on a concrete task: getting a machine learning trained model loaded into Elasticsearch and set up to enrich your documents.

Elasticsearch supports many different ways to use machine learning models. In this guide, we will use a trained model to enrich documents at ingest time using ingest pipelines configured within Kibana’s Content UI.

In this guide, we’ll accomplish the above using the following steps:

Follow the instructions to load a text classification model and set it up to enrich some photo comment data. Once you’re comfortable with the steps involved, use this guide as a blueprint for working with other machine learning trained models.

Table of contents:

Your deployment will need a machine learning instance to upload and deploy trained models.

If your team already has an Elastic Cloud deployment, make sure it has at least one machine learning instance. If it does not, Edit your deployment to add capacity. For this tutorial, we’ll need at least 2GB of RAM on a single machine learning instance.

If your team does not have an Elastic Cloud deployment, start by signing up for a free Elastic Cloud trial. After creating an account, you’ll have an active subscription and you’ll be prompted to create your first deployment.

Follow the steps to Create a new deployment. Make sure to add capacity to the Machine Learning instances under the Advanced settings before creating the deployment. To simplify scaling, turn on the Autoscale this deployment feature. If you use autoscaling, you should increase the minimum RAM for the machine learning instance. For this tutorial, we’ll need at least 2GB of RAM. For more details, refer to Create a deployment in the Elastic Cloud documentation.

Enriching documents using machine learning was introduced in Enterprise Search 8.5.0, so be sure to use version 8.5.0 or later.

Elastic’s Eland tool makes it easy to upload trained models to your deployment via Docker.

Eland is a specialized Elasticsearch client for exploring and manipulating data, which we can use to upload trained models into Elasticsearch.

To clone and build Eland using Docker, run the following commands:

git clone git@github.com:elastic/eland.git
cd eland
docker build -t elastic/eland .

Now that you have a deployment and a way to upload models, you will need to choose a trained model that fits your data. Hugging Face has a large repository of publicly available trained models. The model you choose will depend on your data and what you would like to do with it.

For the purposes of this guide, let’s say we have a data set of photo comments. In order to promote a positive atmosphere on our platform, we’d like the first few comments on each photo to be positive comments. For this task, the distilbert-base-uncased-finetuned-sst-2-english model is a good fit.

To upload this model to your deployment, you need a few pieces of data:

We can now upload our chosen model to Elasticsearch by providing these options to Eland.

docker run -it --rm --network host \
    elastic/eland \
    eland_import_hub_model \
      --url https://ml-test.es.us-west1.gcp.cloud.es.io:443 \
      -u elastic -p <PASSWORD> \
      --hub-model-id distilbert-base-uncased-finetuned-sst-2-english \
      --task-type text_classification \
      --start

This script should take roughly 2-3 minutes to run. Once your model has been successfully deployed to your Elastic deployment, navigate to Kibana’s Trained Models page to verify it is ready. You can find this page under Machine Learning > Analytics menu and then Trained Models > Model Management. If you do not see your model in the list, you may need to click Synchronize your jobs and trained models. Your model is now ready to be used.

We are now ready to use Kibana’s Content UI to enrich our documents with inference data. Before we ingest photo comments into Elasticsearch, we will first create an ML inference pipeline. The pipeline will enrich the incoming photo comments with inference data indicating if the comments are positive.

Let’s say our photo comments look like this when they are uploaded as a document into Elasticsearch:

{
  "photo_id": "78sdv71-8vdkjaj-knew629-vc8459p",
  "body": "your dog is so cute!",
  ...
}

We want to run our documents through an inference processor that uses the trained model we uploaded to determine if the comments are positive. To do this, we first need to set up an Elasticsearch index.

To configure the ML inference pipeline, we need the index to have an existing field mapping so we can choose which field to analyze. This can be done via the index mapping API in the Kibana Dev Tools or simply through a cURL command:

PUT search-photo-comments/_mapping
{
  "properties": {
    "photo_id": { "type": "keyword" },
    "body": { "type": "text" }
  }
}

Now it’s time to create an inference pipeline.

Next, we’ll add an inference pipeline.

You can also run example documents through a simulator and review the pipeline before creating it.

At this point, everything is ready to enrich documents at index time.

From the Kibana Dev Console, or simply using a cURL command, we can index a document. We’ll use a _run_ml_inference flag to tell the search-photo-comments pipeline to run the index-specific ML inference pipeline that we created. This field will not be indexed in the document.

POST search-photo-comments/_doc/my-new-doc?pipeline=search-photo-comments
{
  "photo_id": "78sdv71-8vdkjaj-knew629-vc8459p",
  "body": "your dog is so cute!",
  "_run_ml_inference": true
}

Once the document is indexed, use the API to retrieve it and view the enriched data.

GET search-photo-comments/_doc/my-new-doc

{
  "_index": "search-photo-comments",
  "_id": "_MQggoQBKYghsSwHbDvG",
  ...
  "_source": {
    ...
    "photo_id": "78sdv71-8vdkjaj-knew629-vc8459p",
    "body": "your dog is so cute!",
    "ml": {
      "inference": {
        "positivity_result": {
          "predicted_value": "POSITIVE",
          "prediction_probability": 0.9998022925461774,
          "model_id": "distilbert-base-uncased-finetuned-sst-2-english"
        }
      }
    }
  }
}

The document has new fields with the enriched data. The ml.inference.positivity_result field is an object with the analysis from the machine learning model. The model we used predicted with 99.98% confidence that the analyzed text is positive.

From here, we can write search queries to boost on ml.inference.positivity_result.predicted_value. This field will also be stored in a top-level positivity_result field if the model was confident enough.

In this guide, we covered how to: