Mapper la sortie enrichie aux champs d’un index de recherche dans la Recherche Azure AI
Cet article explique comment configurer des mappages de champs de sortie, en définissant un chemin d’accès de données entre les structures de données en mémoire créées pendant le traitement d’un ensemble de compétences et les champs cibles dans un index de recherche. Un mappage de champs de sortie se définit dans un indexeur et comporte les éléments suivants :
"outputFieldMappings": [
{
"sourceFieldName": "document/path-to-a-node-in-an-enriched-document",
"targetFieldName": "some-search-field-in-an-index",
"mappingFunction": null
}
],
Contrairement à une définition fieldMappings qui mappe un chemin d’accès entre deux structures de données physiques, une définition outputFieldMappings mappe les enrichissements en mémoire aux champs d’un index de recherche.
Les mappages de champs de sortie sont requis si votre indexeur a un ensemble de compétences attaché qui crée de nouvelles informations, comme la traduction de texte ou l’extraction de phrases clés. Durant l’exécution de l’indexeur, les informations générées par l’IA sont uniquement stockées en mémoire. Pour rendre ces informations persistantes dans un index de recherche, vous devez indiquer à l’indexeur où envoyer les données.
Les mappages de champs de sortie peuvent également être utilisés pour récupérer des nœuds spécifiques dans le type complexe d’un document source. Par exemple, vous voulez peut-être juste « FullName/LastName » dans une propriété « FullName » en plusieurs parties. Si vous n’avez pas besoin de la structure complexe complète, vous pouvez aplatir des nœuds individuels dans des structures de données imbriquées, puis utiliser un mappage de champs de sortie pour envoyer la sortie vers une collection de chaînes dans l’index de recherche.
Les mappages de champs de sortie s’appliquent aux éléments suivants :
Le contenu en mémoire créé par des compétences ou extrait par un indexeur. Le champ source est un nœud dans une arborescence de documents enrichie.
Les index de recherche. Si vous remplissez une base de connaissances, utilisez des projections pour la configuration du chemin des données. Si vous remplissez des champs de vecteurs, les mappages de champs de sortie ne sont pas utilisés.
Les mappages de champs de sortie sont appliqués après l’exécution de l’ensemble de compétences, ou après le craquage de document s’il n’y a pas d’ensemble de compétences associé.
Définir un mappage de champs de sortie
Les mappages de champs de sortie sont ajoutés au tableau outputFieldMappings dans une définition d’indexeur, généralement placée après le tableau fieldMappings. Un mappage de champs de sortie se compose de trois parties.
"fieldMappings": []
"outputFieldMappings": [
{
"sourceFieldName": "/document/path-to-a-node-in-an-enriched-document",
"targetFieldName": "some-search-field-in-an-index",
"mappingFunction": null
}
],
| Propriété | Description |
|---|---|
| sourceFieldName | Obligatoire. Spécifie le chemin du contenu enrichi. Exemple : /document/content. Pour obtenir la syntaxe du chemin d’accès et des exemples, consultez Référencer des enrichissements dans un ensemble de compétences Recherche Azure AI. |
| targetFieldName | facultatif. Spécifie le champ de recherche qui reçoit le contenu enrichi. Les champs cibles doivent être des champs ou collections simples de premier niveau. Il ne doit pas s’agir d’un chemin vers un sous-champ dans un type complexe. Si vous souhaitez récupérer des nœuds spécifiques dans une structure complexe, vous pouvez aplatir des nœuds individuels en mémoire, puis envoyer la sortie vers une collection de chaînes dans l’index. |
| mappingFunction | facultatif. Ajoute un traitement supplémentaire fourni par les fonctions de mappage prises en charge par les indexeurs. Pour les nœuds d’enrichissement, l’encodage et le décodage sont les fonctions les plus couramment utilisées. |
Vous pouvez utiliser l’API REST ou un SDK Azure pour définir les mappages de champs de sortie.
Conseil
Les indexeurs créés par l’Assistant Importation de données incluent les mappages de champs de sortie qui sont générés par l’Assistant. Si vous avez besoin d’exemples, lancez l’Assistant sur votre source de données pour voir la définition résultante.
Utilisez Create Indexer (REST) ou Update Indexer (REST) dans la version de l’API de votre choix.
Cet exemple ajoute des entités et des étiquettes de sentiment extraites de la propriété de contenu d’un objet blob aux champs d’un index de recherche.
PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
"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"
}
]
}
Pour chaque mappage de champ de sortie, définissez l’emplacement des données dans l’arborescence de documents enrichis (sourceFieldName) ainsi que le nom du champ tel que référencé dans l’index (targetFieldName). Affectez les fonctions de mappage nécessaires pour transformer le contenu d’un champ avant qu’il ne soit stocké dans l’index.
Aplatir des structures complexes dans une collection de chaînes
Si vos données sources sont composées de données JSON imbriquées ou hiérarchiques, vous ne pouvez pas utiliser de mappages de champs pour configurer les chemins des données. Au lieu de cela, votre index de recherche doit refléter exactement la structure des données source à chaque niveau pour une importation complète.
Cette section vous guide pas à pas tout au long d’un processus d’importation qui reproduit fidèlement un document complexe côté source et côté cible. Ensuite, elle reprend le même document source pour illustrer la récupération et l’aplatissement de nœuds individuels dans des collections de chaînes.
Voici un exemple de document dans Azure Cosmos DB avec des données JSON imbriquées :
{
"palette":"primary colors",
"colors":[
{
"name":"blue",
"medium":[
"acrylic",
"oil",
"pastel"
]
},
{
"name":"red",
"medium":[
"acrylic",
"pastel",
"watercolor"
]
},
{
"name":"yellow",
"medium":[
"acrylic",
"watercolor"
]
}
]
}
Si vous souhaitez indexer entièrement le document source ci-dessus, vous devez créer une définition d’index qui reflète les noms, niveaux et types des champs comme un type complexe. Étant donné que les mappages de champs ne sont pas pris en charge pour les types complexes dans l’index de recherche, votre définition d’index doit refléter exactement le document source.
{
"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,
}
]
}
]
}
Voici un exemple de définition d’indexeur qui exécute l’importation (notez qu’il n’y a aucun mappage de champs ni aucun ensemble de compétences).
{
"name": "my-test-indexer",
"dataSourceName": "my-test-ds",
"skillsetName": null,
"targetIndexName": "my-test-index",
"fieldMappings": [],
"outputFieldMappings": []
}
Le résultat est l’exemple de document de recherche suivant, qui est similaire au document d’origine dans 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"
]
}
]
}
]
}
Un autre résultat possible dans un index de recherche consiste à aplatir des nœuds individuels dans la structure imbriquée de la source afin d’obtenir une collection de chaînes dans un index de recherche.
Pour accomplir cette tâche, vous devez utiliser un outputFieldMappings qui mappe un nœud en mémoire à une collection de chaînes dans l’index. Les mappages de champs de sortie s’appliquent principalement aux sorties de compétences, mais vous pouvez aussi les utiliser pour traiter les nœuds après le « craquage de document » où l’indexeur ouvre un document source et le lit en mémoire.
Voici un exemple de définition d’index, qui utilise des collections de chaînes pour recevoir une sortie aplatie :
{
"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}
]
}
Voici un exemple de définition d’indexeur, qui utilise outputFieldMappings pour associer les données JSON imbriquées aux champs des collections de chaînes. Notez que le champ source utilise la syntaxe de chemin des nœuds d’enrichissement, même s’il n’y a pas d’ensemble de compétences. Les documents enrichis sont créés dans le système pendant le craquage de document. Vous pouvez donc accéder aux nœuds dans chaque arborescence de documents tant que ces nœuds existent au moment du craquage de document.
{
"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"
}
]
}
Les résultats de la définition ci-dessus sont les suivants. La simplification de la structure amenuise le contexte dans ce cas. Il n’y a plus d’associations entre une couleur donnée et les supports qui la proposent. Toutefois, en fonction de votre scénario, un résultat similaire à celui montré ci-dessous peut être exactement ce dont vous avez besoin.
{
"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\"]"
]
}
]
}