Condividi tramite

Indicizzare BLOB e file Markdown in Ricerca di intelligenza artificiale di Azure

  • Articolo

Nota

Questa funzionalità è attualmente in anteprima pubblica. Questa anteprima viene messa a disposizione senza contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

In Ricerca di intelligenza artificiale di Azure, gli indicizzatori per Archiviazione BLOB di Azure, File di Azure e OneLake supportano una markdown modalità di analisi per i file Markdown. I file Markdown possono essere indicizzati in due modi:

  • Modalità di analisi uno-a-molti, creazione di più documenti di ricerca per ogni file Markdown
  • Modalità di analisi uno-a-uno, creazione di un documento di ricerca per ogni file Markdown

Suggerimento

Continuare con l'esercitazione: Cercare i dati markdown da Archiviazione BLOB di Azure dopo aver esaminato questo articolo.

Prerequisiti

  • Un'origine dati supportata: Archiviazione BLOB di Azure, Archiviazione file di Azure, OneLake in Microsoft Fabric.

    Per OneLake, assicurarsi di soddisfare tutti i requisiti dell'indicizzatore OneLake.

    Archiviazione di Azure per indicizzatori BLOB e indicizzatori di file è un'istanza standard delle prestazioni (per utilizzo generico v2) che supporta i livelli di accesso ad accesso frequente e sporadico.

Parametri della modalità di analisi markdown

I parametri della modalità di analisi vengono specificati in una definizione dell'indicizzatore quando si crea o si aggiorna un indicizzatore.

POST https://[service name].search.windows.net/indexers?api-version=2024-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h6"
    }
  },
}

L'indicizzatore BLOB fornisce un submode parametro per determinare l'output della struttura dei documenti di ricerca. La modalità di analisi Markdown offre le opzioni di sottomode seguenti:

parsingMode submode Cerca documento Descrizione
markdown oneToMany Più documenti per BLOB (impostazione predefinita) Suddivide markdown in più documenti di ricerca, ognuno dei quali rappresenta una sezione di contenuto (nonheader) del file Markdown. È possibile omettere la modalità secondaria a meno che non si voglia analizzare uno-a-uno.
markdown oneToOne Un solo documento per BLOB Analizza markdown in un documento di ricerca, con sezioni mappate a intestazioni specifiche nel file Markdown.

Per oneToMany la sottomode, vedere Indicizzazione di un BLOB per produrre molti documenti di ricerca per comprendere in che modo l'indicizzatore BLOB gestisce la disambiguazione della chiave del documento per più documenti di ricerca generati dallo stesso BLOB.

Le sezioni successive descrivono ogni sottomodo in modo più dettagliato. Se non si ha familiarità con i client e i concetti dell'indicizzatore, vedere Creare un indicizzatore di ricerca. È anche necessario avere familiarità con i dettagli della configurazione dell'indicizzatore BLOB di base, che non viene ripetuta qui.

Parametri di analisi markdown facoltativi

I parametri fanno distinzione tra maiuscole e minuscole.

Nome parametro Valori consentiti Descrizione
markdownHeaderDepth h1, h2, h3, h4, h5h6(default) Questo parametro determina il livello di intestazione più profondo che viene considerato durante l'analisi, consentendo la gestione flessibile della struttura del documento (ad esempio, quando markdownHeaderDepth è impostato su h1, il parser riconosce solo le intestazioni di primo livello che iniziano con "#" e tutte le intestazioni di livello inferiore vengono considerate come testo normale). Se non specificato, per impostazione predefinita viene impostato su h6.

Questa impostazione può essere modificata dopo la creazione iniziale dell'indicizzatore, tuttavia la struttura dei documenti di ricerca risultanti potrebbe cambiare a seconda del contenuto Markdown.

Elementi Markdown supportati

L'analisi markdown dividerà solo il contenuto in base alle intestazioni. Tutti gli altri elementi, ad esempio elenchi, blocchi di codice, tabelle e così via, vengono trattati come testo normale e passati in un campo di contenuto.

Contenuto markdown di esempio

Il contenuto Markdown seguente viene usato per gli esempi in questa pagina:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Usare la modalità di analisi uno-a-molti

La modalità di analisi uno-a-molti analizza i file Markdown in più documenti di ricerca, in cui ogni documento corrisponde a una sezione di contenuto specifica del file Markdown in base ai metadati dell'intestazione in quel punto del documento. Markdown viene analizzato in base alle intestazioni nei documenti di ricerca che contengono il contenuto seguente:

  • content: stringa contenente il markdown non elaborato trovato in una posizione specifica, in base ai metadati dell'intestazione in quel punto del documento.

  • sections: oggetto che contiene campi secondari per i metadati dell'intestazione fino al livello di intestazione desiderato. Ad esempio, quando markdownHeaderDepth è impostato su h3, contiene campi h1stringa , h2e h3. Questi campi vengono indicizzati eseguendo il mirroring di questa struttura nell'indice o tramite mapping dei campi nel formato /sections/h1, sections/h2e così via. Per esempi di contesto, vedere configurazioni dell'indice e dell'indicizzatore negli esempi seguenti. I sottocampi contenuti sono:

    • h1 - Stringa contenente il valore dell'intestazione h1. Stringa vuota se non impostata a questo punto del documento.
    • (Facoltativo) h2- Stringa contenente il valore dell'intestazione h2. Stringa vuota se non impostata a questo punto del documento.
    • (Facoltativo) h3- Stringa contenente il valore dell'intestazione h3. Stringa vuota se non impostata a questo punto del documento.
    • (Facoltativo) h4- Stringa contenente il valore dell'intestazione h4. Stringa vuota se non impostata a questo punto del documento.
    • (Facoltativo) h5- Stringa contenente il valore dell'intestazione h5. Stringa vuota se non impostata a questo punto del documento.
    • (Facoltativo) h6- Stringa contenente il valore dell'intestazione h6. Stringa vuota se non impostata a questo punto del documento.

  • ordinal_position: valore intero che indica la posizione della sezione all'interno della gerarchia del documento. Questo campo viene usato per ordinare le sezioni nella sequenza originale come appaiono nel documento, a partire da una posizione ordinale di 1 e incrementando in sequenza per ogni intestazione.

Schema dell'indice per l'analisi uno-a-molti

Una configurazione di indice di esempio potrebbe essere simile alla seguente:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "content",
    "type": "Edm.String",
  },
  {
    "name": "ordinal_position",
    "type": "Edm.Int32"
  },
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "h1",
      "type": "Edm.String"
    },
    {
      "name": "h2",
      "type": "Edm.String"
    }]
  }]
}

Definizione dell'indicizzatore per l'analisi uno-a-molti

Se i nomi dei campi e i tipi di dati sono allineati, l'indicizzatore BLOB può dedurre il mapping senza un mapping di campo esplicito presente nella richiesta, pertanto una configurazione dell'indicizzatore corrispondente alla configurazione dell'indice fornita potrebbe essere simile alla seguente:

POST https://[service name].search.windows.net/indexers?api-version=2024-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": { "parsingMode": "markdown" }
  },
}

Nota

Non submode è necessario impostare in modo esplicito in questo caso perché oneToMany è l'impostazione predefinita.

Output dell'indicizzatore per l'analisi uno-a-molti

Questo file Markdown genera tre documenti di ricerca dopo l'indicizzazione, a causa delle tre sezioni di contenuto. Il documento di ricerca risultante dalla prima sezione contenuto del documento Markdown fornito conterrà i valori seguenti per content, sectionsh1, e h2:

{
  {
    "content": "Content for section 1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": ""
    },
    "ordinal_position": 1
  },
  {
    "content": "Content for subsection 1.1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": "Subsection 1.1"
    },
    "ordinal_position": 2
  },
  {
    "content": "Content for section 2.\r\n",
    "sections": {
      "h1": "Section 2",
      "h2": ""
    },
    "ordinal_position": 3
  }
}

Eseguire il mapping di campi uno-a-molti in un indice di ricerca

I mapping dei campi associano un campo di origine a un campo di destinazione in situazioni in cui i nomi e i tipi dei campi non sono identici. Ma i mapping dei campi possono essere usati anche per trovare le corrispondenze tra parti di un documento Markdown e "sollevarle" in campi di primo livello del documento di ricerca.

Nel seguente scenario di esempio viene illustrato questo aspetto. Per altre informazioni sui mapping dei campi in generale, vedere Mapping dei campi.

Si supponga di avere un indice di ricerca con i campi seguenti: raw_content di tipo Edm.String, h1_header di tipo Edm.String e h2_header di tipo Edm.String. Per eseguire il mapping del markdown alla forma desiderata, usare i mapping dei campi seguenti:

"fieldMappings" : [
    { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
    { "sourceFieldName" : "/sections/h1", "targetFieldName" : "h1_header" },
    { "sourceFieldName" : "/sections/h2", "targetFieldName" : "h2_header" },
  ]

Il documento di ricerca risultante nell'indice sarà simile al seguente:

{
  {
    "raw_content": "Content for section 1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "",
  },
  {
    "raw_content": "Content for section 1.1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "Subsection 1.1",
  },
  {
    "raw_content": "Content for section 2.\r\n",
    "h1_header": "Section 2",
    "h2_header": "",
  }
}

Usare la modalità di analisi uno-a-uno

Nella modalità di analisi uno-a-uno, l'intero documento Markdown viene indicizzato come un singolo documento di ricerca, mantenendo la gerarchia e la struttura del contenuto originale. Questa modalità è più utile quando i file da indicizzare condividono una struttura comune, in modo da poter usare questa struttura comune nell'indice per rendere i campi pertinenti ricercabili.

Nella definizione dell'indicizzatore impostare su parsingMode "markdown" e usare il parametro facoltativo markdownHeaderDepth per definire la profondità massima dell'intestazione per la suddivisione in blocchi. Se non specificato, il valore predefinito è h6, acquisendo tutte le possibili profondità delle intestazioni.

Markdown viene analizzato in base alle intestazioni nei documenti di ricerca che contengono il contenuto seguente:

  • document_content: contiene il testo markdown completo come singola stringa. Questo campo funge da rappresentazione non elaborata del documento di input.

  • sections: matrice di oggetti che contiene la rappresentazione gerarchica delle sezioni all'interno del documento Markdown. Ogni sezione viene rappresentata come oggetto all'interno di questa matrice e acquisisce la struttura del documento in modo annidato corrispondente alle intestazioni e al rispettivo contenuto. I campi sono accessibili tramite mapping dei campi facendo riferimento al percorso, ad esempio /sections/content. Gli oggetti in questa matrice hanno le proprietà seguenti:

    • header_level: stringa che indica il livello dell'intestazione (h1, h2, h3e così via) nella sintassi markdown. Questo campo consente di comprendere la gerarchia e la strutturazione del contenuto.

    • header_name: stringa contenente il testo dell'intestazione visualizzata nel documento Markdown. Questo campo fornisce un'etichetta o un titolo per la sezione.

    • content: stringa contenente contenuto di testo che segue immediatamente l'intestazione, fino all'intestazione successiva. Questo campo acquisisce le informazioni dettagliate o la descrizione associata all'intestazione. Se non è presente alcun contenuto direttamente in un'intestazione, si tratta di una stringa vuota.

    • ordinal_position: valore intero che indica la posizione della sezione all'interno della gerarchia del documento. Questo campo viene usato per ordinare le sezioni nella sequenza originale come appaiono nel documento, a partire da una posizione ordinale di 1 e incrementando in sequenza per ogni blocco di contenuto.

    • sections: matrice che contiene oggetti che rappresentano sottosezioni annidate nella sezione corrente. Questa matrice segue la stessa struttura della matrice di primo livello sections , consentendo la rappresentazione di più livelli di contenuto annidato. Ogni oggetto sottosezione include header_levelanche le proprietà , header_name, contente ordinal_position , abilitando una struttura ricorsiva che rappresenta e gerarchia del contenuto Markdown.

Ecco l'esempio markdown usato per spiegare uno schema di indice progettato per ogni modalità di analisi.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Schema dell'indice per l'analisi uno-a-uno

Se non si utilizzano mapping di campi, la forma dell'indice deve riflettere la forma del contenuto Markdown. Data la struttura di esempio Markdown con le due sezioni e la sottosezione singola, l'indice dovrebbe essere simile all'esempio seguente:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "document_content",
    "type": "Edm.String",
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "header_level",
      "type": "Edm.String",
    },
    {
      "name": "header_name",
      "type": "Edm.String",
    },
    {
      "name": "content",
      "type": "Edm.String"
    },
    {
      "name": "ordinal_position",
      "type": "Edm.Int"
    },
    {
      "name": "sections",
      "type": "Edm.ComplexType",
      "fields": [
      {
        "name": "header_level",
        "type": "Edm.String",
      },
      {
        "name": "header_name",
        "type": "Edm.String",
      },
      {
        "name": "content",
        "type": "Edm.String"
      },
      {
        "name": "ordinal_position",
        "type": "Edm.Int"
      }]
    }]
  }
}

Definizione dell'indicizzatore per l'analisi uno-a-uno

POST https://[service name].search.windows.net/indexers?api-version=2024-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToOne",
    }
  }
}

Output dell'indicizzatore per l'analisi uno-a-uno

Poiché il markdown che si vuole indicizzare passa solo a una profondità di h2 ("##"), sono necessari sections campi annidati a una profondità pari a 2 per trovare una corrispondenza. Questa configurazione genera i dati seguenti nell'indice:

  "document_content": "# Section 1\r\nContent for section 1.\r\n## Subsection 1.1\r\nContent for subsection 1.1.\r\n# Section 2\r\nContent for section 2.\r\n",
  "sections": [
    {
      "header_level": "h1",
      "header_name": "Section 1",
      "content": "Content for section 1.",
      "ordinal_position": 1,
      "sections": [
        {
          "header_level": "h2",
          "header_name": "Subsection 1.1",
          "content": "Content for subsection 1.1.",
          "ordinal_position": 2,
        }]
    }],
    {
      "header_level": "h1",
      "header_name": "Section 2",
      "content": "Content for section 2.",
      "ordinal_position": 3,
      "sections": []
    }]
  }

Come si può notare, la posizione ordinale aumenta in base alla posizione del contenuto all'interno del documento.

Si noti anche che se i livelli di intestazione vengono ignorati nel contenuto, la struttura del documento risultante riflette le intestazioni presenti nel contenuto Markdown, non necessariamente contenenti sezioni nidificate per h1 un valore h6 consecutivo. Ad esempio, quando il documento inizia da h2, il primo elemento nella matrice delle sezioni di primo livello è h2.

Eseguire il mapping di campi uno-a-uno in un indice di ricerca

Se si desidera estrarre campi con nomi personalizzati dal documento, è possibile usare i mapping dei campi a tale scopo. Usando lo stesso esempio markdown di prima, prendere in considerazione la configurazione dell'indice seguente:

{
  "name": "my-markdown-index",
  "fields": [
    {
      "name": "document_content",
      "type": "Edm.String",
    },
    {
      "name": "document_title",
      "type": "Edm.String",
    },
    {
      "name": "opening_subsection_title"
      "type": "Edm.String",
    }
    {
      "name": "summary_content",
      "type": "Edm.String",
    }
  ]
}

L'estrazione di campi specifici dal Markdown analizzato viene gestita in modo simile a come i percorsi dei documenti si trovano in outputFieldMappings, ad eccezione del percorso che inizia con /sections invece di /document. Ad esempio, /sections/0/content eseguirà il mapping al contenuto sotto l'elemento nella posizione 0 nella matrice di sezioni.

Un esempio di caso d'uso sicuro potrebbe essere simile al seguente: tutti i file Markdown hanno un titolo del documento nel primo h1, un titolo di sottosezione nel primo h2e un riepilogo nel contenuto del paragrafo finale sotto l'ultimo h1. È possibile usare i mapping dei campi seguenti per indicizzare solo il contenuto:

"fieldMappings" : [
  { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
  { "sourceFieldName" : "/sections/0/header_name", "targetFieldName" : "document_title" },
  { "sourceFieldName" : "/sections/0/sections/header_name", "targetFieldName" : "opening_subsection_title" },
  { "sourceFieldName" : "/sections/1/content", "targetFieldName" : "summary_content" },
]

Qui si estraggono solo le parti pertinenti da tale documento. Per usare in modo più efficace questa funzionalità, i documenti che si prevede di indicizzare devono condividere la stessa struttura di intestazione gerarchica.

Il documento di ricerca risultante nell'indice sarà simile al seguente:

{
  "content": "Content for section 1.\r\n",
  "document_title": "Section 1",
  "opening_subsection_title": "Subsection 1.1",
  "summary_content": "Content for section 2."
}

Nota

Questi esempi specificano come usare queste modalità di analisi interamente con o senza mapping dei campi, ma è possibile sfruttare entrambi in uno scenario se adatto alle proprie esigenze.

Passaggi successivi