Skip to content

Поиск пользователей по ФИО

📡 Поиск пользователей по ФИО (fuzzy match)#

Ручка#

POST /search_by_fio

Полный адрес в сети#

Среда URL
🧪 Dev http://terra-searcher-service/search_by_fio
🚀 Prod http://terra-searcher-service/search_by_fio

🔐 Авторизация#

Ручка защищена BasicAuth

Authorization: Basic base64(username:password)

Пример:

Authorization: Basic dXNlcm5hbWUxOnBhc3N3b3JkMQ==

📥 Входные данные#

Основной запрос#

Поле Тип Описание Обязательное Пример
searchName string Строка для поиска (ФИО / транслит / шум) ✅ ivan ivanov
limit int Кол-во результатов в ответе ✅ 5
page int Страница ✅ 50
users array Список пользователей для поиска ✅ см. ниже

Пользователь в списке users#

Поле Тип Описание Обязательное Пример
uuid string Уникальный идентификатор ✅ 2222...
firstName string Имя ✅ Ivan
lastName string Фамилия ✅ Ivanov
middleName string Отчество (может быть null) ❌ Petrovich

📤 Пример JSON запроса#

{
  "searchName": "ivan ivanov",
  "limit": 20,
  "page": 1,
  "users": [
    {
      "uuid": "22222222-2222-2222-2222-222222222222",
      "firstName": "Ivan",
      "lastName": "Ivanov",
      "middleName": "Petrovich"
    },
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "firstName": "Иван",
      "lastName": "Иваненко",
      "middleName": null
    }
  ]
}

📤 Выходные данные#

Поле Тип Описание Обязательное Пример
matches array Список найденных совпадений ✅ см. ниже

Элемент matches#

Поле Тип Описание Обязательное Пример
uuid string UUID пользователя ✅ 2222...
score float Скор похожести (0..1) ✅ 0.9821

📤 Пример ответа#

{
  "matches": [
    {
      "uuid": "22222222-2222-2222-2222-222222222222",
      "score": 0.9821
    },
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "score": 0.8114
    }
  ]
}

📌 Особенности работы алгоритма#

Алгоритм поиска

  1. Нормализация (lowercase, очистка)
  2. Замена никнеймов (Саша → Александр)
  3. RapidFuzz предварительный отбор
  4. Embedding reranking (семантическая близость)
  5. Финальный скоринг

🚀 Производственные ограничения#

Warning

  • candidateLimit ограничивает нагрузку CPU
  • embeddings считаются только на top-K
  • сервис stateless (не хранит данные пользователей)

📈 Рекомендации по использованию#

  • candidateLimit = 50–200 для production
  • limit = 5–20 для UI
  • использовать кэш на уровне клиента при повторных запросах