Vector dimensionality reduction service

Service name	Service ID	Description	QPS limit
OpenSearch vector dimensionality reduction service-001	ops-embedding-dim-reduction-001	Reduces vector dimensions. You can fine-tune the model to create a custom service for your business needs. This service supports vectors with up to 4,000 dimensions.	50 Note To request a higher QPS limit, submit a ticket.

Prerequisites

• Obtain authentication credentials

  All API calls to the AI Search Open Platform service require authentication. For details, see Obtain an API key.

• Obtain a service endpoint

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

Request format

General instructions

• The request body cannot exceed 8 MB.

HTTP request method

POST

URL

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

• host: The service endpoint. You can call the API over the public network or a VPC. For details, see Obtain a service endpoint. To obtain the endpoint, log on to the AI Search Open Platform console. In the left-side navigation pane, click API Keys. In the Access domain name section, copy the domain name for the {host} value. Use the public domain name for public network access and the private domain name for VPC access in the China (Shanghai), China (Hangzhou), China (Shenzhen), China (Beijing), China (Zhangjiakou), and China (Qingdao) regions. Click Create API Key to create a new key.

• workspace_name: The name of your workspace, such as default.

• service_id: The built-in service ID, such as ops-embedding-dim-reduction-001.

Request parameters

Header parameters

API key authentication

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	The format of the request. Set this to application/json.	application/json
Authorization	String	Yes	Your API key.	Bearer OS-d1**2a

Body parameters

Parameter	Type	Required	Description	Example
input	List<List<Float>>	Yes	A collection of input vectors.	[0.111,0.222,0.333]
parameters	Map	No	Adjustable request parameters. The available parameters vary based on the service ID.
parameters.output_dimension	Integer	No	The dimension of the output vectors. Default value: 512.	512
parameters.model_name	String	No	The name of your custom-trained model. This parameter is required for vector compression services.	xxxx-model

Response parameters

Parameter	Type	Description	Example
result.output	List<List<Float>>	The output vectors after fine-tuning.
usage.doc_count	Int	The number of vectors in the request.	2

cURL request example

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/embedding-tuning/ops-embedding-dim-reduction-001/' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{  
  "input": [
    [0.111,0.222,0.333],
    [0.121,0.221,0.331]
  ],
  "parameters":{
    "output_dimension": "512",
    "model_name" : "xxxx"
  }
}'

Response examples

Success response example

{
  "request_id": "450fcb80-f796-46c1-8d69-e1e86d29aa9f",
  "latency": 564.903929,
  "usage": {
    "doc_count": 2
  },
  "result": {
    "output":[
      [0.111,0.222,0.333],
      [0.121,0.221,0.331]
    ]
  }
}

Error response example

If a request fails, the response includes a code and a message that describe the error.

{
    "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
    "latency": 0.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "document.file_name required"
}

Status codes

HTTP status code	Error code	Description
200	-	The request is successful.
404	BadRequest.TaskNotExist	The specified task does not exist.
400	InvalidParameter	The request is invalid.
500	InternalServerError	An internal server error occurred.

For a complete list of error codes, see Status codes.