Zuordnen der angereicherten Ausgabe zu Feldern in einem Suchindex in Azure AI Search

In diesem Artikel wird erläutert, wie Sie Ausgabefeldzuordnungen einrichten, die einen Datenpfad zwischen In-Memory-Daten, die während der Verarbeitung von Skillsets generiert wurden, und Zielfelder in einem Suchindex festlegen. Während der Indexerausführung sind die von Skills generierten Informationen nur im Arbeitsspeicher vorhanden. Um diese Informationen dauerhaft in einen Suchindex zu übernehmen, müssen Sie dem Indexer mitteilen, wohin die Daten gesendet werden sollen.

Eine Ausgabefeldzuordnung wird in einem Indexer definiert und enthält die folgenden Elemente:

"outputFieldMappings": [
  {
    "sourceFieldName": "document/path-to-a-node-in-an-enriched-document",
    "targetFieldName": "some-search-field-in-an-index",
    "mappingFunction": null
  }
],

Im Gegensatz zu einer fieldMappings-Definition, die einen Pfad zwischen wörtlichen Quellfeldern und Indexfeldern abbildet, ordnet eine outputFieldMappings-Definition In-Memory-Anreicherungen den Feldern in einem Suchindex zu.

Voraussetzungen

• Indexer, Index, Datenquelle und Skillset

• Indexfelder müssen einfache Felder oder Felder auf oberster Ebene sein. Die Ausgabe kann nicht in einen komplexen Typ erfolgen. Wenn Sie jedoch über einen komplexen Typ verfügen, können Sie eine Ausgabefelddefinition verwenden, um Teile des komplexen Typs zu vereinfachen und an eine Sammlung in einem Suchindex zu senden.

Verwenden einer Ausgabefeldzuordnung

Ausgabefeldzuordnungen sind erforderlich, wenn der Indexer über ein angefügtes Skillset verfügt, das neue Informationen erstellt, die Sie in Ihren Index einbeziehen möchten. Beispiele:

• Vektoren aus der Einbettung von Skills
• Texterkennung mittels optischer Zeichenerkennung (Optical Character Recognition, OCR) aus Bildskills
• Standorte, Organisationen oder Personen aus Entitätserkennungsskills

Ausgabefeldzuordnung können auch zu folgenden Zwecken verwenden werden:

• Erstellen mehrerer Kopien von generierten Inhalten (1:n-Ausgabefeldzuordnungen)

• Vereinfachen des komplexen Typs eines Quelldokuments Angenommen, Quelldokumente enthalten einen komplexen Typ, z. B. eine mehrteilige Adresse, und Sie möchten nur die Stadt angeben. Sie können eine Ausgabefeldzuordnung verwenden, um eine geschachtelte Datenstruktur zu vereinfachen und dann eine Ausgabefeldzuordnung zu verwenden, um die Ausgabe an eine Zeichenfolgensammlung im Suchindex zu senden.

Ausgabefeldzuordnungen gelten nur für Suchindizes. Wenn Sie einen Wissensspeicher auffüllen, verwenden Sie Projektionen für die Datenpfadkonfiguration.

Definieren einer Ausgabefeldzuordnung

Ausgabefeldzuordnungen werden dem outputFieldMappings-Array in einer Indexerdefinition hinzugefügt und in der Regel nach dem fieldMappings-Array platziert. Eine Ausgabefeldzuordnung besteht aus drei Teilen.

Zum Definieren von Ausgabefeldzuordnungen können Sie die REST-API oder ein Azure SDK verwenden.

Tipp

Vom Datenimport-Assistenten erstellte Indexer umfassen vom Assistenten generierte Ausgabefeldzuordnungen. Wenn Sie Beispiele benötigen, führen Sie den Assistenten für Ihre Datenquelle aus, um die Ausgabefeldzuordnungen im Indexer anzuzeigen.

REST-APIs

1. Verwenden Sie Indexer erstellen oder Indexer erstellen oder aktualisieren oder eine äquivalente Methode in einem Azure SDK. Hier ist ein Beispiel für eine Indexerdefinition.

   {
      "name": "myindexer",
      "description": null,
      "dataSourceName": "mydatasource",
      "targetIndexName": "myindex",
      "schedule": { },
      "parameters": { },
      "fieldMappings": [],
      "outputFieldMappings": [],
      "disabled": false,
      "encryptionKey": { }
    }
   

2. Füllen Sie das Array outputFieldMappings aus, um die Zuordnungen anzugeben. Eine Feldzuordnung besteht aus drei Teilen.

   "outputFieldMappings": [
     {
       "sourceFieldName": "/document/path-to-a-node-in-an-enriched-document",
       "targetFieldName": "some-search-field-in-an-index",
       "mappingFunction": null
     }
   ]
   

   Eigenschaft	Beschreibung
   sourceFieldName	Erforderlich. Gibt einen Pfad zum angereicherten Inhalt an. Ein Beispiel ist /document/content. Weitere Informationen zur Pfadsyntax und Beispiele finden Sie unter Referenzanreicherungen in einem Azure KI-Suche-Skillset.
   targetFieldName	Optional. Gibt das Suchfeld an, das den angereicherten Inhalt empfängt. Zielfelder müssen einfache Felder oder Sammlungen auf oberster Ebene sein. Es kann kein Pfad zu einem Unterfeld in einem komplexen Typ sein. Wenn Sie bestimmte Knoten in einer komplexen Struktur abrufen möchten, können Sie einzelne Knoten im Arbeitsspeicher vereinfachen und dann die Ausgabe an eine Zeichenfolgensammlung in Ihrem Index senden.
   mappingFunction	Optional. Fügt zusätzliche Verarbeitung durch von Indexern unterstützte Zuordnungsfunktionen hinzu. Bei Anreicherungsknoten sind Codierung und Decodierung die am häufigsten verwendeten Funktionen.

3. targetFieldName enthält immer den Namen des Felds im Suchindex.

4. sourceFieldName ist ein Pfad zu einem Knoten im erweiterten Dokument. Es ist die Ausgabe eines Skills. Der Pfad beginnt immer mit /document, und wenn Sie von einem Blob aus indizieren, lautet das zweite Element des Pfads /content. Das dritte Element ist der Wert, der vom Skill erzeugt wird. Weitere Informationen und Beispiele finden Sie unter Verweisen auf Erweiterungen in einem Azure KI-Suche-Skillset.

   In diesem Beispiel werden Entitäten und Stimmungsbezeichnungen aus der Inhaltseigenschaft eines Blobs extrahiert und zu Feldern in einem Suchindex hinzugefügt.

   {
       "name": "myIndexer",
       "dataSourceName": "myDataSource",
       "targetIndexName": "myIndex",
       "skillsetName": "myFirstSkillSet",
       "fieldMappings": [],
       "outputFieldMappings": [
           {
               "sourceFieldName": "/document/content/organizations/*/description",
               "targetFieldName": "descriptions",
               "mappingFunction": {
                   "name": "base64Decode"
               }
           },
           {
               "sourceFieldName": "/document/content/organizations",
               "targetFieldName": "orgNames"
           },
           {
               "sourceFieldName": "/document/content/sentiment",
               "targetFieldName": "sentiment"
           }
       ]
   }
   

5. Weisen Sie alle Zuordnungsfunktionen zu, die benötigt werden, um den Inhalt eines Felds zu transformieren, bevor es im Index gespeichert wird. Bei Anreicherungsknoten sind Codierung und Decodierung die am häufigsten verwendeten Funktionen.

.NET SDK (C#)

Verwenden Sie im Azure SDK für .NET die Klasse OutputFieldMappingEntry, die die Eigenschaften Name und TargetFieldName sowie einen optionalen Verweis auf MappingFunction bietet.

Geben Sie Ausgabefeldzuordnungen beim Erstellen des Indexers oder später durch direktes Festlegen von SearchIndexer.OutputFieldMappings an. Im folgenden C#-Beispiel werden die Ausgabefeldzuordnungen beim Erstellen eines Indexers festgelegt.

string indexerName = "cog-search-demo";
SearchIndexer indexer = new SearchIndexer(
    indexerName,
    dataSourceConnectionName,
    indexName)
{
    // Field mappings omitted for this example (assume default mappings)
    OutputFieldMappings =
    {
        new FieldMapping("/document/content/organizations") { TargetFieldName = "orgNames" },
        new FieldMapping("/document/content/sentiment") { TargetFieldName = "sentiment" }
    },
    SkillsetName = skillsetName
};

await indexerClient.CreateIndexerAsync(indexer);

1:n-Ausgabefeldzuordnung

Sie können eine Ausgabefeldzuordnung verwenden, um ein einzelnes Quellfeld an mehrere Felder in einem Suchindex weiterzuleiten. Sie können dies für Vergleichstests nutzen oder wenn Sie Felder mit unterschiedlichen Attributen verwenden möchten.

Angenommen, wir haben ein Skillset, das Einbettungen für ein Vektorfeld generiert, und einen Index mit mehreren Vektorfeldern, die je nach Algorithmus- und Komprimierungseinstellungen variieren. Ordnen Sie innerhalb des Indexers die Ausgabe des Einbettungsskills den einzelnen Vektorfeldern in einem Suchindex zu.

"outputFieldMappings": [
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_hnsw" }, 
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_eknn" },
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_narrow" }, 
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_no_stored" },
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_scalar" }       
  ]

Der Quellfeldpfad ist die Skillausgabe. In diesem Beispiel ist die Ausgabe text_vector. Der Zielname ist eine optionale Eigenschaft. Wenn Sie der Ausgabezuordnung keinen Zielnamen zuweisen, wäre der Pfad embedding bzw. genauer gesagt /document/content/embedding.

{
  "name": "test-vector-size-ss",  
  "description": "Generate embeddings using AOAI",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "#1",
      "description": null,
      "context": "/document/content",
      "resourceUri": "https://my-demo-eastus.openai.azure.com",
      "apiKey": null,
      "deploymentId": "text-embedding-ada-002",
      "dimensions": 1536,
      "modelName": "text-embedding-ada-002",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "authIdentity": null
    }
  ]
}

Vereinfachen komplexer Strukturen in eine Zeichenfolgensammlung

Wenn Ihre Quelldaten aus geschachtelten oder hierarchischen JSON-Daten bestehen, können Sie keine Feldzuordnungen verwenden, um die Datenpfade einzurichten. Stattdessen muss ihr Suchindex für einen vollständigen Import die Quelldatenstruktur jeder Ebene spiegeln.

In diesem Abschnitt werden Sie durch einen Importprozess geführt, der eine 1-1-Spiegelung eines komplexen Dokuments auf Quell- und Zielseite erzeugt. Als Nächstes wird das gleiche Quelldokument verwendet, um den Abruf und die Vereinfachung einzelner Knoten in Zeichenfolgensammlungen zu veranschaulichen.

Im Folgenden finden Sie ein Beispiel für ein Dokument in Azure Cosmos DB mit geschachtelten JSON-Daten:

{
   "palette":"primary colors",
   "colors":[
      {
         "name":"blue",
         "medium":[
            "acrylic",
            "oil",
            "pastel"
         ]
      },
      {
         "name":"red",
         "medium":[
            "acrylic",
            "pastel",
            "watercolor"
         ]
      },
      {
         "name":"yellow",
         "medium":[
            "acrylic",
            "watercolor"
         ]
      }
   ]
}

Wenn Sie dieses Quelldokument vollständig indizieren möchten, erstellen Sie eine Indexdefinition, in der die Feldnamen, Ebenen und Typen als komplexer Typ dargestellt werden. Da Feldzuordnungen für komplexe Typen im Suchindex nicht unterstützt werden, muss ihre Indexdefinition das Quelldokument spiegeln.

{
  "name": "my-test-index",
  "defaultScoringProfile": "",
  "fields": [
    { "name": "id", "type": "Edm.String", "searchable": false, "retrievable": true, "key": true},
    { "name": "palette", "type": "Edm.String", "searchable": true, "retrievable": true },
    { "name": "colors", "type": "Collection(Edm.ComplexType)",
      "fields": [
        {
          "name": "name",
          "type": "Edm.String",
          "searchable": true,
          "retrievable": true
        },
        {
          "name": "medium",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "retrievable": true,
        }
      ]
    }
  ]
}

Hier ist eine Beispielindexerdefinition, die den Import ausführt. Beachten Sie, dass keine Feldzuordnungen und kein Skillset vorhanden sind.

{
  "name": "my-test-indexer",
  "dataSourceName": "my-test-ds",
  "skillsetName": null,
  "targetIndexName": "my-test-index",

  "fieldMappings": [],
  "outputFieldMappings": []
}

Das Ergebnis ist das folgende Beispielsuchdokument, ähnlich dem Original in Azure Cosmos DB.

{
  "value": [
    {
      "@search.score": 1,
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "palette": "primary colors",
      "colors": [
        {
          "name": "blue",
          "medium": [
            "acrylic",
            "oil",
            "pastel"
          ]
        },
        {
          "name": "red",
          "medium": [
            "acrylic",
            "pastel",
            "watercolor"
          ]
        },
        {
          "name": "yellow",
          "medium": [
            "acrylic",
            "watercolor"
          ]
        }
      ]
    }
  ]
}

Ein alternatives Rendering in einem Suchindex besteht darin, einzelne Knoten in der geschachtelten Struktur der Quelle in eine Zeichenfolgensammlung in einem Suchindex zu vereinfachen.

Um diese Aufgabe auszuführen, benötigen Sie einen outputFieldMappings, der einen In-Memory-Speicherknoten einer Zeichenfolgensammlung im Index zuordnet. Die Ausgabefeldzuordnungen werden zwar hauptsächlich auf Skillausgaben angewendet, Sie können sie aber auch verwenden, um Knoten nach der Dokumententschlüsselung zu adressieren, bei der der Indexer ein Quelldokument öffnet und in den Arbeitsspeicher liest.

Das folgende Beispiel für eine Indexdefinition verwendet Zeichenfolgensammlungen, um eine vereinfachte Ausgabe zu erhalten:

{
  "name": "my-new-flattened-index",
  "defaultScoringProfile": "",
  "fields": [
    { "name": "id", "type": "Edm.String", "searchable": false, "retrievable": true, "key": true },
    { "name": "palette", "type": "Edm.String", "searchable": true, "retrievable": true },
    { "name": "color_names", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true },
    { "name": "color_mediums", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true}
  ]
}

Nachfolgend finden Sie ein Beispiel für eine Indexerdefinition, die outputFieldMappings verwendet, um die geschachtelten JSON-Daten den Feldern der Zeichenfolgensammlung zuzuordnen. Beachten Sie, dass das Quellfeld die Pfadsyntax für Anreicherungsknoten verwendet, obwohl kein Skillset vorhanden ist. Angereicherte Dokumente werden während der Dokumententschlüsselung im System erstellt. Das bedeutet, Sie können auf Knoten in jeder Dokumentstruktur zugreifen, solange diese Knoten vorhanden sind, wenn das Dokument entschlüsselt wird.

{
  "name": "my-test-indexer",
  "dataSourceName": "my-test-ds",
  "skillsetName": null,
  "targetIndexName": "my-new-flattened-index",
  "parameters": {  },
  "fieldMappings": [   ],
  "outputFieldMappings": [
    {
       "sourceFieldName": "/document/colors/*/name",
       "targetFieldName": "color_names"
    },
    {
       "sourceFieldName": "/document/colors/*/medium",
       "targetFieldName": "color_mediums"
    }
  ]
}

Ergebnisse der Definition sehen wie folgt aus. Bei der Vereinfachung der Struktur geht in diesem Fall Kontext verloren. Es gibt keine Zuordnungen zwischen einer bestimmten Farbe und den Medien, in der sie verfügbar ist. Je nach Ihrem Szenario kann ein Ergebnis ähnlich dem folgenden Beispiel jedoch genau das sein, was Sie brauchen.

{
  "value": [
    {
      "@search.score": 1,
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "palette": "primary colors",
      "color_names": [
        "blue",
        "red",
        "yellow"
      ],
      "color_mediums": [
        "[\"acrylic\",\"oil\",\"pastel\"]",
        "[\"acrylic\",\"pastel\",\"watercolor\"]",
        "[\"acrylic\",\"watercolor\"]"
      ]
    }
  ]
}

Zugehöriger Inhalt

• Feldzuordnungen und Transformationen
• Einführung in die KI in Azure Cognitive Search
• Skillsetkonzepte