The Embedding use cases of the LWAI Prediction API include various encoder use cases and the custom model prediction. The use cases are:
  • English language model text encoder
  • Multilingual language model text encoder
  • Custom model
For detailed API specifications in Swagger/OpenAPI format, see Platform APIs.

​
Prerequisites

To use this API, you need:
  • The unique APPLICATION_ID for your Lucidworks AI application. For more information, see credentials to use APIs.
  • A bearer token generated with a scope value of machinelearning.predict. For more information, see Authentication API.
  • The USE_CASE and MODEL_ID fields for the use case request. The path is: /ai/prediction/USE_CASE/MODEL_ID. A list of supported models is returned in the Lucidworks AI Use Case API.

​
Unique values for the embeddings use cases

Some parameter values available in the embeddings use case are unique to this use case, including values for the useCaseConfig parameter. Refer to the API spec for more information.

​
Vector quantization

Quantization is implemented by converting float vectors into integer vectors, allowing for byte vector search using 8-bit integers. Float vectors, while very precise, are often a bit of a burden to compute and store, especially as they grow in dimensionality. One solution to this issue is to convert the vector floats into integers after inference, making byte vectors which are lower consumers of memory space and faster to compute with minimal loss in accuracy or quality. Byte vectors are available through all of the Lucidworks LWAI hosted embedding models, including custom trained models. Vector quantization methods are implemented through the modelConfig parameter, vectorQuantizationMethod. The methods are named min-max and max-scale.
  • The min-max method creates tensors of embeddings and converts them to uint8 by normalizing them to the range [0, 255].
  • The max-scale method finds the maximum absolute value along each embedding, normalizes the embeddings by scaling them to a range of -127 to 127, and returns the quantized embeddings as an 8-bit integer tensor.
During testing, it was found that the max-scale method has no loss at the ten-thousandths place during evaluation against non-quantized vectors. However, other methods lose precision when evaluated against non-quantized vectors, with min-max losing the most precision. 
curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/ai/prediction/embedding/{MODEL_ID} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ACCESS_TOKEN'
  --data '{
    "batch": [
      {
        "text": "I need to pick up some fresh produce like apples, bananas, and spinach, as well as dairy products including milk, eggs, and cheddar cheese. I'\''ll also need to get some pantry staples such as pasta, rice, and canned tomatoes. Additionally, I should grab a loaf of whole-grain bread, some chicken breasts, ground beef, and a box of cereal for breakfast. Don'\''t forget to add a bottle of olive oil, a jar of peanut butter, and some snacks like granola bars and yogurt. Finally, I need to remember to buy cleaning supplies like dish soap and paper towels, along with a carton of almond milk and a few avocados for the week."
      }
    ],
    "useCaseConfig": {
      "dataType": "passage"
    },
    "modelConfig": {
      "vectorQuantizationMethod": "max-scale"
    }
  }'

​
Matryoshka vector dimension reduction

Vector dimension reduction is the process of making the default vector size of a model smaller. The purpose of this reduction is to lessen the burden of storing large vectors while still achieving the good quality of a larger model. The technique is called Matryoshka Representation Learning (MRL) and lets you reduce vector size while maintaining good quality. For information about the pre-trained embedding models that use the Matryoshka Representation Learning technique, see:
You can reduce vectors for any model using the modelConfig dimReductionSize, which allows any integer above 0, but less than or equal to the vector dimension of the model.
"modelConfig": {
        "dimReductionSize": 256
    }

​
English language model text encoder

The English language encoder takes in plain English text and returns a 768-dimensional vector encoding of that text. This model powers this semantic search. The API truncates incoming text to approximately 256 words before the model encodes it and returns a vector. An example usage pattern is to encode all the texts and descriptions in a website and then use this encoder on query text, supporting natural language queries such as “1990s children’s fiction”. Each API request includes one batch containing up to 32 text strings. 
curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/ai/prediction/embedding/text-encoder \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "batch": [
    {
      "text": "city streets",
      "text": "city gateways"
    }
  ],
  "useCaseConfig":
    {
      "dataType": "query"
    }
}'

​
Multilingual language model text encoder

The multilingual encoder takes in plain text and returns a 384-dimensional vector encoding of that text. The API truncates incoming text to approximately 256 words before the model encodes it and returns a vector. Each API request includes one batch containing up to 32 text strings. The text strings in a batch do not have to be in the same language. You can also use words from multiple languages with each text value. Because long text strings are truncated to approximately 256 words, the order and length of the value affects the return results. 
curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/ai/prediction/embedding/multilingual-e5-base \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "batch": [
    {
      "text": "city streets",
      "text": "city gateways"
    }
  ],
  "useCaseConfig":
    {
      "dataType": "query"
    }
}'
If a custom model is trained and deployed using the Lucidworks AI Models API, the ‘DEPLOYMENT_ID’ in the Models API is the same value as the MODEL_ID you enter in the custom model to return a prediction. 
curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/ai/prediction/embedding/MODEL_ID \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "batch": [
    {
      "text": "city streets",
      "text": "city gateways"
    }
  ],
  "useCaseConfig":
    {
      "dataType": "query"
    }
}'

​
Verify information sent to embedding models

The Lucidworks AI Tokenization API returns Prediction API embedding use case tokens before being sent to any pre-trained embedding model or custom embedding model. You can use this information to help debug and ensure the input to the pre-trained or custom embedding model is valid, and within the model’s processing limits. For more information, see Tokenization API.