Use the category prediction feature

Prerequisites

Before you begin, make sure that you have:

• Category ID, commodity title, and category name fields configured as attribute fields in your application schema

• (If using Commodity Data) Document data that contains category ID, commodity title, and category name fields

• (If using Behavior Data) Click behavior data collected via data collection

Create and train a category prediction model

1. In the left-side navigation pane, choose Search Algorithm Center > Sort Configuration. In the navigation tree, click Category Prediction Model, then click Create.

   

2. On the Create Category Prediction page, fill in the model details.

   Field	Description	Required
   Model name	A name for the model	Yes
   Data Type	Commodity Data: document data from your application. Requires category ID, commodity title, and category name fields. Behavior Data: collected click behavior data.	Yes
   Category ID	The field representing the category ID in your application documents. Supports the INT data type. Must be a positive integer—a non-positive value causes a server error.	Yes
   Commodity Title	The field representing the commodity title. Supports TEXT and LITERAL data types.	Yes
   Category Name	The field representing the category name. Supports TEXT and LITERAL data types.	Yes
   Filter Condition	A condition to filter training data. Field names must match those in the application schema. Supports: <, >, <=, >=, =, !=. Separate multiple conditions with commas (,)—all conditions use AND logic. OR logic is not supported. Example: is_onsale > 0	No

   

3. Click Completed to go to the model details page.

   

4. On the Category Prediction Model page, the model status is Pending Training. Click Train in the Actions column to start training.

   

   The model moves through the following states:

   State	Meaning
   Pending Training	Model created, training not started
   Training	Model is being trained
   Training Failed	Training failed due to a data error
   Not Applied	Training complete, not yet referenced for retrieval or sorting
   Trained and Not Passed	Training complete, but the model failed to pass the training

   If you have questions, submit a ticket.

Configure query analysis and sort expressions

Activate category prediction in API and SDK calls

Category prediction sorts search results only when the raw_query parameter is present and its value matches the search query in the index.

Set raw_query to the search query entered by the user:

raw_query=<search_query>

• When calling via API: URL-encode the value using URL_ENCODE.

• When calling via SDK: no encoding needed.

# index3 prediction takes effect (query matches raw_query for index3 only)
query=index2:'index_query' AND index3:'search_query'&raw_query=search_query

# index2 prediction takes effect preferentially;
# if index2 config doesn't apply, index3 takes effect
query=index2:'search_query' AND index3:'search_query'&raw_query=search_query

Limits

• Up to five category prediction models can be created per application.

• The data fields used to train the model must be included in the indexes to which the query analysis rule is applied.

• Before creating a model, configure category ID and related fields as attribute fields.

• If a query analysis rule references a category prediction model and the request contains the category_prediction parameter, an error occurs.

• For category prediction to take effect, all three of the following must be configured: a query analysis rule referencing the model, a sort expression containing the category_score function, and the raw_query parameter in the request.

• Related API operations: Algorithms

Troubleshooting model training failures

If your category prediction model training fails, follow these steps to troubleshoot:

1. Check the anomaly report: On the model details page, view the Latest Version Status. If the status shows a data error, open the Anomaly Report to identify the cause of the failure.

2. Check the completeness level: View the Completeness Level and the corresponding Upgrade Conditions. Adjust your data according to the upgrade conditions to improve the completeness level.

3. T-1 data logic: Model training uses statistical data from the previous day (T-1). When a newly created model is trained for the first time, the training may fail with a "Training field does not exist" error because no data from the previous day is available. Wait until the next day when data is ready, then retrain the model.

4. Data volume requirement: Training requires the number of unique queries from the most recent day to exceed 100. The unique query count refers to the number of successful search requests that include the raw_query parameter.

5. Filter condition format: If filter conditions are configured, field names must match fields in the application schema. Multiple conditions use AND logic and must be separated by commas (,). An incorrect format may cause training failures. Example: is_onsale > 0.

Advanced usage

Combine with Named Entity Recognition (NER)

If you configure NER alongside category prediction in a query analysis rule, more documents are retrieved. The NER results are also used for retrieval. If no documents match the predicted categories, words in the search query are selectively ignored to broaden results—these broader results become the final category prediction output. For more information, see Named entity recognition.

Intervene in prediction results

Intervention lets you override the trained model's predictions, similar to query analysis intervention. For more information, see Intervention dictionaries for category prediction.