Aktualisieren oder Neuerstellen eines Indexes in der Azure KI-Suche

  • Artikel

In diesem Artikel wird erläutert, wie Sie einen vorhandenen Index in Azure KI-Suche mit Schemaänderungen oder Inhaltsänderungen durch inkrementelle Indizierung aktualisieren. Es werden die Umstände erläutert, unter denen eine Neuerstellung erforderlich ist. Außerdem werden Empfehlungen bereitgestellt, wie die Auswirkungen von Neuerstellungen auf laufende Abfrageanforderungen auf ein Mindestmaß reduziert werden können.

Während der aktiven Entwicklung ist es üblich, Indizes abzulegen und neu zu erstellen, wenn Sie den Indexentwurf durchlaufen. Die meisten Entwickler arbeiten mit einem kleinen repräsentativen Beispiel ihrer Daten, um die Neuindizierung zu beschleunigen.

Für Schemaänderungen an Anwendungen, die sich bereits in der Produktion befindet, wird empfohlen, einen neuen Index zu erstellen und zu testen, der parallel zu einem vorhandenen Index ausgeführt wird. Verwenden Sie einen Indexalias, um den neuen Index auszutauschen, während Änderungen am Anwendungscode vermieden werden.

Aktualisieren von Inhalten

Die inkrementelle Indizierung und Synchronisierung eines Indexes mit Änderungen an Quelldaten ist für die meisten Suchanwendungen von grundlegender Bedeutung. In diesem Abschnitt wird der Workflow zum Aktualisieren von Feldinhalten in einem Suchindex erläutert.

  1. Verwenden Sie die gleichen Techniken zum Laden von Dokumenten: Documents - Index (REST) oder eine entsprechende API in den Azure SDKs. Weitere Informationen zu Indizierungstechniken finden Sie unter Laden von Dokumenten.

  2. Legen Sie den @search.action-Parameter fest, um den Effekt auf vorhandene Dokumente zu bestimmen:

    Aktion Auswirkung
    delete Entfernt das gesamte Dokument aus dem Index. Wenn Sie ein einzelnes Feld entfernen möchten, verwenden Sie stattdessen merge und legen das betreffende Feld auf NULL fest. Gelöschte Dokumente und Felder geben nicht sofort Speicherplatz im Index frei. Alle paar Minuten führt ein Hintergrundprozess den physischen Löschvorgang durch. Unabhängig davon, ob Sie das Portal oder eine API zum Zurückgeben von Indexstatistiken verwenden, müssen Sie eine kleine Verzögerung erwarten, bevor der Löschvorgang im Portal und über APIs wiedergegeben wird.
    merge Aktualisiert ein bereits vorhandenes Dokument und schlägt fehl, wenn das Dokument nicht gefunden werden kann. Merge ersetzt vorhandene Werte. Achten Sie deshalb darauf, nach Sammlungsfeldern zu suchen, die mehrere Werte enthalten, z. B. Felder vom Typ Collection(Edm.String). Wenn beispielsweise ein tags-Feld mit dem Wert ["budget"] beginnt und Sie eine Zusammenführung mit ["economy", "pool"] durchführen, lautet der Wert für das tags-Feld am Ende des Vorgangs ["economy", "pool"]. Der Wert lautet nicht etwa ["budget", "economy", "pool"].
    mergeOrUpload Verhält sich wie Zusammenführen, wenn das Dokument vorhanden ist, und wie Hochladen, wenn das Dokument neu ist. Dies ist die häufigste Aktion für inkrementelle Updates.
    upload Ähnelt einem „Upsert“, bei dem das Dokument eingefügt wird, wenn es neu ist, und aktualisiert oder ersetzt wird, wenn es bereits vorhanden ist. Wenn im Dokument Werte fehlen, die der Index benötigt, wird der Wert des Dokumentfelds auf NULL festgelegt.

  3. Veröffentlichen Sie das Update.

Abfragen werden weiterhin ausgeführt, aber wenn Sie vorhandene Felder aktualisieren oder entfernen, können Sie gemischte Ergebnisse und eine höhere Inzidenz der Drosselung erwarten.

Tipps für die inkrementelle Indizierung

  • Indexer automatisieren die inkrementelle Indizierung. Wenn Sie einen Indexer verwenden können und die Datenquelle die Änderungsnachverfolgung unterstützt, können Sie den Indexer für einen wiederkehrenden Zeitplan ausführen, um durchsuchbare Inhalte hinzuzufügen, zu aktualisieren oder zu überschreiben, damit sie mit Ihren externen Daten synchronisiert wird.

  • Wenn Sie Indexaufrufe direkt über die Push-API ausführen, verwenden Sie mergeOrUpload als Suchaktion.

  • Die Nutzlast muss die Schlüssel oder Bezeichner jedes Dokuments enthalten, das Sie hinzufügen, aktualisieren oder löschen möchten.

  • Wenn Ihr Index Vektorfelder enthält und Sie die Eigenschaft stored auf „false“ festlegen, stellen Sie sicher, dass Sie den Vektor in der teilweisen Dokumentaktualisierung bereitstellen, auch wenn der Wert unverändert ist. Ein Nebeneffekt der Einstellung von stored auf „false“ besteht darin, dass Vektoren bei einem Neuindizierungsvorgang abgelegt werden. Durch die Bereitstellung des Vektors in der Dokumentnutzlast wird dies verhindert.

  • Um den Inhalt einfacher Felder und Unterfelder in komplexen Typen zu aktualisieren, listen Sie nur die Felder auf, die Sie ändern möchten. Wenn Sie beispielsweise nur ein Beschreibungsfeld aktualisieren müssen, sollte die Nutzlast aus dem Dokumentschlüssel und der geänderten Beschreibung bestehen. Wenn andere Felder weggelassen werden, bleiben ihre vorhandenen Werte erhalten.

  • Um Inlineänderungen in einer Zeichenfolgensammlung zusammenzuführen, geben Sie den gesamten Wert an. Erinnern Sie sich an das tags-Feldbeispiel aus dem vorherigen Abschnitt. Bei neuen Werten werden die alten Werte für ein gesamtes Feld überschrieben, und es gibt keine Zusammenführung innerhalb des Inhalts eines Felds.

Hier ist ein REST-API-Beispiel, in dem diese Tipps veranschaulicht werden:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Ändern Sie ein Indexschema

Das Indexschema definiert die physischen Datenstrukturen, die im Suchdienst erstellt wurden, sodass es nicht viele Schemaänderungen gibt, die Sie vornehmen können, ohne dass eine vollständige Neuerstellung entsteht. In der folgenden Liste werden die Schemaänderungen aufgelistet, die nahtlos in einen vorhandenen Index eingeführt werden können. Im Allgemeinen enthält die Liste neue Felder und Funktionen, die während der Abfrageausführung verwendet werden.

  • Hinzufügen eines neuen Felds
  • Festlegen des retrievable-Attributs für ein vorhandenes Feld
  • Aktualisieren von searchAnalyzer auf einem Feld mit einem vorhandenen indexAnalyzer
  • Hinzufügen einer neuen Analysedefinition in einem Index (die auf neue Felder angewendet werden kann)
  • Hinzufügen, Aktualisieren oder Löschen von Bewertungsprofilen
  • Hinzufügen, Aktualisieren oder Löschen von CORS-Einstellungen
  • Hinzufügen, Aktualisieren oder Löschen von synonymMaps
  • Hinzufügen, Aktualisieren oder Löschen von semantischen Konfigurationen

Die Reihenfolge der Vorgänge lautet:

  1. Dient zum Abrufen der Indexdefinition.

  2. Überarbeiten Sie das Schema mit Aktualisierungen aus der vorherigen Liste.

  3. Aktualisieren des Indexschemas für den Suchdienst.

  4. Aktualisieren des Indexinhalts, damit er Ihrem überarbeiteten Schema entspricht, wenn Sie ein neues Feld hinzugefügt haben. Bei allen anderen Änderungen wird der bestehende indizierte Inhalt unverändert verwendet.

Wenn Sie ein Indexschema so aktualisieren, dass ein neues Feld eingeschlossen ist, erhalten die bereits im Index vorhandenen Dokumente für dieses Feld den Wert NULL. Beim nächsten Indizierungsauftrag werden die von Azure KI-Suche hinzugefügten NULL-Werte durch externe Quelldaten ersetzt.

Während der Aktualisierungen sollten keine Abfrageunterbrechungen auftreten, aber die Abfrageergebnisse variieren, wenn die Aktualisierungen wirksam werden.

Löschen und Neuerstellen eines Indexes

Einige Änderungen erfordern eine Indexlöschung und -neuerstellung, bei der ein aktueller Index durch einen neuen ersetzt wird.

Aktion Beschreibung
Löschen eines Felds Um alle Spuren eines Felds physisch entfernen zu können, müssen Sie den Index neu erstellen. Wenn eine sofortige Neuerstellung nicht praktikabel ist, können Sie den Anwendungscode so ändern, dass der Zugriff von einem veralteten Feld weggeleitet wird, oder die searchFields verwenden und Abfrageparameter auswählen, um auszuwählen, welche Felder durchsucht und zurückgegeben werden. Die Felddefinition und die Inhalte bleiben physisch bis zur nächsten Neuerstellung im Index, wenn Sie ein Schema verwenden, bei dem das betreffende Feld ausgelassen wird.
Ändern einer Felddefinition Für Überarbeitungen eines Feldnamens, Datentyps oder spezifischer Indexattribute (durchsuchbar, filterbar, sortierbar, facettenreich) ist eine vollständige Neuerstellung erforderlich.
Zuweisen eines Analysetools zu einem Feld Analyzers werden in einem Index definiert, Feldern zugewiesen und dann während der Indizierung aufgerufen, um zu informieren, wie Token erstellt werden. Sie können einem Index jederzeit eine neue Analysetooldefinition hinzufügen, aber Sie können ein Analysetool nur zuweisen, wenn das Feld erstellt wird. Dies gilt sowohl für das Analysetool als auch die indexAnalyzer-Eigenschaften. Die searchAnalyzer-Eigenschaft ist eine Ausnahme (Sie können diese Eigenschaft einem vorhandenen Feld zuweisen).
Aktualisieren oder Löschen einer Analysetooldefinition in einem Index Sie können eine bestehende Analysetoolkonfiguration (Analysetool, Tokenizer, Tokenfilter oder Zeichenfilter) im Index nicht löschen oder ändern, es sei denn, Sie erstellen den gesamten Index neu.
Hinzufügen eines Felds zu einer Vorschlagsfunktion Wenn ein Feld bereits vorhanden ist, und Sie es einer Vorschlagsfunktion hinzufügen möchten, müssen Sie den Index neu erstellen.
Wechseln zwischen Ebenen Direkte Upgrades werden nicht unterstützt. Wenn Sie mehr Kapazität benötigen, erstellen Sie einen neuen Dienst erstellen und Ihre Indizes von Grund auf neu. Um diesen Prozess zu automatisieren, können Sie den index-backup-restore-Beispielcode in diesem Azure KI Search .NET-Beispielrepository verwenden. Diese App sichert Ihren Index in einer Reihe von JSON-Dateien und erstellt ihn dann in einem Suchdienst, den Sie angeben, neu.

Die Reihenfolge der Vorgänge lautet:

  1. Rufen Sie eine Indexdefinition für den Fall ab, dass Sie diese in Zukunft als Referenz benötigen, oder um sie als Grundlage für eine neue Version zu verwenden.

  2. Erwägen Sie die Verwendung einer Sicherungs- und Wiederherstellungslösung, um eine Kopie von Indexinhalten beizubehalten. Es gibt Lösungen in C# und in Python. Wir empfehlen die Python-Version, da sie aktueller ist.

    Wenn Sie über ausreichend Kapazität für Ihren Suchdienst verfügen, behalten Sie den vorhandenen Index beim Erstellen und Testen des neuen Index bei.

  3. Legen Sie den vorhandenen Index ab. Abfragen, die sich an diesen Index richten, werden sofort gelöscht. Denken Sie daran, dass das Löschen eines Indexes nicht rückgängig gemacht werden kann. Der physische Speicher für die Feldsammlung und andere Konstrukte wird zerstört.

  4. Veröffentlichen Sie einen überarbeiteten Index, wobei der Text der Anforderung geänderte oder modifizierte Felddefinitionen und -konfigurationen enthält.

  5. Laden Sie den Index mit Dokumenten aus einer externen Quelle. Dokumente werden mithilfe der Felddefinitionen und Konfigurationen des neuen Schemas indiziert.

Wenn Sie den Index erstellen, wird physischer Speicher für jedes Feld im Indexschema zugewiesen, wobei für jedes durchsuchbare Feld ein invertierter Index und für jedes Vektorfeld ein Vektorindex erstellt wird. Nicht durchsuchbare Felder können in Filtern oder Ausdrücken verwendet werden, besitzen aber keine invertierten Indizes und können nicht mit der Volltext- oder Fuzzysuche durchsucht werden. Bei einer Indexneuerstellung werden diese invertierten Indizes und Vektorindizes gelöscht und basierend auf dem von Ihnen angegebenen Indexschema neu erstellt.

Ausgleichen von Workloads

Die Indizierung erfolgt nicht im Hintergrund, aber der Suchdienst gleicht alle Indizierungsaufträge mit laufenden Abfragen aus. Während der Indizierung können Sie Abfrageanforderungen im Portal überwachen, um sicherzustellen, dass die Abfragen innerhalb eines angemessenen Zeitraums abgeschlossen werden.

Wenn die Indizierung von Workloads zu nicht akzeptablen Abfragewartezeiten führt, führen Sie eine Leistungsanalyse durch, und überprüfen Sie diese Leistungstipps auf mögliche Entschärfungen.

Nach Updates suchen

Sie können mit der Abfrage eines Indexes beginnen, sobald das erste Dokument geladen wurde. Wenn Sie die ID eines Dokuments kennen, gibt die REST-API zur Dokumentsuche das jeweilige Dokument zurück. Für umfangreichere Testvorgänge sollten Sie warten, bis der Index vollständig geladen wurde, und anschließend den erwarteten Kontext anhand von Abfragen überprüfen.

Sie können den Suchexplorer oder einen REST-Client verwenden, um nach aktualisierten Inhalten zu suchen.

Wenn Sie ein Feld hinzugefügt oder umbenannt haben, verwenden Sie $select, um dieses Feld zurückzugeben: search=*&$select=document-id,my-new-field,some-old-field&$count=true.

Das Azure-Portal stellt die Indexgröße und die Vektorindexgröße bereit. Sie können diese Werte nach dem Aktualisieren eines Indexes überprüfen, aber denken Sie daran, eine kleine Verzögerung zu erwarten, da der Dienst die Änderung verarbeitet und die Aktualisierungsraten des Portals berücksichtigt, was einige Minuten dauern kann.

Löschen verwaister Dokumente

Azure AI Search unterstützt Operationen auf Dokumentenebene, so dass Sie ein bestimmtes Dokument isoliert nachschlagen, aktualisieren und löschen können. Das folgende Beispiel zeigt den Löschvorgang eines Dokuments.

Durch das Löschen eines Dokuments wird nicht sofort Speicherplatz im Index freigegeben. Alle paar Minuten führt ein Hintergrundprozess den physischen Löschvorgang durch. Unabhängig davon, ob Sie das Portal oder eine API verwenden, um Indexstatistiken zurückzugeben, müssen Sie eine kleine Verzögerung erwarten, bevor der Löschvorgang im Portal und in den API-Metriken widergespiegelt wird.

  1. Identifizieren Sie, welches Feld der Dokumentschlüssel ist. Im Portal können Sie die Felder der einzelnen Indizes anzeigen. Dokumentschlüssel sind Zeichenfolgenfelder und mit einem Schlüsselsymbol gekennzeichnet, damit sie leichter zu erkennen sind.

  2. Überprüfen Sie die Werte des Dokumentschlüsselfelds: search=*&$select=HotelId. Eine einfache Zeichenfolge ist unproblematisch, aber wenn der Index ein Base-64-codiertes Feld verwendet oder wenn Suchdokumente über eine parsingMode-Einstellung generiert wurden, arbeiten Sie möglicherweise mit Werten, mit denen Sie nicht vertraut sind.

  3. Suchen Sie das Dokument, um den Wert der Dokument-ID zu verifizieren und seinen Inhalt zu überprüfen, bevor Sie es löschen. Geben Sie den Schlüssel oder die Dokument-ID in der Anforderung an. Die folgenden Beispiele zeigen eine einfache Zeichenfolge für den Beispielindex „Hotels“ und eine Base-64-codierte Zeichenfolge für den Schlüssel „metadata_storage_path“ des Index „cog-search-demo“.

    GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01

    GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01

  4. Löschen Sie das Dokument mithilfe eines Löschvorgangs @search.action, um es aus dem Suchindex zu entfernen.

    POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

Weitere Informationen