The OpenSearch 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 |
OpenSearch General Text Embedding Service-001 | ops-text-embedding-001 |
|
OpenSearch Text Embedding Service-Chinese-001 | ops-text-embedding-zh-001 |
|
OpenSearch Text Embedding Service-English-001 | ops-text-embedding-en-001 |
|
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.
|
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 | No | Specifies the data type of the input, with 'document' as the default.
| 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 detailed information on status codes, refer to the referenced document.