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

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

  • Статья

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

  • 2024-07-01 является последней стабильной версией.

  • 2024-09-01-preview является последней версией API предварительной версии.

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

Мы рекомендуем обновить версии API в последовательности, работая с каждой версией до тех пор, пока не получите новую версию.

2023-07-01-preview был первым REST API для поддержки векторов. Не используйте эту версию API. Теперь он устарел, и вы должны сразу перейти на стабильные или более новые интерфейсы REST API.

Примечание.

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

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

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

  • Код ссылается на устаревшую или неподдерживаемую версию API и подвергается одному или нескольким критическим изменениям. Необходимо устранить критические изменения, если целевые объекты 2023-07-10-preview кода для векторов, 2020-06-01-preview для семантического ранджера, а 2019-05-06 также для устаревших навыков и обходных решений.

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

  • Код сохраняет запросы API и пытается повторно отправить их в новую версию API. Например, это может произойти, если приложение сохраняет маркеры продолжения, возвращенные API поиска (см. сведения об @search.nextPageParameters в справочнике по API поиска).

Обновление

  1. Просмотрите заметки о выпуске для каждой версии API.

  2. Обновите параметр, указанный api-version в заголовке запроса, до более новой версии.

    В коде приложения, который выполняет прямые вызовы к REST API, найдите все экземпляры существующей версии и замените ее новой версией. Дополнительные сведения о структурировании вызова REST см . в кратком руководстве по использованию REST.

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

  3. Просмотрите критические изменения, описанные в этой статье, и реализуйте обходные пути. Начните с версии, используемой кодом, и устраните критические изменения для каждой новой версии API до тех пор, пока не получите новый стабильный или предварительный выпуск.

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

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

  • Набор навыков GET, GET Index и GET Indexer больше не возвращают ключи или свойства подключения в ответе. Это критическое изменение, если у вас есть подчиненный код, который считывает ключи или подключения (конфиденциальные данные) из ответа GET.

  • Если вам нужно получить ключи API администратора или API для службы поиска, используйте ИНТЕРФЕЙСы REST API управления.

  • Если вам нужно получить строка подключения другого ресурса Azure, например служба хранилища Azure или Azure Cosmos DB, используйте API этого ресурса и опубликованные инструкции для получения сведений.

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

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

  • Во всех версиях после 2020-06-01-preview: semanticConfiguration заменяет searchFields механизм указания полей, используемых для ранжирования L2.

  • Для всех версий API обновления 14 июля 2023 г. до размещенных корпорацией Майкрософт семантических моделей сделало семантику языка рангера не зависящим от этого свойства.queryLanguage В коде нет "критического изменения", но свойство игнорируется.

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

Обновление до версии 2024-09-01-preview

2024-09-01-preview добавляет сжатие Matryoshka Representation Learning (MRL) для моделей внедрения текста-3, целевой фильтрации векторов для гибридных запросов, векторных сведений об отладке и фрагментирования маркеров для навыка разделения текста.

При обновлении 2024-05-01-previewс помощью новых API предварительной версии можно использовать без изменений существующего кода.

Обновление до 2024-07-01

2024-07-01 — общий выпуск. Ранее доступные функции предварительной версии: интегрированные блоки и векторизация (навык разделения текста, навык AzureOpenAIEmbedding), векторизатор запросов на основе AzureOpenAIEmbedding, сжатия векторов (скалярная квантизация, двоичная квантизация, хранимое свойство, узкие типы данных).

При обновлении до 2024-05-01-preview стабильного обновления не возникают критические изменения. Чтобы использовать новый стабильный выпуск, измените версию API и протестируйте код.

При обновлении непосредственно с 2023-11-01помощью обновления возникают критические изменения. Выполните действия, описанные для каждой новой предварительной версии, чтобы перейти из 2023-11-01 2024-07-01нее.

Обновление до версии 2024-05-01-preview

2024-05-01-preview добавляет индекс OneLake, поддержку двоичных векторов и поддержку дополнительных моделей внедрения.

При обновлении с помощью навыка 2024-03-01-previewAzureOpenAIEmbedding теперь требуется свойство модели и измерения.

  1. Выполните поиск в базе кода для ссылок azureOpenAIEmbedding .

  2. Задайте для modelName параметра text-embedding-ada-002 и установите значение dimensions "1536".

Обновление до версии 2024-03-01-preview

2024-03-01-preview добавляет узкие типы данных, скалярную квантизацию и параметры хранилища векторов.

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

  1. Найдите базу кода для vectorFilterMode ссылок.

  2. Если свойство задано явным образом, действие не требуется. Если вы использовали значение по умолчанию, помните, что новое поведение по умолчанию — фильтровать перед выполнением запроса. Если требуется фильтрация после запроса, явно задайте vectorFilterMode для postfilter сохранение старого поведения.

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

2023-11-01 — общий выпуск. Теперь доступны бывшие функции предварительной версии: семантический рангер, векторный индекс и поддержка запросов.

Нет критических изменений от 2023-10-01-preview, но есть несколько критических изменений от 2023-07-01-preview 2023-11-01. Дополнительные сведения см. в разделе "Обновление с версии 2023-07-01-preview".

Чтобы использовать новый стабильный выпуск, измените версию API и протестируйте код.

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

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

Если вы обновляете предыдущую версию, в следующем разделе описаны действия.

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

Не используйте эту версию API. Он реализует синтаксис векторного запроса, несовместимый с любой новой версией API.

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

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

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

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

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

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

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

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

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

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

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

  1. Вызовите get Index , чтобы получить существующее определение.

  2. Измените конфигурацию векторного поиска. 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"
      }
    ]
  }

  3. Измените определения векторного поля, заменив 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"
  }

  4. Вызовите создание или обновление индекса для публикации изменений.

  5. Измените метод Search POST , чтобы изменить синтаксис запроса. Это изменение API позволяет поддерживать типы запросов полиморфных векторов.

    • Переименуйте vectors в vectorQueries.
    • Для каждого векторного запроса добавьте kind, задав для него значение vector.
    • Для каждого векторного запроса переименуйте в value vector.
    • При необходимости добавьте 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"
}

В этих шагах выполняется миграция на 2023-11-01 стабильную версию API или более новую версию 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 и более поздними версиями, если он содержит следующие функции:

  1. Свойство Type для Azure Cosmos DB. Для индексаторов, предназначенных для источника данных API NoSQL для Azure Cosmos DB, перейдите "type": "documentdb" на "type": "cosmosdb".

  2. Если обработка ошибок индексатора содержит ссылки на status свойство, удалите его. Мы удалили состояние из ответа на ошибку, так как не предоставляли полезные сведения.

  3. Источники данных строка подключения больше не возвращаются в ответе. Из версий API и 2019-05-06-Preview более поздних 2019-05-06 версий API источник данных больше не возвращает строка подключения в ответе любой операции REST. В предыдущих версиях API для источников данных, созданных с помощью POST, поиск ИИ Azure вернул 201, а затем ответ OData, содержащий строка подключения в виде обычного текста.

  4. Когнитивный навык распознавания именованных сущностей не поддерживается. Если в коде вызывается навык распознавания сущностей имен, вызов завершается сбоем. Функции, которые можно использовать для замены, — 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:

  1. Выполните запрос GET для получения вашего индекса. Если он уже в новом формате, все готово.

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

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

Примечание.

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

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

Изучите справочную документацию по Search REST API. Если у вас возникнут проблемы, обратитесь к нам за помощью по Stack Overflow или обратитесь в службу поддержки.

Справочник по REST API службы поиска