Создание полнотекстового запроса в службе "Поиск ИИ Azure"

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

Предварительные условия

• Служба поиска Azure AI (любого уровня). Create a service или find an existing one.

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

• Разрешения для запроса индекса:

  • Аутентификация по ключу : ключ API запроса для сервиса поиска.
  • Проверка подлинности на основе ролей: роль средства чтения данных индекса поиска .

• Для разработки пакета SDK установите клиентская библиотека поиска Azure:

  • Python: azure-search-documents
  • .NET: Azure. Search.Documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

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

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

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

Следующий вызов REST API поиска POST иллюстрирует запрос с использованием search и других параметров.

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

Справочник:Search POST

Ключевые моменты

• search задает критерии соответствия, обычно это целые условия или фразы, с операторами или без них. Любое поле, которое приписывается как доступное для поиска в схеме индекса, находится в пределах области для операции поиска.

• queryType задает средство синтаксического анализа: простой, полный. Средство синтаксического анализа простых запросов по умолчанию оптимально для полнотекстового поиска. Полный анализатор запросов Lucene предназначен для сложных запросов, таких как регулярные выражения, поиск с учётом близости, нечеткий поиск и поиск по шаблонам. Этот параметр также можно задать для семантического ранжирования для расширенного семантического моделирования в ответе запроса.

• searchMode указывает, основаны ли совпадения на всех критериях (в пользу точности) или каких-либо критериях (в пользу полноты) в выражении. По умолчанию задано любой. Если предполагается интенсивное использование логических операторов, что, скорее всего, в индексах, содержащих большие текстовые блоки (поле содержимого или длинные описания), обязательно протестируйте запросы с searchMode=Any|All параметром, чтобы оценить влияние этого параметра на логический поиск.

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

Параметры, используемые для формирования ответа:

• select указывает, какие поля должны возвращаться в ответе. В операторе SELECT могут использоваться только поля, помеченные в индексе атрибутом retrievable.

• top возвращает указанное в параметре количество документов, лучше всего соответствующих критериям поиска. В этом примере возвращаются только 10 совпадений. Для постраничной разбивки результатов можно использовать параметры "top" и "skip" (не отображается).

• count сообщает, сколько имеется совпадений документов по всему индексу; это число может быть большим, чем количество возвращенных совпадений. Допустимые значения : true или false. По умолчанию используется значение false. Счетчик является точным, если индекс стабильный, но может показать меньше или больше документов при активном добавлении, обновлении или удалении. Чтобы получить только количество без документов, используйте $top=0.

• orderby применяется, когда результаты необходимо отсортировать по определенному значению, например по рейтингу или расположению. В противном случае по умолчанию для ранжирования результатов используется оценка релевантности. Чтобы поле можно было указать в этом параметре, оно должно иметь атрибут sortable (допускает сортировку).

Выбор клиента

Для раннего разработки и проверки концепции начните с Azure portal или клиента REST или Jupyter notebook. Эти подходы являются интерактивными, полезными для целевого тестирования и помогают оценить влияние различных свойств без необходимости писать код.

Чтобы вызвать поиск из приложения, используйте клиентские библиотеки Azure.Document.Search в пакетах SDK Azure для .NET, Java, JavaScript и Python.

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-query-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Run a full-text search query
results = client.search(
    search_text="NY +view",
    search_mode="all",
    search_fields=["HotelName", "Description", "Address/City", "Tags"],
    select=["HotelName", "Description", "Address/City", "Tags"],
    top=10,
    include_total_count=True
)

print(f"Total documents matching query: {results.get_count()}")
for result in results:
    print(f"Hotel: {result['HotelName']}")

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-query-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Run a full-text search query
SearchOptions options = new SearchOptions
{
    SearchMode = SearchMode.All,
    IncludeTotalCount = true,
    Size = 10
};
options.SearchFields.Add("HotelName");
options.SearchFields.Add("Description");
options.Select.Add("HotelName");
options.Select.Add("Description");

SearchResults<SearchDocument> response = await searchClient.SearchAsync<SearchDocument>("NY +view", options);

Console.WriteLine($"Total documents matching query: {response.TotalCount}");
await foreach (SearchResult<SearchDocument> result in response.GetResultsAsync())
{
    Console.WriteLine($"Hotel: {result.Document["HotelName"]}");
}

Выбор типа запроса: simple | full

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

• Простой синтаксический анализатор понимает простой синтаксис запросов. Это средство синтаксического анализа было выбрано по умолчанию, поскольку оно позволяет быстро и эффективно обрабатывать текстовые запросы. Синтаксис поддерживает распространенные операторы поиска (AND, OR, NOT) для поиска терминов и фраз, а также префиксный поиск * (как в sea* Сиэтле и Сисайде). Общая рекомендация заключается в том, чтобы сначала попробовать выполнить простой синтаксический анализатор, а затем перейти на полный синтаксический анализатор, если для приложения требуется вызов более сложных запросов.

• Полный синтаксис запроса Lucene, который активируется при добавлении queryType=full в запрос, основан на средстве синтаксического анализа Apache Lucene.

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

Выбор метода запроса

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

Влияние атрибутов поля на запросы

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

На следующем снимке экрана индекса hotels-sample, только последние два поля LastRenovationDate и Ratingявляются сортируемыми, что является требованием для использования в условии типа "$orderby" only.

Определения атрибутов поля см. в разделе "Создание индекса" (REST API).

Влияние маркеров на запросы

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

Ключевой точкой является то, что вы думаете, что ваш индекс содержит, и то, что на самом деле в нем, может отличаться. Если запросы не возвращают ожидаемые результаты, можно проверить маркеры, созданные анализатором, через функцию Analyze Text (REST API). Дополнительные сведения о маркеризации и влиянии на запросы см. в разделе "Частичный поиск терминов" и "шаблоны" со специальными символами.

Устранение проблем с запросами

В следующей таблице перечислены распространенные проблемы с запросами и способы их устранения.

Связанный контент

Теперь, когда вы лучше понимаете, как работают запросы, ознакомьтесь со следующими краткими руководствами для практической работы.

• Проводник поиска
• Быстрый старт: Полнотекстовый поиск
• Синтаксис простых запросов
• Lucene query syntax in Azure Search (Синтаксис запросов Lucene в службе поиска Azure)
• Синтаксис фильтра OData