Verrijkte uitvoer toewijzen aan velden in een zoekindex in Azure AI Search

In dit artikel wordt uitgelegd hoe u uitvoerveldtoewijzingen instelt, een gegevenspad definieert tussen in-memory gegevens die zijn gegenereerd tijdens de verwerking van vaardighedensets en doelvelden in een zoekindex. Tijdens de uitvoering van de indexeerfunctie bestaat alleen door vaardigheden gegenereerde informatie in het geheugen. Als u deze informatie in een zoekindex wilt behouden, moet u de indexeerfunctie laten weten waar de gegevens moeten worden verzonden.

Een uitvoerveldtoewijzing wordt gedefinieerd in een indexeerfunctie en heeft de volgende elementen:

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

In tegenstelling tot een fieldMappings definitie die een pad toewijst tussen letterlijke bronvelden en indexvelden, wordt een outputFieldMappings definitie in het geheugen toegewezen aan velden in een zoekindex.

Vereisten

• Indexeerfunctie, index, gegevensbron en vaardighedenset.

• Indexvelden moeten eenvoudige of bovenste velden zijn. U kunt geen uitvoer uitvoeren naar een complex type, maar als u een complex type hebt, kunt u een definitie van het uitvoerveld gebruiken om delen van het complexe type af te vlakken en naar een verzameling in een zoekindex te verzenden.

Wanneer gebruikt u een toewijzing van een uitvoerveld

Uitvoerveldtoewijzingen zijn vereist als uw indexeerfunctie een gekoppelde vaardighedenset heeft waarmee nieuwe informatie wordt gemaakt die u in uw index wilt gebruiken. Voorbeelden zijn:

• Vectoren van het insluiten van vaardigheden
• OCR-tekst van afbeeldingsvaardigheden
• Locaties, organisaties of personen van vaardigheden voor entiteitsherkenning

Uitvoerveldtoewijzingen kunnen ook worden gebruikt voor het volgende:

• Maak meerdere kopieën van de gegenereerde inhoud (een-op-veel-veldtoewijzingen).

• Het complexe type brondocument platmaken. Stel dat brondocumenten een complex type hebben, zoals een adres met meerdere onderdelen, en dat u alleen de plaats wilt. U kunt een uitvoerveldtoewijzing gebruiken om een geneste gegevensstructuur af te vlakken en vervolgens een uitvoerveldtoewijzing gebruiken om de uitvoer naar een tekenreeksverzameling in uw zoekindex te verzenden.

Uitvoerveldtoewijzingen zijn alleen van toepassing op zoekindexen. Als u een kennisarchief invult, gebruikt u projecties voor de configuratie van het gegevenspad.

Een toewijzing van uitvoervelden definiëren

Uitvoerveldtoewijzingen worden toegevoegd aan de outputFieldMappings matrix in een indexeerfunctiedefinitie, meestal geplaatst na de fieldMappings matrix. Een uitvoerveldtoewijzing bestaat uit drie delen.

U kunt de REST API of een Azure SDK gebruiken om veldtoewijzingen voor uitvoer te definiëren.

Tip

Indexeerfuncties die door de wizard Gegevens importeren zijn gemaakt, bevatten uitvoerveldtoewijzingen die door de wizard worden gegenereerd. Als u voorbeelden nodig hebt, voert u de wizard uit via de gegevensbron om de toewijzingen van uitvoervelden in de indexeerfunctie te zien.

REST-API's

1. Gebruik Indexeerfunctie maken of Indexeerfunctie maken of bijwerken of een equivalente methode in een Azure SDK. Hier volgt een voorbeeld van een definitie van een indexeerfunctie.

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

2. Vul de outputFieldMappings matrix in om de toewijzingen op te geven. Een veldtoewijzing bestaat uit drie delen.

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

   Eigenschappen	Beschrijving
   sourceFieldName	Vereist. Hiermee geeft u een pad naar verrijkte inhoud. Een voorbeeld hiervan kan zijn /document/content. Zie Referentieverrijkingen in een Azure AI Search-vaardighedenset voor padsyntaxis en voorbeelden.
   targetFieldName	Optioneel. Hiermee geeft u het zoekveld op dat de verrijkte inhoud ontvangt. Doelvelden moeten eenvoudige velden of verzamelingen op het hoogste niveau zijn. Het kan geen pad naar een subveld in een complex type zijn. Als u specifieke knooppunten in een complexe structuur wilt ophalen, kunt u afzonderlijke knooppunten in het geheugen platmaken en vervolgens de uitvoer verzenden naar een tekenreeksverzameling in uw index.
   mappingFunction	Optioneel. Voegt extra verwerking toe die wordt geleverd door toewijzingsfuncties die worden ondersteund door indexeerfuncties. Voor verrijkingsknooppunten zijn codering en decodering de meest gebruikte functies.

3. Dit targetFieldName is altijd de naam van het veld in de zoekindex.

4. Het sourceFieldName is een pad naar een knooppunt in het verrijkte document. Het is de uitvoer van een vaardigheid. Het pad begint altijd met /document, en als u indexeert vanuit een blob, is /contenthet tweede element van het pad . Het derde element is de waarde die door de vaardigheid wordt geproduceerd. Zie Referentieverrijkingen in een Azure AI Search-vaardighedenset voor meer informatie en voorbeelden.

   In dit voorbeeld worden entiteiten en sentimentlabels toegevoegd die zijn geëxtraheerd uit de inhoudseigenschap van een blob aan velden in een zoekindex.

   {
       "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. Wijs toewijzingsfuncties toe die nodig zijn om de inhoud van een veld te transformeren voordat deze in de index wordt opgeslagen. Voor verrijkingsknooppunten zijn codering en decodering de meest gebruikte functies.

.NET SDK (C#)

Gebruik in de Azure SDK voor .NET de klasse OutputFieldMappingEntry met de eigenschappen Name en TargetFieldName en een optionele verwijzing 'MappingFunction'.

Geef uitvoerveldtoewijzingen op bij het maken van de indexeerfunctie of later door SearchIndexer.OutputFieldMappings rechtstreeks in te stellen. In het volgende C#-voorbeeld worden de toewijzingen van het uitvoerveld ingesteld bij het maken van een indexeerfunctie.

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

Een-op-veel-veldtoewijzing

U kunt een uitvoerveldtoewijzing gebruiken om één bronveld naar meerdere velden in een zoekindex te routeren. U kunt dit doen voor vergelijkingstests of als u velden met verschillende kenmerken wilt.

Stel dat een vaardighedenset waarmee insluitingen worden gegenereerd voor een vectorveld en een index met meerdere vectorvelden die variëren per algoritme- en compressie-instellingen. Wijs in de indexeerfunctie de uitvoer van de insluitvaardigheid toe aan elk van de velden met meerdere vectoren in een zoekindex.

"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" }       
  ]

Het pad naar het bronveld is uitvoer van vaardigheden. In dit voorbeeld is text_vectorde uitvoer . Doelnaam is een optionele eigenschap. Als u de uitvoertoewijzing geen doelnaam geeft, zou het pad of nauwkeuriger zijnembedding. /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
    }
  ]
}

Complexe structuren plat maken in een tekenreeksverzameling

Als uw brongegevens bestaan uit geneste of hiërarchische JSON, kunt u geen veldtoewijzingen gebruiken om de gegevenspaden in te stellen. In plaats daarvan moet uw zoekindex de brongegevensstructuur spiegelen voor elk niveau voor een volledige import.

In deze sectie wordt u begeleid bij een importproces dat een een-op-een weerspiegeling van een complex document aan zowel de bron- als de doelzijde produceert. Vervolgens wordt hetzelfde brondocument gebruikt om het ophalen en afvlakken van afzonderlijke knooppunten in tekenreeksverzamelingen te illustreren.

Hier volgt een voorbeeld van een document in Azure Cosmos DB met geneste JSON:

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

Als u het bovenstaande brondocument volledig wilt indexeren, maakt u een indexdefinitie waarin de veldnamen, niveaus en typen worden weergegeven als een complex type. Omdat veldtoewijzingen niet worden ondersteund voor complexe typen in de zoekindex, moet uw indexdefinitie het brondocument spiegelen.

{
  "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 volgt een voorbeeld van een indexeerfunctiedefinitie waarmee het importeren wordt uitgevoerd (u ziet dat er geen veldtoewijzingen en geen vaardighedenset zijn).

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

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

Het resultaat is het volgende voorbeeldzoekdocument, vergelijkbaar met het origineel in Azure Cosmos DB.

{
  "value": [
    {
      "@search.score": 1,
      "id": "240a98f5-90c9-406b-a8c8-f50ff86f116c",
      "palette": "primary colors",
      "colors": [
        {
          "name": "blue",
          "medium": [
            "acrylic",
            "oil",
            "pastel"
          ]
        },
        {
          "name": "red",
          "medium": [
            "acrylic",
            "pastel",
            "watercolor"
          ]
        },
        {
          "name": "yellow",
          "medium": [
            "acrylic",
            "watercolor"
          ]
        }
      ]
    }
  ]
}

Een alternatieve rendering in een zoekindex is het plat maken van afzonderlijke knooppunten in de geneste structuur van de bron in een tekenreeksverzameling in een zoekindex.

Als u deze taak wilt uitvoeren, hebt u een outputFieldMappings knooppunt in het geheugen toegewezen aan een tekenreeksverzameling in de index. Hoewel uitvoerveldtoewijzingen voornamelijk van toepassing zijn op uitvoer van vaardigheden, kunt u ze ook gebruiken om knooppunten te adresseren na 'document kraken' waar de indexeerfunctie een brondocument opent en in het geheugen leest.

Hieronder ziet u een voorbeeld van een indexdefinitie, waarbij u tekenreeksverzamelingen gebruikt om platte uitvoer te ontvangen:

{
  "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}
  ]
}

Hier volgt de definitie van de voorbeeldindexeerfunctie, waarbij outputFieldMappings u de geneste JSON koppelt aan de tekenreeksverzamelingsvelden. U ziet dat het bronveld gebruikmaakt van de padsyntaxis voor verrijkingsknooppunten, ook al is er geen vaardighedenset. Verrijkte documenten worden in het systeem gemaakt tijdens het kraken van documenten, wat betekent dat u toegang hebt tot knooppunten in elke documentstructuur, zolang deze knooppunten bestaan wanneer het document wordt gekraakt.

{
  "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"
    }
  ]
}

De resultaten van de bovenstaande definitie zijn als volgt. Het vereenvoudigen van de structuur verliest in dit geval context. Er zijn geen verbanden meer tussen een bepaalde kleur en de mediums waarin deze beschikbaar is. Afhankelijk van uw scenario is een resultaat dat vergelijkbaar is met het resultaat dat hieronder wordt weergegeven, mogelijk precies wat u nodig hebt.

{
  "value": [
    {
      "@search.score": 1,
      "id": "240a98f5-90c9-406b-a8c8-f50ff86f116c",
      "palette": "primary colors",
      "color_names": [
        "blue",
        "red",
        "yellow"
      ],
      "color_mediums": [
        "[\"acrylic\",\"oil\",\"pastel\"]",
        "[\"acrylic\",\"pastel\",\"watercolor\"]",
        "[\"acrylic\",\"watercolor\"]"
      ]
    }
  ]
}

Zie ook

• Veldtoewijzingen definiëren in een zoekindexeerfunctie
• Overzicht van AI-verrijking
• Overzicht van vaardighedenset