Aktivieren Sie die Zwischenspeicherung für inkrementelle Anreicherung in Azure AI Search

Artikel
12/10/2024

Wichtig

Dieses Feature befindet sich in der öffentlichen Vorschau und unterliegt den zusätzlichen Nutzungsbedingungen. Dieses Feature wird von Vorschau-REST-APIs nicht unterstützt.

In diesem Artikel wird erklärt, wie Sie eine Zwischenspeicherung zu einer Anreicherungspipeline hinzufügen, sodass Sie Schritte zur Downstreamanreicherung ändern können, ohne jedes Mal eine komplette Neuerstellung durchführen zu müssen. Standardmäßig ist ein Skillset zustandslos, und eine Änderung eines beliebigen Teils seiner Komposition erfordert eine vollständige erneute Ausführung des Indexers. Mit einem Anreicherungscache kann der Indexer auf der Grundlage der in den Skillset- oder Indexer-Definitionen festgestellten Änderungen bestimmen, welche Teile des Dokumentenbaums aktualisiert werden müssen. Die vorhandene verarbeitete Ausgabe wird nach Möglichkeit beibehalten und wiederverwendet.

Zwischengespeicherte Inhalte werden mithilfe der von Ihnen bereitgestellten Kontoinformationen in Azure Storage platziert. Der Container namens ms-az-search-indexercache-<alpha-numerc-string> wird erstellt, wenn Sie den Indexer ausführen. Er sollte als eine interne Komponente angesehen werden, die von Ihrem Suchdienst verwaltet wird und nicht geändert werden darf.

Voraussetzungen

Azure Storage zum Speichern zwischengespeicherter Anreicherungen. Das Speicherkonto muss vom Typ Universell v2 sein.
Gilt nur für die Blob-Indizierung: Wenn Sie eine synchronisierte Löschung von Dokumenten aus dem Cache und dem Index benötigen, wenn Blobs aus Ihrer Datenquelle gelöscht werden, aktivieren Sie eine Löschrichtlinie im Indexer. Ohne diese Richtlinie wird das Löschen von Dokumenten aus dem Cache nicht unterstützt.

Sie sollten mit der Einrichtung von Indexern vertraut sein. Beginnen Sie mit der Indexerübersicht, und fahren Sie dann mit Skillsets fort, um mehr über Anreicherungspipelines zu erfahren. Weitere Hintergrundinformationen zu Schlüsselkonzepten finden Sie unter Inkrementelle Anreicherung.

Achtung

Wenn Sie den SharePoint Online-Indexer (Vorschau) verwenden, sollten Sie die inkrementelle Anreicherung vermeiden. Unter bestimmten Umständen wird der Cache ungültig, so dass ein Reset des Indexers und ein Lauf erforderlich sind, wenn Sie ihn neu laden wollen.

Für neue Indexer aktivieren

Sie können das Azure-Portal, Vorschau-APIs oder Beta-Azure-SDKs verwenden, um einen Anreicherungscache für einen Indexer zu aktivieren.

Azure portal
REST

Wählen Sie auf der linken Seite Indexer und anschließend Indexer hinzufügen aus.
Geben Sie einen Indexernamen und einen vorhandenen Index, eine Datenquelle und ein Skillset an.
Aktivieren Sie das inkrementelle Zwischenspeichern, und legen Sie das Azure Storage-Konto fest.

Fügen Sie bei neuen Indexern die Eigenschaft „cache“ in den Nutzdaten der Indexerdefinition hinzu, wenn Sie „Indexer erstellen oder aktualisieren“ aufrufen.

Sie können API-Vorschauversionen ab 2021-04-30-preview verwenden. Wir empfehlen die neueste Vorschauversion für Indexer erstellen oder aktualisieren (2024-05-01-preview).

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

Für vorhandene Indexer aktivieren

Verwenden Sie für vorhandene Indexer, die bereits über ein Skillset verfügen, die folgenden Schritte, um die Zwischenspeicherung hinzuzufügen. Setzen Sie den Indexer einmalig vollständig zurück, und führen Sie den Indexer erneut aus, um den Cache zu laden.

Schritt 1: Abrufen der Indexer-Definition

Beginnen Sie mit einem gültigen, Arbeitsindexer, der über diese Komponenten verfügt: Datenquelle, Skillset, Index. Senden Sie mit einem API-Client eine GET Indexer-Anforderung, um den Indexer abzurufen. Wenn Sie die Vorschauversion der API verwenden, um den Indexer zu erhalten, wird den Definitionen automatisch eine „cache“-Eigenschaft hinzugefügt, die auf NULL festgelegt ist.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Schritt 2: Festlegen der Cacheeigenschaft

Ändern Sie in der Indexdefinition „cache“, um die folgenden erforderlichen und optionalen Eigenschaften einzuschließen:

(Erforderlich) storageConnectionString muss auf eine Azure Storage-Verbindungszeichenfolge festgelegt werden.
(Optional) Die boolesche Eigenschaft enableReprocessing (standardmäßig true) ist optional und gibt an, dass die inkrementelle Anreicherung aktiviert ist. Legen Sie die Eigenschaft auf false fest, wenn Sie die inkrementelle Verarbeitung anhalten möchten, während andere ressourcenintensive Vorgänge, wie z. B. das Indizieren neuer Dokumente, ausgeführt werden, und setzen Sie die später wieder auf true zurück.

POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Schritt 3: Zurücksetzen des Indexers

Indexer zurücksetzen ist beim Einrichten der inkrementellen Anreicherung für vorhandene Indexer erforderlich, um sicherzustellen, dass sich alle Dokumente in einem konsistenten Zustand befinden. Sie können für diese Aufgabe das Azure-Portal oder einen API-Client verwenden.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Schritt 4: Speichern des Indexers

Aktualisieren Sie den Indexer mit einer PUT-Anforderung, deren Anforderungstext „cache“ enthält.

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

Wenn Sie jetzt eine weitere GET-Anforderung an den Indexer senden, enthält die Antwort des Dienstes die Eigenschaft ID im Cacheobjekt. Die Zeichenfolge wird an den Namen des Containers angehängt, der alle zwischengespeicherten Ergebnisse und den Zwischenzustand der einzelnen Dokumente enthält, die von diesem Indexer verarbeitet werden. Mit der ID wird der Cache in Blobspeicher eindeutig benannt.

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

Schritt 5: Starten Sie den Indexer

Sie können den Indexer über das Azure-Portal oder die API ausführen. Wählen Sie im Azure-Portal den Indexer aus der Indexerliste und dann Ausführen aus. Ein Vorteil bei der Verwendung des Azure-Portals besteht darin, dass Sie den Indexerstatus überwachen und die Dauer des Auftrags sowie die Anzahl der verarbeiteten Dokumente notieren können. Portalseiten werden alle paar Minuten aktualisiert.

Alternativ können Sie REST verwenden, um den Indexer auszuführen:

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Hinweis

Ein Zurücksetzen und erneutes Ausführen des Indexers führt zu einer vollständigen Neuerstellung, sodass der Inhalt zwischengespeichert werden kann. Alle kognitiven Anreicherungen werden für alle Dokumente erneut ausgeführt. Die Wiederverwendung angereicherter Inhalte aus dem Cache beginnt nach dem Laden des Caches.

Überprüfen auf eine zwischengespeicherte Ausgabe

Suchen Sie den Cache in Azure Storage unter Blobcontainer. Der Containername lautet: ms-az-search-indexercache-<some-alphanumeric-string>.

Ein Cache wird erstellt und von einem Indexer verwendet. Der Inhalt ist für Menschen nicht lesbar.

Um zu überprüfen, ob der Cache betriebsbereit ist, ändern Sie ein Skillset, führen Sie den Indexer aus, und vergleichen Sie dann die Vorher-/Nachher-Metriken auf Ausführungszeit und Dokumentanzahl.

Skillsets, die Bildanalyse und optische Zeichenerkennung (Optical Character Recognition, OCR) gescannter Dokumente enthalten, sind gute Testfälle. Wenn Sie einen Downstreamtextskill oder einen beliebigen nicht bildbezogenen Skill ändern, kann der Indexer alle zuvor verarbeiteten Bild- und OCR-Inhalte aus dem Cache abrufen, wobei nur die durch Ihre Bearbeitungen angegebenen textbezogenen Änderungen aktualisiert und verarbeitet werden. Es ist zu erwarten, dass als Dokumentanzahl der Indexerausführung weniger Dokumente, kürzere Ausführungszeiten und weniger Gebühren auf der Rechnung angezeigt werden.

Der in den cog-search-demo-Tutorials verwendete Dateisatz ist ein nützlicher Testfall, da er 14 Dateien in verschiedenen Formaten (JPG, PNG, HTML, DOCX, PPTX und anderen Typen) enthält. Ändern Sie en in es oder eine andere Sprache im Skill „Textübersetzung“, um Proof-of-Concept-Tests der inkrementellen Anreicherung durchzuführen.

Häufige Fehler

Der folgende Fehler tritt auf, wenn Sie vergessen, in der Anforderung eine Vorschauversion der API anzugeben:

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

Der Fehler „400 Ungültige Anforderung“ tritt auch auf, wenn eine Indexeranforderung nicht erfüllt ist. In der Fehlermeldung werden alle fehlenden Abhängigkeiten angegeben.

Nächste Schritte

Die inkrementelle Anreicherung gilt für Indexer, die Skillsets enthalten, und stellt wiederverwendbare Inhalte sowohl für Indizes als auch für Wissensspeicher bereit. Unter den folgenden Links finden Sie weitere Informationen zur Zwischenspeicherung und zu Skillsets.

Freigeben über