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

Простой синтаксис запросов в поиске ИИ Azure

Для сценариев полнотекстового поиска Azure AI Search реализует два языка запросов на базе Lucene, каждый из которых соответствует анализатору запросов. Средство синтаксического анализа простых запросов используется по умолчанию. Он охватывает распространенные варианты использования и пытается интерпретировать запрос, даже если он не полностью составлен. Другой средство синтаксического анализа — Lucene Query Parser и поддерживает более сложные конструкции запросов.

В этой статье приведена ссылка на синтаксис запросов для простого средства синтаксического анализа запросов.

Синтаксис запросов для обоих средств синтаксического анализа применяется к выражениям запросов, переданным в search параметре запроса, не путать с синтаксисом OData, с собственным синтаксисом и правилами для filter и orderby выражений в одном запросе.

Хотя простой синтаксический анализатор основан на классе Apache Lucene Simple Query Parser , его реализация в службе "Поиск ИИ Azure" исключает нечеткий поиск. Если вам нужен поиск по неточным совпадениям, рассмотрите вместо этого использование полного синтаксиса запросов Lucene.

Пример (простой синтаксис)

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

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2025-09-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

Параметр searchMode подходит для данного примера. Всякий раз, когда в запросе используются логические операторы, необходимо установить searchMode=all, чтобы убедиться, что все критерии выполнены. В противном случае можно использовать значение searchMode=any по умолчанию, которое отдает предпочтение полноте, а не точности.

Для получения дополнительных примеров смотрите примеры простого синтаксиса запросов. Дополнительные сведения о запросе и параметрах запроса см. в разделе Поиск документов (REST API).

Поиск по ключевым словам в терминах и фразах

Строки, передаваемые в параметр search, могут содержать термины или фразы на любом поддерживаемом языке, логические операторы, операторы приоритета, подстановочные знаки или символы префикса для запросов "начинается с", управляющие символы и символы кодировки URL. Параметр search является необязательным. Без указания особых условий поиск ( search=* или search=" ") возвращает первые 50 документов в произвольном (неранжированном) порядке.

  • Поиск по термину — это запрос из одного или нескольких терминов, где совпадением считается соответствие какому-либо указанному термину.

  • Поиск по фразе — это точная фраза, заключенная в кавычки " ". Например, при Roach Motel (без кавычек) будут найдены документы, содержащие Roach и/или Motel в любом порядке, а при поиске "Roach Motel" (с кавычками) будут найдены только те документы, в которых есть эта фраза целиком и с таким же порядком слов (лексический анализ по-прежнему применяется).

В зависимости от вашего клиента поиска может потребоваться экранирование кавычек при поиске фраз. Например, в запросе POST поиск фраз на "Roach Motel" в теле запроса может быть указан как "\"Roach Motel\"". Если вы используете SDK Azure, клиент поиска экранирует кавычки при сериализации текста поиска. Ваша фраза поиска может быть отправлена как "Roach Motel".

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

Любой ввод текста с одним или несколькими терминами считается допустимой отправной точкой для выполнения запроса. Поиск ИИ Azure будет соответствовать документам, содержащим любые или все термины, включая любые варианты, обнаруженные во время анализа текста.

Так же просто, как это звучит, существует один аспект выполнения запросов в поиске ИИ Azure, который может привести к непредвиденным результатам, увеличивая, а не уменьшая результаты поиска, так как дополнительные термины и операторы добавляются в входную строку. Произойдет ли это расширение, зависит от возможности включения оператора NOT, а также от настройки параметра searchMode, который определяет, как интерпретируется NOT в контексте поведения AND или OR. Дополнительные сведения см. в разделе "Логические NOT операторы".

Логические операторы

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

Символ Пример Использование
+ pool + ocean Операция AND . Например, pool + ocean предполагает, что документ должен содержать оба термина.
| pool | ocean Операция OR находит совпадение при обнаружении любого термина. В этом примере система обработки запросов вернет совпадение для документов, содержащих либо pool, либо ocean, либо оба эти элемента. Так как OR является оператором сочетания по умолчанию, его можно также оставить, например pool ocean , эквивалентно pool | ocean.
- pool – ocean Операция NOT возвращает совпадения с документами, которые исключают термин.

Параметр searchMode в запросе определяет, выполняется ли терм с оператором NOT в виде операций AND или OR с другими терминами в запросе (при условии отсутствия логических операторов в других терминах). Допустимые значения: any и all.

Значение searchMode=any увеличит количество повторных вызовов запросов, что даст большее количество результатов, и - по умолчанию интерпретируется как OR NOT. Например, pool - ocean будет соответствовать документам, которые содержат термин pool или те, которые не содержат термин ocean.

searchMode=all увеличивает точность запросов, включая меньше результатов, и по умолчанию - будет интерпретировано как "AND NOT". Например, с searchMode=any, запрос pool - ocean будет соответствовать документам, содержащим термин "пул" и всем документам, которые не содержат термин "океан". Вероятно, это более интуитивное поведение оператора -. Поэтому вам следует рассмотреть возможность использования searchMode=all вместо searchMode=any, если вы хотите оптимизировать точность поиска (в ущерб повторным вызовам) и если ваши пользователи часто используют оператор - в своих поисковых запросах.

Принимая решение о параметре searchMode, следует учитывать шаблоны взаимодействия с пользователем для запросов в различных приложениях. Пользователи, которые ищут информацию, с большей вероятностью включат оператор в запрос в отличие от сайтов электронной коммерции, содержащих большее количество встроенных структур навигации.

Запросы с префиксами

Для запросов "начинается с" добавьте оператор суффикса (*) в качестве заполнителя для оставшейся части термина. Перед добавлением оператора суффикса запрос префикса должен начинаться по крайней мере с одним символом обычного текста.

Символ Пример Использование
* Результатом поиска по lingui* станут "linguistic" или "linguini". Звездочка (*) представляет один или несколько символов произвольной длины без учета регистра.

Как и в случае с фильтрами, запрос префикса выполняет поиск точного совпадения. Таким образом, оценка релевантности отсутствует (все результаты получают оценку поиска 1.0). Имейте в виду, что запросы с префиксом могут выполняться долго, особенно если индекс большой, а префикс состоит из небольшого числа символов. Альтернативная методология, такая как n-граммная токенизация, может работать быстрее. Термины, использующие поиск префикса, не могут превышать 1000 символов.

Простой синтаксис поддерживает только сопоставление префиксов. Для поиска с помощью суффиксов или инфиксов, то есть для сопоставления с концом или серединой термина, используйте полный синтаксис Lucene для поиска с подстановочными знаками.

Экранирование поисковых операторов

В простом синтаксисе операторы поиска включают следующие символы: + | " ( ) ' \

Если какой-либо из этих символов является частью лексемы в индексе, добавьте перед ним обратную косую черту (\) в запросе, чтобы экранировать его. Например, предположим, что вы использовали пользовательский анализатор для токенизации целого термина, и ваш индекс содержит строку "Luxury+Hotel". Чтобы получить точное соответствие для этого маркера, вставьте escape-символ: search=luxury\+hotel.

Чтобы упростить более типичные случаи, есть два исключения из этого правила, где экранирование не требуется:

  • Оператор NOT (-) нужно экранировать только в случае, если он является первым символом после пробела. Если - отображается в середине (например, в 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), можно пропустить экранирование.

  • Оператор суффикса * должен быть экранирован только если он является последним символом перед пробелом. Если * отображается в середине (например, в 4*4=16), экранирование не требуется.

Примечание.

По умолчанию стандартный анализатор удаляет и разбивает слова на дефисы, пробелы, амперсанды и другие символы во время лексического анализа. Если требуется, чтобы в строке запроса оставались специальные символы, может потребоваться анализатор, сохраняющий их в индексе. Можно, например, использовать анализаторы естественного языка Майкрософт, которые сохраняют слова с дефисом, или пользовательский анализатор для более сложных шаблонов. Дополнительные сведения см. в частичных терминах, шаблонах и специальных знаках.

Кодирование небезопасных и зарезервированных знаков в URL-адресах

Убедитесь, что в URL-адресе закодированы все небезопасные и зарезервированные знаки. Например, "#" является небезопасным символом, так как это идентификатор фрагмента или привязки в URL-адресе. Знак должен быть закодирован как %23, если он используется в URL-адресе. '&' и '=' — это примеры зарезервированных символов в качестве параметров разделителя и указания значений в службе "Поиск ИИ Azure". Дополнительные сведения см. в разделе RFC1738: унифицированные указатели ресурсов (URL).

Небезопасными знаками являются: " ` < > # % { } | \ ^ ~ [ ]. Зарезервированными знаками являются: ; / ? : @ = + &.

Специальные символы

Специальные символы могут варьироваться от символов валюты, таких как "$" или "€", до эмодзи. Многие анализаторы, включая стандартный анализатор по умолчанию, исключают специальные символы во время индексирования, что означает, что они не будут представлены в индексе.

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

  • Анализатор пробелов рассматривает любую последовательность символов, разделенную пробелами, как маркеры (поэтому эмодзи "❤" будет считаться маркером).

  • Анализатор языка, например анализатор Microsoft English (en.microsoft), будет принимать строку "$" или "€" в качестве токена.

Для подтверждения можно проверить анализатор , чтобы узнать, какие маркеры создаются для данной строки. Как можно ожидать, вы можете не получить полную токенизацию из одного анализатора. Обходным решением является создание нескольких полей, содержащих одно и то же содержимое, но с различными назначениями анализаторов (например, description_en, description_frи т. д. для анализаторов языка).

При использовании символов Unicode убедитесь, что символы правильно экранируются в URL-адресе запроса (например, для '❤' используется последовательность экранирования %E2%9D%A4+). Некоторые веб-клиенты выполняют этот перевод автоматически.

Приоритет (группирование)

Вы можете использовать круглые скобки, чтобы создать вложенные запросы, включая операторы в заключенной в скобки инструкции. Например, motel+(wifi|luxury) будет выполнять поиск документов, содержащих термин "motel" и "wifi" или "luxury" (или оба).

Предельные размеры запроса

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

  • Для GET длина URL-адреса не может превышать 8 КБ.

  • Для POST (и любого другого запроса), где текст запроса включает search и другие параметры, например filter и orderbyмаксимальный размер составляет 16 МБ. К дополнительным ограничениям относятся:

    • Максимальная длина предложения поиска составляет 100 000 символов.
    • Максимальное количество предложений в search (выражениях, разделенных AND или OR), равно 1024.
    • Максимальный размер термина поиска составляет 1000 символов для поиска префикса.
    • Существует также ограничение примерно в 32 КБ по размеру любого отдельного термина в запросе.

Дополнительные сведения об ограничениях запросов см. в разделе об ограничениях запросов API.

Следующие шаги

Если вы будете создавать запросы программным способом, просмотрите полнотекстовый поиск в службе "Поиск ИИ Azure", чтобы понять этапы обработки запросов и последствия анализа текста.

Дополнительные сведения о построении запросов см. в следующих статьях:

  • Last updated on