Een index bijwerken of herbouwen in Azure AI Search

Artikel
07/04/2024

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 terwijl u wijzigingen in uw toepassingscode vermijdt.

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 voor het bijwerken van veldinhoud in een zoekindex uitgelegd.

Gebruik dezelfde technieken voor het laden van documenten: Documenten - Index (REST) of een equivalente API in de Azure SDK's. Zie Documenten laden voor meer informatie over indexeringstechnieken.

Stel de @search.action parameter 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 de portal of een API gebruikt om indexstatistieken te retourneren, u kunt een kleine vertraging verwachten voordat de verwijdering wordt doorgevoerd in de 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"]`.
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.

Plaats de update.

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

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 rechtstreeks indexoproepen uitvoert, 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 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 Secret Point Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

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

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Secret Point 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=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Een indexschema wijzigen

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. 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
CORS-instellingen toevoegen, bijwerken of verwijderen
Synoniemmaps toevoegen, bijwerken of verwijderen
Semantische configuraties toevoegen, bijwerken of verwijderen

De volgorde van bewerkingen is:

Haal de indexdefinitie op.
Wijzig het schema met updates uit de vorige lijst.
Indexschema bijwerken in de zoekservice.
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.

Een index verwijderen en opnieuw opbouwen

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:

Haal een indexdefinitie op voor het geval u deze nodig hebt voor toekomstige naslaginformatie of als basis voor een nieuwe versie.
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.
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.
Post een herziene index, waarbij de hoofdtekst van de aanvraag gewijzigde of gewijzigde velddefinities en -configuraties bevat.
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.

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 in de portal bewaken 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, gebruikt u $select 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 de portal of een API gebruikt om indexstatistieken te retourneren, u kunt een kleine vertraging verwachten voordat de verwijdering wordt weergegeven in de portal en api-metrische gegevens.

Bepaal welk veld de documentsleutel is. In de portal kunt u de velden van elke index weergeven. Documentsleutels zijn tekenreeksvelden en worden aangeduid met een sleutelpictogram om ze gemakkelijker te herkennen.
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.
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=2023-11-01
```
```
GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2023-11-01
```

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=2023-11-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

Delen via