Text embedding - OpenSearch - Alibaba Cloud Documentation Center

The search development workbench supports the invocation of the word embedding service via API. This service enables the conversion of text data into dense vector representations, suitable for use in scenarios such as information retrieval, text classification, and similarity comparison.

Service name	Service ID	Service description	QPS limit for API calls (Alibaba Cloud account and RAM users)
OpenSearch General Text Embedding Service-001	ops-text-embedding-001	Supported languages: Multilingual (40+) Maximum input text length: 300 Output vector dimension: 1536	50 Note To apply for higher QPS, submit a ticket.
OpenSearch Text Embedding Service-Chinese-001	ops-text-embedding-zh-001	Supported languages: Chinese Maximum input text length: 1024 Output vector dimension: 768
OpenSearch Text Embedding Service-English-001	ops-text-embedding-en-001	Supported languages: English Maximum input text length: 512 Output vector dimension: 768
OpenSearch General Text Embedding Service-002	ops-text-embedding-002	This model offers enhanced language support and improved performance in retrieval tasks compared to the 001 model. Supported languages: Multilingual (100+) Maximum input text length: 8192 Output vector dimension: 1024

Prerequisites

Get authentication information
When invoking the OpenSearch Search Development Console service through APIs, you need to authenticate the caller's identity.
Get service access address
Supports invoking the service through both public network and VPC. For more information, see Get service registration address.

Request description

General description

The maximum request body size must not exceed 8MB.

Request method

POST

URL

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

host: The address for invoking the service, accessible via both the public network and VPC. For more information, see the referenced document.
workspace_name: The name of the workspace, such as 'default'.
service_id: The specific service ID, such as 'ops-text-embedding-001'.

Request parameters

Header parameters

API-KEY authentication is required.

Parameter	Type	Required	Description	Example value
Content-Type	String	Yes	The MIME type of the request, which should be set to application/json.	application/json
Authorization	String	Yes	The API key for authentication, prefixed with 'Bearer'.	Bearer OS-d1**2a

Body parameters

Parameter

Type

Required

Description

Example value

input

Array/String

Yes

The content to be processed. It supports multiple text inputs, with a maximum of 32 per request. The length of each input is model-dependent. Empty strings are not accepted.

["Science and technology are the primary productive forces","opensearch product documentation"]

input_type

String

Specifies the data type of the input, with 'document' as the default.

query
document

document

Response parameters

Parameter	Type	Description	Example value
request_id	String	The system-generated unique identifier for the API call.	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	Float/Int	The duration of the request in milliseconds.	10
usage	Object	Information regarding the metering of the call.	"usage": { "token_count": 3072 }
usage.token_count	Int	The number of tokens used in the request.	3072
result.embeddings	List	The array of results containing the output embedding content.	[{ "index": 0, "embedding": [0.003143,0.009750,...,-0.017395] }, {}]
result.embeddings[].index	Int	The ordinal number corresponding to the input text.	0
result.embeddings[].embedding	List(Float)	The vectorized representation of the input text.	[0.003143,0.009750,...,-0.017395]

Curl request example

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

Response example

Normal response example

{
    "request_id": "B4AB89C8-B135-****-A6F8-2BAB801A2CE4",
    "latency": 38,
    "usage": {
        "token_count": 3072
    },
    "result": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.02868066355586052,
                    0.022033605724573135,
                    -0.0417383536696434,
                    -0.044081952422857285,
                    0.02141784131526947,
                    -8.240503375418484E-4,
                    -0.01309406291693449,
                    -0.02169642224907875,
                    -0.03996409475803375,
                    0.008053945377469063,
                    ...
                    -0.05131729692220688,
                    -0.016595875844359398
                ]
            }
        ]
    }
}

Abnormal response example

If the request encounters an error, the response will detail the cause with a specific code and message.

{
    "request_id": "651B3087-8A07-****-B931-9C4E7B60F52D",
    "latency": 0,
    "code": "InvalidParameter",
    "message": "JSON parse error: Cannot deserialize value of type `InputType` from String \"xxx\""
}

Status code description

For more information on status codes, see Status code description.