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

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

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

• Подписка Azure. Создайте его бесплатно.

• Служба поиска ИИ Azure, любой регион и уровень, но это должен быть оплачиваемый уровень (базовый или более высокий) для доступа на основе ролей.

• Разрешения на создание индекса: роль участника службы поиска или ключ API администратора для проверки подлинности на основе ключей.

• Уникальное поле в исходных данных, которое можно использовать в качестве ключа документа в индексе.

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

Создание индекса

Когда вы будете готовы создать индекс, используйте клиент поиска, который может отправить запрос. Вы можете использовать портал Azure или REST API для раннего разработки и проверки концепции, в противном случае часто используются пакеты SDK Azure.

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

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

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

// Create the index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Проверка создания индекса

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

GET https://[servicename].search.windows.net/indexes?api-version=[api-version]

// List all indexes to verify creation
var indexNames = indexClient.GetIndexNames();
foreach (var name in indexNames)
{
    Console.WriteLine(name);
}

Ключи документов

Создание индекса поиска имеет два требования: индекс должен иметь уникальное имя в службе поиска, и он должен иметь ключ документа. Логический key атрибут поля может быть задан как true для указания, какое поле предоставляет ключ документа.

Ключ документа — это уникальный идентификатор документа поиска, а документ поиска — это коллекция полей, которые полностью описывают что-то. Например, если вы индексируете набор данных фильмов, то в документе поиска содержится название, жанр и длительность одного фильма. Имена фильмов уникальны в этом наборе данных, поэтому в качестве ключа документа можно использовать имя фильма.

В поиске ИИ Azure ключ документа является строкой, и он должен исходить из уникальных значений в источнике данных, который предоставляет содержимое для индексирования. Как правило, служба поиска не создает ключевые значения, но в некоторых сценариях (например , индексатор таблиц Azure) синтезирует существующие значения для создания уникального ключа для индексированных документов. Другой сценарий – это индексирование один ко многим для данных, разделённых на части или секционированных, при этом ключи документов создаются для каждого блока.

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

Важные моменты о ключах документов:

• Максимальная длина значений в поле ключа составляет 1024 символов.
• В каждом индексе должно быть выбрано ровно одно поле верхнего уровня, и оно должно быть типом Edm.String.
• Значение по умолчанию key атрибута равно false для простых полей и null для сложных полей.

Ключевые поля можно использовать для поиска документов напрямую и обновления или удаления определенных документов. Значения ключевых полей обрабатываются с учетом регистра при поиске или индексировании документов. Дополнительные сведения см. в разделе GET Document (REST) и Index Documents (REST).

Контрольный список схемы

Этот контрольный список поможет вам в принятии решений о дизайне индекса поиска.

1. Проверьте соглашения об именовании, чтобы имена индексов и полей соответствовали правилам именования.

2. Ознакомьтесь с поддерживаемыми типами данных. Тип данных влияет на то, как используется поле. Например, по отношению к числовому содержимому допускается фильтрация, но не полнотекстовый поиск. Наиболее распространенный тип данных — Edm.String в случае доступного для поиска текста, который токенизирован и запрашивается с помощью полнотекстовой поисковой системы. Наиболее распространенный тип данных для поля вектора , Edm.Single но также можно использовать другие типы.

3. Укажите описание индекса, максимум 4000 символов. Этот читаемый человеком текст бесценен, когда система должна получить доступ к нескольким индексам и принять решение на основе описания. Рассмотрим сервер протокола контекста модели (MCP), который должен выбрать правильный индекс во время выполнения. Решение может быть основано на описании, а не только на имени индекса.

4. Определите ключ документа. Ключ документа требуется для индекса. Это одно строковое поле, заполненное из поля исходных данных, которое содержит уникальные значения. Например, если индексация выполняется из хранилища BLOB-объектов, путь к хранилищу метаданных часто служит в качестве ключа документа, так как он однозначно идентифицирует каждый BLOB-объект в контейнере.

5. Определите поля в источнике данных, добавляющие в индекс доступный для поиска контент.

   Содержимое невектора с возможностью поиска включает короткие или длинные строки, запрашиваемые с помощью полнотекстовой поисковой системы. Если речь идет о подробном контенте (краткие фразы или большие фрагменты), поэкспериментируйте с различными анализаторами, чтобы узнать, как токенизирован текст.

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

   Атрибуты, заданные в полях, например retrievable или filterable, определяют поведение поиска и физическое представление индекса в службе поиска. Определение того, как следует использовать поля, является итеративным процессом для многих разработчиков. Чтобы ускорить итерации, начните с выборки данных, чтобы их можно было легко удалять и перестраивать.

6. Определите, какие исходные поля можно использовать в качестве фильтров. Удачными вариантами являются числовое содержимое и короткие текстовые поля, особенно поля с повторяющимися значениями. При работе с фильтрами помните о следующем:

   • Фильтры можно использовать в векторных и невекторных запросах, но сами фильтры применяются к человека-читаемым (невекторным) полям в вашем индексе.

   • Фильтруемые поля можно использовать по желанию при аспектной навигации.

   • Фильтруемые поля возвращаются в произвольном порядке и не проходят оценку релевантности, поэтому рассмотрите возможность их сортировки.

7. Для полей векторов укажите конфигурацию векторного поиска и алгоритмы, используемые для создания путей навигации и заполнения пространства внедрения. Дополнительные сведения см. в разделе "Добавление векторных полей".

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

   Векторные поля опустят атрибуты, которые не полезны для векторных данных, таких как сортировка, фильтрация и фасетирование.

8. Для полей невектора определите, следует ли использовать анализатор по умолчанию ("analyzer": null) или другой анализатор. Анализаторы служат в целях токенизации текстовых полей во время индексирования и выполнения запросов.

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

   Если же речь идет о строках с дефисами или специальных символах, рассмотрите возможность применения специализированных анализаторов. Например, анализатор keyword обрабатывает все содержимое поля как один токен. Это поведение полезно для таких данных, как zip-коды, идентификаторы и некоторые имена продуктов. Дополнительные сведения см. в разделе Поиск частично введенных слов и шаблоны со специальными символами.

Настройка определений полей

Коллекция полей определяет структуру документа поиска. Все поля имеют имя, тип данных и атрибуты.

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

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

REST API интерфейсы имеют присвоение по умолчанию на основе типов данных, которые также используются мастером импорта данных на портале Azure. У пакетов SDK Azure нет стандартных значений, но они имеют подклассы полей, которые включают свойства и поведение, такие как SearchableField для строк и SimpleField для примитивов.

Атрибуты полей по умолчанию для REST API сведены в следующей таблице.

Строковые поля также могут быть связаны с анализаторами и картами синонимов. Поля типа Edm.String , которые могут быть фильтруемыми, сортируемыми или фасетными, могут иметь длину не более 32 килобайтов. Это связано с тем, что значения таких полей рассматриваются как один поисковый термин, а максимальная длина термина в поиске ИИ Azure составляет 32 килобайта. Если необходимо сохранить больше текста, чем позволяет одно строковое поле, следует явно задать фильтруемыми, сортируемыми и фасетируемыми false в определении индекса.

Поля векторов должны быть связаны с измерениями и профилями векторов. По умолчанию можно получить значение true, если добавить поле вектора с помощью мастера импорта данных на портале Azure. Если вы используете REST API, результат будет false.

Атрибуты полей описаны в следующей таблице.

Разрешенные обновления существующих индексов

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

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

Чтобы свести к минимуму количество изменений в процессе разработки, в следующей таблице описывается, какие элементы являются фиксированными и гибкими в схеме. Для изменения фиксированного элемента требуется перестроение индекса, в то время как гибкие элементы могут быть изменены в любое время без влияния на физическую реализацию. Дополнительные сведения см. в разделе "Обновление или перестроение индекса".

Настройка corsOptions для запросов между доменами

Схемы индексов включают раздел для настройки corsOptions. По умолчанию клиентский JavaScript не может вызывать интерфейсы API, так как браузеры предотвращают все запросы между источниками. Чтобы разрешить перекрестные запросы к индексу, включите CORS (совместное использование ресурсов между источниками), задав атрибут corsOptions . По соображениям безопасности только API запросов поддерживают CORS.

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

Для CORS можно задать следующие свойства:

• allowedOrigins (обязательно): это список источников, которым разрешен доступ к индексу. Код JavaScript, обслуживающийся из этих источников, может запрашивать индекс (если вызывающий объект предоставляет допустимый ключ или имеет разрешения). Источники здесь обычно задаются в формате protocol://<fully-qualified-domain-name>:<port>, хотя <port> часто опускается. Дополнительные сведения см. в разделе общего доступа к ресурсам между источниками (Википедия).

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

• maxAgeInSeconds (необязательный): с помощью этого значения браузеры определяют длительность (в секундах) кэширования предварительных ответов CORS. Это значение должно быть целой неотрицательной величиной. Более длительный период кэша обеспечивает более высокую производительность, но увеличивает время, необходимое для принятия политики CORS. Если это значение не задано, используется значение по умолчанию на пять минут.

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

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

• Добавление векторных полей и профилей векторов
• Добавление профилей оценки
• Добавление семантического ранжирования
• Добавление предложения
• Добавление карт синонимов
• Добавление анализаторов
• Добавление шифрования

Используйте следующие ссылки для загрузки или обновления индекса:

• Общие сведения об импорте данных
• Загрузка документов
• Обновление или перестроение индекса