Upgrade auf die neueste REST-API in Azure AI Search
Verwenden Sie diesen Artikel zum Migrieren von Aufrufen auf Datenebene zu neueren Versionen der Search-REST-API.
2023-11-01 ist die aktuellste stabile Version. Semantische Rangzuweisung und die Unterstützung für Vektorindizierung und Abfragen sind in dieser Version allgemein verfügbar.
2023-10-01-preview ist die aktuellste Vorschauversion. Zu den Previewfunktionen gehören integrierte Abfragevektorisierung, integrierten Datenabschnitts und Vektorisierung während der Indizierung (verwendet die TextTeilung-Fähigkeiten und die Azure OpenAI Embedding-Fähigkeit).
2023-07-01-preview war die erste REST-API für die Vektorunterstützung. Sie ist jetzt veraltet und Sie sollten sofort zu 2023-11-01- oder 2023-10-01-preview migrieren.
Hinweis
REST-API-Referenzdokumente sind jetzt versioniert. Um den richtigen Inhalt zu erhalten, öffnen Sie eine Referenzseite, und filtern Sie dann nach Version, indem Sie den Selektor verwenden, der sich über dem Inhaltsverzeichnis befindet.
Upgradezeitpunkt
Azure KI-Suche unterbricht die Abwärtskompatibilität als letztes Mittel. Das Upgrade ist erforderlich, wenn:
Ihr Code verweist auf eine ausgemusterte oder veraltete API-Version und ist von mindestens einem Breaking Change betroffen, der mit dieser Version eingeführt wurde. API-Versionen, die in diese Kategorie fallen, umfassen 2023-07-10-preview für Vektoren und 2019-05-06.
Der Code erzeugt Fehler, wenn nicht erkannte Eigenschaften in einer API-Antwort zurückgegeben werden. Als eine bewährte Methode sollte Ihre Anwendung Eigenschaften ignorieren, die sie nicht versteht.
Ihr Code behält API-Anforderungen bei und versucht, sie erneut an die neue API-Version zu senden. Dies kann beispielsweise vorkommen, wenn Ihre Anwendung Fortsetzungstoken beibehält, die von der Search-API zurückgegeben wurden (weitere Informationen finden Sie, indem Sie in der Search-API-Referenz nach
@search.nextPageParameters
suchen).
Breaking Change für Clientcode, der Verbindungsinformationen liest
Gilt ab 29. März 2024 und für alle unterstützten REST-APIs:
Von GET Skillset, GET Index und GET Indexer werden in einer Antwort keine Schlüssel oder Verbindungseigenschaften mehr zurückgegeben. Dies ist ein Breaking Change, wenn Sie über Downstreamcode verfügen, der Schlüssel oder Verbindungen (vertrauliche Daten) aus einer GET-Antwort liest.
Wenn Sie Administrator- oder Abfrage-API-Schlüssel für Ihren Suchdienst abrufen müssen, verwenden Sie die REST-APIs für die Verwaltung.
Wenn Sie Verbindungszeichenfolgen einer anderen Azure-Ressource (beispielsweise Azure Storage oder Azure Cosmos DB) abrufen müssen, verwenden Sie die APIs der entsprechenden Ressource sowie veröffentlichte Anleitungen, um die Informationen abzurufen.
Upgrade auf 2023-10-01-preview
Dieser Abschnitt erläutert den Migrationspfad von 2023-07-01-preview zu 2023-10-01-preview. Sie sollten zu 2023-10-01-preview migrieren, wenn Sie Vektorfeatures verwenden möchten, die sich noch in der öffentlichen Vorschau befinden. Wenn Sie die Previewfunktionen nicht benötigen, empfehlen wir ein Upgrade auf den stabilen Release 2023-11-01.
Die Previewfunktionen umfassen:
Da diese Features in früheren API-Versionen nicht vorhanden waren, gibt es keinen Migrationspfad. Informationen zum Hinzufügen dieser Features zu Ihrem Code finden Sie unter Codebeispiele und exemplarische Vorgehensweisen.
Im Gegensatz dazu haben sich die Vektorfelddefinitionen, die Konfiguration des Vektorsuchalgorithmus und die Vektorabfragesyntax geändert, die in 2023-07-01-preview eingeführt wurde. Die Syntax von 2023-10-01-preview für Vektorfelder, Algorithmen und Vektorabfragen ist identisch mit der Syntax von 2023-11-01. Die Migrationsschritte für diese Vektorkonstrukte werden im Upgrade auf 2023-11-01 erläutert.
Portalupgrade für Vektorindizes
Das Azure-Portal unterstützt einen Einklick-Upgradepfad für Indizes von 2023-07-01-preview. Das Portal erkennt Vektorfelder in 2023-07-01-preview und stellt eine Schaltfläche Migrieren bereit.
- Der Migrationspfad ist von 2023-07-01-preview nach 2023-10-01-preview.
- Aktualisierungen sind auf Vektorfelddefinitionen und Konfigurationen für den Vektorsuchalgorithmus beschränkt.
- Updates sind unidirektional. Sie können das Upgrade nicht rückgängig machen. Nachdem für den Index ein Upgrade durchgeführt wurde, müssen Sie 2023-10-01-preview oder höher verwenden, um den Index abzufragen.
Es gibt keine Portalmigration für das Upgraden der Vektorabfragesyntax. Informationen zu Änderungen der Abfragesyntax finden Sie unter Upgrade auf 2023-11-01.
Bevor Sie Migrieren auswählen, wählen Sie JSON bearbeiten aus, um zuerst das aktualisierte Schema zu überprüfen. Sie sollten ein Schema finden, das mit den in Upgrade auf 2023-11-01 beschriebenen Änderungen übereinstimmt. Die Portalmigration behandelt nur Indizes mit einer Konfiguration für den Vektorsuchalgorithmus. Es wird ein Standardprofil erstellt, das dem Vektorsuchalgorithmus 2023-07-01-01-preview entspricht. Indizes mit mehreren Vektorsuchkonfigurationen erfordern eine manuelle Migration.
Upgrade auf 2023-11-01
Diese Version hat Breaking Changes und Verhaltensunterschiede für die Unterstützung der semantischen Rangfolge und der Vektorsuche.
Die semantische Rangfolge ist in 2023-11-01 allgemein verfügbar. Sie verwendet die
queryLanguage
-Eigenschaft nicht mehr. Außerdem ist einesemanticConfiguration
-Definition erforderlich. EinesemanticConfiguration
ersetztsearchFields
in früheren Versionen. Schritte finden Sie unter Migrieren von der Vorschauversion.Die Unterstützung der Vektorsuche wurde in Erstellen oder Aktualisieren des Indexes (2023-07-01-preview) eingeführt. Für das Upgrade von 2023-07-01-preview ist eine Umbenennung und Umstrukturierung der Vektorkonfiguration im Index erforderlich. Außerdem ist es erforderlich, Ihre Vektorabfragen neu zu schreiben. Verwenden Sie die Anweisungen in diesem Abschnitt zum Migrieren von Vektorfeldern, Konfigurationen und Abfragen.
Wenn Sie ein Upgrade von 2023-10-01-preview auf 2023-11-01 durchführen, gibt es keine Breaking Changes, aber es gibt einen Verhaltensunterschied: Der
vectorFilterMode
-Standardwert wurde von Postfilter auf Prefilter für Filterausdrücke geändert. Wenn Ihr 2023-10-01-preview-CodevectorFilterMode
nicht explizit festlegt, stellen Sie sicher, dass Sie das neue Standardverhalten verstehen odervectorFilterMode
explizit auf Postfilter festlegen, um das alte Verhalten beizubehalten.
Hier sind die Schritte für die Migration von 2023-07-01-preview auf 2023-11-01:
Rufen Sie Index abrufen auf, um die vorhandene Definition abzurufen.
Ändern Sie die Vektorsuchkonfiguration. 2023-11-01 führt das Konzept von Vektorprofilen ein, die vektorbezogene Konfigurationen unter einem Namen bündeln. Sie benennt auch
algorithmConfigurations
inalgorithms
um.Benennen Sie
algorithmConfigurations
inalgorithms
um. Dies ist nur eine Umbenennung des Arrays. Die Inhalte sind abwärtskompatibel. Dies bedeutet, dass Ihre vorhandenen HNSW-Konfigurationsparameter verwendet werden können.Fügen Sie
profiles
hinzu, und geben Sie einen Namen und eine Algorithmuskonfiguration für jeden einzelnen an.
Vor der Migration (2023-07-01-preview):
"vectorSearch": { "algorithmConfigurations": [ { "name": "myHnswConfig", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ]}
Nach der Migration (2023-11-01):
"vectorSearch": { "algorithms": [ { "name": "myHnswConfig", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ], "profiles": [ { "name": "myHnswProfile", "algorithm": "myHnswConfig" } ] }
Ändern Sie Vektorfelddefinitionen, indem Sie
vectorSearchConfiguration
durchvectorSearchProfile
ersetzen. Stellen Sie sicher, dass der Profilname in eine neue Vektorprofildefinition und nicht in den Konfigurationsnamen des Algorithmus aufgelöst wird. Andere Vektorfeldeigenschaften bleiben unverändert. Sie können z. B. weder filterbar, sortierbar oder facettierbar sein und auch keine Analysetools oder Normalisierer oder Synonymzuordnungen verwenden.Vor (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" }
Nach (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" }
Rufen Sie Erstellen oder Aktualisieren des Indexes auf, um die Änderungen zu veröffentlichen.
Ändern Sie Search-POST, um die Abfragesyntax zu ändern. Diese API-Änderung ermöglicht die Unterstützung für polymorphe Vektorabfragetypen.
- Benennen Sie
vectors
invectorQueries
um. - Fügen Sie für jede Vektorabfrage
kind
hinzu, und legen Sie den Wert aufvector
fest. - Benennen Sie für jede Vektorabfrage
value
invector
um. - Fügen Sie optional
vectorFilterMode
hinzu, wenn Sie Filterausdrücke verwenden. Der Standardwert ist Prefilter für Indizes, die nach 2023-10-01 erstellt wurden. Indizes, die vor diesem Datum erstellt wurden, unterstützen nur Postfilter, unabhängig davon, wie Sie den Filtermodus festlegen.
Vor (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" }
Nach (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" }
- Benennen Sie
Diese Schritte schließen die Migration zu 2023-11-01 API-Version ab.
Upgrade auf 2020-06-30
In dieser Version gibt es einen Breaking Change und mehrere Abweichungen beim Verhalten. Allgemein verfügbare Features umfassen:
- Wissensspeicher, dauerhafte Speicherung von angereicherten Inhalten, die durch Skillsets für die Downstreamanalyse und die Verarbeitung durch andere Anwendungen erstellt wurden. Ein Wissensspeicher wird über Azure KI-Suche REST-APIs erstellt, befindet sich aber in Azure Storage.
Wichtige Änderung
Code, der für frühere API-Versionen geschrieben wurde, wird ab 2020-06-30
und höher unterbrochen, wenn der Code folgende Funktionalität enthält:
- Ein
Edm.Date
-Literal (ein Datum bestehend aus Jahr-Monat-Tag, z. B.2020-12-12
) in Filterausdrücken muss demEdm.DateTimeOffset
-Format folgen:2020-12-12T00:00:00Z
. Diese Änderung war erforderlich, um fehlerhafte oder unerwartete Abfrageergebnisse aufgrund von Zeitzonenunterschieden zu behandeln.
Verhaltensänderungen
Der BM25-Ähnlichkeitsalgorithmus für die Rangfolge ersetzt den bisherigen Rangfolgealgorithmus durch neuere Technologie. Dienste, die nach 2019 erstellt wurden, verwenden diesen Algorithmus automatisch. Für ältere Dienste müssen Sie Parameter festlegen, um den neuen Algorithmus zu verwenden.
Die Behandlung von Nullwerten in sortierten Ergebnissen hat sich in dieser Version geändert, Nullwerte werden bei
asc
-Sortierung zuerst und beidesc
-Sortierung zuletzt angezeigt. Wenn Sie Code zur Behandlung von Nullwerten geschrieben haben, seien Sie sich dieser Änderung bewusst.
Upgrade auf 2019-05-06
Zu den Features, die in dieser API-Version allgemein verfügbar wurden, gehören:
- AutoVervollständigen ist eine Funktion zur Textvervollständigung, mit der ein teilweise eingegebener Begriff vervollständigt wird.
- Komplexe Typen bieten native Unterstützung für strukturierte Objektdaten in einem Suchindex.
- Der Analysemodus JsonLines ist Teil der Azure-Blobindizierung. Dabei wird ein Suchdokument pro JSON-Entität erstellt, die durch eine neue Zeile getrennt ist.
- Die KI-Anreicherung ermöglicht eine Indizierung, bei der die Engines zur KI-Anreicherung von Azure AI Services genutzt werden.
Wichtige Änderungen
Code, der für eine frühere API-Version geschrieben wurde, wird ab 2019-05-06
und höher unterbrochen, wenn er folgende Funktionalität enthält:
Type-Eigenschaft für Azure Cosmos DB. Für Indexer, die auf eine Azure Cosmos DB for NoSQL-API-Datenquelle abzielen, ändern Sie
"type": "documentdb"
in"type": "cosmosdb"
.Wenn die Indizierungsfehlerbehandlung Verweise auf die
status
-Eigenschaft enthält, sollten Sie sie entfernen. Wir haben den Status aus der Fehlerantwort entfernt, da er keine nützlichen Informationen bereitstellte.Verbindungszeichenfolgen für Datenquellen werden in der Antwort nicht mehr zurückgegeben. Ab den API-Versionen
2019-05-06
und2019-05-06-Preview
gibt die Datenquellen-API als Antwort auf einen REST-Vorgang keine Verbindungszeichenfolgen mehr zurück. In früheren API-Versionen wurde in Azure AI Search für mithilfe der POST-Methode erstellte Datenquellen 201 zurückgegeben, gefolgt von der OData-Antwort, welche die Verbindungszeichenfolge im Textformat enthielt.Der kognitive Skill „Erkennung benannter Entitäten“ wurde eingestellt. Wenn Sie den Skill Erkennung benannter Entitäten im Code aufgerufen haben, schlägt der Aufruf fehl. Die Ersatzfunktion ist Skill „Entitätserkennung“ (V3). Führen Sie unter Berücksichtigung der Empfehlungen unter Veraltete Skills für die kognitive Suche eine Migration zu einem unterstützten Skill durch.
Aktualisieren von komplexen Typen
In API-Version 2019-05-06
wurde formale Unterstützung für komplexe Typen hinzugefügt. Wenn in Ihrem Code frühere Empfehlungen für Äquivalenz zu komplexen Typen in 2017-11-11-Preview oder 2016-09-01-Preview implementiert wurden, gelten ab Version 2019-05-06
einige neue und geänderte Grenzwerte, die Sie berücksichtigen müssen:
Die Grenzwerte für die Tiefe der Unterfelder und die Anzahl der komplexen Sammlungen pro Index wurden abgesenkt. Wenn Sie mit den API-Vorschauversionen Indizes erstellt haben, die diese Grenzwerte überschreiten, treten beim Aktualisieren oder Neuerstellen der Indizes mit API-Version
2019-05-06
Fehler auf. Wenn Sie sich in dieser Situation befinden, müssen Sie Ihr Schema umgestalten, damit es in die neuen Grenzwerte passt, und dann Ihren Index neu erstellen.Ab API-Version
2019-05-06
gilt ein neuer Grenzwert für die Anzahl der Elemente von komplexen Sammlungen pro Dokument. Wenn Sie mit den API-Vorschauversionen Indizes mit Dokumenten erstellt haben, die diese Grenzwerte überschreiten, treten beim Neuindizieren dieser Daten mit API-Version2019-05-06
Fehler auf. Wenn Sie sich in dieser Situation befinden, müssen Sie die Anzahl der Elemente von komplexen Sammlungen pro Dokument reduzieren, bevor Sie die Daten neu indizieren.
Weitere Informationen finden Sie unter Grenzwerte für den Azure AI Search-Dienst.
Aktualisieren einer älteren Struktur mit komplexen Typen
Wenn Ihr Code komplexe Typen mit einer der älteren API-Vorschauversionen verwendet, verwenden Sie möglicherweise ein Indexdefinitionsformat, das wie folgt aussieht:
{
"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" }
]
}
In API-Version 2017-11-11-Preview
wurde ein neueres strukturähnliches Format zum Definieren von Indexfeldern eingeführt. In dem neuen Format enthält jedes komplexe Feld eine Feldsammlung, in der die Unterfelder definiert sind. In API-Version 2019-05-06 wird ausschließlich dieses neue Format verwendet, sodass beim Erstellen oder Aktualisieren eines Index mit dem alten Format Fehler auftreten. Wenn Sie Indizes mit dem alten Format erstellt haben, müssen Sie diese mithilfe der API-Version 2017-11-11-Preview
in das neue Format ändern, bevor sie mit der API-Version 2019-05-06 verwaltet werden können.
Mit den folgenden Schritten können Sie flache Indizes mithilfe der API-Version 2017-11-11-Preview
in das neue Format ändern:
Führen Sie eine GET-Anforderung aus, um den Index abzurufen. Wenn dieser bereits im neuen Format vorliegt, ist kein weiterer Schritt erforderlich.
Wandeln Sie den Index vom flachen Format in das neue Format um. Sie müssen für diese Aufgabe Code schreiben, da zum Zeitpunkt der Erstellung dieses Artikels kein Beispielcode vorhanden ist.
Führen Sie eine PUT-Anforderung aus, um den Index auf das neue Format zu aktualisieren. Vermeiden Sie das Ändern anderer Indexdetails (z. B. die Suchbarkeit/Filterbarkeit von Feldern), da Änderungen, die den physischen Ausdruck des vorhandenen Index beeinflussen, über die Update-Index-API nicht zulässig sind.
Hinweis
Indizes, die mit dem alten „flachen“ Format erstellt wurden, können über das Azure-Portal nicht verwaltet werden. Ändern Sie Ihre Indizes schnellstmöglich von der „flachen“ Darstellung in die Darstellung in „Strukturform“.
Nächste Schritte
Sehen Sie sich die Referenzdokumentation für die Search-REST-API an. Wenn Probleme auftreten, können Sie sich über Stack Overflow an uns wenden oder den Support kontaktieren.