Custom sorting models let you train machine learning ranking models on your own business data — search clicks, purchase conversions, ratings — so OpenSearch returns results ranked by what matters to your users, not just keyword relevance. For example, an e-commerce site can surface best-selling items, and a media platform can promote highly-rated content for each query.
Each instance supports up to three custom sorting models.
How it works
Building a custom sorting model involves four sequential stages:
Create a feature description — define the signals (features) that the model uses to rank documents.
Create a model description — write the Python script that defines model structure and training logic.
Create and train a sorting model — combine the feature description and model description, then trigger training.
Create a Cava-based sort policy — wire the trained model into a sort policy so it affects live search results.
All stages are performed in the OpenSearch Industry Algorithm Edition console under Search Algorithm Center > Sort Configuration.
Prerequisites
Before you begin, ensure that you have:
An OpenSearch Industry Algorithm Edition instance of the Exclusive Cluster type
(Optional) Familiarity with the available feature types — see Feature configuration attributes for custom sorting models
(Optional) Sample Python or TensorFlow script logic — see Developer guide for custom sorting models
Create a feature description
A feature description defines the input signals the model learns from, such as document attributes (price, rating) or query-document relevance scores (BM25).
Log on to the OpenSearch Industry Algorithm Edition console. In the left-side navigation pane, choose Search Algorithm Center > Sort Configuration. In the left-side pane, click Customize Sorting Model. On the Feature Description tab, click Create.
Enter a feature description name, then add the features the model should use. For each feature, specify the feature name, select a feature type, and select the feature.
For details on available feature types, see Feature configuration attributes for custom sorting models. For guidance on selecting specific features, see Basic built-in features.
Create a model description
A model description contains the Python script that defines your model architecture and training logic.
In the Sort Configuration left-side pane, click Customize Sorting Model. On the Model Description tab, click Create.
Enter a model description name, write your Python script in the editor, and click Submit.
For sample code and development guidelines, see Developer guide for custom sorting models.
Create and train a sorting model
In the Sort Configuration left-side pane, click Customize Sorting Model. On the Sorting Model tab, click Create.
Enter a model name. Custom Sorting Model is selected as the model type by default. Turn on Scheduled Training if you want the model to retrain automatically on a schedule.
Select the feature description and model description you created, then click Submit.
On the Sorting Model tab, find the model and click Train in the Actions column.
After training starts, open the model details page to monitor training progress.
When training completes, check the model status:
Available — the model is ready to use. Proceed to Create a Cava-based sort policy.
Unavailable — the model did not meet the required data quality threshold. Open the model details page and review the conditions listed in the Data Verification section. Adjust the model to satisfy those conditions, then retrain the next day.
If the model remains unavailable after adjustment, submit a ticket to contact technical support.
Create a Cava-based sort policy
Custom sorting models can only be used in Cava-based plug-ins. This step creates a sort policy that loads and invokes your trained model at query time.
In the left-side navigation pane, choose Search Algorithm Center > Sort Configuration. In the left-side pane, click Policy Management, then click Create.
Enter a policy name. From the Scope drop-down list, select Fine Sort. From the Type drop-down list, select Cava Script. Click Next.
Click Add Script File and paste your Cava script into the editor. Click Compile. If compilation succeeds, click Save and then Publish.
The following sample script shows how to load and invoke a custom sorting model. Replace "Name of your custom sorting model" with the actual name of the model you trained.
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.algo.AlgoModel;
class BasicSimilarityScorer {
// You can define member variables.
boolean init(OpsScorerInitParams params) {
// Initialize variables related to a search request.
return true;
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
double score = 10;
// Assign the score result to the score parameter.
doc.trace("double value:", score);
return score;
}
};
class IntelligenceAlgorithmScorer {
AlgoModel _algoModel;
boolean init(OpsScorerInitParams params) {
// tf_checkpoint is a fixed parameter name — do not change it.
_algoModel = AlgoModel.create(params, "tf_checkpoint", "rank", "Name of your custom sorting model");
return true;
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
double modelScore = _algoModel.evaluate(params);
doc.trace("rankModelScore: ", modelScore);
double score = modelScore + 700;
return score;
}
};Run a search test
After publishing the sort policy, verify that the model affects search results as expected.
In the left-side navigation pane, choose Feature Extensions > Search Test.
On the Search Test page, specify the following required parameters:
Parameter Description queryThe search query string second_rank_typeThe type of the secondary ranking stage second_rank_nameThe name of the sort policy you published raw_queryA unique, independent search query that returns results. Also required in model upgrade conditions — see Demo code for implementing the search feature Submit the search request and review the ranked results to confirm the model is working as expected.
Usage notes
Training a custom sorting model incurs separate charges. For details, see Billing overview.
For related API operations and SDKs, see Algorithms.
What's next
Best practices: Create a custom sorting model — end-to-end examples with real training data
Feature configuration attributes for custom sorting models — full reference for feature types and parameters
Developer guide for custom sorting models — Python script authoring guide