Installing Custom Embedding Models

Install a custom embedding model when you want Semantic Search to use an embedding model other than the delivered model. A custom embedding model must be registered and deployed in OpenSearch before you import and activate it in PeopleSoft.

Configure proxy settings for the OpenSearch node if the node must access an external model repository through a proxy. Proxy configuration is required only when the OpenSearch node cannot directly access the model source.

Example proxy settings:

-Dhttps.proxyHost=<proxy_host>
-Dhttps.proxyPort=<proxy_port>

Complete these steps to Install a custom embedding model in OpenSearch:

1. Register a model group in OpenSearch.

   Register a model group to organize one or more versions of the custom embedding model. Save the model_group_id from the response. You use this value when you register the model.

   Endpoint:

   POST /_plugins/_ml/model_groups/_register

   Example:

   {
     "name": "ptsf_custom_embedding_model_group",
     "description": "Model group for PeopleSoft Semantic Search custom embedding models",
     "access_mode": "public"
   }
   

   Response:

   {
     "model_group_id": "GDNmQ4gBYW0Qyy5ZcBcg",
     "status": "CREATED"
   }
   

2. Register the embedding model in the model group and monitor the model registration task.

   Register the embedding model to the model group. Save the task_id and model_id from the response. Use the task_id to monitor the registration task until the task completes successfully.

   Endpoint:

   POST /_plugins/_ml/models/_register

   Example:

   {
     "name": "all-MiniLM-L6-v2",
     "version": "1.0.0",
     "description": "Custom text embedding model for PeopleSoft Semantic Search",
     "model_format": "TORCH_SCRIPT",
     "function_name": "TEXT_EMBEDDING",
     "model_group_id": "GDNmQ4gBYW0Qyy5ZcBcg",
     "model_content_hash_value": "c15f0d2e62d872be5b5bc6c84d2e0f4921541e29fefbef51d59cc10a8ae30e0f",
     "model_config": {
       "model_type": "bert",
       "embedding_dimension": 384,
       "framework_type": "sentence_transformers"
     },
     "url": "https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/all-MiniLM-L6-v2/1.0.1/torch_script/sentence-transformers_all-MiniLM-L6-v2-1.0.1-torch_script.zip"
   }
   

   Response:

   {
     "task_id": "tsqvDY4BChVAiNVEuo8F",
     "status": "CREATED",
     "model_id": "t8qvDY4BChVAiNVEuo8q"
   }
   

   Endpoint to monitor the registration task:

   GET /_plugins/_ml/tasks/<task_id>

   Response:

   {
     "model_id": "t8qvDY4BChVAiNVEuo8q",
     "task_type": "REGISTER_MODEL",
     "function_name": "TEXT_EMBEDDING",
     "state": "COMPLETED",
     "worker_node": [
       "N77RInqjTSq_UaLh1k0BUg"
     ],
     "is_async": true
   }
   

3. Deploy the registered model in OpenSearch and monitor the deployment task.

   Deploy the registered model so that OpenSearch can use it to generate vector embedding. Save the task_id from the response and monitor the deployment task until it completes successfully.

   Endpoint:

   POST /_plugins/_ml/models/<model_id>/_deploy

   Example:

   POST /_plugins/_ml/models/t8qvDY4BChVAiNVEuo8q/_deploy

   Response:

   {
     "task_id": "hA8P44MBhyWuIwnfvTKP",
     "task_type": "DEPLOY_MODEL",
     "status": "CREATED"
   }
   

   Endpoint to monitor the deployment task:

   GET /_plugins/_ml/tasks/<task_id>

   Response:

   {
     "model_id": "t8qvDY4BChVAiNVEuo8q",
     "task_type": "DEPLOY_MODEL",
     "function_name": "TEXT_EMBEDDING",
     "state": "COMPLETED",
     "worker_node": [
       "N77RInqjTSq_UaLh1k0BUg"
     ],
     "is_async": true
   }
   

After the deployment task completes successfully, import the deployed model into PeopleSoft, set the model as the active model, and redeploy and fully index the affected search definitions. For more information, see Managing Semantic Search Embedding Models.

For more information about custom embedding models, refer to the OpenSearch Model APIs documentation available on the OpenSearch website (www.opensearch.org).

Note:

Changing the active embedding model does not automatically regenerate existing embedding. If you change the active model, or if a custom model uses a vector dimension that differs from the current mapping, update the Semantic Search configuration as needed, redeploy the affected search definitions, and run a full index to generate the stored embedding using the selected model.

Vector embedding generation and indexing are resource-intensive operations. Before enabling Semantic Search for any additional search definition, perform a proper assessment and ensure that one or more dedicated ML nodes are configured to support high usage.

Evaluate the storage requirements for vector embedding by using representative sample data before performing a full index. Ensure that sufficient storage is available for the fully indexed data. In general, indexes with vector embedding may require approximately three to four times more storage than indexes without vectors. The actual storage requirement may vary depending on the embedding model, vector dimension, chunking, and Semantic Search configuration.