Согласованный формат переупорядочения (Rerank)

📝 Введение

Учитывая запрос и список текста, API переупорядочения будет сортировать текст в зависимости от его релевантности запросу. Каждому тексту присваивается оценка релевантности, в результате чего получается упорядоченный массив результатов. Эта функция особенно полезна для поисковых приложений, оптимизируя сортировку документов и помогая пользователям быстрее находить нужную информацию.

💡 Пример запроса

Базовый запрос на повторный заказ ✅

curl https://88api.ai/v1/rerank \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "какая столица Соединённых Штатов？",
    "documents": [
      "Столица штата Невада — Карсон-Сити.。",
      "Северные Марианские острова — группа островов в Тихом океане.，Столица — Сайпан.。",
      "Вашингтон, округ Колумбия（также называется Вашингтоном или округом Колумбия.，Официально известный как округ Колумбия.）является столицей Соединенных Штатов。",
      "Капитализация в английской грамматике – это использование заглавной буквы в начале слова.。Использование английского языка отличается от использования заглавных букв на других языках.。",
      "Поскольку до того, как Соединенные Штаты стали страной，В США существует смертная казнь。По состоянию на2017Год，существовать50в штатах30Смертная казнь законна во всех штатах。"
    ],
    "top_n": 3
  }'

Пример ответа:

{
  "results": [
    {
      "index": 2,
      "relevance_score": 0.999071
    },
    {
      "index": 0,
      "relevance_score": 0.32713068
    },
    {
      "index": 1,
      "relevance_score": 0.1867867
    }
  ],
  "id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
  "meta": {
    "api_version": {
      "version": "2",
      "is_experimental": false
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

Используйте структурированные данные ✅

curl https://88api.ai/v1/rerank \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-v3.5",
    "query": "Ищем недорогую зеркальную камеру для начинающих.",
    "documents": [
      "модель: Canon EOS 800D\nцена: 4299Юань\nФункция: 2410Мегапиксель, Оптический видоискатель, Wi-Fi\nПодходит для толпы: новичок, энтузиаст",
      "модель: Nikon D3500\nцена: 3099Юань\nФункция: 2416Мегапиксель, Оптический видоискатель, до1550Время автономной работы Чжана\nПодходит для толпы: новичок, студент",
      "модель: Sony A7III\nцена: 12999Юань\nФункция: 2420Мегапиксель, полный кадр, 4Kвидео\nПодходит для толпы: профессиональный фотограф, создатель видео"
    ],
    "max_tokens_per_doc": 512
  }'

Пример ответа:

{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.918472
    },
    {
      "index": 0,
      "relevance_score": 0.854321
    },
    {
      "index": 2,
      "relevance_score": 0.423156
    }
  ],
  "id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa",
  "meta": {
    "api_version": {
      "version": "2"
    },
    "billed_units": {
      "search_units": 1
    }
  }
}

📮 Запрос

Конечная точка

POST /v1/rerank

Измените порядок текстовых списков в зависимости от релевантности запроса.

Метод аутентификации

Включите в заголовок запроса для аутентификации ключа API следующее:

Authorization: Bearer $API_KEY

Где $API_KEY — ваш ключ API.

Параметры заголовка запроса

$API_KEY

• Тип: строка
• Требуется: Нет
• Описание: название проекта, инициировавшего запрос.

Параметры тела запроса

$API_KEY

• Тип: строка
• Требуется: Да
• Описание: используемый идентификатор модели, например. реранк-v3.5.

$API_KEY

• Тип: строка
• Требуется: Да
• Описание: Текст поискового запроса. Это вопрос или запрос, введенный пользователем.

$API_KEY

• Тип: массив строк.
• Требуется: Да
• Описание: список текста для сравнения с запросом. Для достижения максимальной производительности рекомендуется не отправлять более 1000 документов за один запрос.
• Примечания:
  • Длинные документы будут автоматически усекаться до значения, указанного в max_tokens_per_doc. – Для лучшей производительности структурированные данные должны быть отформатированы как строки YAML.

$API_KEY

• Тип: целое число
• Требуется: Нет
• Описание: Ограничить количество возвращаемых переупорядоченных результатов. Если не указано, будут возвращены все переупорядоченные результаты.

$API_KEY

• Тип: целое число
• Требуется: Нет -По умолчанию: 4096
• Описание: длинные документы будут автоматически усекаться до указанного количества токенов.

📥 Ответ

Успешный ответ

Возвращает объект, содержащий отсортированный список документов.

$API_KEY

• Тип: массив объектов.
• Описание: Отсортированный список документов, отсортированный по релевантности в порядке убывания.
• Свойства:
  • $API_KEY: целое число, соответствующее индексу документа в исходном списке документов.
  • $API_KEY: число с плавающей запятой, диапазон оценок корреляции — [0, 1]. Оценка, близкая к 1, указывает на высокую релевантность запросу, а оценка, близкая к 0, указывает на низкую релевантность.

$API_KEY

• Тип: строка
• Описание: уникальный идентификатор запроса.

$API_KEY

• Тип: Объект
• Описание: Содержит метаданные о запросе.
• Свойства:
  • $API_KEY: объект, содержащий информацию о версии API.
    • $API_KEY: строка, номер версии API.
    • $API_KEY: логическое значение, является ли оно устаревшим.
    • $API_KEY: логическое значение, является ли это экспериментальной функцией.
  • $API_KEY: объект, содержащий платежную информацию.
    • $API_KEY: число с плавающей запятой, количество оплачиваемых единиц поиска.
  • $API_KEY: объект, содержащий статистику использования токенов.
    • $API_KEY: число с плавающей запятой, количество токенов в качестве входных данных для модели.
    • $API_KEY: число с плавающей запятой, количество токенов, сгенерированных моделью.

$API_KEY

• Тип: массив строк.
• Требуется: Нет
• Описание: предупреждающая информация, возвращаемая API.

Ошибка ответа

При возникновении проблемы с запросом API может вернуть следующие коды состояния HTTP и соответствующие ошибки:

• 400 Bad Request: ошибка формата запроса или параметра.
• 400 Bad Request: не предоставлен действительный ключ API.
• 400 Bad Request: нет разрешения на доступ к этому ресурсу.
• 400 Bad Request: запрошенный ресурс не существует.
• 400 Bad Request: запрос правильно сформирован, но содержит семантические ошибки.
• 400 Bad Request: частота запросов превышает лимит.
• 400 Bad Request: внутренняя ошибка сервера.
• 400 Bad Request: Сервис временно недоступен.

🌟 Лучшие практики

Рекомендации по подготовке документов

1. Длина документа. Каждый документ должен быть кратким и ясным, избегайте слишком длинного текста. Длинные документы автоматически усекаются.
2. Структурированные данные: форматируйте структурированные данные в строки YAML для оптимальной производительности. Например:

   title: Название продукта
   price: 9999Юань
   features:
     - характеристика1
     - характеристика2

3. Количество документов: для обеспечения максимальной производительности не превышайте 1000 документов в одном запросе.

Оптимизация запросов

1. Будьте ясны и конкретны. Разработайте четкие и конкретные запросы, чтобы получить более точные результаты ранжирования.

2. Избегайте нечетких запросов. Старайтесь избегать слишком расплывчатых или общих терминов запроса, поскольку это может привести к менее очевидным различиям в показателях релевантности.

Понимание показателей релевантности

Оценка релевантности нормализуется до значения в диапазоне [0, 1]:

• Оценка, близкая к 1, указывает на высокую степень релевантности запросу.

• Оценка, близкая к 0, указывает на низкую корреляцию.

Примечание. Нельзя просто предположить, что документ с рейтингом 0,9 в 2 раза релевантнее, чем документ с рейтингом 0,45. Оценка релевантности — это относительный показатель, используемый для ранжирования, а не абсолютного сравнения.