Synoniemen in Azure AI Search

In een zoekservice zijn synoniemenkaarten een globale resource die equivalente termen koppelt, waardoor het bereik van een query wordt uitgebreid zonder dat de gebruiker de term daadwerkelijk hoeft op te geven. Als bijvoorbeeld 'hond', 'canine' en 'puppy' synoniemen zijn toegewezen, komt een query op 'canine' overeen met een document met 'hond'.

Synoniemen maken

Een synoniemenkaart is een asset die eenmaal kan worden gemaakt en door veel indexen kan worden gebruikt. De servicelaag bepaalt hoeveel synoniemenkaarten u kunt maken, variërend van drie synoniemenkaarten voor gratis en Basic-lagen, tot 20 voor de Standard-lagen.

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. Hoewel u meerdere synoniementoewijzingen in uw zoekservice kunt maken, kan een velddefinitie slechts één synoniemtoewijzingstoewijzing hebben binnen een index.

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.

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

Als u een synoniemenkaart wilt maken, moet u dit programmatisch doen (de portal biedt geen ondersteuning voor synoniementoewijzingsdefinities):

• Synoniemtoewijzing (REST API) maken. Deze verwijzing is de meest beschrijvende.
• SynonymMap-klasse (.NET) en een synoniemenkaart maken (Azure SDK-voorbeeld)
• SynonymMap-klasse (Python)
• SynonymMap-interface (JavaScript)
• SynonymMap-klasse (Java)

Regels definiëren

Toewijzingsregels voldoen aan de opensource-filterspecificatie van Apache Solr, zoals beschreven in dit document: SynonymFilter. 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 voorafgaand aan het uitvoeren van query's)

Elke regel moet worden 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) hebben. Zie Synoniemenlimieten voor meer informatie.

Queryparsers maken automatisch kleine letters voor hoofdletters of gemengde hoofdletters, maar 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 uit USA naar USA OR OF "United States""United States of America". Als u wilt overeenkomen met een woordgroep, moet de query zelf een woordgroepsquery tussen aanhalingstekens zijn.

In het gelijkwaardigheidsscenario breidt een query dog de query uit zodat deze ook wordt opgenomen puppy en canine.

{
"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 , of wordt herschreven als WA, en de query-engine zoekt alleen naar overeenkomsten op de term WA.WAWash.Washington Expliciete toewijzing is alleen van toepassing in de opgegeven richting en de query WAWashington wordt in dit geval niet opnieuw geschreven.

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

Speciale tekens ontsnappen

In zoekopdrachten in volledige tekst worden synoniemen geanalyseerd tijdens het verwerken van query's, net als elke andere queryterm, wat betekent dat regels rond gereserveerde en speciale tekens van toepassing zijn op de termen in uw synoniemenkaart. De lijst met tekens waarvoor escape-tekens zijn vereist, varieert tussen de eenvoudige syntaxis en de volledige syntaxis:

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

Denk eraan dat als u tekens wilt behouden die anders tijdens het indexeren door de standaardanalyse zouden worden verwijderd, u een analyse moet vervangen 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. De JSON die is verzonden naar de REST API voor de bovenstaande synoniemenkaart ziet er bijvoorbeeld als volgt uit:

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

Synoniemenkaarten uploaden en beheren

Zoals eerder vermeld, kunt u een synoniemenkaart maken of bijwerken zonder query's en indexeringsworkloads te verstoren. Een synoniemenkaart is een zelfstandig object (zoals indexen of gegevensbronnen) en zolang er geen veld wordt gebruikt, kunnen indexeringen of query's niet mislukken door updates. Als u echter een synoniementoewijzing toevoegt aan een velddefinitie, mislukt elke query met de betreffende velden met een 404-fout als u vervolgens een synoniemtoewijzing verwijdert.

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

Synoniemen toewijzen aan velden

Nadat u een synoniemenkaart hebt geüpload, kunt u de synoniemen inschakelen voor velden van het type Edm.String of Collection(Edm.String), op velden met "searchable":true. Zoals vermeld, kan een velddefinitie slechts één synoniemtoewijzing gebruiken.

POST /indexes?api-version=2023-11-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"
            ]
        }
    ]
}

Query uitvoeren op equivalente of toegewezen velden

Het toevoegen van synoniemen legt geen nieuwe vereisten op voor het bouwen van query's. U kunt termen- en woordgroepenquery's net als voor de toevoeging van synoniemen uitgeven. Het enige verschil is dat als er een queryterm bestaat in de synoniementoewijzing, de query-engine de term of woordgroep zal uitbreiden of herschrijven, 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 Analyzer tijdens het uitvoeren 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 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.

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

Als u een bestaande index in een ontwikkelomgeving (niet-productie) hebt, experimenteert u 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.

Volgende stappen

Een synoniemenkaart maken (REST API)