Uaktualnianie do najnowszego interfejsu API REST w usłudze Azure AI Search

Artykuł
05/06/2024

Ten artykuł służy do migrowania wywołań płaszczyzny danych do nowszych wersji interfejsu API REST wyszukiwania.

2023-11-01 jest najnowszą stabilną wersją. Semantyczne klasyfikowanie i obsługa indeksowania wektorów i zapytań są ogólnie dostępne w tej wersji.
2023-10-01-preview to najnowsza wersja zapoznawcza . Funkcje w wersji zapoznawczej obejmują wbudowaną wektoryzację zapytań, wbudowane fragmentowanie i wektoryzację danych podczas indeksowania (korzysta z umiejętności dzielenia tekstu i umiejętności osadzania w usłudze Azure OpenAI).
2023-07-01-preview był pierwszym interfejsem API REST obsługującym wektory. Jest ona teraz przestarzała i należy natychmiast przeprowadzić migrację do wersji 2023-11-01 lub 2023-10-01-preview .

Uwaga

Dokumentacja referencyjna interfejsu API REST jest teraz wersjonowana. Aby uzyskać odpowiednią zawartość, otwórz stronę odwołania, a następnie przefiltruj według wersji, używając selektora znajdującego się nad spisem treści.

Kiedy należy uaktualnić

Usługa Azure AI Search przerywa zgodność z poprzednimi wersjami w ostateczności. Uaktualnienie jest konieczne, gdy:

Kod odwołuje się do wycofanej lub przestarzałej wersji interfejsu API i podlega co najmniej jednej zmianie powodującej niezgodność. Wersje interfejsu API, które należą do tej kategorii, obejmują 2023-07-10-preview dla wektorów i 2019-05-06.
Kod kończy się niepowodzeniem, gdy nierozpoznane właściwości są zwracane w odpowiedzi interfejsu API. Najlepszym rozwiązaniem jest ignorowanie właściwości, których nie rozumie.
Kod utrwala żądania interfejsu API i próbuje ponownie wysłać je do nowej wersji interfejsu API. Na przykład może się to zdarzyć, jeśli aplikacja będzie utrwalać tokeny kontynuacji zwracane z interfejsu API wyszukiwania (aby uzyskać więcej informacji, poszukaj @search.nextPageParameters w dokumentacji interfejsu API wyszukiwania).

Zmiana powodująca niezgodność dla kodu klienta, który odczytuje informacje o połączeniu

Od 29 marca 2024 r. i dotyczy wszystkich obsługiwanych interfejsów API REST:

Zestaw umiejętności GET, indeks GET i indeksator GET nie zwracają już kluczy ani właściwości połączenia w odpowiedzi. Jest to zmiana powodująca niezgodność, jeśli kod podrzędny odczytuje klucze lub połączenia (dane poufne) z odpowiedzi GET.
Jeśli musisz pobrać klucze interfejsu API administratora lub zapytania dla usługi wyszukiwania, użyj interfejsów API REST zarządzania.
Jeśli musisz pobrać parametry połączenia innego zasobu platformy Azure, takiego jak Azure Storage lub Azure Cosmos DB, skorzystaj z interfejsów API tego zasobu i opublikowanych wskazówek, aby uzyskać informacje.

Uaktualnianie do wersji 2023-10-01-preview

W tej sekcji opisano ścieżkę migracji z wersji 2023-07-01-preview do 2023-10-01-preview. Należy przeprowadzić migrację do wersji 2023-10-01-preview, jeśli chcesz używać funkcji wektorów, które są nadal dostępne w publicznej wersji zapoznawczej. Jeśli nie potrzebujesz funkcji w wersji zapoznawczej, zalecamy uaktualnienie do stabilnej wersji 2023-11-01.

Funkcje w wersji zapoznawczej obejmują:

Ponieważ te funkcje nie istniały w poprzednich wersjach interfejsu API, nie ma ścieżki migracji. Aby dowiedzieć się, jak dodać te funkcje do kodu, zobacz przykłady kodu i przewodniki.

Z kolei definicje pól wektorów, konfiguracja algorytmu wyszukiwania wektorów i składnia zapytań wektorów, które zostały wprowadzone po raz pierwszy w wersji zapoznawczej 2023-07-01-preview zostały zmienione. Składnia 2023-10-01-preview dla pól, algorytmów i zapytań wektorowych jest identyczna ze składnią 2023-11-01. Kroki migracji tych konstrukcji wektorów wyjaśniono w uaktualnieniu do wersji 2023-11-01.

Uaktualnianie portalu dla indeksów wektorów

Witryna Azure Portal obsługuje ścieżkę uaktualnienia jednym kliknięciem dla indeksów 2023-07-01-preview. Portal wykrywa pola wektorów 2023-07-01-preview i udostępnia przycisk Migruj .

Ścieżka migracji to 2023-07-01-preview do 2023-10-01-preview.
Aktualizacje są ograniczone do definicji pól wektorowych i konfiguracji algorytmów wyszukiwania wektorów.
Aktualizacje są jednokierunkowe. Nie można cofnąć uaktualnienia. Po uaktualnieniu indeksu należy użyć polecenia 2023-10-01-preview lub nowszego, aby wykonać zapytanie dotyczące indeksu.

Nie ma migracji portalu do uaktualniania składni zapytań wektorowych. Zobacz uaktualnianie do wersji 2023-11-01 , aby uzyskać informacje o zmianach składni zapytań.

Przed wybraniem pozycji Migruj wybierz pozycję Edytuj kod JSON, aby najpierw przejrzeć zaktualizowany schemat. Należy znaleźć schemat zgodny ze zmianami opisanymi w uaktualnieniu do wersji 2023-11-01. Migracja portalu obsługuje tylko indeksy z jedną konfiguracją algorytmu wyszukiwania wektorowego. Tworzy on profil domyślny, który mapuje się na algorytm wyszukiwania wektorów wektorów 2023-07-01-preview. Indeksy z wieloma konfiguracjami wyszukiwania wektorowego wymagają migracji ręcznej.

Uaktualnianie do wersji 2023-11-01

Ta wersja ma zmiany powodujące niezgodność i różnice behawioralne w zakresie obsługi klasyfikacji semantycznej i wyszukiwania wektorów.

Ranking semantyczny jest ogólnie dostępny w 2023-11-01. Nie używa queryLanguage już właściwości . Wymaga również semanticConfiguration definicji. Zamienia semanticConfiguration się searchFields w poprzednich wersjach. Aby uzyskać instrukcje, zobacz Migrowanie z wersji zapoznawczej.
Obsługa wyszukiwania wektorowego została wprowadzona w sekcji Tworzenie lub aktualizowanie indeksu (2023-07-01-preview). Uaktualnienie z wersji 2023-07-01-preview wymaga zmiany nazwy i restrukturyzacji konfiguracji wektora w indeksie. Wymaga również ponownego zapisywania zapytań wektorowych. Skorzystaj z instrukcji w tej sekcji, aby przeprowadzić migrację pól wektorów, konfiguracji i zapytań.

W przypadku uaktualniania z wersji 2023-10-01-preview do wersji 2023-11-01 nie ma żadnych zmian powodujących niezgodność, ale istnieje jedna różnica między zachowaniem: vectorFilterMode domyślna zmiana z filtru postfiltru na filtr wstępny dla wyrażeń filtru. Jeśli kod 2023-10-01-preview nie jest ustawiony vectorFilterMode jawnie, upewnij się, że rozumiesz nowe zachowanie domyślne lub jawnie ustawiono vectorFilterMode na postfiltr, aby zachować stare zachowanie.

Poniżej przedstawiono kroki migracji z wersji 2023-07-01-preview do wersji 2023-11-01:

Wywołaj metodę Pobierz indeks , aby pobrać istniejącą definicję.

Zmodyfikuj konfigurację wyszukiwania wektorowego. 2023-11-01 wprowadza koncepcję profilów wektorów , które łączą konfiguracje związane z wektorami pod jedną nazwą. Zmienia również nazwę algorithmConfigurations na algorithms.

Zmień nazwę algorithmConfigurations na algorithms. Jest to tylko zmiana nazwy tablicy. Zawartość jest zgodna z poprzednimi wersjami. Oznacza to, że można użyć istniejących parametrów konfiguracji HNSW.
Dodaj profileselement , podając nazwę i konfigurację algorytmu dla każdego z nich.

Przed migracją (2023-07-01-preview):

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

Po migracji (2023-11-01):

  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

Zmodyfikuj definicje pól wektorów, zastępując ciąg vectorSearchConfiguration ciągiem vectorSearchProfile. Upewnij się, że nazwa profilu jest rozpoznawana jako nowa definicja profilu wektorowego, a nie nazwa konfiguracji algorytmu. Inne właściwości pola wektorowego pozostają niezmienione. Na przykład nie można ich filtrować, sortować ani aspektów, ani używać analizatorów, normaliatorów ani map synonimów.

Przed (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"
  }

Po (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"
  }

Wywołaj metodę Utwórz lub Zaktualizuj indeks , aby opublikować zmiany.

Zmodyfikuj wyszukiwanie POST , aby zmienić składnię zapytania. Ta zmiana interfejsu API umożliwia obsługę typów zapytań wektorów polimorficznych.

Zmień nazwę vectors na vectorQueries.
Dla każdego zapytania wektorowego dodaj kindelement , ustawiając go na vector.
Dla każdego zapytania wektorowego zmień nazwę value na vector.
Opcjonalnie dodaj vectorFilterMode , jeśli używasz wyrażeń filtru. Wartość domyślna to wstępne filtrowanie indeksów utworzonych po 2023-10-01. Indeksy utworzone przed tą datą obsługują tylko filtr postfiltr, niezależnie od sposobu ustawiania trybu filtrowania.

Przed (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"
}

Po (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"
}

Te kroki umożliwiają ukończenie migracji do wersji interfejsu API 2023-11-01.

Uaktualnianie do wersji 2020-06-30

W tej wersji istnieje jedna zmiana powodująca niezgodność i kilka różnic behawioralnych. Ogólnie dostępne funkcje obejmują:

Magazyn wiedzy, trwały magazyn wzbogaconej zawartości utworzonej za pomocą zestawów umiejętności utworzonych na potrzeby analizy podrzędnej i przetwarzania za pośrednictwem innych aplikacji. Magazyn wiedzy jest tworzony za pomocą interfejsów API REST usługi Azure AI Search, ale znajduje się w usłudze Azure Storage.

Zmiana powodująca niezgodność

Kod napisany w starszych wersjach interfejsu API przerywa działanie 2020-06-30 i nowsze, jeśli kod zawiera następujące funkcje:

Wszystkie Edm.Date literały (data składająca się z dnia miesiąca, na przykład 2020-12-12) w wyrażeniach filtru muszą być zgodne z formatem Edm.DateTimeOffset : 2020-12-12T00:00:00Z. Ta zmiana była konieczna do obsługi błędnych lub nieoczekiwanych wyników zapytania z powodu różnic w strefie czasowej.

Zmiany zachowania

Algorytm klasyfikacji BM25 zastępuje poprzedni algorytm klasyfikacji nowszą technologią. Usługi utworzone po 2019 r. automatycznie używają tego algorytmu. W przypadku starszych usług należy ustawić parametry, aby używać nowego algorytmu.
Uporządkowane wyniki dla wartości null zostały zmienione w tej wersji, a wartości null są wyświetlane jako pierwsze, jeśli sortowanie to asc i ostatnie, jeśli sortowanie to desc. Jeśli napisaliśmy kod do obsługi sposobu sortowania wartości null, należy pamiętać o tej zmianie.

Uaktualnianie do wersji 2019-05-06

Funkcje, które stały się ogólnie dostępne w tej wersji interfejsu API, obejmują:

Autouzupełnianie to funkcja typu, która kończy częściowo określony termin wejściowy.
Typy złożone zapewniają natywną obsługę danych obiektów strukturalnych w indeksie wyszukiwania.
Tryby analizowania JsonLines, część indeksowania obiektów blob platformy Azure, tworzy jeden dokument wyszukiwania dla jednostki JSON oddzielonej nową linią.
Wzbogacanie sztucznej inteligencji zapewnia indeksowanie korzystające z aparatów wzbogacania sztucznej inteligencji usług Azure AI.

Zmiany powodujące niezgodność

Kod napisany we wcześniejszej wersji interfejsu API jest przerywany 2019-05-06 i nowszy, jeśli zawiera on następujące funkcje:

Właściwość type dla usługi Azure Cosmos DB. W przypadku indeksatorów przeznaczonych dla źródła danych interfejsu API NoSQL dla usługi Azure Cosmos DB zmień wartość "type": "documentdb" na "type": "cosmosdb".
Jeśli obsługa błędów indeksatora zawiera odwołania do status właściwości, należy ją usunąć. Usunięto stan z odpowiedzi na błąd, ponieważ nie dostarczał przydatnych informacji.
W odpowiedzi nie są już zwracane parametry połączenia źródła danych. Od wersji 2019-05-06 interfejsu API i 2019-05-06-Preview nowszych interfejs API źródła danych nie zwraca już parametry połączenia w odpowiedzi na każdą operację REST. W poprzednich wersjach interfejsu API w przypadku źródeł danych utworzonych przy użyciu funkcji POST usługa Azure AI Search zwróciła 201, a następnie odpowiedź OData, która zawierała parametry połączenia w postaci zwykłego tekstu.
Umiejętność poznawcza rozpoznawania jednostek została wycofana. W przypadku wywołania umiejętności rozpoznawania jednostek nazw w kodzie wywołanie zakończy się niepowodzeniem. Funkcja zamiany to umiejętność rozpoznawania jednostek (V3). Postępuj zgodnie z zaleceniami w temacie Przestarzałe umiejętności , aby przeprowadzić migrację do obsługiwanej umiejętności.

Uaktualnianie typów złożonych

Wersja 2019-05-06 interfejsu API dodała formalną obsługę typów złożonych. Jeśli kod zaimplementował poprzednie zalecenia dotyczące równoważności typu złożonego w wersji 2017-11-11-Preview lub 2016-09-01-Preview, istnieją pewne nowe i zmienione limity, których 2019-05-06 należy pamiętać:

Limity głębokości pól podrzędnych i liczby kolekcji złożonych na indeks zostały obniżone. Jeśli utworzono indeksy przekraczające te limity przy użyciu wersji interfejsu API w wersji zapoznawczej, próba zaktualizowania lub ponownego utworzenia ich przy użyciu wersji 2019-05-06 interfejsu API zakończy się niepowodzeniem. Jeśli znajdziesz się w tej sytuacji, musisz przeprojektować schemat, aby dopasować go do nowych limitów, a następnie ponownie skompilować indeks.
Istnieje nowy limit rozpoczynający się od wersji 2019-05-06 interfejsu API dla liczby elementów złożonych kolekcji na dokument. Jeśli utworzono indeksy z dokumentami, które przekraczają te limity przy użyciu wersji zapoznawczej interfejsu API-versions, każda próba ponownego indeksowania tych danych przy użyciu interfejsu API-version 2019-05-06 zakończy się niepowodzeniem. Jeśli znajdziesz się w tej sytuacji, musisz zmniejszyć liczbę złożonych elementów kolekcji na dokument przed ponownym indeksowaniem danych.

Aby uzyskać więcej informacji, zobacz Limity usługi dla usługi Azure AI Search.

Jak uaktualnić starą strukturę typu złożonego

Jeśli kod używa złożonych typów ze starszymi wersjami interfejsu API w wersji zapoznawczej, może być używany format definicji indeksu, który wygląda następująco:

{
  "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" }
  ]
}

Nowszy format przypominający drzewo do definiowania pól indeksu został wprowadzony w wersji 2017-11-11-Previewinterfejsu API . W nowym formacie każde pole złożone ma kolekcję pól, w której są zdefiniowane jego pola podrzędne. W interfejsie API w wersji 2019-05-06 ten nowy format jest używany wyłącznie i próba utworzenia lub zaktualizowania indeksu przy użyciu starego formatu zakończy się niepowodzeniem. Jeśli masz indeksy utworzone przy użyciu starego formatu, musisz użyć wersji 2017-11-11-Preview interfejsu API, aby zaktualizować je do nowego formatu, zanim będzie można nimi zarządzać przy użyciu interfejsu API w wersji 2019-05-06.

Indeksy płaskie można zaktualizować do nowego formatu, wykonując następujące kroki przy użyciu wersji 2017-11-11-Previewinterfejsu API:

Wykonaj żądanie GET, aby pobrać indeks. Jeśli jest już w nowym formacie, wszystko jest gotowe.
Przetłumacz indeks z formatu płaskiego na nowy format. Musisz napisać kod dla tego zadania, ponieważ w momencie pisania tego tekstu nie ma dostępnego przykładowego kodu.
Wykonaj żądanie PUT, aby zaktualizować indeks do nowego formatu. Unikaj zmiany innych szczegółów indeksu, takich jak możliwość wyszukiwania/filtrowanie pól, ponieważ zmiany wpływające na fizyczne wyrażenie istniejącego indeksu nie są dozwolone przez interfejs API indeksu aktualizacji.