Предложения (REST API поиска Azure ИИ)

Статья
05/10/2023

Запрос предложений — это запрос типа поиска, который ищет совпадающие значения в полях с поддержкой средства подбора и возвращает документы, содержащие совпадение. Например, если вы включите предложения в поле города , при вводе "sea" будут создаваться документы, содержащие "Сиэтл", "Sea Tac" и "Приморский" (все фактические названия городов) для этого поля.

Ответ — это содержимое из соответствующего документа и ключа документа. В отличие от автозаполнения, которая возвращает завершенный термин или фразу, используемую во вторичном запросе, этот запрос возвращает сведения, которые разрешаются в фактические документы. Если совпадающие термины или фразы идентичны в документах, совпадающее содержимое повторяется. Чтобы улучшить структуру результатов, рассмотрите $select возможность использования фильтра для возврата дополнительных полей, которые обеспечивают большую дифференциацию и контекст.

Запросы к службе отправляются по протоколу HTTPS. Запрос Suggest можно создать с помощью методов GET или POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]  
  Content-Type: application/json  
  api-key: [admin or query key]

POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

В отличие от запроса "Поиск документов" , вы можете привязать вызов Предложения к вводу с клавиатуры, тогда как вызов Поиска может быть привязан к событию щелчка.

При вызове с помощью GET длина URL-адреса запроса не может превышать 8 КБ. Обычно такой длины достаточно для большинства приложений. Однако некоторые приложения создают очень большие запросы, особенно при использовании выражений фильтра OData. Для этих приложений http POST является лучшим выбором, так как он позволяет использовать фильтры большего размера, чем GET.

При использовании запроса POST ограничивающим фактором является количество предложений в запросе, а не необработанная строка фильтра, так как предельный размер запроса для POST ограничен примерно 16 МБ. Даже несмотря на то, что размер запроса POST очень большой, выражения фильтров не могут иметь произвольную сложность. Дополнительные сведения об ограничениях сложности фильтра см. в статье Синтаксис выражений OData для поиска ИИ Azure.

Параметры URI

Параметр	Описание
[имя службы]	Обязательный. Задайте уникальное, определяемое пользователем имя службы поиска.
[имя индекса]/docs	Обязательный. Указывает коллекцию документов именованного индекса.
api-version	Обязательный. Текущая стабильная версия — `api-version=2020-06-30`. Дополнительные версии см. в разделе Версии API . Для запросов версия API всегда указывается в качестве параметра URI для GET и POST.

Заголовки запросов

Таблица ниже содержит обязательные и необязательные заголовки запроса.

Поля Описание

Content-Type Обязательный. Для этого заголовка необходимо задать значение application/json

api-key Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса к службе поиска. Запросы к коллекции документов могут указывать ключ администратора или ключ запроса в качестве ключа API. Ключ запроса используется для операций только для чтения в коллекции документов. Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу .

Поля	Описание
Content-Type	Обязательный. Для этого заголовка необходимо задать значение `application/json`
api-key	Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса к службе поиска. Запросы к коллекции документов могут указывать ключ администратора или ключ запроса в качестве ключа API. Ключ запроса используется для операций только для чтения в коллекции документов. Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу .

Текст запроса

Для запроса GET: нет.

Для запроса POST:

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}

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

Запрос принимает несколько параметров в URL-адресе при вызове с помощью GET и в качестве свойств JSON в тексте запроса при вызове с помощью POST. Синтаксис некоторых параметров зависит от выбора запроса GET и POST. Эти различия приведены ниже.

Имя	Тип	Описание
api-version	строка	Обязательный. Версия REST API, используемая для запроса. Список поддерживаемых версий см. в разделе Версии API. Для этой операции версия api указывается в качестве параметра запроса в URL-адресе независимо от того, вызывается ли API с помощью GET или POST.
$filter	строка	Необязательный параметр. Выражение, фильтрующее документы, рассматриваемые для предложений. В фильтре можно использовать только фильтруемые поля. Выражения фильтра "search.ismatch" и "search.ismatchscoring*" не поддерживаются в API автозаполнения. При вызове с помощью POST этот параметр называется filter вместо $filter. Дополнительные сведения о подмножестве грамматики выражений OData, поддерживаемых поиском ИИ Azure, см. в статье Синтаксис выражений OData для поиска ИИ Azure .
Нечеткой	Логическое	Необязательный элемент. Значение по умолчанию — false. Если задано значение true, этот API находит предложения, даже если в тексте поиска есть заменяющий или отсутствующий символ. Расстояние редактирования равно 1 для каждой строки запроса. Если строка запроса состоит из нескольких терминов, во всей строке может быть только один отсутствующий, дополнительный, замененный или транспонированный символ. Включение нечеткого соответствия может быть более подходящим в некоторых сценариях. Это стоить за производительность, так как поиск нечетких предложений выполняется медленнее и потребляет больше ресурсов.
highlightPostTag	строка	Необязательный параметр. По умолчанию используется пустая строка. Строковый тег, добавляющий к выделенному термину. Необходимо задать параметр highlightPreTag. Зарезервированные символы в составе URL должно быть экранированы знаком процента (например, %23 вместо #). При вызове с помощью GET зарезервированные символы в URL-адресе должны быть закодированы в процентах (например, %23 вместо #).
highlightPreTag	строка	Необязательный параметр. По умолчанию используется пустая строка. Строковый тег, который добавляется к выделенному термину. Должен быть задан с параметром highlightPostTag. При вызове с помощью GET зарезервированные символы в URL-адресе должны быть закодированы в процентах (например, %23 вместо #).
$orderby	строка	Необязательный параметр. Список выражений, разделенных запятыми, для сортировки результатов по ним. Выражение может быть именем поля или вызовом функции `geo.distance()` . За каждым выражением может следовать "asc" (по возрастанию) или "desc" (по убыванию). По умолчанию результаты сортируются по возрастанию. Существует ограничение в 32 предложения для $orderby. При вызове с помощью POST этот параметр называется order вместо $orderby.
minimumCoverage	Целое число	Необязательный элемент. Значение по умолчанию — 80. Число от 0 до 100, указывающее процент индекса, который должен быть доступен для обслуживания запроса, прежде чем его можно будет сообщить об успешном выполнении. Значение по умолчанию отражает смещение в сторону скорости и эффективности по сравнению с полным охватом. Сокращение охвата ограничивает расширение запросов, позволяя быстрее возвращать результаты. Это также позволяет выполнить запрос при частичной доступности индекса, даже если один сегмент медленно отвечает или недоступен из-за проблем с работоспособностью службы или обслуживания индекса. Независимо от значения minimumCoverage, этот процент индекса должен быть доступен, или предложения возвращают код состояния HTTP 503. Если предложения завершатся успешно на минимальном уровнеCoverage, он возвращает HTTP 200 и включает @search.coverage в ответ значение, указывающее процент индекса, который был доступен при обслуживании запроса. Уменьшение этого значения может быть полезным, если возникают ошибки 503. В противном случае можно рассмотреть возможность повышения значения, если в ответе недостаточно совпадений.
search	строка	Обязательный. Текст для поиска, используемый для предложения запросов. Минимальная длина — 1 символ, максимальная — 100 символов. Он не может содержать операторы, синтаксис запросов или фразы, заключенные в кавычки.
searchFields	строка	Необязательный параметр. Список имен полей, разделенных запятой, для поиска указанного текста. Целевые поля должны быть указаны в определении средства подбора в индексе.
$select	строка	Необязательный параметр. Список полей для получения, разделенных запятыми. Если это не указано, возвращаются только ключ документа и текст предложения. Чтобы явным образом запросить все поля, задайте для этого параметра значение `*`. При вызове с помощью POST этот параметр называется select вместо $select.
suggesterName	строка	Обязательный. Имя средства подбора, указанное в коллекции Средств подбора , которая является частью определения индекса. Средство подбора определяет, какие поля проверяются на наличие предлагаемых терминов запроса.
$top	Целое число	Необязательный элемент. Значение по умолчанию — 5). Количество автозавершенных предложений, которые требуется извлечь. Значение должно быть числом от 1 до 100. При вызове с помощью POST этот параметр называется top, а не $top.

Ответ

Код состояния: "200 OK" возвращается для успешного ответа.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

Если для извлечения полей используется параметр проекции, поля включаются в каждый элемент массива:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

Примеры

Получение 5 предложений при вводе частичного условия поиска lux.

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

Обратите внимание, что в операции Suggestions требуется suggesterName .

Поделиться через