События и рекомендации

Рекомендации учатся на действиях посетителей, поэтому работа состоит из двух частей: отправлять события с витрины и запрашивать рекомендации у модели. Оба вызова доступны поисковой области и могут выполняться из браузера с поисковым или браузерным ключом (см. ключи и области доступа). Создание и изменение моделей требует полного ключа.

События

ingestEvents — POST /events — записывает пакет из 1–500 событий:

await client.events.ingestEvents({
  events: [
    { type: "search", collection: "products", session_id, q: "дрель", found: 0, query_id },
    { type: "click", collection: "products", session_id, query_id, doc_ids: ["42"], positions: [3] },
    {
      type: "purchase",
      collection: "products",
      session_id,
      doc_ids: ["42"],
      value: 12990,
      currency: "RUB",
      event_id: crypto.randomUUID(),
    },
  ],
});

Каждому событию нужны type и collection. type — одно из search, view, click, add_to_cart, purchase, conversion, impression, favorite, wishlist, share, dismiss, suggestion_impression, suggestion_select, chip_click, correction_accept, correction_reject.

API проверяет пакет сразу, а сохраняет асинхронно. Ответ — 202:

{ "accepted": 2, "deduplicated": 1, "rejected": [{ "index": 4, "reason": "…" }] }

Отклонённое событие указывается по индексу в пакете; остальные сохраняются. Повторять пакет безопасно, если у каждого события есть event_id.

Используйте один query_id на страницу результатов и отправляйте его с кликами и покупками, которые с неё пришли. Готовые виджеты рекомендаций передают id модели как query_id в записываемых кликах.

Модели рекомендаций

Модель живёт в коллекции:

await client.recommendations.upsertRecommendationModel({
  collectionName: "products",
  modelId: "similar",
  body: { type: "looking_similar", vector_field: "embedding", filter_by: "in_stock:true" },
});

await client.recommendations.upsertRecommendationModel({
  collectionName: "products",
  modelId: "trending",
  body: {
    type: "trending",
    event_weights: { view: 1, add_to_cart: 3, purchase: 5 },
    decay_half_life_hours: 48,
    window_days: 14,
  },
});

Общие настройки: event_weights (по типам событий; незаданные считаются 0), window_days (по умолчанию 30), decay_half_life_hours (для trending, по умолчанию 72), filter_by (применяется к каждому результату), exclude_filter_by (никогда не рекомендовать такие), category_field и price_field (для типов на основе категории и цены), pins для гарантированных мест.

Получение рекомендаций

getRecommendations — POST /collections/{collectionName}/recommendations:

const similar = await client.recommendations.getRecommendations({
  collectionName: "products",
  model_id: "similar",
  object_id: "42",
  k: 8,
  exclude_ids: cartIds,
});

Ответ содержит model_id, hits в той же форме, что и результаты поиска (один рендер для обоих), took_ms, queries для моделей recently_searched (с пустыми hits) и experiment, если запрос попал в запущенный эксперимент.

Замкните цикл