Build an end-to-end image search service by using OpenSearch Vector Search Edition - OpenSearch

OpenSearch Vector Search Edition handles image vectorization and vector indexing internally, so you can build an image search service without managing vector pipelines yourself. This guide walks you through the full setup: uploading images to Object Storage Service (OSS), configuring an OpenSearch instance, and running your first image search query.

How it works

Upload images to an OSS bucket or store them in MaxCompute. OpenSearch pulls the image data, runs it through a CLIP vectorization model to generate 512-dimensional vectors, and builds a vector index. Once indexed, you can search by image or by text.

Three data ingestion paths are supported:

Path	Description
OSS + MaxCompute + OpenSearch	Store images in OSS; store business table data and OSS image URLs (e.g., `/image/1.jpg`) in MaxCompute. OpenSearch reads from MaxCompute.
MaxCompute + OpenSearch	Store Base64-encoded images and table data directly in MaxCompute.
API + OpenSearch	Push Base64-encoded images and table data directly to OpenSearch via API.

This guide uses the OSS + MaxCompute + OpenSearch path.

Prerequisites

Before you begin, make sure you have:

An Alibaba Cloud account with an AccessKey pair. An AccessKey pair is required to create and use an OpenSearch instance. To use a Resource Access Management (RAM) user instead, see Create and authorize RAM users.
An OSS bucket with your images uploaded. This guide uses a bucket with 1,000 images.
A MaxCompute project containing a table with your business data and the OSS URL for each image.

Set up the OSS bucket

Create an OSS bucket and upload your images.
Add the opensearch tag to the bucket. Set both the key and value to opensearch.
Make sure the service-linked role AliyunServiceRoleForSearchEngine exists in your account. This role grants OpenSearch read access to OSS.

Purchase an OpenSearch Vector Search Edition instance

See Purchase an OpenSearch Vector Search Edition instance for purchase steps.

After purchase, the instance is in the Pending Configuration state. Complete the following steps to configure it before running searches.

Configure the instance

The configuration wizard has five steps: basic table information, data synchronization, field configuration, index schema, and confirmation.

Step 1: Set basic table information

Configure the following parameters, then click Next.

Parameter	Description
Table Name	A name for the table. Choose any name that suits your naming conventions.
Data Shards	Number of shards for the table. Enter an integer from 1 to 256. More shards speed up full indexing and improve single-query performance. If you create multiple index tables in the same instance, all tables must have the same shard count—or one table has 1 shard and the rest share the same count.
Number of Resources for Data UpdatesBilling overview of OpenSearch Vector Search Edition for the international site (alibabacloud.com)	Resources allocated for data updates. Each instance includes a free quota of 2 resources per data source (4 CPU cores and 8 GB of memory each). Additional resources are billed. See Billing overview.
Scenario Template	Select Vector: Image Search.
Data Processing	Select Convert Raw Data to Vector Data.

Step 2: Configure data synchronization

Add a data source, then click Check to validate it. If validation passes, click Next.

Parameter	Description
Full Data Source	The data source type. Select MaxCompute + API for this guide. Other options: OSS + API, API.
Project	The MaxCompute project name.
AccessKey	The AccessKey ID of your Alibaba Cloud account or RAM user.
AccessKey Secret	The AccessKey secret corresponding to the AccessKey ID.
Table	The MaxCompute table name.
Partition Key	The partition key of the MaxCompute data source. Required. Example: `ds=20170626`.
Timestamp	The point in time from which OpenSearch starts syncing incremental data. Select a time within the previous 72 hours. Only applies when incremental data is pushed via API.
Automatic Reindexing	When enabled, OpenSearch automatically reindexes the table each time it detects a data change in the data source.

Enabling Automatic Reindexing requires a done table in MaxCompute. See the Configure automatic reindexing section of the MaxCompute data source topic.

Step 3: Configure fields

At minimum, configure a primary key field, a vector field, and a field marked for embedding.

The Vector: Image Search template generates four preset fields:

Field	Type	Description
`id`	Primary key	Unique identifier for each record
`cate_id`	—	Category ID
`vector`	FLOAT	The vector generated from the image
`vector_source_image`	STRING	The image URL (for OSS images) or Base64-encoded image data

After you connect a MaxCompute data source, the fields from your MaxCompute table appear below the preset fields. Rename preset fields to match your business table field names if needed.

For images stored in OSS

Configure vector_source_image:

Set Type to STRING and select Require Embedding for the field.
Click Edit in the Advanced Configurations column and set the following:
Important
The value of vector_source_image must match the OSS object path exactly. For example, if the OSS URL of an image is /test image/lake.jpg, set the field value to /test image/lake.jpg.
Parameter Description
Vectorization Model clip for regular images; clip_ecom for e-commerce images.
Data Type Select image(path).
Source Content Type Select oss.
OSS Bucket The name of your OSS bucket.

Parameter	Description
Vectorization Model	`clip` for regular images; `clip_ecom` for e-commerce images.
Data Type	Select image(path).
Source Content Type	Select oss.
OSS Bucket	The name of your OSS bucket.

Configure vector:

Set Type to FLOAT and select Vector Field for the field.

For Base64-encoded images

Configure vector_source_image:

Set Type to STRING and select Require Embedding for the field.
Click Edit in the Advanced Configurations column and set the following:
Parameter Description
Vectorization Model clip for regular images; clip_ecom for e-commerce images.
Data Type Select Image (Base64-encoded).

Parameter	Description
Vectorization Model	`clip` for regular images; `clip_ecom` for e-commerce images.
Data Type	Select Image (Base64-encoded).

Configure vector:

Set Type to FLOAT and select Vector Field for the field.

Step 4: Configure the index schema

Configure the vector index and click Next.

The vector index name defaults to the vector field name.
Fields Contained includes Primary Key Field, Vector Field, and an optional Namespace.
The vector dimension for images is fixed at 512 and cannot be changed.
Adjust advanced index settings based on your performance and recall requirements.

Step 5: Confirm and create

Review the configuration summary and click Confirm.

To track table creation progress, open Change History in the left-side pane of the instance details page.

Once full data sync completes, the instance is ready for search queries.

Run query tests

Test in the OpenSearch console

See Query tests for how to run search queries from the console.

Test with an SDK

Use the prediction-based query method to search by image or text. See the Prediction-based query section of the Query data topic for request examples.

A successful response looks like this:

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

result contains the returned results.

What's next

Query syntax: For image vectorization-based queries, see the Image vectorization-based query section of the Prediction-based query topic. For primary key lookups, see Primary key-based query. For filtering results, see Filter expression.
SDK integration: To run vector queries or primary key queries with an SDK, see Query data. To add or delete documents, see Update data.