Een index maken in Azure AI Search

Artikel
10/19/2023

In Azure AI Search richten queryaanvragen zich op de doorzoekbare tekst in een zoekindex.

In dit artikel leert u de stappen voor het definiëren en publiceren van een zoekindex. Als u een index maakt, worden de fysieke gegevensstructuren in uw zoekservice vastgelegd. Zodra de indexdefinitie bestaat, wordt de index als een afzonderlijke taak geladen.

Vereisten

Schrijfmachtigingen. De machtiging kan worden verleend via een beheer-API-sleutel voor de aanvraag. Als u op rollen gebaseerd toegangsbeheer gebruikt, kunt u ook een aanvraag verzenden als lid van de rol Inzender voor zoeken.
Inzicht in de gegevens die u wilt indexeren. Het maken van een index is een schemadefinitieoefening, dus u moet een duidelijk beeld hebben van welke bronvelden u doorzoekbaar, ophaalbaar, filterbaar, facetabel en sorteerbaar wilt maken (zie de controlelijst voor schema's voor richtlijnen).

U moet ook een uniek veld hebben in brongegevens die kunnen worden gebruikt als documentsleutel (of id) in de index.
Een stabiele indexlocatie. Het verplaatsen van een bestaande index naar een andere zoekservice wordt niet standaard ondersteund. Ga opnieuw naar de toepassingsvereisten en zorg ervoor dat uw bestaande zoekservice, de capaciteit en locatie ervan voldoende zijn voor uw behoeften.
Ten slotte hebben alle servicelagen indexlimieten voor het aantal objecten dat u kunt maken. Als u bijvoorbeeld experimenteert op de gratis laag, kunt u op elk gewenst moment slechts drie indexen hebben. Binnen de index zelf gelden limieten voor het aantal complexe velden en verzamelingen.

Documentsleutels

Een zoekindex heeft één vereist veld: een documentsleutel. Een documentsleutel is de unieke id van een zoekdocument. In Azure AI Search moet het een tekenreeks zijn en moet deze afkomstig zijn van unieke waarden in de gegevensbron die de inhoud levert die moet worden geïndexeerd. Een zoekservice genereert geen sleutelwaarden, maar in sommige scenario's (zoals de Azure-tabelindexeerfunctie) worden bestaande waarden gesyntheteerd om een unieke sleutel te maken voor de documenten die worden geïndexeerd.

Tijdens incrementele indexering, waarbij nieuwe en bijgewerkte inhoud wordt geïndexeerd, worden binnenkomende documenten met nieuwe sleutels toegevoegd, terwijl binnenkomende documenten met bestaande sleutels worden samengevoegd of overschreven, afhankelijk van of indexvelden null of ingevuld zijn.

Controlelijst voor schema's

Gebruik deze controlelijst om de ontwerpbeslissingen voor uw zoekindex te helpen.

Controleer naamconventies zodat index- en veldnamen voldoen aan de naamgevingsregels.
Bekijk ondersteunde gegevenstypen. Het gegevenstype is van invloed op de manier waarop het veld wordt gebruikt. Numerieke inhoud kan bijvoorbeeld worden gefilterd, maar kan niet in volledige tekst worden doorzocht. Het meest voorkomende gegevenstype is Edm.String voor doorzoekbare tekst, die is getokeniseerd en opgevraagd met behulp van de zoekprogramma voor volledige tekst.
Een documentsleutel identificeren. Een documentsleutel is een indexvereiste. Het is één tekenreeksveld en wordt gevuld vanuit een brongegevensveld dat unieke waarden bevat. Als u bijvoorbeeld indexeert vanuit Blob Storage, wordt het opslagpad voor metagegevens vaak gebruikt als documentsleutel, omdat deze elke blob in de container uniek identificeert.
Identificeer de velden in uw gegevensbron die doorzoekbare inhoud in de index bijdragen. Doorzoekbare inhoud bevat korte of lange tekenreeksen waarop een query wordt uitgevoerd met behulp van de zoekprogramma voor volledige tekst. Als de inhoud uitgebreid is (kleine woordgroepen of grotere segmenten), experimenteert u met verschillende analysen om te zien hoe de tekst wordt getokeniseerd.

Veldkenmerktoewijzingen bepalen zowel zoekgedrag als de fysieke weergave van uw index in de zoekservice. Bepalen hoe velden moeten worden opgegeven, is een iteratief proces voor veel klanten. Als u iteraties wilt versnellen, begint u met voorbeeldgegevens, zodat u deze eenvoudig kunt verwijderen en opnieuw kunt opbouwen.
Bepalen welke bronvelden kunnen worden gebruikt als filters. Numerieke inhoud en korte tekstvelden, met name velden met herhalende waarden, zijn goede keuzes. Wanneer u met filters werkt, moet u het volgende onthouden:
- Filterbare velden kunnen eventueel worden gebruikt in facetnavigatie.
- Filterbare velden worden in willekeurige volgorde geretourneerd, dus overweeg ze ook sorteerbaar te maken.
Bepaal of u de standaardanalyse ("analyzer": null) of een andere analyse wilt gebruiken. Analysefuncties worden gebruikt om tekstvelden te tokeniseren tijdens het indexeren en uitvoeren van query's.

Voor meertalige tekenreeksen kunt u een taalanalyse overwegen.

Voor afbreekstreepjes of speciale tekens kunt u gespecialiseerde analyses overwegen. Een voorbeeld is een trefwoord dat de volledige inhoud van een veld als één token behandelt. Dit gedrag is handig voor gegevens zoals postcodes, id's en sommige productnamen. Zie Gedeeltelijke zoektermen en patronen met speciale tekens voor meer informatie.

Notitie

Zoekopdrachten in volledige tekst worden uitgevoerd op termen die tijdens het indexeren worden tokeniseerd. Als uw query's de verwachte resultaten niet retourneren, test u op tokenisatie om te controleren of de tekenreeks daadwerkelijk bestaat. U kunt verschillende analysen op tekenreeksen proberen om te zien hoe tokens worden geproduceerd voor verschillende analysen.

Een index maken

Wanneer u klaar bent om de index te maken, gebruikt u een zoekclient die de aanvraag kan verzenden. U kunt Azure Portal of REST API's gebruiken voor vroege ontwikkeling en proof-of-concept-tests.

Plan tijdens de ontwikkeling regelmatig herbouwen. Omdat fysieke structuren in de service worden gemaakt, zijn het verwijderen en opnieuw maken van indexen nodig voor veel wijzigingen. U kunt overwegen om met een subset van uw gegevens te werken om herbouwen sneller te laten verlopen.

Indexontwerp via de portal dwingt vereisten en schemaregels af voor specifieke gegevenstypen, zoals het ongedaan maken van de toewijzing van zoekmogelijkheden voor volledige tekst op numerieke velden.

Meld u aan bij het Azure-portaal.
Kies op de pagina Overzicht van de zoekservice een van de opties voor het maken van een zoekindex:
- Index toevoegen, een ingesloten editor voor het opgeven van een indexschema
- Wizard Gegevens importeren
De wizard is een end-to-end werkstroom waarmee een indexeerfunctie, een gegevensbron en een voltooide index worden gemaakt. De gegevens worden ook geladen. Als dit meer is dan wat u wilt, gebruikt u in plaats daarvan Index toevoegen.

In de volgende schermopname ziet u waar index - en importgegevens toevoegen worden weergegeven op de opdrachtbalk. Nadat een index is gemaakt, kunt u deze opnieuw vinden op het tabblad Indexen .

Tip

Nadat u een index in de portal hebt gemaakt, kunt u de JSON-weergave kopiëren en toevoegen aan uw toepassingscode.

Create Index (REST API) wordt gebruikt om een index te maken. U hebt een REST-client nodig om verbinding te maken met uw zoekservice en aanvragen te verzenden. Zie snelstartgids: Tekst zoeken met REST om aan de slag te gaan.

De REST API biedt standaardwaarden voor veldtoewijzing. Alle velden zijn bijvoorbeeld Edm.String standaard doorzoekbaar. Kenmerken worden volledig hieronder weergegeven voor illustratieve doeleinden, maar u kunt de toewijzing weglaten in gevallen waarin de standaardwaarden van toepassing zijn.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

De Azure SDK voor .NET heeft SearchIndexClient met methoden voor het maken en bijwerken van indexen.

// Create the index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Zieazure-search-dotnet-samples/quickstart/v11/voor meer voorbeelden.

Voor Azure AI Search implementeren de Azure SDK's algemeen beschikbare functies. Als zodanig kunt u een van de SDK's gebruiken om een zoekindex te maken. Ze bieden allemaal een SearchIndexClient met methoden voor het maken en bijwerken van indexen.

Azure SDK	Klant	Voorbeelden
Java	SearchIndexClient	CreateIndexExample.java
JavaScript	SearchIndexClient	Indexen
Python	SearchIndexClient	sample_index_crud_operations.py

Instellen `corsOptions` voor cross-origin-query's

Indexschema's bevatten een sectie voor het instellen corsOptions. JavaScript aan de clientzijde kan standaard geen API's aanroepen, omdat browsers alle cross-origin-aanvragen voorkomen. Als u cross-origin-query's naar uw index wilt toestaan, schakelt u CORS (Cross-Origin Resource Sharing) in door het kenmerk corsOptions in te stellen. Om veiligheidsredenen bieden alleen query-API's ondersteuning voor CORS.

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

De volgende eigenschappen kunnen worden ingesteld voor CORS:

allowedOrigins (vereist): Dit is een lijst met oorsprongen die toegang hebben tot uw index. JavaScript-code die vanaf deze oorsprongen wordt geleverd, mag een query uitvoeren op uw index (ervan uitgaande dat de aanroeper een geldige sleutel biedt of machtigingen heeft). Elke oorsprong is meestal van de vorm protocol://<fully-qualified-domain-name>:<port> , hoewel <port> deze vaak wordt weggelaten. Zie Cross-origin resource sharing (Wikipedia) voor meer informatie.

Als u toegang tot alle origins wilt toestaan, neemt * u deze op als één item in de matrix allowedOrigins . Dit is geen aanbevolen procedure voor productiezoekservices , maar dit is vaak handig voor ontwikkeling en foutopsporing.
maxAgeInSeconds (optioneel): Browsers gebruiken deze waarde om de duur (in seconden) te bepalen voor het opslaan van CORS-preflight-antwoorden. Dit moet een niet-negatief geheel getal zijn. Een langere cacheperiode levert betere prestaties, maar het verlengt de hoeveelheid tijd die een CORS-beleid moet uitvoeren. Als deze waarde niet is ingesteld, wordt een standaardduur van vijf minuten gebruikt.

Toegestane updates voor bestaande indexen

Met Index maken worden de fysieke gegevensstructuren (bestanden en omgekeerde indexen) in uw zoekservice gemaakt. Zodra de index is gemaakt, is de mogelijkheid om wijzigingen te effecteren met behulp van Update Index afhankelijk van of uw wijzigingen deze fysieke structuren ongeldig maken. De meeste veldkenmerken kunnen niet worden gewijzigd zodra het veld in uw index is gemaakt.

U kunt ook een indexalias maken die fungeert als een stabiele verwijzing in uw toepassingscode. In plaats van uw code bij te werken, kunt u een indexalias bijwerken zodat deze verwijst naar nieuwere indexversies.

Om het verloop in het ontwerpproces te minimaliseren, wordt in de volgende tabel beschreven welke elementen vast en flexibel zijn in het schema. Voor het wijzigen van een vast element moet een index opnieuw worden opgebouwd, terwijl flexibele elementen op elk gewenst moment kunnen worden gewijzigd zonder dat dit van invloed is op de fysieke implementatie.

Element	Kan worden bijgewerkt?
Naam	Nee
Sleutel	Nee
Veldnamen en -typen	Nee
Veldkenmerken (doorzoekbaar, filterbaar, facetable, sorteerbaar)	Nee
Veldkenmerk (ophaalbaar)	Ja
Analyzer	U kunt aangepaste analysefuncties toevoegen en wijzigen in de index. Met betrekking tot analysetoewijzingen voor tekenreeksvelden kunt u alleen wijzigen `searchAnalyzer`. Alle andere toewijzingen en wijzigingen vereisen een herbouw.
Scoreprofielen	Ja
Suggesties	Nee
cross-origin resource sharing (CORS)	Ja
Versleuteling	Ja

Volgende stappen

Gebruik de volgende koppelingen om vertrouwd te raken met het laden van een index met gegevens of het uitbreiden van een index met een synoniemenkaart.