Erstellen Sie einen Index in Azure AI Search

In diesem Artikel lernen Sie die Schritte zum Definieren eines Schemas für einen Suchindex und zum Pushen dieses Index an einen Suchdienst kennen. Durch die Erstellung eines Indexes werden die physischen Datenstrukturen Ihres Suchdienstes festgelegt. Wenn er vorhanden ist, laden Sie den Index in einer separaten Aufgabe.

Voraussetzungen

• Schreibberechtigungen als Suchdienstmitwirkender oder einen Administrator-API-Schlüssel für die schlüsselbasierte Authentifizierung.

• Ein Verständnis der Daten, die Sie indizieren möchten. Ein Suchindex basiert auf externen Inhalten, die durchsuchbar gemacht werden sollen. Durchsuchbare Inhalte werden als Felder in einem Index gespeichert. Sie sollten eine klare Vorstellung davon haben, welche Quellfelder in Azure KI-Suche durchsuchbar, abrufbar, filterbar, facettierbar und sortierbar sein sollen. Eine Anleitung finden Sie in der Schemaprüfliste.

• Sie müssen auch ein eindeutiges Feld in den Quelldaten haben, das als Dokumentenschlüssel (oder ID) im Index verwendet werden kann.

• Eine stabile Indexposition. Das Verschieben eines vorhandenen Index zu einem anderen Suchdienst wird nicht sofort unterstützt. Sehen Sie sich die Anwendungsanforderungen erneut an, und vergewissern Sie sich, dass Ihr vorhandener Suchdienst (Kapazität und Region) für Ihre Anforderungen ausreichend sind. Bei einer Abhängigkeit von Azure KI Services oder Azure OpenAI wählen Sie eine Region aus, die alle erforderlichen Ressourcen bereitstellt.

• Schließlich verfügen alle Dienstebenen über Indexgrenzwerte für die Anzahl von Objekten, die Sie erstellen können. Wenn Sie z. B. mit der kostenlosen Version experimentieren, können Sie immer nur drei Indizes gleichzeitig haben. Innerhalb des Index selbst gibt es Grenzwerte für Vektoren und Indexgrenzwerte für die Anzahl einfacher und komplexer Felder.

Dokumentschlüssel

Bei der Suchindexerstellung gelten zwei Anforderungen: Ein Index muss einen eindeutigen Namen im Suchdienst haben und einen Dokumentschlüssel besitzen. Das boolesche Attribut key für ein Feld kann auf „true“ festgelegt werden, um anzugeben, welches Feld den Dokumentschlüssel bereitstellt.

Ein Dokumentschlüssel ist der eindeutige Bezeichner eines Suchdokuments, und ein Suchdokument ist eine Sammlung von Feldern, die etwas vollständig beschreiben. Wenn Sie beispielsweise einen Filmdatensatzindizieren, enthält ein Suchdokument den Titel, das Genre und die Dauer der einzelnen Filme. Filmnamen sind in diesem Dataset eindeutig, daher können Sie den Filmnamen als Dokumentschlüssel verwenden.

In Azure KI-Suche ist ein Dokumentschlüssel eine Zeichenfolge, die aus eindeutigen Werten in der Datenquelle stammt, die den zu indizierenden Inhalt bereitstellt. Ein Suchdienst generiert im Allgemeinen keine Schlüsselwerte, aber in einigen Szenarien (wie dem Azure-Tabellenindexer) synthetisiert er vorhandene Werte, um einen eindeutigen Schlüssel für die zu indizierenden Dokumente zu erstellen. Ein weiteres Szenario ist die 1:n-Indizierung für in Blöcke unterteilte oder partitionierte Daten. In diesem Fall werden Dokumentschlüssel für jeden Block generiert.

Bei der inkrementellen Indizierung, bei der neue und aktualisierte Inhalte indiziert werden, werden eingehende Dokumente mit neuen Schlüsseln hinzugefügt, während eingehende Dokumente mit vorhandenen Schlüsseln entweder zusammengeführt oder überschrieben werden, je nachdem, ob Indexfelder leer oder gefüllt sind.

Wichtige Punkte zu Dokumentschlüsseln:

• Werte in einem Schlüsselfeld dürfen maximal 1.024 Zeichen lang sein.
• Es muss genau ein Feld auf oberster Ebene in jedem Index als Schlüsselfeld ausgewählt werden, und es muss vom Typ Edm.String sein.
• Der Standardwert des Attributs key ist „false“ für einfache Felder und NULL für komplexe Felder.

Schlüsselfelder können verwendet werden, um Dokumente direkt nachzuschlagen und bestimmte Dokumente zu aktualisieren oder zu löschen. Die Werte von Schlüsselfeldern werden beim Nachschlagen oder Indizieren von Dokumenten unter Berücksichtigung der Groß- und Kleinschreibung behandelt. Ausführliche Informationen finden Sie unter GET – Dokument (REST) und Indexdokumente (REST).

Schemaprüfliste

Verwenden Sie diese Prüfliste bei den Entwurfsentscheidungen für Ihren Suchindex.

1. Überprüfen Sie die Benennungskonventionen, damit Index- und Feldnamen den Benennungsregeln entsprechen.

2. Sehen Sie sich die unterstützten Datentypen an. Der Datentyp hat EinFlow auf die Verwendung des Feldes. Numerische Inhalte können beispielsweise gefiltert, aber nicht per Volltextsuche durchsucht werden. Der gängigste Datentyp ist Edm.String für durchsuchbaren Text, in Token umgewandelt und abgefragt mithilfe der Volltextsuchmaschine. Der gängigste Datentyp für ein Vektorfeld ist Edm.Single, Sie können jedoch auch andere Typen verwenden.

3. Identifizieren Sie einen Dokumentschlüssel. Ein Dokumentschlüssel ist eine Anforderung für einen Index. Es handelt sich um ein einzelnes Zeichenfolgenfeld, das aus einem Quelldatenfeld mit eindeutigen Werten gespeist wird. Beispiel: Beim Indizieren über Blob Storage wird der Metadatenspeicherpfad häufig als Dokumentschlüssel verwendet, da er jeden Blob im Container eindeutig identifiziert.

4. Identifizieren Sie die Felder in Ihrer Datenquelle, die zu durchsuchbaren Inhalten im Index beitragen.

   Durchsuchbare Nicht-Vektorinhalte sind beispielsweise kurze oder lange Zeichenfolgen, die mit dem Volltext-Suchmodul abgefragt werden. Wenn der Inhalt ausführlich ist (kleine Ausdrücke oder größere Blöcke), experimentieren Sie mit verschiedenen Analyzern, um zu sehen, wie der Text in Token umgewandelt wird.

   Durchsuchbare Vektorinhalte können Bilder oder Text (in einer beliebigen Sprache) sein, die als mathematische Darstellung vorhanden sind. Sie können schlanke Datentypen oder die Vektorkomprimierung verwenden, um Vektorfelder zu verkleinern.

   Für Felder festgelegte Attribute wie retrievable oder filterable bestimmen sowohl das Suchverhalten als auch die physische Darstellung Ihres Index im Suchdienst. Festzulegen, mit welchen Attributen Felder versehen werden sollen, ist für viele Entwickler ein iterativer Prozess. Um Iterationen zu beschleunigen, beginnen Sie mit Beispieldaten, damit Sie problemlos löschen und neu erstellen können.

5. Identifizieren Sie, welche Quellfelder als Filter verwendet werden können. Numerische Inhalte und kurze Textfelder, insbesondere solche mit sich wiederholenden Werten, sind gute Optionen. Beachten Sie beim Arbeiten mit Filtern Folgendes:

   • Filter können in Vektor- und Nicht-Vektorabfragen verwendet werden. Der Filter selbst wird aber auf alphanumerische (Nicht-Vektor-)Felder in Ihrem Index angewandt.

   • Filterbare Felder können optional in der Facettennavigation verwendet werden.

   • Filterbare Felder werden in beliebiger Reihenfolge zurückgegeben und unterliegen keiner Relevanzbewertung. Erwägen Sie daher, sie auch sortierbar zu machen.

6. Geben Sie für Vektorfelder eine Konfiguration für die Vektorsuche und die Algorithmen an, die zum Erstellen von Navigationspfaden und zum Ausfüllen des Einbettungsbereichs verwendet werden. Weitere Informationen finden Sie unter Hinzufügen von Vektorfeldern.

   Vektorfelder weisen zusätzliche Eigenschaften auf, die Nicht-Vektorfelder nicht enthalten, z. B. für die zu verwendenden Algorithmen und die Vektorkomprimierung.

   Attribute, die für Vektordaten nicht erforderlich sind, z. B. für Sortierung, Filterung und Facettierung, sind in Vektorfeldern nicht enthalten.

7. Legen Sie für Nicht-Vektorfelder fest, ob Sie das Standardanalysetool ("analyzer": null) oder ein anderes Analysetool verwenden möchten. Analysetools werden verwendet, um Textfelder während der Indizierung und Abfrageausführung mit Token zu versehen.

   Für mehrsprachige Zeichenketten wird ein Sprachanalysator verwendet.

   Für Strings mit Bindestrich oder Sonderzeichen sollten Sie spezialisierte Analysatoren in Betracht ziehen. Ein Beispiel hierfür ist ein Schlüsselwort, durch das der gesamte Inhalt eines Felds als ein einzelnes Token behandelt wird. Dieses Verhalten ist nützlich für Daten wie Postleitzahlen, IDs und einige Produktnamen. Weitere Informationen finden Sie unter Suche nach Teilausdrücken und Mustern mit Sonderzeichen (Bindestriche, Platzhalter, reguläre Ausdrücke, Muster).

Konfigurieren von Felddefinitionen

Mit der Feldsammlung wird die Struktur eines Suchdokuments definiert. Alle Felder besitzen einen Namen, Datentyp und Attribute.

Das Festlegen eines Felds als durchsuchbar, filterbar, sortierbar oder facettierbar wirkt sich auf die Indexgröße und die Abfrageleistung aus. Legen Sie diese Attribute nicht für Felder fest, auf die in Abfrageausdrücken nicht verwiesen werden soll.

Wenn ein Feld nicht als durchsuchbar, filterbar, sortierbar oder facettierbar festgelegt ist, kann auf das Feld in keinem Abfrageausdruck verwiesen werden. Dies ist für Felder wünschenswert, die nicht in Abfragen verwendet werden, aber in den Suchergebnissen erforderlich sind.

Die REST-APIs verfügen über Standardzuordnungen basierend auf Datentypen, die auch von den Import-Assistenten im Azure-Portal verwendet wird. Die Azure-SDKs weisen keine Standards, aber Feldunterklassen auf, die Eigenschaften und Verhaltensweisen enthalten, z. B. SearchableField für Zeichenfolgen und SimpleField für Primitiven.

Standardfeldzuordnungen für die REST-APIs werden in der folgenden Tabelle zusammengefasst.

Zeichenfolgenfelder können auch optional mit Analysemethoden und Synonymzuordnungen verknüpft werden. Felder vom Typ Edm.String, die filterbar, sortierbar oder facettierbar sind, dürfen höchstens 32 KB lang sein. Grund hierfür ist, dass Werte dieser Felder wie einzelne Suchbegriffe behandelt werden und die maximale Länge eines Begriffs in Azure KI-Suche 32 KB beträgt. Wenn Sie in einem Zeichenfolgenfeld mehr Text speichern müssen, setzen Sie filterbar, sortierbar und facettierbar in Ihrer Indexdefinition explizit auf false.

Vektorfelder müssen Dimensionen und Vektorprofile zugeordnet werden. Der abrufbare Standardwert ist „true“, wenn Sie das Vektorfeld mithilfe des Assistenten zum Importieren und Vektorisieren im Portal hinzufügen. Andernfalls ist er „false“, wenn Sie die REST-API verwenden.

Feldattribute werden in der folgenden Tabelle beschrieben.

Erstellen eines Index

Wenn Sie bereit sind, den Index zu erstellen, verwenden Sie einen Suchclient, der die Anforderung senden kann. Für die anfängliche Entwicklung sowie für Proof of Concept-Tests empfiehlt sich die Verwendung des Azure-Portals oder der REST-APIs, andernfalls werden dazu auch die Azure-SDKs verwendet.

Planen Sie während der Entwicklung häufige Neuerstellungen ein. Da physische Strukturen im Dienst erstellt werden, ist bei vielen Änderungen das Löschen und Neuerstellen von Indizes erforderlich. Sie sollten erwägen, mit einer Teilmenge Ihrer Daten zu arbeiten, damit Neuerstellungen schneller gehen.

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)[ ... ]
}

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

corsOptions für ursprungsübergreifende Abfragen festlegen

Indexschemas enthalten einen Abschnitt zum Festlegen von corsOptions. Standardmäßig kann clientseitiges JavaScript keine APIs aufrufen, da die Browser alle herkunftsübergreifenden Anfragen verhindern. Um herkunftsübergreifende Abfragen an Ihren Index zu ermöglichen, aktivieren Sie CORS (Cross-Origin Resource Sharing), indem Sie das Attribut corsOptions setzen. Aus Sicherheitsgründen wird CORS nur von Abfrage-APIs unterstützt.

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

Die folgenden Eigenschaften können für CORS festgelegt werden:

• allowedOrigins (erforderlich): Dies ist eine Liste von Herkunftsländern, die Zugriff auf Ihren Index haben. JavaScript-Code, der von diesen Ursprüngen geliefert wird, darf Ihren Index abfragen (vorausgesetzt, der Aufrufer gibt einen gültigen Schlüssel an oder verfügt über Berechtigungen). Ursprünge werden in der Regel im Format protocol://<fully-qualified-domain-name>:<port> angegeben, wobei <port> häufig weggelassen wird. Weitere Informationen finden Sie unter Ursprungsübergreifende Ressourcennutzung (Wikipedia).

  Wenn Sie den Zugriff auf alle Ursprünge zulassen möchten, beziehen Sie * als ein einzelnes Element in das Array allowedOrigins ein. Dies ist keine empfohlene Praxis für produktive Suchdienste, aber es ist oft nützlich für die Entwicklung und Fehlersuche.

• maxAgeInSeconds (optional): Browser verwenden diesen Wert, um die Dauer (in Sekunden) für das Caching von CORS-Preflight-Antworten zu bestimmen. Dies muss eine positive ganze Zahl sein. Ein längerer Cache-Zeitraum sorgt für eine bessere Leistung, verlängert aber die Zeit, die eine CORS-Richtlinie benötigt, um wirksam zu werden. Wenn dieser Wert nicht festgelegt ist, wird eine Standarddauer von fünf Minuten verwendet.

Zulässige Updates für vorhandene Indizes

Index erstellen erstellt die physischen Datenstrukturen (Dateien und invertierte Indizes) in Ihrem Suchdienst. Nachdem der Index erstellt wurde, hängt die Möglichkeit, Änderungen mithilfe von Index erstellen oder aktualisieren vorzunehmen, davon ab, ob diese physischen Strukturen durch Ihre Änderungen ungültig werden. Die meisten Feldattribute können nicht mehr geändert werden, nachdem das Feld in Ihrem Index erstellt wurde.

Zum Minimieren von Churn im Anwendungscode können Sie einen Indexalias erstellen, der als stabiler Verweis im Suchindex dient. Anstatt Ihren Code mit Indexnamen zu aktualisieren, können Sie einen Indexalias aktualisieren, um auf neuere Indexversionen zu verweisen.

Um die Änderungsrate im Entwurfsprozess zu minimieren, wird in der folgenden Tabelle beschrieben, welche Elemente im Schema fest und welche flexibel sind. Das Ändern eines festen Elements erfordert eine Indexneuerstellung, während flexible Elemente jederzeit ohne Beeinträchtigung der physischen Implementierung geändert werden können. Weitere Informationen finden Sie unter Aktualisieren oder Neuerstellen eines Indexes.

Nächste Schritte

Unter den folgenden Links erfahren Sie mehr über spezielle Features, die einem Index hinzugefügt werden können:

• Hinzufügen von Vektorfeldern und Vektorprofilen
• Hinzufügen von Bewertungsprofilen
• Hinzufügen der Zuweisung einer semantischen Rangfolge
• Hinzufügen von Vorschlagsfunktionen
• Hinzufügen von Synonymzuordnungen
• Hinzufügen von Analysemethoden
• Hinzufügen von Verschlüsselung

Verwenden Sie diese Links zum Laden oder Aktualisieren eines Indexes:

• Übersicht über den Datenimport
• Laden von Dokumenten
• Aktualisieren oder Neuerstellen eines Indexes