Caching inschakelen voor incrementele verrijking in Azure AI Search

  • Artikel

Belangrijk

Deze functie is beschikbaar als openbare preview onder aanvullende gebruiksvoorwaarden. De preview-REST API ondersteunt deze functie.

In dit artikel wordt uitgelegd hoe u caching toevoegt aan een verrijkingspijplijn, zodat u downstreamverrijkingsstappen kunt wijzigen zonder dat u elke keer volledig opnieuw hoeft te bouwen. Een vaardighedenset is standaard staatloos en het wijzigen van een deel van de samenstelling vereist een volledige herrun van de indexeerfunctie. Met een verrijkingscache kan de indexeerfunctie bepalen welke onderdelen van de documentstructuur moeten worden vernieuwd op basis van wijzigingen die zijn gedetecteerd in de definitie van de vaardighedenset of indexeerfunctie. Bestaande verwerkte uitvoer blijft behouden en waar mogelijk opnieuw gebruikt.

Inhoud in de cache wordt in Azure Storage geplaatst met behulp van accountgegevens die u opgeeft. De container met de naam ms-az-search-indexercache-<alpha-numerc-string>wordt gemaakt wanneer u de indexeerfunctie uitvoert. Het moet worden beschouwd als een intern onderdeel dat wordt beheerd door uw zoekservice en mag niet worden gewijzigd.

Vereisten

  • Azure Storage voor het opslaan van verrijkingen in cache. Het opslagaccount moet algemeen v2 zijn.

  • Als u alleen voor het indexeren van blobs gesynchroniseerde documenten wilt verwijderen uit zowel de cache als de index wanneer blobs uit uw gegevensbron worden verwijderd, schakelt u een verwijderingsbeleid in de indexeerfunctie in. Zonder dit beleid wordt documentverwijdering uit de cache niet ondersteund.

U moet bekend zijn met het instellen van indexeerfuncties. Begin met het overzicht van de indexeerfunctie en ga verder met vaardighedensets voor meer informatie over verrijkingspijplijnen. Zie incrementele verrijking voor meer achtergrondinformatie over belangrijke concepten.

Let op

Als u de SharePoint Online-indexeerfunctie (preview) gebruikt, moet u incrementele verrijking voorkomen. Onder bepaalde omstandigheden wordt de cache ongeldig, waarvoor een indexeerfunctie opnieuw moet worden ingesteld en uitgevoerd, moet u ervoor kiezen om deze opnieuw te laden.

Inschakelen voor nieuwe indexeerfuncties

U kunt Azure Portal, preview-API's of bèta-AZURE SDK's gebruiken om een verrijkingscache in te schakelen op een indexeerfunctie.

  1. Selecteer aan de linkerkant Indexeerfuncties en selecteer vervolgens Indexeerfunctie toevoegen.

  2. Geef een indexeerfunctienaam en een bestaande index, gegevensbron en vaardighedenset op.

  3. Schakel incrementele caching in en stel het Azure Storage-account in.

    Screenshot of the portal option for enrichment cache.

Inschakelen voor bestaande indexeerfuncties

Voor bestaande indexeerfuncties die al een vaardighedenset hebben, gebruikt u de volgende stappen om caching toe te voegen. Als eenmalige bewerking kunt u de indexeerfunctie opnieuw instellen en opnieuw uitvoeren om de cache te laden.

Stap 1: de definitie van de indexeerfunctie ophalen

Begin met een geldige werkindexeerfunctie met deze onderdelen: gegevensbron, vaardighedenset, index. Verzend met behulp van een API-client een GET Indexer-aanvraag om de indexeerfunctie op te halen. Wanneer u de preview-API-versie gebruikt voor de GET-indexeerfunctie, wordt automatisch een cacheeigenschap die is ingesteld op null, toegevoegd aan de definitie.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Stap 2: De cache-eigenschap instellen

Wijzig 'cache' in de indexdefinitie zodat deze de volgende vereiste en optionele eigenschappen bevat:

  • (Vereist) storageConnectionString moet worden ingesteld op een Azure Storage-verbindingsreeks.
  • (Optioneel) enableReprocessing Booleaanse eigenschap (true standaard) geeft aan dat incrementele verrijking is ingeschakeld. Stel deze false optie in als u incrementele verwerking wilt onderbreken terwijl andere resource-intensieve bewerkingen, zoals het indexeren van nieuwe documenten, worden uitgevoerd en vervolgens terugkeren naar true later.
POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-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": []
    }

Stap 3: de indexeerfunctie opnieuw instellen

Indexeerfunctie opnieuw instellen is vereist bij het instellen van incrementele verrijking voor bestaande indexeerfuncties om ervoor te zorgen dat alle documenten een consistente status hebben. U kunt de portal of een API-client voor deze taak gebruiken.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Stap 4: De indexeerfunctie opslaan

Indexeerfunctie (2021-04-30-Preview) bijwerken met een PUT-aanvraag, waarbij de hoofdtekst van de aanvraag 'cache' bevat.

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

Als u nu een andere GET-aanvraag op de indexeerfunctie uitgeeft, bevat het antwoord van de service een ID eigenschap in het cacheobject. De alfanumerieke tekenreeks wordt toegevoegd aan de naam van de container met alle resultaten in de cache en tussenliggende status van elk document dat door deze indexeerfunctie wordt verwerkt. De id wordt gebruikt om de cache in Blob Storage een unieke naam te geven.

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

Stap 5: De indexeerfunctie uitvoeren

Als u een indexeerfunctie wilt uitvoeren, kunt u de portal of de API gebruiken. Selecteer in de portal in de lijst met indexeerfuncties de indexeerfunctie en selecteer Uitvoeren. Een voordeel van het gebruik van de portal is dat u de status van de indexeerfunctie kunt controleren, de duur van de taak kunt noteren en hoeveel documenten worden verwerkt. Portalpagina's worden elke paar minuten vernieuwd.

U kunt OOK REST gebruiken om de indexeerfunctie uit te voeren:

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Notitie

Een reset en opnieuw uitvoeren van de indexeerfunctie resulteert in een volledige herbouw, zodat inhoud in de cache kan worden opgeslagen. Alle cognitieve verrijkingen worden opnieuw uitgevoerd op alle documenten. Het opnieuw gebruiken van verrijkte inhoud uit de cache begint nadat de cache is geladen.

Controleren op uitvoer in cache

Zoek de cache in Azure Storage onder Blob-container. De containernaam is ms-az-search-indexercache-<some-alphanumeric-string>.

Er wordt een cache gemaakt en gebruikt door een indexeerfunctie. De inhoud ervan kan niet door mensen worden gelezen.

Als u wilt controleren of de cache operationeel is, wijzigt u een vaardighedenset en voert u de indexeerfunctie uit en vergelijkt u de metrische gegevens vóór en na voor de uitvoeringstijd en het aantal documenten.

Vaardighedensets met afbeeldingsanalyse en OCR (Optical Character Recognition) van gescande documenten maken goede testcases. Als u een vaardigheid voor downstreamtekst of een vaardigheid wijzigt die niet gerelateerd is aan afbeeldingen, kan de indexeerfunctie alle eerder verwerkte afbeeldings- en OCR-inhoud ophalen uit de cache, alleen de tekstgerelateerde wijzigingen bijwerken en verwerken die worden aangegeven door uw bewerkingen. U kunt verwachten dat er minder documenten worden weergegeven in het aantal indexeerdocumenten, kortere uitvoeringstijden en minder kosten op uw factuur.

De bestandsset die wordt gebruikt in cog-search-demo tutorials is een handige testcase omdat het 14 bestanden van verschillende indelingen JPG, PNG, HTML, DOCX, PPTX en andere typen bevat. Wijzig en of es een andere taal in de vaardigheid voor tekstvertaling voor proof-of-concept-testen van incrementele verrijking.

Algemene fouten

De volgende fout treedt op als u vergeet een preview-API-versie op te geven voor de aanvraag:

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

Er treedt ook een fout met 400 ongeldige aanvragen op als u een indexeerfunctievereiste mist. Het foutbericht geeft eventuele ontbrekende afhankelijkheden op.

Volgende stappen

Incrementele verrijking is van toepassing op indexeerfuncties die vaardighedensets bevatten en herbruikbare inhoud bieden voor zowel indexen als kennisarchieven. De volgende koppelingen bevatten meer informatie over caching en vaardighedensets.