Synonyme in Azure SearchSynonyms in Azure Search

Synonyme in Suchmaschinen ordnen entsprechende Begriffe zu, die den Bereich einer Abfrage implizit erweitern, ohne dass der Benutzer den Begriff tatsächlich bereitstellen muss.Synonyms in search engines associate equivalent terms that implicitly expand the scope of a query, without the user having to actually provide the term. Bei dem Begriff „Hund“ und Synonymzuordnungen von „hündisch“ und „Welpe“ fallen z. B. alle Dokumente, die „Hund“, „hündisch“ oder „Welpe“ enthalten, in den Gültigkeitsbereich der Abfrage.For example, given the term "dog" and synonym associations of "canine" and "puppy", any documents containing "dog", "canine" or "puppy" will fall within the scope of the query.

In Azure Search erfolgt die Synonymerweiterung zur Abfragezeit.In Azure Search, synonym expansion is done at query time. Sie können Synonymzuordnungen zu einem Dienst hinzufügen, ohne vorhandene Vorgänge zu stören.You can add synonym maps to a service with no disruption to existing operations. Sie können eine synonymMaps-Eigenschaft zu einer Felddefinition hinzufügen, ohne den Index neu erstellen zu müssen.You can add a synonymMaps property to a field definition without having to rebuild the index.

Erstellen von SynonymenCreate synonyms

Die Erstellung von Synonymen wird über das Portal nicht unterstützt, Sie können dafür jedoch die REST-API oder das .NET SDK verwenden.There is no portal support for creating synonyms but you can use the REST API or .NET SDK. Zum Einstieg in REST werden die Verwendung von Postman und die Erstellung von Anforderungen mit der folgenden API empfohlen: Create Synonym Map.To get started with REST, we recommend using Postman and formulation of requests using this API: Create Synonym Maps. C#-Entwickler können mit dem Hinzufügen von Synonymen in Azure Search mit C# beginnen.For C# developers, you can get started with Add Synonyms in Azure Searching using C#.

Bei Verwendung von von Kunden verwalteten Schlüsseln für die dienstseitige Verschlüsselung ruhender Daten können Sie diesen Schutz optional auf die Inhalte der Synonymzuordnung anwenden.Optionally, if you are using customer-managed keys for service-side encryption-at-rest, you can apply that protection to the contents of your synonym map.

Verwenden von SynonymenUse synonyms

In Azure Search basiert die Synonymunterstützung auf Synonymzuordnungen, die Sie definieren und zu Ihrem Dienst hochladen.In Azure Search, synonym support is based on synonym maps that you define and upload to your service. Diese Zuordnungen bilden eine unabhängige Ressource (wie Indizes oder Datenquellen) und können von jedem durchsuchbaren Feld in einem beliebigen Index in Ihrem Suchdienst verwendet werden.These maps constitute an independent resource (like indexes or data sources), and can be used by any searchable field in any index in your search service.

Synonymzuordnungen und Indizes werden unabhängig voneinander verwaltet.Synonym maps and indexes are maintained independently. Nachdem Sie eine Synonymzuordnung definiert und zu Ihrem Dienst hochgeladen haben, können Sie die Synonymfunktion für ein Feld aktivieren, indem Sie eine neue Eigenschaft namens synonymMaps in der Felddefinition hinzufügen.Once you define a synonym map and upload it to your service, you can enable the synonym feature on a field by adding a new property called synonymMaps in the field definition. Das Erstellen, Aktualisieren und Löschen einer Synonymzuordnung betrifft immer das ganze Dokument. Daher können Sie keine Teile der Synonymzuordnung inkrementell erstellen, aktualisieren oder löschen.Creating, updating, and deleting a synonym map is always a whole-document operation, meaning that you cannot create, update or delete parts of the synonym map incrementally. Selbst das Aktualisieren eines einzelnen Eintrags erfordert das erneute Laden.Updating even a single entry requires a reload.

Das Integrieren von Synonymen in Ihre Suchanwendung ist ein zweistufiger Prozess:Incorporating synonyms into your search application is a two-step process:

  1. Fügen Sie Ihrem Suchdienst über die nachfolgenden APIs eine Synonymzuordnung hinzu.Add a synonym map to your search service through the APIs below.

  2. Konfigurieren Sie ein durchsuchbares Feld, um die Synonymzuordnung in der Indexdefinition zu verwenden.Configure a searchable field to use the synonym map in the index definition.

Ressourcen-APIs von SynonymMapsSynonymMaps Resource APIs

Fügen Sie eine Synonymzuordnung mithilfe von POST oder PUT unter Ihrem Dienst hinzu, oder aktualisieren Sie sie.Add or update a synonym map under your service, using POST or PUT.

Synonymzuordnungen werden über POST oder PUT zum Dienst hochgeladen.Synonym maps are uploaded to the service via POST or PUT. Jede Regel muss durch das Zeilenumbruchzeichen („\n“) getrennt werden.Each rule must be delimited by the new line character ('\n'). Sie können bis zu 5.000 Regeln pro Synonymzuordnung in einem kostenlosen Dienst und 10.000 Regeln in allen anderen SKUs definieren.You can define up to 5,000 rules per synonym map in a free service and 10,000 rules in all other SKUs. Jede Regel kann bis zu 20 Erweiterungen aufweisen.Each rule can have up to 20 expansions.

Synonymzuordnungen müssen das unten beschriebene „Apache Solr“-Format aufweisen.Synonym maps must be in the Apache Solr format which is explained below. Wenn ein vorhandenes Synonymwörterbuch in einem anderen Format vorliegt und sie es direkt verwenden möchten, können Sie uns über UserVoice informieren.If you have an existing synonym dictionary in a different format and want to use it directly, please let us know on UserVoice.

Sie können eine neue Synonymzuordnung mithilfe von HTTP POST erstellen, wie im folgenden Beispiel:You can create a new synonym map using HTTP POST, as in the following example:

POST https://[servicename].search.windows.net/synonymmaps?api-version=2019-05-06
api-key: [admin key]

{
   "name":"mysynonymmap",
   "format":"solr",
   "synonyms": "
      USA, United States, United States of America\n
      Washington, Wash., WA => WA\n"
}

Alternativ können Sie PUT verwenden und den Namen der Synonymzuordnung für den URI angeben.Alternatively, you can use PUT and specify the synonym map name on the URI. Wenn die Synonymzuordnung nicht vorhanden ist, wird sie erstellt.If the synonym map does not exist, it will be created.

PUT https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2019-05-06
api-key: [admin key]

{
   "format":"solr",
   "synonyms": "
      USA, United States, United States of America\n
      Washington, Wash., WA => WA\n"
}
Apache Solr-SynonymformatApache Solr synonym format

Das Solr-Format unterstützt vergleichbare und explizite Synonymzuordnungen.The Solr format supports equivalent and explicit synonym mappings. Zuordnungsregeln entsprechen den Open-Source-Synonymfilterspezifikation von Apache Solr, die im folgenden Dokument beschrieben ist: SynonymFilter.Mapping rules adhere to the open-source synonym filter specification of Apache Solr, described in this document: SynonymFilter. Im folgenden finden Sie eine Beispielregel für vergleichbare Synonyme.Below is a sample rule for equivalent synonyms.

USA, United States, United States of America

Mit der obigen Regel wird die Suchabfrage „USA“ zu „USA“ ODER „Vereinigte Staaten“ ODER „Vereinigte Staaten von Amerika“ erweitert.With the rule above, a search query "USA" will expand to "USA" OR "United States" OR "United States of America".

Eine explizite Zuordnung wird durch einen Pfeil gekennzeichnet „=>“.Explicit mapping is denoted by an arrow "=>". Eine Begriffsfolge (sofern angegeben) einer Suchabfrage, die den linken Teil von „=>“ vergleicht, wird durch die Alternativen auf der rechten Seite ersetzt.When specified, a term sequence of a search query that matches the left-hand side of "=>" will be replaced with the alternatives on the right-hand side. Bei der nachfolgenden Regel werden die Suchabfragen „Washington“, „Wash.“Given the rule below, search queries "Washington", "Wash." oder „WA“ alle in „WA“ umgeschrieben.or "WA" will all be rewritten to "WA". Die explizite Zuordnung gilt nur für die angegebene Richtung und schreibt in diesem Fall die Abfrage „WA“ nicht zu „Washington“ um.Explicit mapping only applies in the direction specified and does not rewrite the query "WA" to "Washington" in this case.

Washington, Wash., WA => WA

Listen Sie Synonymzuordnungen unter Ihrem Dienst auf.List synonym maps under your service.

GET https://[servicename].search.windows.net/synonymmaps?api-version=2019-05-06
api-key: [admin key]

Rufen Sie eine Synonymzuordnung unter Ihrem Dienst ab.Get a synonym map under your service.

GET https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2019-05-06
api-key: [admin key]

Löschen Sie eine Synonymzuordnung unter Ihrem Dienst.Delete a synonyms map under your service.

DELETE https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2019-05-06
api-key: [admin key]

Konfigurieren Sie ein durchsuchbares Feld, um die Synonymzuordnung in der Indexdefinition zu verwenden.Configure a searchable field to use the synonym map in the index definition.

Es kann die neue synonymMaps-Feldeigenschaft verwendet werden, um eine Synonymzuordnung anzugeben, die für ein durchsuchbares Feld verwendet werden soll.A new field property synonymMaps can be used to specify a synonym map to use for a searchable field. Synonymzuordnungen sind Ressourcen der Dienstebene. Jedes Feld eines Index unter dem Dienst kann auf die Zuordnungen verweisen.Synonym maps are service level resources and can be referenced by any field of an index under the service.

POST https://[servicename].search.windows.net/indexes?api-version=2019-05-06
api-key: [admin key]

{
   "name":"myindex",
   "fields":[
      {
         "name":"id",
         "type":"Edm.String",
         "key":true
      },
      {
         "name":"name",
         "type":"Edm.String",
         "searchable":true,
         "analyzer":"en.lucene",
         "synonymMaps":[
            "mysynonymmap"
         ]
      },
      {
         "name":"name_jp",
         "type":"Edm.String",
         "searchable":true,
         "analyzer":"ja.microsoft",
         "synonymMaps":[
            "japanesesynonymmap"
         ]
      }
   ]
}

synonymMaps kann für durchsuchbare Felder vom Typ „Edm.String“ oder „Collection(Edm.String)“ angegeben werden.synonymMaps can be specified for searchable fields of the type 'Edm.String' or 'Collection(Edm.String)'.

Hinweis

Sie können nur eine Synonymzuordnung pro Feld verwenden.You can only have one synonym map per field. Wenn Sie mehrere Synonymzuordnungen verwenden möchten, können Sie uns über UserVoice informieren.If you want to use multiple synonym maps, please let us know on UserVoice.

Auswirkungen von Synonymen auf andere SuchfeaturesImpact of synonyms on other search features

Das Feature „Synonyme“ ändert die ursprüngliche Abfrage mithilfe von Synonymen mit dem OR-Operator.The synonyms feature rewrites the original query with synonyms with the OR operator. Aus diesem Grund werden der ursprüngliche Begriff und Synonyme von der Treffermarkierung und von Bewertungsprofilen als gleichwertig behandelt.For this reason, hit highlighting and scoring profiles treat the original term and synonyms as equivalent.

Das Feature „Synonyme“ gilt für Suchabfragen und nicht für Filter oder Facets.Synonym feature applies to search queries and does not apply to filters or facets. Ebenso basieren Vorschläge nur auf dem ursprünglichen Begriff. Synonymübereinstimmungen werden in der Antwort nicht angezeigt.Similarly, suggestions are based only on the original term; synonym matches do not appear in the response.

Die Synonymerweiterungen gelten nicht für Platzhaltersuchbegriffe. Präfix-, Fuzzy- und Regex-Begriffe werden nicht erweitert.Synonym expansions do not apply to wildcard search terms; prefix, fuzzy, and regex terms aren't expanded.

Wenn Sie eine einzelne Abfrage, die eine Synonymerweiterung sowie Platzhalter-, Regex- und Fuzzysuche umfasst, durchführen möchten, können Sie die Abfragen mit der OR-Syntax kombinieren.If you need to do a single query that applies synonym expansion and wildcard, regex, or fuzzy searches, you can combine the queries using the OR syntax. Um beispielsweise Synonyme mit Platzhaltern für eine einfache Abfragesyntax zu kombinieren, lautet der Begriff <query> | <query>*.For example, to combine synonyms with wildcards for simple query syntax, the term would be <query> | <query>*.

Tipps zum Erstellen einer SynonymzuordnungTips for building a synonym map

  • Eine präzise, ausgereifte Synonymzuordnung ist effizienter als eine vollständige Liste möglicher Übereinstimmungen.A concise, well-designed synonym map is more efficient than an exhaustive list of possible matches. Die Analyse übermäßig großer oder komplexer Wörterbücher dauert länger und wirkt sich auf die Abfragewartezeit aus, wenn bei der Abfrage zu viele Synonyme erweitert werden.Excessively large or complex dictionaries take longer to parse and affect the query latency if the query expands to many synonyms. Anstatt zu erraten, welche Begriffe verwendet werden, können Sie die tatsächlichen Begriffe über einen Analysebericht zum Suchdatenverkehr abrufen.Rather than guess at which terms might be used, you can get the actual terms via a search traffic analysis report.

  • Aktivieren Sie diesen Bericht sowohl zur Vorbereitung als auch zur Überprüfung und verwenden Sie ihn, um genau zu ermitteln, welche Begriffe von einer Synonymzuordnung profitieren. Verwenden Sie ihn dann zur Überprüfung, ob Ihre Synonymzuordnung zu besserer Ergebnissen führt.As both a preliminary and validation exercise, enable and then use this report to precisely determine which terms will benefit from a synonym match, and then continue to use it as validation that your synonym map is producing a better outcome. Im vordefinierten Bericht enthalten die Kacheln für „Häufigste Suchabfragen“ und „Suchabfragen ohne Ergebnis“ die erforderlichen Informationen.In the predefined report, the tiles "Most common search queries" and "Zero-result search queries" will give you the necessary information.

  • Sie können mehrere Synonymzuordnungen für Ihre Suchanwendung erstellen (z. B. nach Sprache, wenn Ihre Anwendung einen mehrsprachigen Kundenstamm unterstützt).You can create multiple synonym maps for your search application (for example, by language if your application supports a multi-lingual customer base). Derzeit kann ein Feld nur eine der Zuordnungen verwenden.Currently, a field can only use one of them. Sie können die „synonymMaps“-Eigenschaft für ein Feld jederzeit aktualisieren.You can update a field's synonymMaps property at any time.

Nächste SchritteNext steps

  • Wenn Sie über einen vorhandenen Index in einer Entwicklungsumgebung (nicht Produktionsumgebung) verfügen, experimentieren Sie mit einem kleinen Wörterbuch, um zu prüfen, wie sich das Hinzufügen von Synonymen auf die Suche auswirkt, einschließlich der Auswirkungen auf Bewertungsprofile, Treffermarkierungen und Vorschläge.If you have an existing index in a development (non-production) environment, experiment with a small dictionary to see how the addition of synonyms changes the search experience, including impact on scoring profiles, hit highlighting, and suggestions.

  • Aktivieren Sie die Datenverkehrsanalyse für Suchen, und verwenden Sie den vordefinierten Power BI-Bericht, um zu erfahren, welche Begriffe am meisten verwendet werden und welche Begriffe keine Dokumente zurückgeben.Enable search traffic analytics and use the predefined Power BI report to learn which terms are used the most, and which ones return zero documents. Überarbeiten Sie das Wörterbuch unter Einbeziehung dieser Erkenntnisse, um Synonyme für unproduktive Abfragen einzubeziehen, die zu Dokumenten in Ihrem Index führen sollten.Armed with these insights, revise the dictionary to include synonyms for unproductive queries that should be resolving to documents in your index.