Delen via

Een index bijwerken of herbouwen in Azure AI Search

  • Artikel

In dit artikel wordt uitgelegd hoe u een bestaande index in Azure AI Search bijwerkt met schemawijzigingen of inhoudswijzigingen via incrementele indexering. Hierin wordt uitgelegd onder welke omstandigheden herbouwen vereist zijn en worden aanbevelingen geboden voor het beperken van de gevolgen van herbouw van lopende queryaanvragen.

Tijdens de actieve ontwikkeling is het gebruikelijk om indexen te verwijderen en opnieuw te bouwen wanneer u het ontwerp van de index doorgeeft. De meeste ontwikkelaars werken met een kleine representatieve steekproef van hun gegevens, zodat het opnieuw indexeren sneller gaat.

Voor schemawijzigingen in toepassingen die al in productie zijn, raden we u aan een nieuwe index te maken en te testen die naast een bestaande index wordt uitgevoerd. Gebruik een indexalias om in de nieuwe index te wisselen, zodat u wijzigingen in uw toepassingscode kunt voorkomen.

Inhoud bijwerken

Incrementeel indexeren en synchroniseren van een index met wijzigingen in brongegevens is fundamenteel voor de meeste zoektoepassingen. In deze sectie wordt de werkstroom uitgelegd voor het bijwerken van veldinhoud in een zoekindex via de REST API, maar de Azure SDK's bieden gelijkwaardige functionaliteit.

De hoofdtekst van de aanvraag bevat een of meer documenten die moeten worden geïndexeerd. Documenten worden geïdentificeerd met een unieke hoofdlettergevoelige sleutel. Elk document is gekoppeld aan een actie: 'uploaden', 'verwijderen', 'samenvoegen' of 'mergeOrUpload'. Uploadaanvragen moeten de documentgegevens bevatten als een set sleutel-waardeparen.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

  • Gebruik eerst de API's voor het laden van documenten, zoals Documents - Index (REST) of een equivalente API in de Azure SDK's. Zie Documenten laden voor meer informatie over indexeringstechnieken.

  • Voor een grote update wordt batchverwerking (maximaal 1.000 documenten per batch of ongeveer 16 MB per batch, afhankelijk van de limiet die het eerst voorkomt) aanbevolen en worden de indexeringsprestaties aanzienlijk verbeterd.

  • Stel de @search.action parameter voor de API in om het effect op bestaande documenten te bepalen.

    Actie Effect
    delete Hiermee verwijdert u het hele document uit de index. Als u een afzonderlijk veld wilt verwijderen, gebruikt u in plaats daarvan samenvoegen en stelt u het betreffende veld in op null. Verwijderde documenten en velden maken niet onmiddellijk ruimte vrij in de index. Elke paar minuten voert een achtergrondproces de fysieke verwijdering uit. Of u nu Azure Portal of een API gebruikt om indexstatistieken te retourneren, u kunt een kleine vertraging verwachten voordat het verwijderen wordt doorgevoerd in Azure Portal en via API's.
    samenvoegen Werkt een document bij dat al bestaat en mislukt een document dat niet kan worden gevonden. Samenvoegen vervangt bestaande waarden. Zorg er daarom voor dat u controleert op verzamelingsvelden die meerdere waarden bevatten, zoals velden van het type Collection(Edm.String). Als een tags veld bijvoorbeeld begint met een waarde van ["budget"] en u een samenvoegbewerking ["economy", "pool"]uitvoert, is ["economy", "pool"]de uiteindelijke waarde van het tags veld. Het zal niet zijn ["budget", "economy", "pool"].

    Hetzelfde gedrag is van toepassing op complexe verzamelingen. Als het document een complex verzamelingsveld bevat met de naam Ruimten met een waarde van [{ "Type": "Budget Room", "BaseRate": 75.0 }], en u een samenvoeging uitvoert met een waarde van [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], is [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]de uiteindelijke waarde van het veld Ruimten. Er worden geen nieuwe en bestaande waarden toegevoegd of samengevoegd.
    mergeOrUpload Gedraagt zich als samenvoegen als het document bestaat en uploadt of het document nieuw is. Dit is de meest voorkomende actie voor incrementele updates.
    uploaden Vergelijkbaar met een upsert waarin het document wordt ingevoegd als het nieuw is en bijgewerkt of vervangen als het bestaat. Als het document ontbrekende waarden bevat die de index vereist, wordt de waarde van het documentveld ingesteld op null.

Query's blijven worden uitgevoerd tijdens het indexeren, maar als u bestaande velden bijwerkt of verwijdert, kunt u gemengde resultaten en een hogere incidentie van beperking verwachten.

Notitie

Er zijn geen bestelgaranties waarvoor actie in de aanvraagbody eerst wordt uitgevoerd. Het is niet raadzaam om meerdere samenvoegacties te hebben die zijn gekoppeld aan hetzelfde document in één aanvraagbody. Als er meerdere 'samenvoegacties' vereist zijn voor hetzelfde document, voert u de samenvoegingsclient uit voordat u het document bijwerkt in de zoekindex.

Antwoorden

Statuscode 200 wordt geretourneerd voor een geslaagd antwoord, wat betekent dat alle items duurzaam zijn opgeslagen en worden geïndexeerd. Indexering wordt op de achtergrond uitgevoerd en maakt nieuwe documenten (dat wil gezegd, doorzoekbaar en doorzoekbaar) enkele seconden nadat de indexeringsbewerking is voltooid. De specifieke vertraging is afhankelijk van de belasting van de service.

Geslaagde indexering wordt aangegeven door de statuseigenschap die wordt ingesteld op waar voor alle items, evenals de statusCode eigenschap die wordt ingesteld op 201 (voor nieuw geüploade documenten) of 200 (voor samengevoegde of verwijderde documenten):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

Statuscode 207 wordt geretourneerd wanneer ten minste één item niet is geïndexeerd. Items die niet zijn geïndexeerd, hebben het statusveld ingesteld op false. De errorMessage en statusCode eigenschappen geven de reden voor de indexeringsfout aan:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}

De errorMessage eigenschap geeft indien mogelijk de reden voor de indexeringsfout aan.

In de volgende tabel worden de verschillende statuscodes per document uitgelegd die in het antwoord kunnen worden geretourneerd. Sommige statuscodes geven problemen aan met de aanvraag zelf, terwijl andere tijdelijke foutvoorwaarden aangeven. De laatste moet u opnieuw proberen na een vertraging.

Statuscode Betekenis Opnieuw proberen Opmerkingen
200 Document is gewijzigd of verwijderd. n.v.t. Verwijderingsbewerkingen zijn idempotent. Zelfs als er geen documentsleutel in de index bestaat, resulteert een verwijderbewerking met die sleutel in een statuscode van 200.
201 Het document is gemaakt. n.v.t.
400 Er is een fout opgetreden in het document waardoor het niet kon worden geïndexeerd. Nee Het foutbericht in het antwoord geeft aan wat er mis is met het document.
404 Het document kan niet worden samengevoegd omdat de opgegeven sleutel niet in de index bestaat. Nee Deze fout treedt niet op bij uploads, omdat ze nieuwe documenten maken en deze niet optreedt voor verwijderingen omdat ze idempotent zijn.
409 Er is een versieconflict gedetecteerd bij een poging om een document te indexeren. Ja Dit kan voorkomen wanneer u hetzelfde document meer dan één keer achter elkaar probeert te indexeren.
422 De index is tijdelijk niet beschikbaar omdat deze is bijgewerkt met de vlag allowIndexDowntime ingesteld op waar. Ja
503 Uw zoekservice is tijdelijk niet beschikbaar, mogelijk vanwege zware belasting. Ja In dit geval moet de code wachten voordat u het opnieuw probeert, anders riskeert u dat de service nog langer niet beschikbaar is.

Als uw clientcode vaak een 207-antwoord tegenkomt, is een mogelijke reden dat het systeem wordt belast. U kunt dit bevestigen door de eigenschap statusCode voor 503 te controleren. Als de statusCode 503 is, raden we u aan om indexeringsaanvragen te beperken. Als het indexeren van verkeer niet afzakt, kan het systeem alle aanvragen met 503-fouten weigeren.

Statuscode 429 geeft aan dat u het quotum voor het aantal documenten per index hebt overschreden. U moet een nieuwe index maken of upgraden voor hogere capaciteitslimieten.

Notitie

Wanneer u waarden uploadt DateTimeOffset met tijdzonegegevens naar uw index, normaliseert Azure AI Search deze waarden naar UTC. Bijvoorbeeld: 2024-01-13T14:03:00-08:00 wordt opgeslagen als 2024-01-13T22:03:00Z. Als u tijdzonegegevens wilt opslaan, voegt u een extra kolom toe aan uw index voor dit gegevenspunt.

Tips voor incrementeel indexeren

  • Indexeerfuncties automatiseren incrementele indexering. Als u een indexeerfunctie kunt gebruiken en als de gegevensbron wijzigingen bijhouden ondersteunt, kunt u de indexeerfunctie uitvoeren volgens een terugkerend schema om doorzoekbare inhoud toe te voegen, bij te werken of te overschrijven, zodat deze wordt gesynchroniseerd met uw externe gegevens.

  • Als u indexoproepen rechtstreeks via de push-API maakt, gebruikt mergeOrUpload u deze als zoekactie.

  • De nettolading moet de sleutels of id's bevatten van elk document dat u wilt toevoegen, bijwerken of verwijderen.

  • Als uw index vectorvelden bevat en u de stored eigenschap instelt op false, moet u de vector opgeven in de gedeeltelijke documentupdate, zelfs als de waarde ongewijzigd is. Een neveneffect van het instellen stored op false is dat vectoren worden verwijderd bij een herindexeringsbewerking. Door de vector in de nettolading van documenten op te geven, voorkomt u dat dit gebeurt.

  • Als u de inhoud van eenvoudige velden en subvelden in complexe typen wilt bijwerken, moet u alleen de velden weergeven die u wilt wijzigen. Als u bijvoorbeeld alleen een beschrijvingsveld hoeft bij te werken, moet de nettolading bestaan uit de documentsleutel en de gewijzigde beschrijving. Als u andere velden weglaat, blijven de bestaande waarden behouden.

  • Als u inlinewijzigingen wilt samenvoegen in een tekenreeksverzameling, geeft u de volledige waarde op. U herinnert zich het tags veldvoorbeeld uit de vorige sectie. Nieuwe waarden overschrijven de oude waarden voor een heel veld en er is geen samenvoeging binnen de inhoud van een veld.

Hier volgt een REST API-voorbeeld waarin deze tips worden gedemonstreerd:

### 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}}

Een indexschema bijwerken

Het indexschema definieert de fysieke gegevensstructuren die zijn gemaakt in de zoekservice, dus er zijn niet veel schemawijzigingen die u kunt aanbrengen zonder dat er een volledige herbouwbewerking wordt uitgevoerd.

Updates zonder herbouwing

In de volgende lijst worden de schemawijzigingen opgesomd die naadloos in een bestaande index kunnen worden geïntroduceerd. Over het algemeen bevat de lijst nieuwe velden en functionaliteit die worden gebruikt tijdens het uitvoeren van query's.

  • Een nieuw veld toevoegen
  • Het retrievable kenmerk voor een bestaand veld instellen
  • Bijwerken searchAnalyzer voor een veld met een bestaande indexAnalyzer
  • Een nieuwe analysedefinitie toevoegen in een index (die kan worden toegepast op nieuwe velden)
  • Scoreprofielen toevoegen, bijwerken of verwijderen
  • Synoniemmaps toevoegen, bijwerken of verwijderen
  • Semantische configuraties toevoegen, bijwerken of verwijderen
  • CORS-instellingen toevoegen, bijwerken of verwijderen

De volgorde van bewerkingen is:

  1. Haal de indexdefinitie op.

  2. Wijzig het schema met updates uit de vorige lijst.

  3. Indexschema bijwerken in de zoekservice.

  4. Werk indexinhoud bij zodat deze overeenkomt met uw herziene schema als u een nieuw veld hebt toegevoegd. Voor alle andere wijzigingen wordt de bestaande geïndexeerde inhoud als zodanig gebruikt.

Wanneer u een indexschema bijwerkt om een nieuw veld op te nemen, krijgen bestaande documenten in de index een null-waarde voor dat veld. In de volgende indexeringstaak vervangen waarden uit externe brongegevens de null's die zijn toegevoegd door Azure AI Search.

Er mogen geen queryonderbrekingen optreden tijdens de updates, maar de queryresultaten variëren naarmate de updates van kracht worden.

Updates waarvoor een herbouwing is vereist

Voor sommige wijzigingen moet een index worden verwijderd en opnieuw worden opgebouwd, waarbij een huidige index wordt vervangen door een nieuwe index.

Actie Beschrijving
Een veld verwijderen Als u alle traceringen van een veld fysiek wilt verwijderen, moet u de index opnieuw opbouwen. Wanneer een onmiddellijke herbouwing niet praktisch is, kunt u toepassingscode wijzigen om de toegang om te leiden van een verouderd veld of de zoekvelden gebruiken en queryparameters selecteren om te kiezen welke velden worden doorzocht en geretourneerd. Fysiek blijft de velddefinitie en inhoud in de index staan totdat u het volgende opnieuw maakt, wanneer u een schema toepast dat het betreffende veld weglaat.
Een velddefinitie wijzigen Revisies van een veldnaam, gegevenstype of specifieke indexkenmerken (doorzoekbaar, filterbaar, sorteerbaar, facetable) vereisen een volledige herbouw.
Een analyse toewijzen aan een veld Analysefuncties worden gedefinieerd in een index, toegewezen aan velden en vervolgens aangeroepen tijdens het indexeren om te informeren hoe tokens worden gemaakt. U kunt op elk gewenst moment een nieuwe analysedefinitie toevoegen aan een index, maar u kunt alleen een analyse toewijzen wanneer het veld wordt gemaakt. Dit geldt voor zowel de eigenschappen analyzer als indexAnalyzer . De eigenschap searchAnalyzer is een uitzondering (u kunt deze eigenschap toewijzen aan een bestaand veld).
Een analysedefinitie in een index bijwerken of verwijderen U kunt een bestaande analyseconfiguratie (analyse, tokenizer, tokenfilter of tekenfilter) in de index niet verwijderen of wijzigen, tenzij u de hele index opnieuw opbouwt.
Een veld toevoegen aan een suggestie Als er al een veld bestaat en u het wilt toevoegen aan een suggesters-constructie , bouwt u de index opnieuw op.
Schakelen tussen lagen In-place upgrades worden niet ondersteund. Als u meer capaciteit nodig hebt, maakt u een nieuwe service en bouwt u uw indexen helemaal opnieuw op. Als u dit proces wilt automatiseren, kunt u de voorbeeldcode voor het herstellen van een back-up maken van indexen gebruiken in deze Azure AI Search .NET-voorbeeldopslagplaats. Deze app maakt een back-up van uw index naar een reeks JSON-bestanden en maakt vervolgens de index opnieuw in een zoekservice die u opgeeft.

De volgorde van bewerkingen is:

  1. Haal een indexdefinitie op voor het geval u deze nodig hebt voor toekomstige naslaginformatie of als basis voor een nieuwe versie.

  2. Overweeg om een back-up- en hersteloplossing te gebruiken om een kopie van indexinhoud te behouden. Er zijn oplossingen in C# en in Python. We raden de Python-versie aan omdat deze up-to-date is.

    Als u capaciteit hebt voor uw zoekservice, moet u de bestaande index behouden terwijl u de nieuwe index maakt en test.

  3. Verwijder de bestaande index. Query's die gericht zijn op de index, worden onmiddellijk verwijderd. Houd er rekening mee dat het verwijderen van een index niet ongedaan kan worden gemaakt, waardoor fysieke opslag voor de verzameling velden en andere constructies wordt vernietigd.

  4. Post een herziene index, waarbij de hoofdtekst van de aanvraag gewijzigde of gewijzigde velddefinities en -configuraties bevat.

  5. Laad de index met documenten van een externe bron. Documenten worden geïndexeerd met behulp van de velddefinities en configuraties van het nieuwe schema.

Wanneer u de index maakt, wordt fysieke opslag toegewezen voor elk veld in het indexschema, met een omgekeerde index die is gemaakt voor elk doorzoekbaar veld en een vectorindex die voor elk vectorveld wordt gemaakt. Velden die niet doorzoekbaar zijn, kunnen worden gebruikt in filters of expressies, maar hebben geen omgekeerde indexen en zijn niet in volledige tekst of fuzzy doorzoekbaar. Bij het opnieuw opbouwen van een index worden deze omgekeerde indexen en vectorindexen verwijderd en opnieuw gemaakt op basis van het indexschema dat u opgeeft.

Als u onderbreking van toepassingscode wilt minimaliseren, kunt u een indexalias maken. Toepassingscode verwijst naar de alias, maar u kunt de naam bijwerken van de index waarnaar de alias verwijst.

Workloads verdelen

Indexering wordt niet op de achtergrond uitgevoerd, maar de zoekservice brengt indexeringstaken in balans met lopende query's. Tijdens het indexeren kunt u queryaanvragen bewaken in Azure Portal om ervoor te zorgen dat query's tijdig worden voltooid.

Als het indexeren van workloads onaanvaardbare niveaus van querylatentie introduceert, voert u prestatieanalyse uit en bekijkt u deze prestatietips voor mogelijke risicobeperking.

Controleren op updates

U kunt beginnen met het uitvoeren van query's op een index zodra het eerste document is geladen. Als u de id van een document kent, retourneert de REST API voor opzoekdocument het specifieke document. Voor uitgebreidere tests moet u wachten totdat de index volledig is geladen en vervolgens query's gebruiken om de context te controleren die u verwacht te zien.

U kunt Search Explorer of een REST-client gebruiken om te controleren op bijgewerkte inhoud.

Als u een veld hebt toegevoegd of de naam ervan hebt gewijzigd, selecteert u om dat veld te retourneren:

"search": "*",
"select": "document-id, my-new-field, some-old-field",
"count": true

Azure Portal biedt indexgrootte en vectorindexgrootte. U kunt deze waarden controleren na het bijwerken van een index, maar vergeet niet om een kleine vertraging te verwachten wanneer de service de wijziging verwerkt en rekening houdt met de vernieuwingsfrequenties van de portal. Dit kan enkele minuten duren.

Zwevende documenten verwijderen

Azure AI Search ondersteunt bewerkingen op documentniveau, zodat u een specifiek document afzonderlijk kunt opzoeken, bijwerken en verwijderen. In het volgende voorbeeld ziet u hoe u een document verwijdert.

Als u een document verwijdert, wordt er niet onmiddellijk ruimte vrijgemaakt in de index. Elke paar minuten voert een achtergrondproces de fysieke verwijdering uit. Of u nu Azure Portal of een API gebruikt om indexstatistieken te retourneren, u kunt een kleine vertraging verwachten voordat de verwijdering wordt doorgevoerd in de Metrische gegevens van Azure Portal en API.

  1. Bepaal welk veld de documentsleutel is. In Azure Portal kunt u de velden van elke index weergeven. Documentsleutels zijn tekenreeksvelden en worden aangeduid met een sleutelpictogram om ze gemakkelijker te herkennen.

  2. Controleer de waarden van het documentsleutelveld: search=*&$select=HotelId. Een eenvoudige tekenreeks is eenvoudig, maar als de index gebruikmaakt van een met base 64 gecodeerd veld of als zoekdocumenten zijn gegenereerd op basis van een parsingMode instelling, werkt u mogelijk met waarden waarmee u niet bekend bent.

  3. Zoek het document op om de waarde van de document-id te controleren en de inhoud ervan te controleren voordat u het verwijdert. Geef de sleutel- of document-id op in de aanvraag. In de volgende voorbeelden ziet u een eenvoudige tekenreeks voor de voorbeeldindex Hotels en een met base 64 gecodeerde tekenreeks voor de metadata_storage_path sleutel van de cog-search-demo-index.

    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. Verwijder het document met een verwijderbewerking @search.action om het te verwijderen uit de zoekindex.

    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"  
    }  
  ]  
}

Zie ook