Mapping dei campi e trasformazioni con gli indicizzatori di Ricerca di intelligenza artificiale di Azure

Articolo
01/17/2024

Quando un indicizzatore di Ricerca intelligenza artificiale di Azure carica un indice di ricerca, determina il percorso dei dati usando mapping dei campi da origine a destinazione. I mapping dei campi impliciti sono interni e si verificano quando i nomi dei campi e i tipi di dati sono compatibili tra l'origine e la destinazione. Se gli input e gli output non corrispondono, è possibile definire mapping di campi espliciti per configurare il percorso dati, come descritto in questo articolo.

I mapping dei campi possono essere usati anche per le conversioni di dati leggeri, ad esempio la codifica o la decodifica, tramite funzioni di mapping. Se è necessaria un'ulteriore elaborazione, prendere in considerazione Azure Data Factory per colmare il divario.

I mapping dei campi si applicano a:

Strutture di dati fisici su entrambi i lati del flusso di dati (tra campi in un'origine dati supportata e campi in un indice di ricerca). Se si importa contenuto arricchito da competenze che si trova in memoria, usare outputFieldMappings per eseguire il mapping dei nodi in memoria ai campi di output in un indice di ricerca.
Solo indici di ricerca. Se si popola un archivio conoscenze, usare le proiezioni per la configurazione del percorso dati.
Solo campi di ricerca di primo livello, dove è targetFieldName un campo semplice o una raccolta. Un campo di destinazione non può essere un tipo complesso.

Nota

Se si lavora con dati complessi (strutture annidate o gerarchiche) e si vuole eseguire il mirroring della struttura dei dati nell'indice di ricerca, l'indice di ricerca deve corrispondere esattamente alla struttura di origine (stessi nomi di campo, livelli e tipi) in modo che i mapping predefiniti funzionino. Facoltativamente, è possibile che nella struttura complessa siano presenti solo alcuni nodi. Per ottenere singoli nodi, è possibile rendere flat i dati in ingresso in una raccolta di stringhe (vedere outputFieldMappings per questa soluzione alternativa).

Scenari supportati

Caso d'uso	Descrizione
Discrepanza dei nomi	Si supponga che l'origine dati abbia un campo denominato `_city`. Dato che Ricerca intelligenza artificiale di Azure non consente nomi di campo che iniziano con un carattere di sottolineatura, un mapping dei campi consente di eseguire in modo efficace il mapping di "_city" a "city". Se i requisiti di indicizzazione includono il recupero di contenuto da più origini dati, in cui i nomi dei campi variano tra le origini, è possibile usare un mapping dei campi per chiarire il percorso.
Discrepanza tra i tipi	Supponendo che si desideri che un campo di tipo integer di origine sia di tipo `Edm.String` in modo che sia ricercabile nell'indice di ricerca. Poiché i tipi sono diversi, è necessario definire un mapping dei campi affinché il percorso dati abbia esito positivo. Si noti che Ricerca intelligenza artificiale di Azure ha un set di tipi di dati supportato più piccolo rispetto a molte origini dati. Se si importano dati SQL, un mapping dei campi consente di eseguire il mapping del tipo di dati SQL desiderato in un indice di ricerca.
Percorsi dati uno-a-molti	È possibile popolare più campi nell'indice con contenuto dello stesso campo di origine. Ad esempio, è possibile applicare analizzatori diversi a ogni campo per supportare casi d'uso diversi nell'app client.
Codifica e decodifica	È possibile applicare funzioni di mapping per supportare la codifica Base64 o la decodifica dei dati durante l'indicizzazione.
Dividere stringhe o ricastare matrici in raccolte	È possibile applicare funzioni di mapping per suddividere una stringa che include un delimitatore o inviare una matrice JSON a un campo di ricerca di tipo `Collection(Edm.String)`.

Definire un mapping dei campi

I mapping dei campi vengono aggiunti alla fieldMappings matrice di una definizione dell'indicizzatore. Un mapping dei campi è costituito da tre parti.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]

Proprietà	Descrizione
sourceFieldName	Obbligatorio. Rappresenta un campo nell'origine dati.
targetFieldName	Facoltativo. Rappresenta un campo nell'indice di ricerca. Se omesso, viene utilizzato il valore di `sourceFieldName` per la destinazione. I campi di destinazione devono essere campi o raccolte semplici di primo livello. Non può essere un tipo o una raccolta complessa. Se si gestisce un problema del tipo di dati, il tipo di dati di un campo viene specificato nella definizione dell'indice. Il mapping dei campi deve avere solo il nome del campo.
mappingFunction	Facoltativo. È costituito da funzioni predefinite che trasformano i dati.

Se viene visualizzato un errore simile a "Field mapping specifies target field 'Address/city' that doesn't exist in the index", perché i mapping dei campi di destinazione non possono essere un tipo complesso. La soluzione alternativa consiste nel creare uno schema di indice identico al contenuto non elaborato per i nomi dei campi e i tipi di dati. Per un esempio, vedere Esercitazione: Indicizzare BLOB JSON annidati.

Ricerca di intelligenza artificiale di Azure usa un confronto senza distinzione tra maiuscole e minuscole per risolvere i nomi dei campi e delle funzioni nei mapping dei campi. Ciò è utile (non è necessario ottenere tutte le maiuscole/minuscole), ma significa che l'origine dati o l'indice non può avere campi che differiscono solo per caso.

Nota

Se non sono presenti mapping di campi, gli indicizzatori presuppongono che i campi dell'origine dati vengano mappati ai campi di indice con lo stesso nome. L'aggiunta di un mapping dei campi sostituisce i mapping dei campi predefiniti per il campo di origine e di destinazione. Alcuni indicizzatori, ad esempio l'indicizzatore di archiviazione BLOB, aggiungono mapping di campi predefiniti per il campo chiave di indice.

È possibile usare l'API REST o Azure SDK per definire i mapping dei campi.

API REST
.NET SDK (C#)

Usare Create Indexer (REST) o Update Indexer (REST), qualsiasi versione dell'API.

In questo esempio viene gestita una discrepanza del nome di campo.

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_city", "targetFieldName" : "city" } ]
}

In questo esempio viene eseguito il mapping di un singolo campo di origine a più campi di destinazione ("mapping uno-a-molti"). È possibile "creare una copia tramite fork" di un campo, copiando lo stesso contenuto del campo di origine in due campi di indice diversi che verranno analizzati o attribuiti in modo diverso nell'indice.


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

In Azure SDK per .NET usare la classe FieldMapping che fornisce SourceFieldName proprietà e TargetFieldName e un riferimento facoltativo MappingFunction .

Specificare i mapping dei campi quando si costruisce l'indicizzatore o versioni successive impostando direttamente SearchIndexer.FieldMappings. Nell'esempio C# seguente vengono impostati i mapping dei campi durante la costruzione di un indicizzatore.

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_hotelId") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Funzioni ed esempi di mapping

Una funzione di mapping dei campi trasforma il contenuto di un campo prima che venga archiviato nell'indice. Sono attualmente supportate le funzioni di mapping seguenti:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
Urlencode
urlDecode

Funzione base64Encode

Esegue la codifica Base64 sicura per gli URL della stringa di input. Si presuppone che l'input sia con codifica UTF-8.

Esempio: Codifica di base di una chiave del documento

Solo i caratteri sicuri dell'URL possono essere visualizzati in una chiave del documento di Ricerca intelligenza artificiale di Azure , in modo da poter indirizzare il documento usando l'API Ricerca. Se il campo di origine per la chiave contiene caratteri URL-unsafe, ad esempio - e \, usare la base64Encode funzione per convertirla in fase di indicizzazione.

Nell'esempio seguente viene specificata la funzione base64Encode su metadata_storage_name per gestire i caratteri non supportati.

PUT /indexers?api-version=2020-06-30
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

Una chiave del documento (prima e dopo la conversione) non può superare i 1.024 caratteri. Quando si recupera la chiave codificata in fase di ricerca, usare la base64Decode funzione per ottenere il valore della chiave originale e usarla per recuperare il documento di origine.

Esempio: rendere un campo con codifica base "ricercabile"

In alcuni casi è necessario usare una versione codificata di un campo come metadata_storage_path la chiave, ma è necessaria anche una versione non codificata per la ricerca full-text. Per supportare entrambi gli scenari, è possibile eseguire il mapping metadata_storage_path a due campi: uno per la chiave (codificata) e un secondo per un campo di percorso che è possibile presupporre sia attribuito come searchable nello schema dell'indice.

PUT /indexers/blob-indexer?api-version=2020-06-30
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

Esempio: mantenere i valori originali

L'indicizzatore di archiviazione BLOB aggiunge automaticamente un mapping dei campi da metadata_storage_path, l'URI del BLOB, al campo della chiave di indice se non viene specificato alcun mapping dei campi. Questo valore è codificato in Base64, quindi è sicuro da usare come chiave del documento di Ricerca intelligenza artificiale di Azure. Nell'esempio seguente viene illustrato come eseguire contemporaneamente il mapping di una versione con codifica Base64 indipendente dall'URL di metadata_storage_path a un index_key campo e mantenere il valore originale in un metadata_storage_path campo:

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Se non si include una proprietà parameters per la funzione di mapping, il valore {"useHttpServerUtilityUrlTokenEncode" : true}predefinito è .

Ricerca di intelligenza artificiale di Azure supporta due diverse codifiche Base64. È consigliabile usare gli stessi parametri durante la codifica e la decodifica dello stesso campo. Per altre informazioni, vedere Opzioni di codifica base64 per decidere quali parametri usare.

funzione base64Decode

Esegue la decodifica Base64 della stringa di input. Si presuppone che l'input sia una stringa con codifica Base64 indipendente dall'URL.

Esempio: decodificare i metadati o gli URL del BLOB

I dati di origine possono contenere stringhe con codifica Base64, ad esempio stringhe di metadati BLOB o URL Web, che si desidera rendere ricercabile come testo normale. È possibile usare la base64Decode funzione per ripristinare i dati codificati in stringhe regolari durante il popolamento dell'indice di ricerca.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }
]

Se non si include una proprietà parameters, il valore {"useHttpServerUtilityUrlTokenEncode" : true}predefinito è .

Opzioni di codifica base64

Ricerca di intelligenza artificiale di Azure supporta la codifica base64 sicura degli URL e la normale codifica base64. Una stringa con codifica Base64 durante l'indicizzazione deve essere decodificata in un secondo momento con le stesse opzioni di codifica oppure il risultato non corrisponde all'originale.

Se i parametri o per la useHttpServerUtilityUrlTokenEncode codifica e la decodifica sono impostati rispettivamente su true, base64Encode si comportano come HttpServerUtility.UrlTokenEncode e base64Decode si comportano come HttpServerUtility.UrlTokenDecode.useHttpServerUtilityUrlTokenDecode

Avviso

Se base64Encode viene usato per produrre valori di chiave, useHttpServerUtilityUrlTokenEncode deve essere impostato su true. Per i valori delle chiavi è possibile usare solo la codifica base64 indipendente dall'URL. Vedere Regole di denominazione per il set completo di restrizioni sui caratteri nei valori chiave.

Le librerie .NET in Ricerca di intelligenza artificiale di Azure presuppongono .NET Framework completo, che fornisce la codifica predefinita. Le useHttpServerUtilityUrlTokenEncode opzioni e useHttpServerUtilityUrlTokenDecode applicano questa funzionalità predefinita. Se si usa .NET Core o un altro framework, è consigliabile impostare tali opzioni false su e chiamare direttamente le funzioni di codifica e decodifica del framework.

La tabella seguente confronta diverse codifiche Base64 della stringa 00>00?00. Per determinare l'elaborazione richiesta (se presente) per le funzioni base64, applicare la funzione di codifica della libreria sulla stringa 00>00?00 e confrontare l'output con l'output MDA-MDA_MDAprevisto.

Codifica	Output della codifica Base64	Elaborazione aggiuntiva dopo la codifica della libreria	Elaborazione aggiuntiva prima della decodifica della libreria
Base64 con spaziatura interna	`MDA+MDA/MDA=`	Usare caratteri sicuri per gli URL e rimuovere la spaziatura interna	Usare caratteri Base64 standard e aggiungere spaziatura interna
Base64 senza spaziatura interna	`MDA+MDA/MDA`	Usare caratteri sicuri per gli URL	Usare caratteri Base64 standard
Base64 sicura per gli URL con spaziatura interna	`MDA-MDA_MDA=`	Rimuovere la spaziatura interna	Aggiungere spaziatura interna
Base64 sicura per gli URL senza spaziatura interna	`MDA-MDA_MDA`	None	None

funzione extractTokenAtPosition

Divide un campo stringa usando il delimitatore specificato e sceglie il token nella posizione specificata della divisione risultante.

Questa funzione usa i parametri seguenti:

delimiter: stringa da usare come separatore quando si divide la stringa di input.
position: posizione in base zero di tipo integer del token da scegliere dopo la divisione della stringa di input.

Ad esempio, se l'input è Jane Doe, delimiter è " " (spazio) e position è 0, il risultato è Jane; se position è 1, il risultato è Doe. Se la posizione fa riferimento a un token che non esiste, viene restituito un errore.

Esempio: estrarre un nome

L'origine dati contiene un campo PersonName e si vuole indicizzarla come due campi separati, FirstName e LastName. È possibile usare questa funzione per dividere l'input usando il carattere spazio come delimitatore.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

Funzione jsonArrayToStringCollection

Trasforma una stringa formattata come matrice di stringhe JSON in una matrice di stringhe che può essere usata per popolare un campo Collection(Edm.String) nell'indice.

Ad esempio, se la stringa di input è ["red", "white", "blue"], il campo di destinazione di tipo Collection(Edm.String) viene popolato con i tre valori red, white e blue. Per i valori di input che non possono essere analizzati come matrici di stringhe JSON, viene restituito un errore.

Esempio: popolare la raccolta da dati relazionali

database SQL di Azure non ha un tipo di dati predefinito che esegue naturalmente il mapping ai Collection(Edm.String) campi in Ricerca di intelligenza artificiale di Azure. Per popolare i campi della raccolta di stringhe, è possibile pre-elaborare i dati di origine come matrice di stringhe JSON e quindi usare la jsonArrayToStringCollection funzione di mapping.

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

funzione urlEncode

Questa funzione può essere usata per codificare una stringa in modo che sia "sicura per l'URL". Se usato con una stringa che contiene caratteri non consentiti in un URL, questa funzione convertirà tali caratteri "non sicuri" in equivalenti di entità carattere. Questa funzione usa il formato di codifica UTF-8.

Esempio - Ricerca chiave documento

urlEncode la funzione può essere usata come alternativa alla base64Encode funzione, se devono essere convertiti solo i caratteri url non sicuri, mantenendo così invariati gli altri caratteri.

Ad esempio, la stringa di input è <hello> , quindi il campo di destinazione di tipo (Edm.String) verrà popolato con il valore %3chello%3e

Quando si recupera la chiave codificata in fase di ricerca, è quindi possibile usare la urlDecode funzione per ottenere il valore della chiave originale e usarla per recuperare il documento di origine.

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }
]

Funzione urlDecode

Questa funzione converte una stringa con codifica URL in una stringa decodificata usando il formato di codifica UTF-8.

Esempio: decodificare i metadati del BLOB

Alcuni client di archiviazione di Azure codificano automaticamente i metadati DEL BLOB se contengono caratteri non ASCII. Tuttavia, se si desidera rendere tali metadati ricercabili (come testo normale), è possibile usare la urlDecode funzione per ripristinare i dati codificati in stringhe regolari durante il popolamento dell'indice di ricerca.

"fieldMappings" : [
  {
    "sourceFieldName" : "UrlEncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : {
      "name" : "urlDecode"
    }
  }
]

funzione fixedLengthEncode

Questa funzione converte una stringa di qualsiasi lunghezza in una stringa a lunghezza fissa.

Esempio: eseguire il mapping delle chiavi del documento troppo lunghe

Quando si verificano errori correlati alla lunghezza della chiave del documento superiore a 1024 caratteri, questa funzione può essere applicata per ridurre la lunghezza della chiave del documento.


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }
]

Funzione toJson

Questa funzione converte una stringa in un oggetto JSON formattato. Può essere usato per scenari in cui l'origine dati, ad esempio Azure SQL, non supporta in modo nativo i tipi di dati composti o gerarchici e quindi ne esegue il mapping a campi complessi.

Esempio: eseguire il mapping del contenuto di testo a un campo complesso

Si supponga che sia presente una riga SQL con una stringa JSON che deve essere mappata a un campo complesso (corrispondentemente definito) nell'indice, la toJson funzione può essere usata per ottenere questo risultato. Ad esempio, se un campo complesso nell'indice deve essere popolato con i dati seguenti:

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

A tale scopo, è possibile usare la toJson funzione di mapping in una colonna stringa JSON in una riga SQL simile alla seguente: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Il mapping dei campi deve essere specificato come illustrato di seguito.


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]