Prediction-based query - OpenSearch - Alibaba Cloud Documentation Center

Description

After you convert the texts and images to vectors by using the built-in vector models of OpenSearch Vector Search Edition, you can use texts or images to perform prediction-based queries.

Note: For more information about how to perform queries if you have vector data and the vector data is imported to an OpenSearch Vector Search Edition instance, see Vector-based query.

URL

/vector-service/inference-query

The sample URL omits information such as the request headers and the encoding method.
The sample URL also omits the endpoint that is used to connect to the OpenSearch application.
For more information about the definitions, usage, and example values of all the request parameters that are concatenated in the preceding URL, see the "Request parameters" section of this topic.

Protocol

HTTP

Request method

POST

Supported format

JSON

Request signature

You can use the fields in the following table to calculate the request signature. The request signature is stored in the authorization header.

Parameter	Type	Description
accessUserName	STRING	The username. You can view the username in the API Endpoint section of the Instance Details page.
accessPassWord	STRING	The password. You can modify the password in the API Endpoint section of the Instance Details page.

import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;

public class GenerateAuthorization {
 public static void main(String[] args) throws Exception {
 String accessUserName = "username";
 String accessPassWord = "password";
 String realmStr = "" + accessUserName + ":" + accessPassWord + "";
 String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
 System.out.println(authorization);
 }
}

Valid format for the value of the authorization header:

cm9vdDp******mdhbA==

You must add the Basic prefix when you specify the authorization header in an HTTP request.

Example:

authorization: Basic cm9vdDp******mdhbA==

Request parameters

Parameter	Description	Default value	Type	Required
tableName	The name of the table to be queried.	N/A	STRING	Yes
indexName	The name of the index to be queried.	The first index configured	string	No
content	The vector data to be queried.	N/A	STRING	Yes
modal	The vectorization model. Valid values: text: the text vectorization model. The model is used for text searches or image searches based on specific text. image: the image vectorization model. The model is used for image searches based on specific images.	N/A	STRING
namespace	The namespace of the vector data.	""	STRING	No
topK	The number of results to be returned.	100	INT	No
includeVector	Specifies whether to return the vector information in documents.	false	BOOLEAN	No
outputFields	The fields to be returned.	[]	LIST[STRING]	No
order	The order in which the results are sorted. A value of ASC indicates the ascending order. A value of DESC indicates the descending order.	ASC	STRING	No
searchParams	The parameters that are used to query data. QcSearcher HnswSearcher	""	STRING	No
filter	The filter expression.	""	STRING	No
scoreThreshold	The threshold score used to filter documents. If the score is the squared Euclidean distance, only the documents whose squared Euclidean distance is smaller than the value of the scoreThreshold parameter are returned. If the score is the inner product, only the documents whose inner product is greater than the value of the scoreThreshold parameters are returned.	By default, the results are not filtered.	FLOAT	No

Response parameters

Parameter	Description	Type
result	The returned results.	LIST[ITEM]
totalCount	The number of results.	INT
totalTime	The response time. Unit: millisecond.	FLOAT
errorCode	The error code returned if the request failed.	INT
errorMsg	The error message returned if the request failed.	STRING

Item

Parameter	Description	Type
score	The score of the vector.	FLOAT
fields	The fields and the corresponding values.	MAP<STRING, FieldType>
vector	The vector value.	LIST[FLOAT]
id	The primary key value. The value is of the defined data type.	FieldType
namespace	The namespace of the vector. This parameter is returned if a namespace is configured for the vector.	STRING

Examples

Text vectorization-based query

Sample request:

{
  "tableName": "gist",
  "indexName": "test",
  "content": "hello",
  "modal": "text",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

Sample response:

{
  "result":[
    {
      "id": 1,
      "score":1.0508723258972169,
      "vector": [0.1, 0.2, 0.3]
    },
    {
      "id": 2,
      "score":1.0329746007919312,
      "vector": [0.2, 0.2, 0.3]
    },
    {
      "id": 3,
      "score":0.980593204498291,
      "vector": [0.3, 0.2, 0.3]
    }
  ],
  "totalCount":3,
  "totalTime":2.943
}

Image vectorization-based query

Search for images based on text

Sample request:

{
  "tableName": "gist",
  "indexName": "test",
  "content": "Bicycle",
  "modal": "text",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

Sample response:

{
  "result":[
    {
      "id": 1,
      "score":1.0508723258972169,
      "vector": [0.1, 0.2, 0.3]
    },
    {
      "id": 2,
      "score":1.0329746007919312,
      "vector": [0.2, 0.2, 0.3]
    },
    {
      "id": 3,
      "score":0.980593204498291,
      "vector": [0.3, 0.2, 0.3]
    }
  ],
  "totalCount":3,
  "totalTime":2.943
}

Search for images based on a specific image:

Sample request:

{
  "tableName": "gist",
  "indexName": "test",
  "content": "Base64-encoded image",
  "modal": "image",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

Sample response:

{
    "totalCount": 5,
    "result": [
        {
            "id": 5,
            "score": 1.103209137916565
        },
        {
            "id": 3,
            "score": 1.1278988122940064
        },
        {
            "id": 2,
            "score": 1.1326735019683838
        }
    ],
    "totalTime": 242.615
}

Subject identification

Sample request:

The following sample code shows an example on how to perform a query for subject identification when the range parameter is not specified:

{
 "tableName": "gist",
 "indexName": "test",
 "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQ",
 "modal": "image",
 "searchParams": "{\"crop\": true}",
 "topK": 3,
 "includeVector": true
}

Note: A value of true for the crop parameter indicates that the subject is used for the query. If the range parameter is not specified, the subject identification model is called.

The following sample code shows an example on how to perform a query for subject identification when the range parameter is specified:

{
 "tableName": "gist",
 "indexName": "test",
 "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQ",
 "modal": "image",
 "searchParams": "{\"crop\": true, \"range\": \"100,100,60,70\"}",
 "topK": 3,
 "includeVector": true
}

Note: A value of true indicates that the subject is used for the query. The range parameter indicates the subject area of the image. In this example, 100 and 100 indicate the x and y coordinates of the upper-left corner of the subject area, 60 indicates the width of the subject area, and 70 indicates the height of the subject area.

Sample response:

{
 "result":[
 {
 "id": 1,
 "score":1.0508723258972169,
 "vector": [0.1, 0.2, 0.3]
 }
 ],
 "__meta__": {
 "__range__": "100,100,60,70;",
 }
 "totalCount":1,
 "totalTime":2.943
}

Note:

A value is returned for the range parameter only if the modal parameter is set to image.
The four numbers in the value of the range parameter indicate the x coordinate and y coordinate of the upper-left corner of the subject area and the width and height of the subject area.
If the model identifies multiple subjects in an image, the range parameter sorts the subjects in descending order based on the subject scores that are generated by the model. In this case, the subject with the highest score is returned by default.