Семантический, фото- и голосовой поиск

Помимо ключевого поиска коллекция может сопоставлять по смыслу. Документы несут векторные поля float[] (num_dim: 1024); запросы встраиваются той же мультиязычной моделью (@cf/baai/bge-m3), поэтому текстовый запрос на любом языке, фотография и описание товара попадают в одно векторное пространство.

У всех векторных поисков общий набор опций:

Поиск по смыслу

searchSemantic (POST /collections/{collectionName}/documents/search/semantic) встраивает текст запроса и возвращает ближайшие документы по vector_field. Работает на любом языке, который понимает модель встраивания, — русский запрос находит английское описание.

const found = await client.media.searchSemantic({
  collectionName: "products",
  q: "тёплая куртка на зиму",
  vector_field: "embedding",
  filter_by: "in_stock:true",
  k: 50,
  distance_threshold: 0.35,
});

Сначала документам нужны векторы. Заполните поле float[] при импорте своими встраиваниями или доверьте это платформе:

• createEmbeddings — встройте текст самостоятельно и запишите в документы.
• uploadMedia — загрузите изображение; его сгенерированное описание встраивается в указанный документ.
• YML-фиды и коннекторы могут нести поля, пригодные для встраивания, — см. YML-фиды и коннекторы.

Поиск по изображению

searchByImage находит документы, чей vector_field ближе всего к заданному изображению. Передайте одно из: media_id (изображение, загруженное через uploadMedia), image_url (публичный HTTPS-URL, скачивается на сервере, до 8 МБ) или image_base64 (байты инлайн, с префиксом data-URI или без). Изображение встраивается так же, как загрузки, поэтому результаты совпадают с тем, что видит фото-поиск на витрине.

const similar = await client.media.searchByImage({
  collectionName: "products",
  media_id: "med_123",
  vector_field: "embedding",
  k: 30,
});

Встройте текст

createEmbeddings превращает текст в 1024-мерные мультиязычные векторы — та же модель встраивает запросы и описания изображений, поэтому всё, что встроено ею, находится через searchSemantic и searchByImage. Каждый вход — до ~500 токенов. Вызовы встраивания оплачиваются кредитами.

const { embeddings } = await client.media.createEmbeddings({
  input: ["зимняя пуховка с капюшоном"],
});

Библиотека изображений

uploadMedia сохраняет изображение (PNG, JPEG, WebP или GIF, до 8 МБ) и в фоновом режиме считает его встраивание: vision-модель описывает изображение, а описание встраивается той же мультиязычной текстовой моделью. Укажите документ полями collection, document_id и vector_field; опционально сохраните сгенерированное описание в caption_field.

await client.media.uploadMedia({
  body: {
    file: imageFile, // PNG, JPEG, WebP или GIF, ≤ 8 МБ
    collection: "products",
    document_id: "sku-4821",
    vector_field: "embedding",
    caption_field: "image_caption",
  },
});

Для больших файлов загружайте в два шага: createMediaUpload регистрирует ресурс, затем putMediaContent стримит сырые байты (до 100 МБ, обязателен Content-Length). Задача встраивания стартует, когда байты дошли; 409 означает, что у ресурса уже есть содержимое.

Голосовой поиск

createTranscription превращает короткую запись в текст — webm/opus, mp4/m4a, ogg, wav, mp3 или flac, до 25 МБ, конвертировать в WAV не нужно; язык определяется автоматически, если не передан (language — код ISO 639-1). searchByVoice транскрибирует и ищет одним вызовом: любые параметры поиска (query_by, filter_by, nl_query) передаются JSON-строкой в поле params, а расшифровка читается из request_params.voice_query.transcribed_query в ответе.

const result = await client.voice.searchByVoice({
  collectionName: "products",
  body: {
    file: audioBlob,
    language: "ru",
    params: JSON.stringify({ query_by: "title,description", filter_by: "in_stock:true" }),
  },
});

В пакете витрины и виджете уже есть кнопки микрофона, подключённые к этим эндпоинтам, — используйте их вместо ручных вызовов голосового поиска из браузера.