Aktualizacja do najnowszego interfejsu API REST w Wyszukiwanie AI platformy Azure

Uwaga

Wyszukiwanie AI platformy Azure jest dostępna za pośrednictwem portalu Azure, interfejsów API REST i Azure SDKs. Jest także podstawą Foundry IQ — zarządzanej warstwy wiedzy, która przekształca treści przedsiębiorstwa w bazy wiedzy wielokrotnego użytku z uwzględnieniem uprawnień dla agentów w portalu Microsoft Foundry.

Użyj tego artykułu, aby przeprowadzić migrację do nowszych wersji interfejsów API REST usługi wyszukiwania i interfejsów API REST zarządzania wyszukiwaniem na potrzeby operacji płaszczyzny danych i płaszczyzny sterowania .

Poniżej przedstawiono najnowsze wersje interfejsów API REST:

Operacje ukierunkowane interfejs API REST Stan
Płaszczyzna danych 2026-04-01 Stabilne
Płaszczyzna danych 2026-05-01-preview Podgląd
Płaszczyzna sterowania 2025-05-01 Stabilne
Płaszczyzna sterowania 2026-03-01-preview Podgląd

Instrukcje uaktualniania koncentrują się na zmianach kodu, które pomagają przezwyciężyć zmiany łamiące zgodność z poprzednich wersji, aby istniejący kod działał tak samo jak wcześniej, ale na nowszej wersji API. Gdy kod jest w porządku roboczym, możesz zdecydować, czy wdrażać nowsze funkcje. Aby dowiedzieć się więcej o nowych funkcjach, zobacz Co nowego w Wyszukiwanie AI platformy Azure.

Zalecamy aktualizowanie wersji interfejsu API kolejno, przechodząc przez każdą wersję do uzyskania najnowszej.

2023-07-01-preview był pierwszym interfejsem API REST obsługującym wektory. Nie używaj tej wersji interfejsu API. Jest ona teraz przestarzała i natychmiast należy przeprowadzić migrację do stabilnych lub nowszych interfejsów API REST w wersji zapoznawczej.

Uwaga

Dokumentacja referencyjna interfejsu API REST jest teraz wersjonowana. W przypadku zawartości specyficznej dla wersji otwórz stronę referencyjną, a następnie użyj selektora znajdującego się powyżej spisu treści, aby wybrać wersję.

Kiedy należy uaktualnić

Wyszukiwanie AI platformy Azure łamie zgodność z poprzednimi wersjami jedynie w ostateczności. Uaktualnienie jest konieczne, gdy:

  • Kod odwołuje się do wycofanej lub nieobsługiwanej wersji interfejsu API i podlega co najmniej jednej krytycznej zmianie.

  • 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).

Jak uaktualnić

  1. Jeśli uaktualniasz wersję płaszczyzny danych, sprawdź, co zostało wydane w nowej wersji interfejsu API.

  2. api-version Zaktualizuj parametr określony w nagłówku żądania do nowszej wersji.

    W kodzie aplikacji, który wykonuje bezpośrednie wywołania interfejsów API REST, wyszukaj wszystkie wystąpienia istniejącej wersji, a następnie zastąp ją nową wersją. Aby uzyskać więcej informacji na temat tworzenia struktury wywołania REST, zobacz Szybki start: wyszukiwanie pełnotekstowe przy użyciu interfejsu REST.

    Jeśli używasz Azure SDK, każdy pakiet jest przeznaczony dla określonej wersji interfejsu API REST. Aby określić, która wersja interfejsu API REST obsługuje pakiet, przejrzyj jego dziennik zmian. Zaktualizuj do najnowszej wersji pakietu, aby uzyskać dostęp do najnowszych funkcji i ulepszeń interfejsu API.

  3. Jeśli uaktualniasz wersję płaszczyzny danych, przejrzyj zmiany powodujące niezgodność udokumentowane w tym artykule i zaimplementuj obejścia. Zacznij od wersji używanej przez kod i rozwiąż wszelkie zmiany powodujące niezgodność dla każdej nowszej wersji interfejsu API, dopóki nie uzyskasz najnowszej stabilnej wersji lub wersji zapoznawczej.

Zmiany powodujące niezgodność

Następujące zmiany powodujące niezgodność dotyczą operacji na danych.

Zmiany powodujące niezgodność dotyczące autonomicznego pobierania

2026-04-01 jest pierwszą stabilną wersją interfejsu API REST dla agentowego przetwarzania danych. Wprowadzono następujące zmiany powodujące niezgodność z 2025-11-01-preview elementem:

  • Synteza odpowiedzi, planowanie zapytań i konfigurowalne wysiłki dotyczące rozumowania są usuwane. Pobieranie zwraca tylko ekstrakcyjną, ugruntowaną zawartość.

  • Zmiany kształtu żądania pobierania: messages są zastępowane przez intents, a kilka parametrów jest zmienianych lub usuwanych.

  • Filtrowanie uprawnień na poziomie dokumentu dla obiektów blob i źródeł wiedzy OneLake nie jest obsługiwane.

Aby uzyskać pełną listę zmian na poziomie właściwości oraz kroki migracji, zobacz Migrowanie kodu agentowego pobierania danych.

Istotne zmiany dla agentów wiedzy

Agenci wiedzy zostali wprowadzeni w 2025-05-01-preview. W 2025-08-01-preview, targetIndexes został zastąpiony nowym obiektem źródła wiedzy, a defaultMaxDocsForReranker innymi interfejsami API. Wprowadzono więcej zmian powodujących niezgodność w programie 2025-11-01-preview.

Aby uzyskać pełną listę zmian na poziomie właściwości oraz kroki migracji, zobacz Migrowanie kodu agentowego pobierania danych.

Istotne zmiany 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 potrzebujesz uzyskać klucze API administracyjne lub klucze zapytań do swojej usługi wyszukiwania, użyj Search Management REST API.

  • Jeśli musisz pobrać parametry połączenia innego zasobu Azure, takiego jak Azure Storage lub Azure Cosmos DB, skorzystaj z interfejsów API tego zasobu i opublikowanych wskazówek, aby uzyskać informacje.

Zmiany destrukcyjne dla rankera semantycznego

Semantic ranker stał się powszechnie dostępny w 2023-11-01. Są to zmiany powodujące niezgodność z wcześniejszych wersji:

  • We wszystkich wersjach po 2020-06-01-preview: semanticConfiguration zastępuje searchFields jako mechanizm określania pól, które mają być używane do klasyfikacji L2.

  • W przypadku wszystkich wersji interfejsu API, aktualizacje z dnia 14 lipca 2023 r. w modelach semantycznych hostowanych przez Microsoft, wykorzystanie semantycznego klasyfikatora językowego skutkuje wycofaniem właściwości queryLanguage. W kodzie nie ma żadnej „zmiany łamiącej”, ale właściwość jest ignorowana.

Zobacz Migrowanie z wersji zapoznawczej, aby przenieść kod do używania semanticConfiguration.

Aktualizacje warstwy danych

Wskazówki dotyczące aktualizacji zakładają aktualizację z najnowszej wcześniejszej wersji. Jeśli twój kod jest oparty na starej wersji interfejsu API, zalecamy uaktualnienie do każdej kolejnej wersji, aby przejść do najnowszej wersji.

Uaktualnianie do wersji 2026-05-01-preview

2026-05-01-preview dodaje nowe typy źródeł wiedzy, nowe parametry akcji pobierania, nowe typy zawartości indeksatora SharePoint i opcje listy ACL oraz inne możliwości.

Nie ma niekompatybilnych zmian na poziomie protokołu względem 2025-11-01-preview. Jeśli jednak używasz zestawu SDK języka Python lub JavaScript do agentic retrieval, klient retrieve zmienia nazwę na KnowledgeBaseRetrievalClient, a retrieveKnowledge(...) zostaje zastąpione przez retrieve(...). Wskazówki dotyczące migracji SDK znajdziesz w artykule Migrowanie kodu wyszukiwania agentowego.

W przypadku wszystkich innych istniejących interfejsów API nie ma żadnych zmian zachowania. Możesz przejść na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2026-04-01

2026-04-01 to najnowsza stabilna wersja interfejsu API REST. Promuje agenturyczne pozyskiwanie informacji, wybór źródeł wiedzy oraz kilka umiejętności i funkcji do szerokiej dostępności.

Przed uaktualnieniem sprawdź, czy do kodu mają zastosowanie dowolne z następujących 2026-04-01 zmian powodujących niezgodność:

  • Sześć właściwości jest usuwanych z definicji umiejętności GenAI Prompt: httpMethod, timeout, batchSize, degreeOfParallelism, httpHeaders i authResourceId. Usuń te właściwości przed uaktualnieniem. Definicje, które nadal zawierają te właściwości, zwracają 400 Bad Request błąd.

  • Pozyskiwanie agentów wymaga teraz własnej zgody na fakturowanie. Jeśli obecnie masz semanticSearch=standard, musisz jednoznacznie ustawić knowledgeRetrieval=standard przed uaktualnieniem. Aby uzyskać więcej informacji, zobacz Włączanie lub wyłączanie rozliczeń za agentów.

  • Jeśli kod pobierania agenta jest przeznaczony dla 2025-11-01-preview, 2026-04-01 usuwa kilka funkcji w wersji zapoznawczej i standaryzuje pobieranie wokół intencji wejścia, wyjściowych danych wyodrębniania i minimalnego rozumowania. Aby uzyskać więcej informacji, zobacz Migrowanie kodu pobierania agenta.

W przypadku wszystkich innych istniejących interfejsów API nie ma żadnych zmian zachowania. Możesz przejść na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2025-11-01-preview

2025-11-01-preview wprowadza następujące zmiany powodujące niezgodność w procesie agentowego pobierania, zgodnie z implementacją w 2025-08-01-preview.

  • Zamienia element agents na knowledgebases. Kilka właściwości związanych ze źródłami wiedzy przeniesiono z definicji bazy wiedzy i do akcji pobierania.

  • Właściwości źródła wiedzy są refaktoryzowane poprzez implementację nowego obiektu ingestionParameters dla źródeł wiedzy, które generują potok indeksatora.

Aby uzyskać pełną listę zmian na poziomie właściwości oraz kroki migracji, zobacz Migrowanie kodu agentowego pobierania danych.

W przypadku wszystkich innych istniejących interfejsów API nie ma żadnych zmian zachowania. Możesz przejść na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2025-09-01

2025-09-01 to stabilna wersja interfejsu API REST, która dodaje ogólną dostępność indeksatora OneLake, umiejętności układu dokumentów i innych interfejsów API.

Nie ma żadnych zmian powodujących niezgodność, jeśli uaktualniasz program 2024-07-01 i nie korzystasz z żadnych funkcji w wersji zapoznawczej. Aby użyć nowej stabilnej wersji, zmień wersję interfejsu API i przetestuj kod.

Uaktualnianie do wersji 2025-08-01-preview

2025-08-01-preview wprowadza następujące zmiany łamiące zgodność dla agentów wiedzy utworzonych za pomocą 2025-05-01-preview:

  • Zamienia element targetIndexes na knowledgeSources.
  • Usuwa defaultMaxDocsForReranker bez zamiany.

W przeciwnym razie nie ma żadnych zmian zachowania w istniejących interfejsach API. Możesz przejść na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2025-05-01-preview

2025-05-01-preview udostępnia nowe funkcje, ale nie ma żadnych zmian zachowania w istniejących interfejsach API. Możesz przejść na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2025-03-01-preview

2025-03-01-preview udostępnia nowe funkcje, ale nie ma żadnych zmian zachowania w istniejących interfejsach API. Możesz przejść na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2024-11-01-preview

2024-11-01-preview przekształcanie zapytań, funkcja układu dokumentu, rozliczanie bezkluczowe dla przetwarzania umiejętności, tryb analizowania Markdown i opcje przeliczania dla skompresowanych wektorów.

W przypadku uaktualniania z 2024-09-01-preview możesz podmienić na nową wersję interfejsu API, a kod działa tak samo jak poprzednio.

Jednak nowa wersja wprowadza zmiany składni w pliku vectorSearch.compressions:

  • Zamienia rerankWithOriginalVectors z enableRescoring
  • Przenosi defaultOversampling do nowego rescoringOptions obiektu właściwości

Zgodność z poprzednimi wersjami jest zachowywana z powodu wewnętrznego mapowania interfejsu API, ale zalecamy zmianę składni w przypadku wdrożenia nowej wersji zapoznawczej. Aby uzyskać porównanie składni, zobacz Kompresowanie wektorów przy użyciu kwantyzacji skalarnej lub binarnej.

Uaktualnianie do wersji 2024-09-01-preview

2024-09-01-preview dodaje kompresję Matryoshka Representation Learning (MRL) dla modeli text-embedding-3, ukierunkowane filtrowanie wektorów dla zapytań hybrydowych, szczegóły subskorów wektorowych na potrzeby debugowania i chunkowanie tokenów dla umiejętności dzielenia tekstu.

W przypadku uaktualniania z 2024-05-01-preview możesz podmienić na nową wersję interfejsu API, a kod działa tak samo jak poprzednio.

Uaktualnianie do wersji 2024-07-01

2024-07-01 jest wydaniem ogólnym. Funkcje w wersji zapoznawczej są teraz ogólnie dostępne: zintegrowane fragmentowanie i wektoryzacja (umiejętność dzielenia tekstu, umiejętność AzureOpenAIEmbedding), wektoryzator zapytań oparty na AzureOpenAIEmbedding, kompresja wektorów (kwantyzacja skalarna, kwantyzacja binarna, właściwość przechowywana, wąskie typy danych).

Nie ma żadnych zmian powodujących niezgodność podczas aktualizacji z 2024-05-01-preview do wersji stabilnej. Aby użyć nowej stabilnej wersji, zmień wersję interfejsu API i przetestuj kod.

Występują zmiany powodujące zakłócenia, jeśli uaktualnisz bezpośrednio z 2023-11-01. Wykonaj kroki opisane dla każdej nowszej wersji zapoznawczej, aby przeprowadzić migrację z 2023-11-01 do 2024-07-01programu .

Uaktualnianie do wersji 2024-05-01-preview

2024-05-01-preview dodaje indeksator dla Microsoft OneLake, wektorów binarnych i innych modeli osadzania.

W przypadku uaktualniania z 2024-03-01-preview programu umiejętność AzureOpenAIEmbedding teraz wymaga właściwości nazwy modelu i jego wymiarów.

  1. Wyszukaj w swojej bazie kodu odniesienia do AzureOpenAIEmbedding.

  2. Ustaw modelName na "text-embedding-ada-002" oraz dimensions na "1536".

Uaktualnianie do wersji 2024-03-01-preview

2024-03-01-preview Dodaje wąskie typy danych, kwantyzację skalarną i opcje magazynu wektorów.

W przypadku uaktualniania z 2023-10-01-preview, nie ma żadnych zmian powodujących niezgodność. Jednak istnieje jedna różnica w zachowaniu: w przypadku 2023-11-01 i nowszych wersji podglądu w vectorFilterMode domyślnie zmieniono filtr z postfiltru na filtr wstępny dla wyrażeń filtrów.

  1. Wyszukaj bazę kodu pod kątem vectorFilterMode odwołań.

  2. Jeśli właściwość jest jawnie ustawiona, nie jest wymagana żadna akcja. Jeśli opierasz się na wartości domyślnej, nowe domyślne zachowanie polega na filtrowaniu przed wykonaniem zapytania. Jeśli chcesz filtrować po kwerendzie, jawnie ustaw vectorFilterMode na postfilter, aby zachować stare zachowanie.

Uaktualnianie do wersji 2023-11-01

2023-11-01 jest wydaniem ogólnym. Poprzednie funkcje w wersji zapoznawczej są teraz ogólnie dostępne: ranker semantyczny i obsługa wektorów.

Nie ma żadnych zmian powodujących niezgodność z 2023-10-01-preview, ale istnieje wiele zmian powodujących niezgodność między 2023-07-01-preview a 2023-11-01. Aby uzyskać więcej informacji, zobacz Uaktualnianie z wersji 2023-07-01-preview.

Aby użyć nowej stabilnej wersji, zmień wersję interfejsu API i przetestuj kod.

Uaktualnianie do wersji 2023-10-01-preview

2023-10-01-preview była pierwszą wersją zapoznawczą, która dodała wbudowane segmentowanie danych i wektoryzację podczas indeksowania oraz wbudowaną wektoryzację zapytań. Obsługuje również indeksowanie wektorów i zapytania z poprzedniej wersji.

Jeśli uaktualniasz poprzednią wersję, w następnej sekcji przedstawiono kroki.

Uaktualnianie z wersji 2023-07-01-preview

Nie używaj tej wersji interfejsu API. Implementuje on składnię zapytania wektorowego, która jest niezgodna z dowolną nowszą wersją interfejsu API.

2023-07-01-preview jest teraz przestarzały, więc nie należy bazować nowego kodu na tej wersji ani nie należy uaktualniać do tej wersji w żadnych okolicznościach. W tej sekcji opisano ścieżkę migracji z 2023-07-01-preview do nowszej wersji interfejsu API.

Uaktualnianie portalu dla indeksów wektorów

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

  • Ścieżka migracji to od 2023-07-01-preview do 2024-05-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ć 2024-05-01-preview polecenia lub nowszego, aby wykonać zapytanie dotyczące indeksu.

Nie ma migracji portalu do uaktualniania składni zapytań wektorowych. Zobacz Uaktualnienia kodu , 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 sekcji uaktualniania kodu . Migracja portalu obsługuje tylko indeksy z jedną konfiguracją algorytmu wyszukiwania wektorowego. Tworzy domyślny profil, który mapuje do algorytmu wyszukiwania wektorowego 2023-07-01-preview. Indeksy z wieloma konfiguracjami wyszukiwania wektorowego wymagają migracji ręcznej.

Uaktualnianie kodu dla indeksów wektorów i zapytań

Obsługa wyszukiwania wektorowego została wprowadzona w sekcji Tworzenie lub aktualizowanie indeksu (2023-07-01-preview).

Uaktualnienie z 2023-07-01-preview do nowszej stabilnej lub zapoznawczej wersji wymaga:

  • Zmiana nazwy i restrukturyzacja konfiguracji wektora w indeksie
  • Ponowne zapisywanie zapytań wektorowych

Skorzystaj z instrukcji w tej sekcji, aby przeprowadzić migrację pól wektorów, konfiguracji i zapytań z programu 2023-07-01-preview.

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

  2. Zmodyfikuj konfigurację wyszukiwania wektorowego. 2023-11-01 i nowsze wersje przedstawiają koncepcję profilów wektorów , które łączą konfiguracje związane z wektorami pod jedną nazwą. Nowsze wersje również zmieniają 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 profiles, podając nazwę oraz 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"
      }
    ]
  }

  3. 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 grupować, ani używać analizatorów, normalizatoró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"
  }

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

  5. 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 postfilter, niezależnie od tego, jak ustawiono tryb filtrowania.

    Przed (2023-07-01-preview):

    {
    "search": "*", //Required by the API but ignored for ranking in vector-only queries
    "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": "*", //Required by the API but ignored for ranking in vector-only queries
  "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 2023-11-01 stabilnej wersji interfejsu API lub nowszych wersji interfejsu API w wersji zapoznawczej.

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 Wyszukiwanie AI platformy Azure, ale znajduje się w Azure Storage.

Zmiana łamiąca kompatybilność

Kod napisany w starszych wersjach interfejsu API przestaje działać w 2020-06-30 lub nowszych, jeśli kod zawiera następujące funkcjonalności:

  • Wszystkie Edm.Date literały (data składająca się z roku-miesiąca-dnia, 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 przewidująca wpis, która kończy częściowo wprowadzony tekst.
  • Typy złożone zapewniają natywną obsługę danych obiektów strukturalnych w indeksie wyszukiwania.
  • Tryby analizowania JsonLines są częścią indeksowania obiektów blob Azure i tworzą jeden dokument wyszukiwania dla każdej jednostki JSON oddzielonej nową linią.
  • Moduł wzbogacania AI zapewnia indeksowanie przy użyciu silników wzbogacających AI narzędzi Foundry Tools.

Zmiany powodujące niezgodność

Kod napisany w starszej wersji interfejsu API przestaje działać w wersji 2019-05-06 i nowszej, jeśli zawiera następującą funkcjonalność:

  1. Wpisz właściwość dla Azure Cosmos DB. W przypadku indeksatorów wykorzystujących Azure Cosmos DB dla NoSQL API jako źródło danych, zmień "type": "documentdb" na "type": "cosmosdb".

  2. 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.

  3. Parametry połączenia źródła danych nie są już zwracane w odpowiedzi. Od wersji 2019-05-06 oraz 2019-05-06-Preview nowszych, interfejs API źródła danych nie zwraca parametrów połączenia w odpowiedzi na każdą operację REST. W poprzednich wersjach API, dla źródeł danych utworzonych przy użyciu POST, Wyszukiwanie AI platformy Azure zwracał 201, po czym następowała odpowiedź OData zawierająca ciąg połączenia w postaci zwykłego tekstu.

  4. Technika rozpoznawania nazwanych 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.

Aktualizacja typów złożonych

Wersja 2019-05-06 interfejsu API dodała formalną obsługę typów złożonych. Jeśli Twój 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ą nowe oraz zmienione limity, na które 2019-05-06 należy zwrócić uwagę.

  • Limity głębokości pól podrzędnych i liczby kolekcji złożonych na indeks zostały obniżone. Jeśli utworzono indeksy, które przekraczają te limity przy użyciu wersji zapoznawczej interfejsu API, 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 Wyszukiwanie AI platformy Azure.

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

Jeśli Twój kod używa złożonych typów przy starszych wersjach zapoznawczych interfejsu API, to możesz używać formatu 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:

  1. Wykonaj żądanie GET, aby pobrać indeks. Jeśli jest już w nowym formacie, wszystko jest gotowe.

  2. 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.

  3. 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.

Uwaga

Nie można zarządzać indeksami utworzonymi przy użyciu starego formatu "płaskiego" z portalu Azure. Zaktualizuj indeksy z reprezentacji "płaskiej" do reprezentacji "drzewa" w dogodnym dla Ciebie momencie.

Uaktualnienia płaszczyzny sterowania

Dotyczy:2014-07-31-Preview , 2015-02-28i 2015-08-19

Żądanie listQueryKeys GET w starszych wersjach interfejsu API Search Management zostało wycofane. Zalecamy migrację do najnowszej stabilnej wersji interfejsu listQueryKeysAPI płaszczyzny sterowania, aby używać żądania POST.

  1. W istniejącym kodzie zmień api-version parametr na najnowszą wersję (2025-05-01).

  2. Zmień ramkę żądania z GET na :POST

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

  3. Jeśli używasz Azure SDK, zaleca się uaktualnienie do najnowszej wersji.

Następne kroki

Przejrzyj dokumentację referencyjną interfejsu API REST wyszukiwania. Jeśli wystąpią problemy, poproś nas o pomoc w witrynie Stack Overflow lub skontaktuj się z pomocą techniczną.

Dokumentacja interfejsu API REST usługi Wyszukiwania

  • Last updated on