Персонализация

Область «Персонализация» в Relevance Studio превращает сигналы анонимных и залогиненных пользователей в правки ранжирования. Она построена на четырёх слоях, каждый из которых опционален и включается независимо для каждого индекса:

1. Профили пользователей — векторы признаков на пользователя, полученные из истории покупок и кликов.
2. Сегменты — крупные когорты (напр. «частые покупатели», «охотники за скидками»), группирующие профили для редакторских бустов.
3. Реранкинг сессии — короткоживущее переупорядочивание внутри сессии на основе последних запросов и кликов.
4. Рекомендации — блоки похожие товары, с этим покупают, часто просматривают вместе, питаемые тем же хранилищем профилей.

Когда включать персонализацию

Включайте персонализацию только если выполнены все три условия:

• В вашем поиске есть реальное понятие возвращающегося пользователя (залогинен или есть стабильный анонимный ID).
• На индекс приходит хотя бы ~10 тыс. click-событий в неделю — ниже сигнал слишком шумный.
• Редакторских curations недостаточно, чтобы один и тот же запрос по-разному показывался разным пользователям.

Если сомневаетесь — начните с только реранкинга сессии: он не требует исторических данных и для новых посетителей деградирует в no-op.

Как personalize=true + sessionId подключаются к поиску

Любой публичный search-запрос может включить персонализацию, отправив два дополнительных поля:

• personalize: true в теле — включает слой для этого запроса.
• sessionId: "<стабильный-id>" — UUID или хеш cookie, связывающий запрос с профилем (или, для анонимов, с их сессией).

Сервер разрешает эти поля в пути чтения до вызова Typesense multi_search и AND-комбинирует выражение профильного буста с существующим ранжированием. Поток — те же пять гейтов, что у обычного поиска: auth, rate limit, tenant filter, scoped filter, multi_search, — с одним дополнительным шагом между rate-limit и tenant-filter: applyPersonalization.

Стабильные ID и PII

sessionId ДОЛЖЕН быть непрозрачным для AACsearch. Не отправляйте сырые e-mail, телефоны или ID пользователя из CRM. Рекомендуемый шаблон:

sessionId = sha256(your_internal_user_id + BETTER_AUTH_SECRET_FRAGMENT).slice(0, 32)

Серверная история, на которой строится профиль, ограничена 100 записями на сессию. Более старые клики и просмотры вытесняются FIFO. Это намеренно: профиль остаётся компактным, быстро грузится на горячем пути и легко чистится по GDPR-запросу права на забвение (одного DELETE /personalization/profile/<sessionId> достаточно).

Пример: curl

curl -X POST https://api.aacsearch.com/api/search/public/multi \
  -H "Authorization: Bearer ss_search_pub_XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "collection": "products",
        "q": "running shoes",
        "query_by": "title,brand,description",
        "personalize": true,
        "sessionId": "9f3c1b2e8a7d4f6c0b1a2d3e4f5a6b7c"
      }
    ]
  }'

Форма ответа не меняется. Если personalize=true не удалось применить — профиль пуст, персонализация отключена на индексе, нет права Scale-плана — запрос аккуратно деградирует к стандартному ранжированию, а в метаданных ответа появляется флаг personalization_applied: false.

Пример: TypeScript SDK / oRPC-клиент

import { client } from "@repo/api/client";

const res = await client.search.public.multi.call({
  searches: [
    {
      collection: "products",
      q: "running shoes",
      query_by: "title,brand,description",
      personalize: true,
      sessionId: visitorSessionId, // sha256(uid + secret).slice(0, 32)
    },
  ],
});

Для браузера используйте поток scoped search token, описанный в Архитектуре → Путь чтения — поля personalize и sessionId пробрасываются через токен без изменений.

Подключение профильного буста к ранжированию

В Studio → Релевантность → Персонализация админ выбирает, как признаки профиля влияют на ранжирование. Поддерживается три режима:

Вес буста — число 0–10. Начните с 1.0, неделю смотрите CTR в панели Обратная связь по кликам, затем повышайте шагами по 0.5. Значения > 5.0 обычно перебивают curations — переходите туда, только если это подтверждено в A/B.

Сегменты

Сегмент — это сохранённый фильтр над пространством профилей. Сегменты задаются в Studio и вычисляются на сервере при каждом персонализированном запросе. Поставляемые из коробки примеры:

• frequent_buyers — профили с ≥ 3 покупками за 30 дней.
• cart_abandoners — профили с ≥ 1 add_to_cart и 0 purchase за 7 дней.
• discount_hunters — профили, у которых ≥ 50% последних кликнутых товаров имели discount_pct > 0.

У каждого сегмента свой вес буста. Пользователь в двух сегментах получает максимум из двух (а не сумму) — так математика остаётся предсказуемой при пересечениях.

Рекомендации

То же хранилище профилей питает эндпоинты рекомендаций. Они выставлены как отдельные oRPC-процедуры и не требуют personalize=true в search-вызове:

• recommendations.related — content-based: похожие на входной productId.
• recommendations.alsoBought — коллаборативные: из click-and-buy-графа.
• recommendations.frequentlyViewedTogether — со-просмотры в одной сессии.

Полный schema запроса/ответа — в разделе Рекомендации.

Лучшие практики по PII

1. Никогда не отправляйте сырой email / телефон / customer ID в sessionId. Сначала хешируйте серверным секретом.
2. Считайте sessionId токеном, а не идентификатором. Он должен ротироваться при выходе пользователя.
3. Ограничение истории — 100 записей. Это серверный default и единственная поддерживаемая конфигурация — задокументировано, чтобы клиенты могли рассуждать о retention.
4. Заведите хук GDPR-удаления. По запросу «право на забвение» вызывайте процедуру personalization.profile.delete со стабильным sessionId. Удаление синхронно и идемпотентно.
5. Не персонализируйте админские сессии в режиме инспекции. Запросы инспекции из Studio должны идти с personalize=false, чтобы объяснитель ранжирования видел несмещённое ранжирование.

Связанные материалы

• Справка API персонализации — полный schema запроса/ответа для personalize=true и recommendations.*.
• Learning to Rank — ортогональный цикл обратной связи, обучающийся на кликах независимо от персонализации.
• Архитектура → Путь чтения — место шага applyPersonalization в потоке запроса.
• Рекомендации — поверхность, потребляющая то же хранилище профилей.