Synoniemen toevoegen in Azure AI Search

In een zoekservice koppelt een synoniemtoewijzing equivalente termen, waarbij het bereik van een query wordt uitgebreid zonder dat de gebruiker de term daadwerkelijk hoeft op te geven. Stel dat honden, canine en puppy synoniemen zijn toegewezen, een query op canineovereenkomsten in een document met hond. U kunt meerdere synoniemenkaarten maken voor verschillende talen, zoals Engelse en Franse versies, of lexicons als uw inhoud technische jargon, slang of onduidelijke terminologie bevat.

Enkele belangrijke punten over synoniemenkaarten:

• Een synoniemenkaart is een resource op het hoogste niveau die eenmaal kan worden gemaakt en door veel indexen kan worden gebruikt.
• Een synoniemtoewijzing is van toepassing op tekenreeksvelden.
• U kunt op elk gewenst moment een synoniemtoewijzing maken en toewijzen zonder onderbreking van indexering of query's.
• Uw servicelaag stelt de limieten in voor het aantal synoniementoewijzingen dat u kunt maken.
• Uw zoekservice kan meerdere synoniementoewijzingen hebben, maar binnen een index kan een velddefinitie slechts één synoniemtoewijzingstoewijzing hebben.

Een synoniemenkaart maken

Een synoniemenkaart bestaat uit naam, indeling en regels die fungeren als synoniemkaartvermeldingen. De enige indeling die wordt ondersteund, is solren de indeling bepaalt de solr constructie van regels.

Als u een synoniemenkaart wilt maken, doet u dit programmatisch. De portal biedt geen ondersteuning voor synoniementoewijzingsdefinities.

REST

Gebruik de synonymtoewijzing maken (REST API) om een synoniemenkaart te maken.

POST /synonymmaps?api-version=2024-07-01
{
    "name": "geo-synonyms",
    "format": "solr",
    "synonyms": "
        USA, United States, United States of America\n
        Washington, Wash., WA => WA\n"
}

.NET

Gebruik de klasse SynonymMap (.NET) en maak een synoniemenkaart (Azure SDK-voorbeeld) om de kaart te maken.

Python

Gebruik de klasse SynonymMap (Python) om de kaart te maken.

Java

Gebruik de klasse SynonymMap (Java) om de kaart te maken.

JavaScript

Gebruik de SynonymMap-interface (JavaScript) om de kaart te maken.

Regels definiëren

Toewijzingsregels voldoen aan de opensource-filterspecificatie van Apache Solr, zoals beschreven in dit document: SynonymGraphFilter. De solr indeling ondersteunt twee soorten regels:

• gelijkwaardigheid (waarbij termen gelijk zijn aan vervangingen in de query)

• expliciete toewijzingen (waarbij termen worden toegewezen aan één expliciete term)

Elke regel wordt gescheiden door het nieuwe regelteken (\n). U kunt maximaal 5000 regels per synoniemkaart definiëren in een gratis service en 20.000 regels per kaart in andere lagen. Elke regel kan maximaal 20 uitbreidingen of items in een regel bevatten. Zie Synoniemenlimieten voor meer informatie.

Queryparsers gebruiken automatisch kleine letters voor hoofdletters of gemengde hoofdletters. Als u speciale tekens in de tekenreeks wilt behouden, zoals een komma of streepje, voegt u de juiste escapetekens toe bij het maken van de synoniemenkaart.

Regels voor gelijkwaardigheid

Regels voor equivalente termen worden door komma's gescheiden binnen dezelfde regel. In het eerste voorbeeld breidt een query op DE V.S.S. OF 'Verenigde Staten' OF 'Verenigde Staten van Amerika' uit. Als u wilt overeenkomen met een woordgroep, moet de query zelf een woordgroepsquery tussen aanhalingstekens zijn.

In het gelijkwaardigheidsscenario breidt een query voor hond de query uit om ook puppy en canine op te nemen.

{
"format": "solr",
"synonyms": "
    USA, United States, United States of America\n
    dog, puppy, canine\n
    coffee, latte, cup of joe, java\n"
}

Expliciete toewijzing

Regels voor een expliciete toewijzing worden aangeduid met een pijl =>. Wanneer dit is opgegeven, wordt een termenreeks van een zoekquery die overeenkomt met de linkerkant => vervangen door de alternatieven aan de rechterkant van de query.

In het expliciete geval wordt een query voor Washington, Wash of WA herschreven als WA en zoekt de query-engine alleen naar overeenkomsten op de term WA. Expliciete toewijzing is alleen van toepassing in de opgegeven richting en herschrijft de query WA in dit geval niet naar Washington .

{
"format": "solr",
"synonyms": "
    Washington, Wash., WA => WA\n
    California, Calif., CA => CA\n"
}

Speciale tekens ontsnappen

Synoniemen worden geanalyseerd tijdens het verwerken van query's, net als elke andere queryterm, wat betekent dat regels voor gereserveerde en speciale tekens van toepassing zijn op de termen in uw synoniemenkaart. De lijst met tekens waarvoor escape-tekens nodig zijn, verschilt per eenvoudige syntaxis en volledige syntaxis:

• eenvoudige syntaxis + | " ( ) ' \
• volledige syntaxis + - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Als u tekens wilt behouden die door de standaardanalyse worden verwijderd, vervangt u een analyse die deze bewaart. Sommige opties zijn onder andere Microsoft natuurlijke taalanalyses, die afbreekstreepjes bevatten, of een aangepaste analyse voor complexere patronen. Zie Gedeeltelijke termen, patronen en speciale tekens voor meer informatie.

In het volgende voorbeeld ziet u een voorbeeld van het escapen van een teken met een backslash:

{
    "format": "solr",
    "synonyms": "WA\, USA, WA, Washington\n"
}

Omdat de backslash zelf een speciaal teken is in andere talen, zoals JSON en C#, moet u deze waarschijnlijk dubbel escapen. Hier volgt een voorbeeld in JSON:

{
    "format":"solr",
    "synonyms": "WA\\, USA, WA, Washington"
}

Synoniemenkaarten beheren

U kunt een synoniemtoewijzing bijwerken zonder query's en indexeringsworkloads te verstoren. Wanneer u echter een synoniemtoewijzing toevoegt aan een veld, mislukt een query met de betreffende velden met een 404-fout als u vervolgens een synoniementoewijzing verwijdert.

Het maken, bijwerken en verwijderen van een synoniemenkaart is altijd een hele documentbewerking. U kunt delen van de synoniemenkaart niet incrementeel bijwerken of verwijderen. Voor het bijwerken van zelfs één regel is een herlaadbeurt vereist.

Synoniemen toewijzen aan velden

Nadat u de synoniemtoewijzing hebt gemaakt, wijst u deze toe aan een veld in uw index. Als u synoniemenkaarten wilt toewijzen, doet u dit programmatisch. De portal biedt geen ondersteuning voor synoniementoewijzingsveldkoppelingen.

• Een veld moet van het type Edm.String of Collection(Edm.String)
• Een veld moet een veld hebben "searchable":true
• Een veld kan slechts één synoniemtoewijzing hebben

Als het synoniemenoverzicht bestaat in de zoekservice, wordt deze gebruikt voor de volgende query, zonder opnieuw te indexeren of opnieuw te bouwen.

REST

Gebruik de REST API (Create or Update Index) om een velddefinitie te wijzigen.

PUT /indexes?api-version=2024-07-01
{
    "name":"hotels-sample-index",
    "fields":[
        {
            "name":"description",
            "type":"Edm.String",
            "searchable":true,
            "synonymMaps":[
            "en-synonyms"
            ]
        },
        {
            "name":"description_fr",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"fr.microsoft",
            "synonymMaps":[
            "fr-synonyms"
            ]
        }
    ]
}

.NET SDK

Gebruik SearchIndexClient om een index bij te werken. Geef de volledige indexdefinitie op en neem de nieuwe parameters voor synoniemtoewijzingen op.

In dit voorbeeld heeft het country veld een synonymMapName eigenschap.

// Update an 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);

Zie de quickstart/v11 op GitHub voor meer voorbeelden.

Andere SDK's

U kunt elke ondersteunde SDK gebruiken om een zoekindex bij te werken. Ze bieden allemaal een SearchIndexClient met methoden voor het bijwerken van indexen.

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

Query uitvoeren op equivalente of toegewezen velden

Een synoniemveldtoewijzing verandert niet hoe u query's schrijft. Na de toewijzing van synoniementoewijzing is het enige verschil dat als er een queryterm bestaat in de synoniementoewijzing, de zoekmachine de term of woordgroep uitbreidt of herschrijft, afhankelijk van de regel.

Hoe synoniemen worden gebruikt tijdens het uitvoeren van query's

Synoniemen zijn een queryuitbreidingstechniek die de inhoud van een index aanvullen met equivalente termen, maar alleen voor velden met een synoniemtoewijzing. Als een veldquery een veld met een veldbereik uitsluit , ziet u geen overeenkomsten van de synoniementoewijzing.

Voor velden met synoniemen zijn synoniemen onderworpen aan dezelfde tekstanalyse als het bijbehorende veld. Als een veld bijvoorbeeld wordt geanalyseerd met behulp van de standaard Lucene-analyse, zijn synoniemtermen ook onderhevig aan de standaard Lucene-analyse op het moment van query's. Als u interpunctie wilt behouden, zoals punten of streepjes, past u in de synoniemterm een analyse met inhoudsbehoud toe op het veld.

Intern herschrijft de functie synoniemen de oorspronkelijke query met synoniemen met behulp van de OPERATOR OR. Daarom behandelen markerings- en scoreprofielen de oorspronkelijke term en synoniemen als gelijkwaardig.

Synoniemen zijn alleen van toepassing op vrije tekstquery's en worden niet ondersteund voor filters, facetten, automatisch aanvullen of suggesties. Automatisch aanvullen en suggesties zijn alleen gebaseerd op de oorspronkelijke term; Synoniemenovereenkomsten worden niet weergegeven in het antwoord.

Als u een bestaande index in een ontwikkelomgeving (niet-productieomgeving) hebt, kunt u experimenteren met een kleine woordenlijst om te zien hoe de toevoeging van synoniemen de zoekervaring wijzigt, inclusief invloed op scoreprofielen, het markeren van treffers en suggesties.

Zoekopdrachten met jokertekens

Synoniemenuitbreidingen zijn niet van toepassing op zoektermen met jokertekens; voorvoegsel, fuzzy en regex-termen worden niet uitgevouwen.

Als u één query wilt uitvoeren waarmee synoniemenuitbreiding en jokertekens, regex- of fuzzy zoekopdrachten worden toegepast, kunt u de query's combineren met behulp van de OR-syntaxis. Als u bijvoorbeeld synoniemen wilt combineren met jokertekens voor eenvoudige querysyntaxis, zou de term zijn <query> | <query>*.

Volgende stap

Een synoniemenkaart maken (REST API)