OpenSearch:Sparse text embedding

Service name	Service ID	Description	QPS limit
OpenSearch sparse text embedding service-001	ops-text-sparse-embedding-001	Supported languages: 100+ Maximum input length: 8,192 tokens	50 Note To request a higher API QPS limit, submit a ticket to technical support.

Prerequisites

• Get authentication credentials

  The AI Search open platform requires an API key for authentication. For instructions, see Get an API key.

• Get the service endpoint

  You can call the service via the public network or a VPC. For details, see Get the service endpoint.

Usage notes

• The request body cannot exceed 8 MB.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/text-sparse-embedding/{service_id} 

URL parameters

• host: The service endpoint. You can call the API service over the internet or through a VPC. For more information, see Get service endpoints.

  On the API Keys page in the console, you can view the internet and VPC API domains in the Access Domain Name section. The domain name format is http://<instance_id>.opensearch.aliyuncs.com (HTTPS is also supported). The VPC API domain applies to VPC environments in the China (Shanghai), China (Hangzhou), China (Shenzhen), China (Beijing), China (Zhangjiakou), and China (Qingdao) regions.

• workspace_name: The name of the workspace. Example: default.

• service_id: The built-in service ID. Example: ops-text-sparse-embedding-001.

Request parameters

Header parameters

API key authentication

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	The media type of the request. Set this to application/json.	application/json
Authorization	String	Yes	The API key for authentication. The format is Bearer <your_api_key>.	Bearer OS-d1**2a

Body parameters

Parameter	Type	Required	Description	Example
input	Array/String	Yes	The input text to embed, provided as a string or an array of strings. A single request can contain up to 32 entries. The maximum length of each entry depends on the model. Empty strings are not supported.	["Science and technology are the primary productive forces", "OpenSearch product documentation"]
input_type	String	No	The type of the input. Valid values: query document The default value is document.	document
return_token	boolean	No	Specifies whether to return the tokenized text. Valid values: true: The tokenized text is returned. false: The tokenized text is not returned. The default value is false.	false

Response parameters

Parameter	Type	Description	Example
request_id	String	A unique ID for the API call.	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	Float/Int	The request latency in milliseconds (ms).	10
usage	Object	Usage information for the call.	"usage": { "token_count": 11 }
usage.token_count	Int	The number of tokens.	11
result.sparse_embeddings	List	The embedding results. This is an array of objects, with each object corresponding to an item in the input array.	[ { "index": 0, "embedding": [{ "tokenId": 6, "weight": 0.10137939453125 }] }, { "index": 1, "embedding": [{ "tokenId": 9803, "weight": 0.1951904296875 }] } ]
result.sparse_embeddings[].index	Int	The index of the corresponding text in the input array.	0
result.sparse_embeddings[].embedding	List	The sparse embedding result.	[ { "token":"test", "token_id": 900, "weight":0.423 }]
result.sparse_embeddings[].embedding[].token	String	The text token. This field is returned only when return_token is set to true in the request.	"xxx"
result.sparse_embeddings[].embedding[].token_id	Int	The token ID.	123
result.sparse_embeddings[].embedding[].weight	Float	The weight.	0.121

cURL example

curl -XPOST -H "Content-Type: application/json" \
"http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/text-sparse-embedding/ops-text-sparse-embedding-001" \
-H "Authorization: Bearer " \
-d '{
    "input": [
          "Science and technology are the primary productive forces", 
          "OpenSearch product documentation"
    ], 
    "input_type": "query", 
    "return_token": false
}'

Response examples

Successful response

{
	"request_id": "75C50B5B-E79E-4930-****-F48DBB392231",
	"latency": 22,
	"usage": {
		"token_count": 11
	},
	"result": {
		"sparse_embeddings": [
			{
				"index": 0,
				"embedding": [
					{
						"tokenId": 6,
						"weight": 0.10137939453125
					},
					{
						"tokenId": 163040,
						"weight": 0.2841796875
					},
					{
						"tokenId": 354,
						"weight": 0.1431884765625
					},
					{
						"tokenId": 5998,
						"weight": 0.161376953125
					},
					{
						"tokenId": 8550,
						"weight": 0.2388916015625
					},
					{
						"tokenId": 2017,
						"weight": 0.1614990234375
					}
				]
			},
			{
				"index": 1,
				"embedding": [
					{
						"tokenId": 9803,
						"weight": 0.1951904296875
					},
					{
						"tokenId": 86250,
						"weight": 0.317138671875
					},
					{
						"tokenId": 5889,
						"weight": 0.17529296875
					},
					{
						"tokenId": 2564,
						"weight": 0.11614990234375
					},
					{
						"tokenId": 59529,
						"weight": 0.1666259765625
					}
				]
			}
		]
	}
}

Error response

If an error occurs, the response contains the code and message fields that describe the error.

{
    "request_id": "45C8C9E5-6BCB-****-80D3-E298F788512B",
    "latency": 0,
    "code": "InvalidParameter",
    "message": "JSON parse error: Unexpected character ..."
}

Status codes

For more information, see the AI Search Open Platform Status codes.