OpenSearch:Demo code for vectorizing text, slicing text, and vectorizing slices

Prerequisites

Before you begin, make sure you have:

• An OpenSearch LLM-Based Conversational Search Edition application

• An AccessKey pair (AccessKey ID and AccessKey secret) for a Resource Access Management (RAM) user with the required permissions. See Create a RAM user and Access authorization rules

• The AliyunServiceRoleForOpenSearch role granted to your Alibaba Cloud account. See AliyunServiceRoleForOpenSearch

Set environment variables

Set the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to your RAM user's AccessKey ID and AccessKey secret.

Linux and macOS

Replace <access_key_id> and <access_key_secret> with your values, then run:

export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>

Windows

1. Create an environment variable file and add the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET variables with your AccessKey ID and AccessKey secret.

2. Restart Windows for the changes to take effect.

Install dependencies

Java

Add the following dependency to your Maven project:

<dependency>
    <groupId>com.aliyun.opensearch</groupId>
    <artifactId>aliyun-sdk-opensearch</artifactId>
    <version>6.0.0</version>
</dependency>

Python

Install the required packages:

pip install alibabacloud_tea_util
pip install alibabacloud_opensearch_util
pip install alibabacloud_credentials

For the BaseRequest module used in the Python samples, see Python client example.

PHP

Download and install the PHP SDK (V3.4.1, released 2021-05-11):

https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20230719/mxik/opensearch-sdk-php-release-v3.4.1.zip

Vectorize text

The knowledge-embedding endpoint converts text into a vector embedding. Set "query": false to embed a document (not a search query). Set "query": true when vectorizing a search query.

Java

package com.aliyun.opensearch;

import com.aliyun.opensearch.OpenSearchClient;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchResult;

import java.util.HashMap;
import java.util.Map;

public class LLMSearch {
    private static String appName = "The name of the OpenSearch application";
    private static String host = "The API endpoint of the OpenSearch application";
    private static String path = "/apps/AppName/actions/knowledge-embedding";

    public static void main(String[] args) {
        // Read credentials from environment variables.
        // Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET before running.
        String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
        openSearch.setTimeout(62000); // API read timeout in milliseconds

        OpenSearchClient openSearchClient = new OpenSearchClient(openSearch);

        Map<String, String> params = new HashMap<String, String>() {{
            put("format", "full_json");
            // content: the text to vectorize
            // query: false means this is a document (not a search query)
            put("_POST_BODY", "{\"content\":\"Test text\",\"query\":false}");
        }};

        try {
            OpenSearchResult openSearchResult = openSearchClient
                .callAndDecodeResult(path, params, "POST");
            System.out.println("RequestID=" + openSearchResult.getTraceInfo().getRequestId());
            System.out.println(openSearchResult.getResult());
        } catch (OpenSearchException e) {
            System.out.println("RequestID=" + e.getRequestId());
            System.out.println("ErrorCode=" + e.getCode());
            System.out.println("ErrorMessage=" + e.getMessage());
        } catch (OpenSearchClientException e) {
            System.out.println("ErrorMessage=" + e.getMessage());
        }
    }
}

Python

# -*- coding: utf-8 -*-

import os
from typing import Dict, Any

from Tea.exceptions import TeaException
from alibabacloud_tea_util import models as util_models
from BaseRequest import Config, Client


class LLMSearch:
    def __init__(self, config: Config):
        self.Clients = Client(config=config)
        self.runtime = util_models.RuntimeOptions(
            connect_timeout=10000,
            read_timeout=10000,
            autoretry=False,
            ignore_ssl=False,
            max_idle_conns=50,
            max_attempts=3
        )
        self.header = {}

    def searchDoc(self, app_name: str, body: Dict, query_params: dict = {}) -> Dict[str, Any]:
        try:
            response = self.Clients._request(
                method="POST",
                pathname=f'/v3/openapi/apps/{app_name}/actions/knowledge-embedding',
                query=query_params,
                headers=self.header,
                body=body,
                runtime=self.runtime
            )
            return response
        except TeaException as e:
            print(e)


if __name__ == "__main__":
    # The OpenSearch API endpoint — do not include the http:// prefix.
    endpoint = "<endpoint>"

    # Request protocol. Valid values: HTTPS, HTTP.
    endpoint_protocol = "HTTP"

    # Read credentials from environment variables.
    # Set these variables before running. See "Set environment variables" above.
    access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID")
    access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

    # Authentication method. Default: access_key.
    # Use sts for RAM + Security Token Service (STS) authentication.
    auth_type = "access_key"

    # Required only when auth_type is sts.
    # Get an STS token by calling the AssumeRole operation of Alibaba Cloud RAM.
    security_token = "<security_token>"

    Configs = Config(
        endpoint=endpoint,
        access_key_id=access_key_id,
        access_key_secret=access_key_secret,
        security_token=security_token,
        type=auth_type,
        protocol=endpoint_protocol
    )

    ops = LLMSearch(Configs)
    app_name = "<Application name>"

    # content: the text to vectorize
    # query: false means this is a document (not a search query)
    docQuery = {"content": "Test text", "query": False}

    res1 = ops.searchDoc(app_name=app_name, body=docQuery)
    print(res1)

PHP

<?php
require_once($path . "/OpenSearch/Autoloader/Autoloader.php");

use OpenSearch\Client\OpenSearchClient;

// Read credentials from environment variables.
// Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET before running.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$secret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');
$endPoint = '<The API endpoint of the OpenSearch application>';
$appName = '<The application name>';
$options = array('debug' => true);

// content: the text to vectorize
// query: false means this is a document (not a search query)
$requestBody = '{"content":"Test text","query":false}';

$client = new OpenSearchClient($accessKeyId, $secret, $endPoint, $options);

$uri = "/apps/{$appName}/actions/knowledge-embedding";

try {
    $ret = $client->post($uri, $requestBody);
    print_r(json_decode($ret->result, true));
} catch (\Throwable $e) {
    print_r($e);
}

Slice text and vectorize slices

The knowledge-split endpoint splits text into chunks. Setting "use_embedding": true also vectorizes each chunk in the same call, returning both the chunked text and the embeddings in one request. This is more efficient than calling knowledge-embedding separately for each chunk.

Java

package com.aliyun.opensearch;

import com.aliyun.opensearch.OpenSearchClient;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchResult;

import java.util.HashMap;
import java.util.Map;

public class LLMSearch {
    private static String appName = "The name of the OpenSearch application";
    private static String host = "The API endpoint of the OpenSearch application";
    private static String path = "/apps/AppName/actions/knowledge-split";

    public static void main(String[] args) {
        // Read credentials from environment variables.
        // Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET before running.
        String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
        openSearch.setTimeout(62000); // API read timeout in milliseconds

        OpenSearchClient openSearchClient = new OpenSearchClient(openSearch);

        Map<String, String> params = new HashMap<String, String>() {{
            put("format", "full_json");
            // title: document title used to guide chunking
            // content: the full text to split into chunks
            // use_embedding: true means each chunk is also vectorized
            put("_POST_BODY", "{\"title\":\"Test title\",\"content\":\"Test text\",\"use_embedding\":true}");
        }};

        try {
            OpenSearchResult openSearchResult = openSearchClient
                .callAndDecodeResult(path, params, "POST");
            System.out.println("RequestID=" + openSearchResult.getTraceInfo().getRequestId());
            System.out.println(openSearchResult.getResult());
        } catch (OpenSearchException e) {
            System.out.println("RequestID=" + e.getRequestId());
            System.out.println("ErrorCode=" + e.getCode());
            System.out.println("ErrorMessage=" + e.getMessage());
        } catch (OpenSearchClientException e) {
            System.out.println("ErrorMessage=" + e.getMessage());
        }
    }
}

Python

# -*- coding: utf-8 -*-

import os
from typing import Dict, Any

from Tea.exceptions import TeaException
from alibabacloud_tea_util import models as util_models
from BaseRequest import Config, Client


class LLMSearch:
    def __init__(self, config: Config):
        self.Clients = Client(config=config)
        self.runtime = util_models.RuntimeOptions(
            connect_timeout=10000,
            read_timeout=10000,
            autoretry=False,
            ignore_ssl=False,
            max_idle_conns=50,
            max_attempts=3
        )
        self.header = {}

    def searchDoc(self, app_name: str, body: Dict, query_params: dict = {}) -> Dict[str, Any]:
        try:
            response = self.Clients._request(
                method="POST",
                pathname=f'/v3/openapi/apps/{app_name}/actions/knowledge-split',
                query=query_params,
                headers=self.header,
                body=body,
                runtime=self.runtime
            )
            return response
        except TeaException as e:
            print(e)


if __name__ == "__main__":
    # The OpenSearch API endpoint — do not include the http:// prefix.
    endpoint = "<endpoint>"

    # Request protocol. Valid values: HTTPS, HTTP.
    endpoint_protocol = "HTTP"

    # Read credentials from environment variables.
    # Set these variables before running. See "Set environment variables" above.
    access_key_id = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID")
    access_key_secret = os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

    # Authentication method. Default: access_key.
    # Use sts for RAM + Security Token Service (STS) authentication.
    auth_type = "access_key"

    # Required only when auth_type is sts.
    # Get an STS token by calling the AssumeRole operation of Alibaba Cloud RAM.
    security_token = "<security_token>"

    Configs = Config(
        endpoint=endpoint,
        access_key_id=access_key_id,
        access_key_secret=access_key_secret,
        security_token=security_token,
        type=auth_type,
        protocol=endpoint_protocol
    )

    ops = LLMSearch(Configs)
    app_name = "<Application name>"

    # title: document title used to guide chunking
    # content: the full text to split into chunks
    # use_embedding: True means each chunk is also vectorized
    docQuery = {"title": "Test title", "content": "Test text", "use_embedding": True}

    res1 = ops.searchDoc(app_name=app_name, body=docQuery)
    print(res1)

PHP

<?php
require_once($path . "/OpenSearch/Autoloader/Autoloader.php");

use OpenSearch\Client\OpenSearchClient;

// Read credentials from environment variables.
// Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET before running.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$secret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');
$endPoint = '<The API endpoint of the OpenSearch application>';
$appName = '<The application name>';
$options = array('debug' => true);

// title: document title used to guide chunking
// content: the full text to split into chunks
// use_embedding: true means each chunk is also vectorized
$requestBody = '{"title":"Test title","content":"Test text","use_embedding":true}';

$client = new OpenSearchClient($accessKeyId, $secret, $endPoint, $options);

$uri = "/apps/{$appName}/actions/knowledge-split";

try {
    $ret = $client->post($uri, $requestBody);
    print_r(json_decode($ret->result, true));
} catch (\Throwable $e) {
    print_r($e);
}

What's next

• Python client example — the BaseRequest module used in the Python samples above

• Access authorization rules — required permissions for API calls

• AliyunServiceRoleForOpenSearch — service-linked role details