Автозавершение (REST API поиска ИИ Azure)

Статья
05/10/2023

API автозаполнения завершает ввод частично типизированного запроса, используя существующие термины в индексе поиска для использования во вторичном запросе. Например, если входные данные запроса имеют значение "medic", API автозаполнения возвращает "medicare", "medicaid", "medicine" если эти термины находятся в индексе. На внутреннем сервере поисковая система ищет соответствующие термины в полях, для которых настроено средство подбора .

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

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

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?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. Для запросов версия API всегда указывается в качестве параметра URI для GET и POST.

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

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

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

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

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

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

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

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

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

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "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),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}

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

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

Имя	Тип	Описание
api-version	строка	Обязательный. Версия REST API, используемого для запроса. Список поддерживаемых версий см. в разделе Управление версиями API. Для этой операции версия API указывается в качестве параметра URI независимо от того, вызывается ли функция автозаполнения с помощью GET или POST.
autocompleteMode	строка	Необязательный параметр. По умолчанию — oneTerm. Допустимые значения: oneTerm, twoTerms, oneTermWithContext. функция oneTerm возвращает один термин. Если запрос содержит два термина, выполняется только последний термин. Например, учитывая `"washington medic"`, ответом может быть любой из следующих отдельных терминов: `"medicaid"`, `"medicare"`, `"medicine"`. TwoTerms совпадает с фразами из двух терминов в индексе. Например, если задано `"medic"`значение , ответом может быть `"medicare coverage"`или `"medical assistant"`. Во многих случаях отдельные термины `"medicare"` или `"medical"` не возвращаются, так как предпочтение отдается двум фразам, которые соответствуют. oneTermWithContext завершает последний термин в запросе двумя или более терминами, где последние два термина являются фразой, существующей в индексе. Например, если задано `"washington medic"`, ответом может быть `"washington medicaid"`, `"washington medical"`.
$filter	строка	Необязательный параметр. Структурированное выражение поиска в стандартном синтаксисе OData, которое фильтрует документы, рассматриваемые для создания готовых предложений терминов. Выражения фильтра "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 вместо #).
minimumCoverage	Целое число	Необязательный элемент. Значение по умолчанию — 80. Число от 0 до 100, указывающее процент индекса, который должен быть доступен для обслуживания запроса, прежде чем его можно будет сообщить об успешном выполнении. Значение по умолчанию отражает смещение к скорости и эффективности по сравнению с полным охватом. Сокращение охвата ограничивает расширение запросов, позволяя быстрее возвращать результаты. Это также позволяет выполнить запрос при частичной доступности индекса, даже если один сегмент медленно отвечает или недоступен из-за проблем со работоспособностью службы или обслуживания индекса. Независимо от значения minimumCoverage, этот процент индекса должен быть доступен, или функция автозаполнения возвращает код состояния HTTP 503. Если автозавершение выполнено успешно на минимальном уровнеCoverage, он возвращает HTTP 200 и включает @search.coverage в ответ значение, указывающее процент индекса, который был доступен при обслуживании запроса. Если возникают ошибки 503, это значение может быть полезным. В противном случае можно рассмотреть возможность повышения значения, если в ответе недостаточно совпадений.
search	строка	Обязательный. Текст для поиска. Текст для завершения поиска. Минимальная длина — 1 символ, максимальная — 100 символов. Он не может содержать операторы, синтаксис запросов или фразы в кавычках.
searchFields	строка	Необязательный параметр. Список имен полей, разделенных запятой, для поиска указанного текста. Целевые поля должны быть перечислены в определении средства подбора в индексе.
suggesterName	строка	Обязательный. Имя средства подбора, указанное в коллекции Средств подбора , которая является частью определения индекса. Средство подбора определяет, какие поля проверяются на наличие предлагаемых терминов запроса.
$top	Целое число	Необязательный элемент. Значение по умолчанию — 5. Количество получаемых предложений с автозавершением. Значение должно быть числом от 1 до 100. При вызове с помощью POST этот параметр называется top вместо $top.

(1) Ограничения нечеткости в автозаполнения:

Во-первых, в отличие от нечеткого параметра при поиске, расстояние редактирования ограничено одной разницей символов на маркер. Ограничение расстояния редактирования до одного символа означает, что не все совпадения с кандидатами будут найдены, но ограничение необходимо для обеспечения приемлемого уровня производительности.

Во-вторых, нечеткий шаг происходит после частичного расширения маркера, и для нечетких совпадений учитываются только термины из одного сегмента индекса. Это ограничение повышает производительность API автозаполнения, устраняя агрегирование нечетких совпадений по всем сегментам. Это ограничение становится менее заметным, так как в индекс добавляется больше терминов, что приводит к аналогичному распределению терминов для каждого сегмента. Поскольку термины распределены равномерно, нечеткие совпадения в сегменте являются хорошим приближением нечетких совпадений во всем индексе. Однако результаты могут быть ниже, если индекс содержит меньше терминов, например в тесте или прототипе индекса, что приводит к неравномерному представлению между сегментами. Дополнительные сведения о том, как индексы делятся на сегменты, см. в разделе Сочетания секций и реплика.

Ответ

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

Полезные данные ответа имеют два свойства.

Свойство	Описание
"text"	Завершенный термин или фраза
"queryPlusText"	Начальные входные данные запроса плюс завершенный термин или фраза

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

Примеры

Пример 1. Получите три предложения автозаполнения, в которых входные данные частичного поиска доступны 'washington medic' в режиме по умолчанию (oneTerm):

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

Ответ:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

Пример 2. Получение трех предложений автозаполнения, в которых входные данные частичного поиска и 'washington medic'autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}

Ответ:

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}

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