Search Personalization

Introduction

This guide explains how to configure, activate, and maintain search personalization models using the Raptor API. It covers model versioning, embedding management, API endpoints, and authentication.

The Search Personalization API (search-personalization-api.raptorsmartadvisor.com) enables personalized search experiences by leveraging machine learning models trained on customer-specific data. These models continuously learn and adapt to ensure relevant and dynamic search results.

How It Works

Models are configured per customer account and continuously retrained on the latest data

1. A file containing item embeddings, and

2. An API that generates user embeddings based on each user’s most recent history.

At query time, the search engine compares the user embedding to personalize results by performing vector-similarity comparison between the user embedding and the item embeddings loaded into the search index.

Key Principles

• Raptor continuously collects data and produces new model versions. It is essential that item embeddings and user embeddings always come from the same model version. Each new version includes a new item-embedding file, which must be downloaded and loaded into the search index. After loading these embeddings, you must instruct the Search Personalization API to use the same version for generating user embeddings.

• Its recommended always upgrading to the latest version, as new versions include newly added products and are trained on the most recent data. (Check the latestVersion endpoint regularly (eg. daily) to ensure you’re using the newest model.)

• The Search Personalization API will always return embeddings for the currently active version. To upgrade, load the item embeddings for the new version into your search index and then switch the active version in the Search Personalization API. (From that point on, the API will generate embeddings from the new model version.)

• The recommended flow is to pre-fetch user embeddings before users perform searches, ensuring embeddings are available instantly at query time without adding latency.

---

API Endpoints

Explore all endpoints in the swagger

Model Management

• /{CustomerId}/models
Lists all configured models.

• /{CustomerId}/model/{ModelId}/versions
  Lists all available versions and shows the active one.

• /{CustomerId}/model/{ModelId}/latestVersion
  Returns the newest version.

Item Embeddings

• /{CustomerId}/model/{ModelId}/itemEmbeddings/{ModelVersion}
  Downloads item embeddings for a specific model/version.

Once the item embeddings have been loaded into your search index, switch the active version in the Search Personalization API using:

Activation

• /{CustomerId}/model/{ModelId}/activate/{ModelVersion}
  Activates a new model version (takes ~30 sec). Deactivates the old version automatically.

• /{CustomerId}/model/{ModelId}/deactivate
  Deactivates the currently active version.

After activation, retrieve user embeddings via the Raptor Recommendation Engine module GetUserEmbeddings (documented in the Control Panel). 

---

Restrictions

• Maximum 2 models can be active in parallel.
• Only one version per model can be active at a time.

---

Authentication

All API calls require Bearer Token authentication in the header

The flow involves calling *login.raptorsmartadvisor.com* for a bearer token then using it in subsequent calls. Tokens expire after 300 seconds so re-authentication is required for longer running flows. 

Token Flow

1. Request token from login.raptorsmartadvisor.com.
2. Use token in subsequent API calls.
3. Tokens expire after 300 seconds; re-authentication is required for long-running processes.

curl --location 'https://login.raptorsmartadvisor.com/realms/raptor/protocol/openid-connect/token' \

--request POST \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'client_id=search-personalization-external-api-[CUSTOMERID]' \

--data-urlencode 'client_secret=...' \

--data-urlencode 'grant_type=client_credentials'

Use the token:

curl --location 'https://search-personalization-api.raptorsmartadvisor.com/[CUSTOMERID]/models' \

--request GET \

--header 'Authorization: bearer [token here]'