Обновление до последней версии REST API в службе "Поиск ИИ Azure"

Статья
04/19/2024

Используйте эту статью для переноса вызовов плоскости данных в более новые версии REST API поиска.

2023-11-01 является последней стабильной версией. Семантический ранжирование и поддержка индексирования и запросов векторов обычно доступны в этой версии.
2023-10-01-preview — это последняя предварительная версия. Предварительные версии функций включают встроенную векторизацию запросов, встроенные блоки данных и векторизацию во время индексирования (использует навык разделения текста и навык внедрения Azure OpenAI). Дополнительные сведения о новых функциях см. в примерах кода и пошаговых руководствах .
2023-07-01-preview был первым REST API для поддержки векторов. Теперь он устарел, и вы должны немедленно перейти на 2023-11-01 или 2023-10-01-preview .

Примечание.

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

Обновление

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

Код ссылается на устаревшую или нерекомендуемую версию API и подвергается одному или нескольким критическим изменениям. Версии API, падающие в эту категорию, включают 2023-07-10-preview для векторов и 2019-05-06.
Код завершается ошибкой, если в ответе API возвращаются нераспознанные свойства. Как рекомендуется, приложение должно игнорировать свойства, которые он не понимает.
Код сохраняет запросы API и пытается повторно отправить их в новую версию API. Например, это может произойти, если приложение сохраняет маркеры продолжения, возвращенные API поиска (см. сведения об @search.nextPageParameters в справочнике по API поиска).

Обновление до версии 2023-10-01-preview

Эта версия идентична версии 2023-11-01, но имеет дополнительные функции в общедоступной предварительной версии: встроенный векторизатор запросов и режим префильтратора векторов. Если вы хотите использовать эти функции, необходимо обновить до последней предварительной версии.

Конфигурация алгоритма векторного поиска внутри индекса поиска идентична 2023-11-01. Чтобы исправить критические изменения с 2023-07-01-preview, следуйте инструкциям в следующем разделе.

Обновление до 2023-11-01

Эта версия имеет критические изменения и различия в поведении для семантического ранжирования и поддержки векторного поиска.

Семантический ранжирование общедоступен и больше не использует queryLanguage свойство. Для этого также требуется semanticConfiguration определение.

Чтобы обновить версию 2020-06-30-preview, создайте замену semanticConfigurationsearchFields. Инструкции см. в статье "Миграция из предварительной версии ".
Поддержка поиска векторов появилась в разделе "Создание или обновление индекса" (2023-07-01-preview).

Чтобы обновить версию с версии 2023-07-01-preview, переименуйте и реструктурируйте конфигурацию вектора в индексе и переопределите синтаксис векторного запроса с помощью инструкций в этом разделе.

Для обновления с 2023-10-01-preview нет критических изменений, но есть одно различие в поведении: vectorFilterMode по умолчанию изменено с postfilter на префильтратор для выражений фильтров. Если код предварительной версии 2023-10-01-preview не задан vectorFilterMode явным образом, убедитесь, что вы понимаете новое поведение или установите режим послефильтровать, чтобы сохранить старое поведение.

Совет

портал Azure поддерживает путь обновления по одному щелчку для индексов 2023-07-01-preview. Портал обнаруживает индексы 2023-07-01-preview и предоставляет кнопку "Миграция ". Перед нажатием кнопки "Миграция " нажмите кнопку "Изменить JSON ", чтобы сначала просмотреть обновленную схему. Вы должны найти схему, соответствующую изменениям, описанным в этом разделе. Миграция портала обрабатывает только индексы с одной конфигурацией алгоритма векторного поиска, создавая профиль по умолчанию, который сопоставляется с алгоритмом. Индексы с несколькими конфигурациями требуют ручной миграции.

Ниже приведены шаги по миграции с 2023-07-01-preview:

Вызовите get Index , чтобы получить существующее определение.
Измените конфигурацию векторного поиска. Этот API представляет концепцию профилей векторов, которые объединяют конфигурации, связанные с векторами, под одним именем. Он также переименовывается algorithmConfigurations в algorithms.
- Переименуйте algorithmConfigurations в algorithms. Это только переименование массива. Содержимое обратно совместимо. Это означает, что можно использовать существующие параметры конфигурации HNSW.
- Добавьте profiles, указав имя и конфигурацию алгоритма для каждой из них.
Перед миграцией (2023-07-01-preview):
```
  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}
```
После миграции (2023-11-01):
```
  "vectorSearch": {
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ],
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ]
  }
```

Измените определения векторного поля, заменив vectorSearchConfiguration на vectorSearchProfile. Убедитесь, что имя профиля разрешается в новое определение профиля вектора, а не имя конфигурации алгоритма. Другие свойства поля вектора остаются неизменными. Например, они не могут быть фильтруемыми, сортируемыми или фасетными, а также не использовать анализаторы или нормализаторы или карты синонимов.

До (2023-07-01-preview):

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

После (2023-11-01):

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

Вызовите создание или обновление индекса для публикации изменений.
Измените метод Search POST , чтобы изменить синтаксис запроса. Это изменение API позволяет поддерживать типы запросов полиморфных векторов.
- Переименуйте vectors в vectorQueries.
- Для каждого векторного запроса добавьте kind, придав ему значение vector.
- Для каждого векторного запроса переименуйте в valuevector.
- При необходимости добавьте vectorFilterMode , если вы используете выражения фильтров. По умолчанию используется префильтратор для индексов, созданных после 2023-10-01. Индексы, созданные до этой даты, поддерживают только postfilter независимо от того, как задать режим фильтра.
До (2023-07-01-preview):
```
{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}
```
После (2023-11-01):
```
{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}
```

Эти шаги по завершении миграции в версию API 2023-11-01.

Обновление до 2020-06-30

В этой версии есть одно критическое изменение и несколько различий в поведении. К общим возможностям относятся:

Хранилище знаний, постоянное хранилище обогащенного контента, созданного с помощью наборов навыков, созданного для последующего анализа и обработки с помощью других приложений. Хранилище знаний создается с помощью REST API поиска ИИ Azure, но он находится в служба хранилища Azure.

Критическое изменение

Код, написанный в предыдущих версиях API, прерывается на 2020-06-30 и более поздних версиях, если код содержит следующие функции:

Любые литералы Edm.Date (дата, состоящая из года, месяца и дня, например 2020-12-12) в выражениях фильтра должны соответствовать формату Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Это изменение было необходимо для обработки ошибочных или неожиданных результатов запроса из-за различий в часовых поясах.

Изменения в работе

Алгоритм ранжирования BM25 заменяет предыдущий алгоритм ранжирования более новой технологией. Службы, созданные после 2019 года, автоматически используют этот алгоритм. Для старых служб необходимо задать параметры для использования нового алгоритма.
В этой версии были изменены упорядоченные результаты для значений NULL, значения NULL отображаются первыми при сортировке asc и последними при сортировке desc. Если вы написали код для обработки сортировки нулевых значений, помните об этом изменении.

Обновление до 2019-05-06

Функции, которые стали общедоступными в этой версии API, включают:

Автозаполнение — это функция с опережением ввода, которая завершает ввод частично указанного термина.
Сложные типы обеспечивают встроенную поддержку данных структурированных объектов в поисковом индексе.
Режимы синтаксического анализа JsonLines, являющиеся частью индексации BLOB-объектов Azure, создают один поисковый документ для каждой сущности JSON, разделенный новой строкой.
Обогащение ИИ обеспечивает индексирование, использующее механизмы обогащения ИИ служб ИИ Azure.

Критические изменения

Код, написанный на более ранних версиях API, прерывается на 2019-05-06 и более поздних версиях, если он содержит следующие функции:

Свойство Type для Azure Cosmos DB. Для индексаторов, предназначенных для источника данных API NoSQL для Azure Cosmos DB, перейдите "type": "documentdb" на "type": "cosmosdb".
Если обработка ошибок индексатора содержит ссылки на status свойство, удалите его. Мы удалили состояние из ответа на ошибку, так как не предоставляли полезные сведения.
Источники данных строка подключения больше не возвращаются в ответе. Начиная с версий API 2019-05-06 и 2019-05-06-Preview API источника данных больше не возвращает строки подключения в ответ на любую операцию REST. В предыдущих версиях API для источников данных, созданных с помощью POST, поиск ИИ Azure вернул 201, а затем ответ OData, содержащий строка подключения в виде обычного текста.
Когнитивный навык распознавания именованных сущностей не поддерживается. Если в коде вызывается навык распознавания сущностей имен, вызов завершается сбоем. Функции, которые можно использовать для замены, — Entity Recognition Skill (версии 3). Следуйте рекомендациям в нерекомендуемых навыках , чтобы перейти на поддерживаемый навык.

Обновление сложных типов

В API версии 2019-05-06 добавлена формальное поддержка сложных типов. Если в коде были реализованы предыдущие рекомендации по эквивалентности сложного типа в 2017-11-11-Preview или 2016-09-01-Preview, то существуют новые и измененные ограничения, начиная с версии 2019-05-06, которую необходимо учитывать:

Ограничения на глубину подфилдов и количество сложных коллекций на индекс были снижены. Если вы создали индексы, которые превышают эти ограничения, используя предварительные версии api, любая попытка обновить или воссоздать их с помощью версии API 2019-05-06 потерпит неудачу. Если вы находитесь в этой ситуации, необходимо изменить схему в соответствии с новыми ограничениями, а затем перестроить индекс.
Существует новое ограничение, начиная с api-версии 2019-05-06 по количеству элементов сложных коллекций на документ. Если вы создали индексы с документами, превышающими эти ограничения, с помощью предварительных версий api, любая попытка переиндексировать эти данные с помощью api-версии 2019-05-06 завершится ошибкой. Если вы находитесь в этой ситуации, необходимо уменьшить количество сложных элементов коллекции на документ, прежде чем переиндексировать данные.

Дополнительные сведения см. в разделе "Ограничения службы" для поиска ИИ Azure.

Как обновить старую структуру сложного типа

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

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

Более новый древовидный формат для определения полей индекса был представлен в версии API 2017-11-11-Preview. В новом формате каждое сложное поле имеет коллекцию полей, в которой определены его подполя. В версии API 2019-05-06 этот новый формат используется исключительно, и попытка создания или обновления индекса с использованием старого формата завершится ошибкой. Если у вас есть индексы, созданные с использованием старого формата, вам необходимо использовать API версии 2017-11-11-Preview, чтобы обновить их до нового формата, прежде чем ими можно будет управлять с помощью API версии 2019-05-06.

Вы можете обновить "плоские" индексы до нового формата, выполнив следующие действия, используя версию API 2017-11-11-Preview:

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