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

Статья
05/09/2024

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

2023-11-01 является последней стабильной версией. Семантический ранжирование и поддержка индексирования векторов и запросов обычно доступны в этой версии.

Если вы обновляетесь с 2023-10-01-preview до 2023-11-01, нет критических изменений, но есть одно различие в поведении: vectorFilterMode по умолчанию изменено с postfilter на префильтратор для выражений фильтров. Если код предварительной версии 2023-10-01-preview не задан явным образом, убедитесь, что вы понимаете новое поведение по умолчанию или явным образом задается vectorFilterModevectorFilterMode значение postfilter, чтобы сохранить старое поведение.
2024-05-01-preview — это последняя предварительная версия API. Он добавляет двоичный тип данных для векторных полей, свойств релевантности для улучшения результатов поиска, индексатора файлов OneLake, больше векторизаторов и других навыков внедрения. Навык azureOpenAIEmbedding обновляется для включения dimensions и modelName свойств. Единственная проблема с обратной совместимостью между этим предварительным просмотром и предыдущими двумя предварительными версиями теперь modelName требуется.
2024-03-01-preview добавляет новые типы данных и свойства для сжатия, но в противном случае полностью обратная совместимость с 2023-10-01-preview. Инструкции по обновлению для использования этой предварительной версии отсутствуют.
2023-10-01-preview — это первая предварительная версия, которая добавила встроенную векторизацию запросов, встроенную блокирование и векторизацию данных во время индексирования (использует навык разделения текста и навык внедрения Azure OpenAI). Он вводит критические изменения в конфигурации векторов в запросах индекса и вектора.
2023-07-01-preview был первым REST API для поддержки векторов. Теперь он устарел, и вы должны немедленно перейти на 2023-11-01 или любой из более новых интерфейсов REST API предварительной версии.

Примечание.

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

Когда необходимо обновить

Поиск ИИ Azure нарушает обратную совместимость в качестве последнего средства. Обновление необходимо при:

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

Критическое изменение клиентского кода, считывающего сведения о подключении

Действует с 29 марта 2024 г. и применяется ко всем поддерживаемым REST API:

Набор навыков GET, GET Index и GET Indexer больше не возвращают ключи или свойства подключения в ответе. Это критическое изменение, если у вас есть подчиненный код, который считывает ключи или подключения (конфиденциальные данные) из ответа GET.
Если вам нужно получить ключи API администратора или API для службы поиска, используйте ИНТЕРФЕЙСы REST API управления.
Если вам нужно получить строка подключения другого ресурса Azure, например служба хранилища Azure или Azure Cosmos DB, используйте API этого ресурса и опубликованные инструкции для получения сведений.

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

Семантический рейтинг общедоступен в 2023-11-01. В отличие от предыдущих версий REST API, он больше не использует queryLanguage свойство. Для этого также требуется semanticConfiguration определение, заменяющее предыдущие searchFields версии. См . статью "Миграция из предварительной версии " для перехода кода на общедоступную версию или более новую предварительную версию.

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

В этом разделе объясняется путь миграции от 2023-07-01-preview к любой более новой версии API. Существует несколько критических изменений с 2023-07-01-preview до любой более новой версии, но только незначительные проблемы совместимости между более новыми версиями API, которые следуют ниже.

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

Обновление портала для векторных индексов

портал Azure поддерживает путь обновления по одному щелчку для индексов 2023-07-01-preview. Портал обнаруживает поля вектора 2023-07-01-preview и предоставляет кнопку "Миграция ".

Путь миграции — от 2023-07-01-preview до 2023-10-01-preview.
Обновления ограничены определениями векторных полей и конфигурациями алгоритмов векторного поиска.
Обновления односторонняя. Невозможно отменить обновление. После обновления индекса необходимо использовать 2023-10-01-preview или более поздней версии для запроса индекса.

Миграция портала для обновления синтаксиса векторного запроса отсутствует. Ознакомьтесь с обновлениями кода для изменений синтаксиса запросов.

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

Обновление кода для векторных индексов и запросов

Поддержка поиска векторов появилась в разделе "Создание или обновление индекса" (2023-07-01-preview).

Обновление с 2023-07-01-preview до любой более новой стабильной или предварительной версии:

Переименование и реструктуризация конфигурации вектора в индексе
Перезапись векторных запросов

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

Вызовите get Index , чтобы получить существующее определение.
Измените конфигурацию векторного поиска. В версиях 2023-11-01 и более поздних версий представлена концепция профилей векторов, которые объединяют конфигурации, связанные с векторами, под одним именем. Более новые версии также переименуют 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": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }
```

Измените определения векторного поля, заменив 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 или более новую версию API предварительной версии.

Обновление до 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-Preview более поздних 2019-05-06 версий API источник данных больше не возвращает строка подключения в ответе любой операции REST. В предыдущих версиях API для источников данных, созданных с помощью POST, поиск ИИ Azure вернул 201, а затем ответ OData, содержащий строка подключения в виде обычного текста.
Когнитивный навык распознавания именованных сущностей не поддерживается. Если в коде вызывается навык распознавания сущностей имен, вызов завершается сбоем. Функции, которые можно использовать для замены, — Entity Recognition Skill (версии 3). Следуйте рекомендациям в нерекомендуемых навыках , чтобы перейти на поддерживаемый навык.

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

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

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

Дополнительные сведения см. в разделе "Ограничения службы" для поиска ИИ 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" }
  ]
}

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

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

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